Brook

A cross-platform programmable network tool.

Sponsor

❤️ Shiliew - A network app designed for those who value their time

Getting Started

Server

bash <(curl https://bash.ooo/nami.sh)
nami install brook
brook server -l :9999 -p hello

Client

You may want to use brook link to customize some parameters

Server

brook dnsserver, dohserver, dnsserveroverbrook, server, wsserver, wssserver, quicserver can use script to do more complex thing. brook will pass different global variables to the script at different times, and the script only needs to assign the processing result to the global variable out

Brook DNS Server

x

Script can do more:

Brook Server

x

Script can do more:

Variables

variable type command timing description out type
in_dnsservers map dnsserver/dnsserveroverbrook/dohserver/server/wsserver/wssserver/quicserver When just running Predefine multiple dns servers, and then programmatically specify which one to use map
in_dohservers map dnsserver/dnsserveroverbrook/dohserver/server/wsserver/wssserver/quicserver When just running Predefine multiple doh servers, and then programmatically specify which one to use map
in_brooklinks map server/wsserver/wssserver/quicserver When just running Predefine multiple brook links, and then programmatically specify which one to use map
in_dnsquery map dnsserver/dnsserveroverbrook/dohserver When a DNS query occurs Script can decide how to handle this request map
in_address map server/wsserver/wssserver/quicserver When the Server connects the proxied address Script can decide how to handle this request map

in_dnsservers

Key Type Description Example
_ bool meaningless true

out, ignored if not of type map

Key Type Description Example
... ... ... ...
custom name string dns server 8.8.8.8:53
... ... ... ...

in_dohservers

Key Type Description Example
_ bool meaningless true

out, ignored if not of type map

Key Type Description Example
... ... ... ...
custom name string dohserver https://dns.quad9.net/dns-query?address=9.9.9.9%3A443
... ... ... ...
Key Type Description Example
_ bool meaningless true

out, ignored if not of type map

Key Type Description Example
... ... ... ...
custom name string brook link brook://...
... ... ... ...

in_dnsquery

Key Type Description Example
fromipaddress string client address which send this request 1.2.3.4:5
domain string domain name google.com
type string query type A
... ... ... ...
tag_key string --tag specifies the key value tag_value
... ... ... ...

out, if it is error type will be recorded in the log. Ignored if not of type map

Key Type Description Example
block bool Whether Block, default false false
ip string Specify IP directly, only valid when type is A/AAAA 1.2.3.4
dnsserverkey string Use the dnsserver specified by key to resolve custom name
dohserverkey string Use the dohserver specified by key to resolve custom name

in_address

Key Type Description Example
network string tcp or udp tcp
fromipaddress string client address which send this request 1.2.3.4:5
ipaddress string ip address to be proxied 1.2.3.4:443
domainaddress string domain address to be proxied google.com:443
user string user ID, only available when used with --userAPI 9
... ... ... ...
tag_key string --tag specifies the key value tag_value
... ... ... ...

out, if it is error type will be recorded in the log. Ignored if not of type map

Key Type Description Example
block bool Whether Block, default false false
address string Rewrite destination to an address 1.2.3.4
ipaddressfromdnsserverkey string If the destination is domain address, use the dnsserver specified by key to resolve custom name
ipaddressfromdnsserverkey string If the destination is domain address, use the dohserver specified by key to resolve custom name
aoraaaa string Must be used with ipaddressfromdnsserverkey or ipaddressfromdnsserverkey. Valid value is A/AAAA A
speedlimit int Set a rate limit for this request, for example 1000000 means 1000 kb/s 1000000
brooklinkkey string Use the brook link specified by key to proxy custom name
dialwith string If your server has multiple IPs or network interfaces, you can specify the IP or network interface name to initiate this request 192.168.1.2 or 2606:4700:3030::ac43:a86a or en1

Client

CLI

Before discussing the GUI client, let's first talk about the command line client brook. As we know, after you have deployed the server, you can use the command line client brook to create a local socks5 proxy or http proxy on your machine, and then configure it in your system proxy settings or in your browser to use this proxy. However:

  1. Not all apps will use this proxy, whether they use it is up to the app itself.
  2. Generally, all UDP protocols will not go through this proxy, such as http3.

For the specifics of socks5 and http proxy, you can read this article.

GUI

The GUI client does not use socks5 and http proxy mode, so there is no issue with some software not using the system proxy. Instead, it uses a virtual network card to take over the entire system's network, including UDP-based http3. Moreover, Brook allows us to control network requests programmatically, so it is necessary to have basic knowledge of network requests. Brook GUI will pass different global variables to the script at different times, and the script only needs to assign the processing result to the global variable out

Without Brook

Note: When we talk about addresses, we mean addresses that include the port number, such as a domain address: google.com:443, or an IP address: 8.8.8.8:53

x

  1. When an app requests a domain address, such as google.com:443
  2. It will first perform a DNS resolution, which means that the app will send a network request to the system-configured DNS, such as 8.8.8.8:53, to inquire about the IP of google.com
  3. The system DNS will return the IP of google.com, such as 1.2.3.4, to the app
  4. The app will combine the IP and port into an IP address, such as: 1.2.3.4:443
  5. The app makes a network request to this IP address 1.2.3.4:443
  6. The app receives the response data

In the above process, the app actually makes two network requests: one to the IP address 8.8.8.8:53 and another to the IP address 1.2.3.4:443. In other words, the domain name is essentially an alias for the IP, and must obtain the domain's IP to establish a connection.

With Brook

Brook has a Fake DNS feature default, which can parse the domain name out of the query requests that an app sends to the system DNS UDP 53 and decide how to respond to the app.

x

  1. When an app requests a domain name address, such as google.com:443
  2. A DNS resolution will be performed first. That is, the app will send a network request to the system-configured DNS, such as 8.8.8.8:53, to inquire about the IP of google.com
  3. The Brook client detects that an app is sending a network request to 8.8.8.8:53. This will trigger the in_dnsquery variable, carrying information such as domain
  4. The Brook client returns a fake IP to the app, such as 240.0.0.1
  5. The app combines the IP and port into an IP address, such as: 240.0.0.1:443
  6. The app makes a network request to the IP address 240.0.0.1:443
  7. The Brook client detects that an app is sending a network request to 240.0.0.1:443, discovers that this is a fake IP, and will convert the fake IP address back to the domain address google.com:443. This will trigger the in_address variable, carrying information such as domainaddress
  8. The Brook client sends google.com:443 to the Brook Server
  9. The Brook Server first requests its own DNS to resolve the domain name to find out the IP of google.com, such as receiving 1.2.3.4
  10. The Brook Server combines the IP and port into an IP address, such as: 1.2.3.4:443
  11. The Brook Server sends a network request to 1.2.3.4:443 and returns the data to the Brook client
  12. The Brook client then returns the data to the app
  13. The app receives the response data

However, if the following situations occur, the domain name will not/cannot be parsed, meaning that the Brook client will not/cannot know what the domain name is and will treat it as a normal request sent to an IP address. To avoid the ineffectiveness of Fake DNS, please refer to this article:

Script can do more:

Variables

variable type condition timing description out type
in_brooklinks map / Before connecting Predefine multiple brook links, and then programmatically specify which one to connect to map
in_dnsquery map FakeDNS: On When a DNS query occurs Script can decide how to handle this request map
in_address map / When connecting to an address Script can decide how to handle this request map
in_httprequest map / When an HTTP(S) request comes in Script can decide how to handle this request map
in_httprequest,in_httpresponse map / when an HTTP(S) response comes in Script can decide how to handle this response map
Key Type Description Example
_ bool meaningless true

out, ignored if not of type map

Key Type Description Example
... ... ... ...
custom name string brook link brook://...
... ... ... ...

in_dnsquery

Key Type Description Example
domain string domain name google.com
type string query type A
appid string macOS App Mode: this is app id; Linux and Windows: this is app path; OpenWrt: this is IP address of client device. Note: In some operating systems, the app may initiate DNS queries through the system app. com.google.Chrome.helper

out, if it is error type will be recorded in the log. Ignored if not of type map

Key Type Description Example
block bool Whether Block, default false false
ip string Ignore fake DNS, specify IP directly, only valid when type is A/AAAA 1.2.3.4
system bool Ignore fake DNS, resolve by System DNS over brook, default false false
bypass bool Ignore fake DNS, resolve by Bypass DNS, default false false
brooklinkkey string When need to connect the Server, instead, perfer connect to the Server specified by the key in_brooklinks custom name

in_address

Key Type Description Example
network string Network type, the value tcp/udp tcp
ipaddress string IP type address. There is only one of ipaddress and domainaddress. Note that there is no relationship between these two 1.2.3.4:443
domainaddress string Domain type address, because of FakeDNS we can get the domain name address here google.com:443
appid string macOS App Mode: this is app id; Linux and Windows: this is app path; OpenWrt: this is IP address of client device com.google.Chrome.helper

out, if it is error type will be recorded in the log. Ignored if not of type map

Key Type Description Example
block bool Whether Block, default false false
ipaddress string Rewrite destination to an ip address 1.2.3.4:443
ipaddressfrombypassdns string Use Bypass DNS to obtain A or AAAA IP and rewrite the destination, only valid when domainaddress exists, the value A/AAAA A
bypass bool Bypass, default false. If true and domainaddress exists, then ipaddress or ipaddressfrombypassdns must be specified false
mitm bool Whether to perform MITM, default false. Only valid when network is tcp. Need to install CA, see below false
mitmprotocol string MITM protocol needs to be specified explicitly, the value is http/https https
mitmcertdomain string The MITM certificate domain name, which is taken from domainaddress by default. If ipaddress exists and mitm is true and mitmprotocol is https then must be must be specified explicitly example.com
mitmwithbody bool Whether to manipulate the http body, default false. will read the body of the request and response into the memory and interact with the script. iOS 50M total memory limit may kill process false
mitmautohandlecompress bool Whether to automatically decompress the http body when interacting with the script, default false. Usually need set this to true false
mitmclienttimeout int Timeout for MITM talk to server, second, default 0 0
mitmserverreadtimeout int Timeout for MITM read from client, second, default 0 0
mitmserverwritetimeout int Timeout for MITM write to client, second, default 0 0
brooklinkkey string When need to connect the Server,instead, connect to the Server specified by the key in_brooklinks custom name

in_httprequest

Key Type Description Example
URL string URL https://example.com/hello
Method string HTTP method GET
Body bytes HTTP request body /
... string other fields are HTTP headers /

out, must be set to an unmodified or modified request or a response

in_httpresponse

Key Type Description Example
StatusCode int HTTP status code 200
Body bytes HTTP response body /
... string other fields are HTTP headers /

out, must be set to an unmodified or modified response

Modules

In Brook GUI, scripts are abstracted into Modules. There are already some modules, and there is no magic, it just automatically combine _header.tengo and _footer.tengo, so you only need to write the module itself.

modules = append(modules, {
    // If you want to predefine multiple brook links, and then programmatically specify which one to connect to, then define `brooklinks` key a function
    brooklinks: func(m) {
        // Please refer to the example in `brooklinks.tengo`
    },
    // If you want to intercept and handle a DNS query, then define `dnsquery` key a function, `m` is the `in_dnsquery`
    dnsquery: func(m) {
        // Please refer to the example in `block_aaaa.tengo`
    },
    // If you want to intercept and handle an address, then define `address` key a function, `m` is the `in_address`
    address: func(m) {
        // Please refer to the example in `block_google_secure_dns.tengo`
    },
    // If you want to intercept and handle a http request, then define `httprequest` key a function, `request` is the `in_httprequest`
    httprequest: func(request) {
        // Please refer to the example in `ios_app_downgrade.tengo` or `redirect_google_cn.tengo`
    },
    // If you want to intercept and handle a http response, then define `httpresponse` key a function, `request` is the `in_httprequest`, `response` is the `in_httpresponse`
    httpresponse: func(request, response) {
        // Please refer to the example in `response_sample.tengo`
    }
})

ipio

https://github.com/txthinking/ipio

ipio uses the same script as the GUI. If you are using ipio, you can manually combine multiple modules into a complete script in the following way. For example:

cat _header.tengo > my.tengo

cat block_google_secure_dns.tengo >> my.tengo
cat block_aaaa.tengo >> my.tengo

cat _footer.tengo >> my.tengo

openwrt

https://www.txthinking.com/talks/articles/brook-openwrt-en.article

openwrt uses the same script as the GUI. If you are using openwrt, you can manually combine multiple modules into a complete script in the following way. For example:

cat _header.tengo > my.tengo

cat block_google_secure_dns.tengo >> my.tengo
cat block_aaaa.tengo >> my.tengo

cat _footer.tengo >> my.tengo

Debug

If you are writing complex scripts, the GUI may not be convenient for debugging. It is recommended to use ipio on desktop to debug with fmt.println

CA

https://txthinking.github.io/ca/ca.pem

OS How
iOS https://www.youtube.com/watch?v=HSGPC2vpDGk
Android Android has user CA and system CA, must be installed in the system CA after ROOT
macOS nami install mad ca.txthinking, sudo mad install --ca ~/.nami/bin/ca.pem
Windows nami install mad ca.txthinking, Admin: mad install --ca ~/.nami/bin/ca.pem

Some software may not read the system CA,you can use curl --cacert ~/.nami/bin/ca.pem to debug

IPv6

Brook's stance on IPv6 is positive, if your server or local environment doesn't have an IPv6 stack, read this article.

Troubleshooting Steps

  1. After adding your Server to the Brook client
  2. If your Server uses a domain and has not specified an IP address via brook link --address, then Brook client will attempt to resolve the domain's IP using local DNS, preferring AAAA record. For example:
    • domain.com:9999
    • ws://domain.com:9999
    • wss://domain.com:9999
    • quic://domain.com:9999
  3. Connectivity check: Go to the Server details page and click Connectivity Check. If it works sometimes but not others, this indicates instability.
  4. After connected
  5. Brook will change your system DNS to the System DNS configured in Brook (by default Google's DNS). In very rare cases, this change may be ignored on Windows, you can confirm this in the system settings.
  6. Test IPv4 TCP: Use Test IPv4 TCP for testing; this test has hardcoded the IP address, so does not trigger DNS resolution.
  7. Test IPv4 UDP: Use Test IPv4 UDP for testing; this test has hardcoded the IP address, so does not trigger DNS resolution.
  8. Test IPv6 TCP: Use Test IPv6 TCP for testing; this test has hardcoded the IP address, so does not trigger DNS resolution.
  9. Test IPv6 UDP: Use Test IPv6 UDP for testing; this test has hardcoded the IP address, so does not trigger DNS resolution.
  10. Test TCP and UDP: Use the Echo Client for testing. If the echo server entered is a domain address, it will trigger DNS resolution.
  11. Ensure the effectiveness of Fake DNS: Fake DNS is essential to do something with a domain or domain address. Generally, enable the Block Google Secure DNS module is sufficient. For other cases, refer to this article.
  12. If your local or Server does not support IPv6: Refer to this article.
  13. macOS App Mode: Refer to this article.
  14. Windows:
    • The client can pass the tests without any special configuration on a brand-new, genuine Windows 11.
    • Be aware that the Windows system time is often incorrect.
    • Do not have other similar network software installed; they can cause conflicting network settings in the system.
    • Try restarting the computer.
    • Windows Defender may ask for permission to connect to the network or present other issues.
    • System DNS may need to be set to 8.8.8.8 and/or 2001:4860:4860::8888
  15. Android:
    • The client can pass the tests without any special configuration on the official Google ROM.
    • Different ROMs may have made different modifications to the system.
    • Permission for background running might require separate settings.
    • System DNS may need to be set to 8.8.8.8 and/or 2001:4860:4860::8888
  16. Bypass traffic such as China, usually requires the following modules to be activated:
    • Block Google Secure DNS
    • Bypass Geo
    • Bypass Apple: To prevent issues receiving Apple message notifications.
    • Bypass China domain or Bypass China domain A: The former uses Bypass DNS to obtain the IP, then Bypass Geo or other modules decide whether to bypass; the latter bypasses directly after obtaining the IP with Bypass DNS using A records. The latter is needed if your local does not support IPv6.
    • If you are a Shiliew user, some modules are enabled by default, which is usually sufficient.
  17. Search GitHub issues
  18. Read the blog
  19. Read the documentation
  20. Submit new issue
  21. Seek help in the group

Other

Script Syntax

I think just reading this one page is enough: Tengo Language Syntax

Library

Example

Each subcommand has a --example, such as:

brook server --example

Resources

CLI Description
nami A clean and tidy decentralized package manager
joker Joker can turn process into daemon. Zero-Configuration
nico Nico can work with brook wsserver together
z z - process manager
ipio Proxy all traffic just one line command
mad Generate root CA and derivative certificate for any domains and any IPs
hancock Manage multiple remote servers and execute commands remotely
sshexec A command-line tool to execute remote command through ssh
bash Many one-click scripts
docker docker run txthinking/brook
Resources Description
Protocol Brook Protocol
Blog Some articles you should read
YouTube Some videos you should watch
Telegram Ask questions here
Announce All news you should care
GitHub Other useful repos
Socks5 Configurator If you prefer CLI brook client
IPvBar See domain, IP and country in browser
TxThinking SSH A SSH Terminal
brook-store A Brook User System
TxThinking Everything

CLI Documentation

NAME

Brook - A cross-platform programmable network tool

SYNOPSIS

Brook

brook --help

Usage:

Brook [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]

GLOBAL OPTIONS

COMMANDS

server

Start a brook server that supports tcp and udp

client

Start a brook client that supports tcp and udp. It can open a socks5 proxy, [src <-> socks5 <-> $ brook client <-> $ brook server <-> dst]

wsserver

Start a brook wsserver that supports tcp and udp. It opens a standard http server and a websocket server

wsclient

Start a brook wsclient that supports tcp and udp. It can open a socks5 proxy, [src <-> socks5 <-> $ brook wsclient <-> $ brook wsserver <-> dst]

wssserver

Start a brook wssserver that supports tcp and udp. It opens a standard https server and a websocket server

wssclient

Start a brook wssclient that supports tcp and udp. It can open a socks5 proxy, [src <-> socks5 <-> $ brook wssclient <-> $ brook wssserver <-> dst]

quicserver

Start a brook quicserver that supports tcp and udp.

quicclient

Start a brook quicclient that supports tcp and udp. It can open a socks5 proxy, [src <-> socks5 <-> $ brook quicclient <-> $ brook quicserver <-> dst]

relayoverbrook

Relay network traffic over brook, which supports TCP and UDP. Accessing [from address] is equal to accessing [to address], [src <-> from address <-> $ brook server/wsserver/wssserver/quicserver <-> to address]

dnsserveroverbrook

Run a dns server over brook, which supports TCP and UDP, [src <-> $ brook dnserversoverbrook <-> $ brook server/wsserver/wssserver/quicserver <-> dns]

connect

Run a client and connect with a brook link, which supports TCP and UDP. It can start a socks5 proxy, [src <-> socks5 <-> $ brook connect <-> $ brook server/wsserver/wssserver/quicserver <-> dst]

Generate a brook link

relay

Run a standalone relay, which supports TCP and UDP. Accessing [from address] is equal to accessing [to address], [src <-> from address <-> to address]

dnsserver

Run a standalone dns server

dnsclient

Send a dns query

dohserver

Run a standalone doh server

dohclient

Send a dns query

dhcpserver

Run a standalone dhcp server. IPv4 only. Other running dhcp servers need to be stopped.

socks5

Run a standalone standard socks5 server, which supports TCP and UDP

socks5tohttp

Convert a socks5 proxy to a http proxy, [src <-> listen address(http proxy) <-> socks5 address <-> dst]

testsocks5

Test a socks5 server to see if it works properly

testbrook

Test UDP and TCP of a brook server/wsserver/wssserver/quicserver connection.

echoserver

Echo server, echo UDP and TCP address of routes

echoclient

Connect to echoserver, echo UDP and TCP address of routes

ipcountry

Get country of IP

completion

Generate shell completions

mdpage

Generate markdown page

manpage

Generate man.1 page

help, h

Shows a list of commands or help for one command