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

iOS	Android	Mac	Windows	Linux	OpenWrt
/	/	App Mode	How	How	How

You may want to use brook link to customize some parameters

Client

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

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.

Without Brook: Basic Knowledge of Network Requests

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

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
   1. The system DNS will return the IP of google.com, such as 1.2.3.4, to the app
3. The app will combine the IP and port into an IP address, such as: 1.2.3.4:443
4. The app makes a network request to this IP address 1.2.3.4:443
5. 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: Fake DNS On

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

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
   1. The Brook client returns a fake IP to the app, such as 240.0.0.1
4. The app combines the IP and port into an IP address, such as: 240.0.0.1:443
5. The app makes a network request to the IP address 240.0.0.1:443
6. 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
   1. The Brook client sends google.com:443 to the Brook Server
   2. 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
   3. The Brook Server combines the IP and port into an IP address, such as: 1.2.3.4:443
   4. The Brook Server sends a network request to 1.2.3.4:443 and returns the data to the Brook client
   5. The Brook client then returns the data to the app
7. 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:

• Fake DNS not enabled: in this case, the Brook client will not attempt to parse the domain name from the request sent to the system DNS and will treat it as a normal request sent to an IP address.
• Even with Fake DNS enabled, but the app uses the system's secure DNS or the app's own secure DNS: in this case, the Brook client cannot parse the domain name from the request sent to the secure DNS 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.

With Brook: Fake DNS Off

1. When an app requests a domain 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_address variable, carrying information such as ipaddress
   1. The Brook client sends 8.8.8.8:53 to the Brook Server
   2. The Brook Server sends a network request to 8.8.8.8:53 and returns the result, such as 1.2.3.4, to the Brook client
   3. The Brook client then returns the result to the app
4. The app combines the IP and port into an IP address, such as: 1.2.3.4:443
5. The app makes a network request to the IP address 1.2.3.4:443
6. The Brook client detects that an app is sending a network request to 1.2.3.4:443. This will trigger the in_address variable, carrying information such as ipaddress
   1. The Brook client sends 1.2.3.4:443 to the Brook Server
   2. The Brook Server sends a network request to 1.2.3.4:443 and returns the data to the Brook client
   3. The Brook client then returns the data to the app
7. The app receives the response data

With Brook: Fake DNS On, But the App Uses the System's Secure DNS or Its Own Secure DNS

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 secure DNS, such as 8.8.8.8:443, 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:443. This will trigger the in_address variable, carrying information such as ipaddress
   1. The Brook client sends 8.8.8.8:443 to the Brook Server
   2. The Brook Server sends a network request to 8.8.8.8:443, and returns the result, such as 1.2.3.4, to the Brook client
   3. The Brook client then returns the result to the app
4. The app combines the IP and port into an IP address, such as: 1.2.3.4:443
5. The app makes a network request to the IP address 1.2.3.4:443
6. The Brook client detects that an app is sending a network request to 1.2.3.4:443. This will trigger the in_address variable, carrying information such as ipaddress
   1. The Brook client sends 1.2.3.4:443 to the Brook Server
   2. The Brook Server sends a network request to 1.2.3.4:443 and returns the data to the Brook client
   3. The Brook client then returns the data to the app
7. The app receives the response data

To avoid the ineffectiveness of Fake DNS, please refer to this article.

Handle Variable Trigger

• When the in_brooklinks variable is triggered:
  • This is currently the only variable that gets triggered before the Brook client starts.
  • We know that Brook starts with your choice of a Brook Server, and this variable lets you specify multiple Brook Servers.
  • Then during runtime, you can use one of these Brook Servers as needed.
• When the in_dnsquery variable is triggered, you can process as needed, such as:
  • Blocking, such as to prevent ad domain names.
  • Directly specifying the response IP.
  • Letting the system DNS resolve this domain.
  • Letting Bypass DNS resolve this domain.
  • And so on.
• When the in_address variable is triggered, you can process as needed, such as:
  • Block this connection.
  • Rewrite the destination.
  • If it's a domain address, you can specify that Bypass DNS is responsible for resolving the IP of this domain.
  • Allow it to connect directly without going through a proxy.
  • If it's HTTP/HTTPS, you can start MITM (Man-In-The-Middle), which will subsequently trigger in_httprequest and in_httpresponse.
  • And so on.
• When the in_httprequest variable is triggered, you can process as needed, such as:
  • Modifying the HTTP request.
  • Returning a custom HTTP response directly.
• When the in_httpresponse variable is triggered, you can process as needed, such as:
  • Modifying the HTTP response.

For detailed information on the properties and responses of variables, please refer to the following content.

Variables

in_brooklinks

out, ignored if not of type map

in_dnsquery

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

in_address

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