How the Brook GUI works

https://talks.txthinking.com
Created at: 22 Apr 2022
Updated at: 01 May 2022
cloud@txthinking.com

Table of Contents

• Brook
• GUI: macOS GUI proxy mode, Windows GUI proxy mode
  • Rule
  • Data Flow
• GUI: macOS tun mode, Windows tun mode, iOS, Android
  • Rule
  • Data Flow
    • Configure System DNS
    • Block block ads
    • When Fake DNS is off
    • When Fake DNS is on
• Brook GUI Client Import Server List
• Why and How to Turn Off System and Browser Secure DNS
  • Will closing it reduce security?
• MITM
  • ROOT CA
    • macOS
    • Windows
    • iOS
    • Android
  • Rule
  • Script
  • request
  • response
  • How it works
  • MITM with Body
  • Example
  • Debugging
• Log
• Apple push problem
• Windows IPv6 tun mode
• Resources

Brook

https://github.com/txthinking/brook

GUI: macOS GUI proxy mode, Windows GUI proxy mode

You can see the proxy mode in Proxy & Tun in the left menu of the graphical client. In this mode, it will ignore: Bypass CIDR4 list, Bypass CIDR6 list, DNS Server, Fake DNS, Block list, Block configuration items.

In this mode, will create:

• socks5 proxy: socks5://[::1]:1080 may be created under IPv6 network, socks5://127.0.0.1:1080 may be created under IPv4 network
  • If you need to use this socks5 proxy directly, you can use curl to determine which proxy was created: curl -x socks5://[::1]:1080 ipip.ooo or curl -x socks5://127.0.0.1 :1080 ipip.ooo
• http proxy: http://[::1]:8010 may be created under IPv6 network, http://127.0.0.1:8010 may be created under IPv4 network
  • If you need to use this http proxy directly, you can use curl to determine which proxy was created: curl -x http://[::1]:1080 ipip.ooo or curl -x http://127.0.0.1 :1080 ipip.ooo
• A pac server will be created based on the Bypass Domain list, and the system proxy will be configured to use this pac
  • But it should be noted that some software may not use the proxy configured by the system.

Rule

• Bypass Domain list is a txt file, one domain name per line
• Suffix matching pattern: For example, if there is a.com in the list, then a.com, x.a.com, x.x.a.com will all be matched; for example, if there is cn in the list, then x.cn, x.x.cn will all be matched

Data Flow

• If read system proxy, such as Chrome:

  • The domain name does not match the Bypass Domain list (domain name resolve will be completed on the server)

      Initiate a request--HTTP/HTTPS(TCP)--> pac server --> Brook client--(Brook protocol)--> brook server/wsserver/wssserver/socks5 --HTTP/HTTPS(TCP)--> DST
    

  • The domain name matches the Bypass Domain list (domain name resolve will be done locally)

      Initiate a request --HTTP/HTTPS(TCP)--> pac server --> local --HTTP/HTTPS(TCP)--> DST
    

• If don't read system proxy, for example, on the Telegram client (Telegram should only use TCP?), configure the socks5 proxy created above separately (domain name resolve will be done on the server):

    Initiate request --TCP/UDP--> socks5 proxy --TCP/UDP--> Brook client --(Brook protocol) --> brook server/wsserver/wssserver/socks5 --TCP/UDP--> DST
  

GUI: macOS tun mode, Windows tun mode, iOS, Android

Rule

can be specified

• A system v4 DNS
  • Note: Do not include this DNS in the bypass CIDR4 list
• A system v6 DNS
  • Note: Do not include this DNS in the bypass CIDR6 list
• A default v4 DNS
  • Such as 8.8.8.8:53
  • Or DoH, with address paramter to specify DoH address, such as https://dns.google/dns-query?address=8.8.8.8%3A443
  • Note: Do not include this DNS in the bypass CIDR4 list
• A default v6 DNS
  • Such as [2001:4860:4860::8888]:53
  • Or DoH, with address paramter to specify DoH address, such as https://dns.google/dns-query?address=%5B2001%3A4860%3A4860%3A%3A8888%5D%3A443
  • Note: Do not include this DNS in the bypass CIDR6 list
• A bypass v4 DNS
  • Such as 223.5.5.5:53
  • Or DoH, with address paramter to specify DoH address, such as https://dns.alidns.com/dns-query?address=223.5.5.5%3A443
  • Auto bypass
• A bypass v6 DNS
  • Such as [2400:3200::1]:53
  • Or DoH, with address paramter to specify DoH address, such as https://dns.alidns.com/dns-query?address=%5B2400%3A3200%3A%3A1%5D%3A443
  • Auto bypass
• A list of bypass domains
  • The list is a txt file, one domain name per line
  • Suffix matching pattern: For example, if there is a.com in the list, then a.com, x.a.com, x.x.a.com will all be matched; for example, if there is cn in the list, then x.cn, x.x.cn will all be matched
  • Does not match to resolve with default DNS
  • Match to resolve with bypass DNS
• A bypass CIDR4 list
  • The list is just a txt file, one CIDR per line, each CIDR is actually an IPv4 IP segment
  • Matching mode: It will traverse all CIDR4, if it contains the IP to be requested, it will be matched. Otherwise, it will not be matched
  • No match to go brook proxy
  • matched direct connection
• a bypass CIDR6 list
  • The list is just a txt file, one CIDR per line, each CIDR is actually an IPv6 IP segment
  • Matching mode: It will traverse all CIDR6, if it contains the IP to be requested, it will be matched. Otherwise, it will not be matched
  • No match to go brook proxy
  • matched direct connection
• Bypass switch
  • If disabled, bypass domain name list, bypass CIDR4 list, bypass CIDR6 list will be ignored
• Fake DNS switch
  • If turned on
    • If the domain name does not match the bypass domain name list
      • The domain name will be resolved on the server
    • If the domain name matches the bypass domain name list (Bypass is also enabled)
      • The domain name will be resolved with bypass DNS
• A list of block domains
  • The list is a txt file, one domain name per line
  • Suffix matching pattern: For example, if there is a.com in the list, then a.com, x.a.com, x.x.a.com will all be matched; for example, if there is cn in the list, then x.cn, x.x.cn will all be matched
  • If it matches, block the domain (Block switch is on)
• Block switch

Data Flow

Configure System DNS

Brook client will automatically choose to configure the system v4 DNS or v6 DNS according to the current network IPv4/IPv6 situation and server IPv4/IPv6.

Block block ads

Under normal circumstances, the block domain name list is used to block advertisements, and the second situation is for you to discover.

• If the Block switch is on, if the domain name matches the block domain name list, it will be directly blocked

When Fake DNS is off

We know that a network request generally first queries the domain name to get the IP, and then initiates a request to the IP.

1. An application wants to initiate a network request

2. The first is DNS query IP of domain name

   • The domain name does not match the bypass domain name list

     • Make a query to the default DNS

       • If the default DNS does not match the bypass CIDR list (the default DNS is also an IP)

           Initiate DNS query --(DNS protocol)--> Brook client --(Brook protocol)--> brook server/wsserver/wssserver --(DNS protocol)--> Default DNS
         

       • If the default DNS matches the bypass CIDR list (the default DNS is also an IP)

           Initiate DNS query --(DNS protocol)--> Brook client --(DNS protocol)--> Default DNS
         

   • The domain name matches the bypass domain name list

     • Make a query to bypass DNS

       • If bypass DNS does not match the bypass CIDR list (bypass DNS is also an IP)

           Initiate DNS query --(DNS protocol)--> Brook client --(Brook protocol)--> brook server/wsserver/wssserver --(DNS protocol)--> bypass DNS
         

       • If bypass DNS matches bypass CIDR list (bypass DNS is also an IP)

           Initiate DNS query --(DNS protocol)--> Brook client --(DNS protocol)--> bypass DNS
         

3. The IP of the domain name has been queried, and is ready to initiate a network request to this target IP

   • If IP does not match to bypass CIDR list

       Initiate request --TCP/UDP--> Brook client --(Brook protocol)--> brook server/wsserver/wssserver --TCP/UDP--> target IP
     

   • If the IP matches the bypass CIDR list

       Initiate request --TCP/UDP--> Brook client --TCP/UDP--> target IP
     

When Fake DNS is on

We know that a network request generally first queries the domain name to get the IP, and then initiates a request to the IP.

1. An application wants to initiate a network request

2. The first is query the IP of the domain name

   • The domain name does not match the bypass domain name list
     • Return Fake IP by Fake DNS

   • The domain name matches the bypass domain name list

     • Make a query to bypass DNS

       • If bypass DNS does not match the bypass CIDR list (bypass DNS is also an IP)

           Initiate DNS query --(DNS protocol)--> Brook client --(Brook protocol)--> brook server/wsserver/wssserver --(DNS protocol)--> bypass DNS
         

       • If bypass DNS matches bypass CIDR list (bypass DNS is also an IP)

           Initiate DNS query --(DNS protocol)--> Brook client --(DNS protocol)--> bypass DNS
         

3. The IP of the domain name has been queried, and is ready to initiate a network request to this target IP

   • If it is Fake IP (the resovle of the domain name will be completed on the server)

       Brook client --(convert Fake IP to original domain name)--(Brook protocol)--> brook server/wsserver/wssserver --TCP/UDP--> DST
     

   • If not Fake IP

     • If IP does not match to bypass CIDR list

         Initiate a request --TCP/UDP--> Brook client --(Brook protocol)--> brook server/wsserver/wssserver --TCP/UDP--> target IP
       

     • If the IP matches the bypass CIDR list

         Initiate request --TCP/UDP--> Brook client --TCP/UDP--> target IP
       

Brook GUI Client Import Server List

• The list is a txt file, one brook link per line
• Support brook server/wsserver/wssserver/socks5

Why and How to Turn Off System and Browser Secure DNS

At present, the Android system has built-in Private DNS (DoT), and the desktop and mobile versions of Chrome provide built-in Secure DNS (DoH). This is ideal for the full-scale Anycast network world and the DNS query of ordinary users without proxy can be encrypted in the intermediate network. But Reality is not ideal.

Suppose a domain name provides different IPs for multiple regions, and the final resolved IP depends on:

1. DNS Server
2. The network that initiated the DNS query

When DoT or DoH is turned on, the query content cannot be intercepted to achieve the effect of using different DNS resolutions for different domain names, and FakeDNS cannot be used to resolve domain names on the server side to avoid one more network request.

So we're going to close it:

• Android: Settings -> Network & internet -> Private DNS -> Off
• Chrome on Mobile: Settings -> Privacy and security -> Use secure DNS -> Off
• Chrome on Desktop: Settings -> Privacy and security -> Security -> Use secure DNS -> Off
• Windows: Windows Settings -> Network & Internet -> Your Network -> DNS settings -> Edit -> Preferred DNS -> Unencrypted only -> 8.8.8.8

Will closing it reduce security?

You can enable FakeDNS or configure DoH in Brook GUI.

MITM

Note: This feature requires programming skills and will run your script to intercept and modify HTTP and HTTPS. At the same time, if the writing is complex, it may take up more resources and performance.

ROOT CA

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

To perform MITM

• The ROOT CA above must be installed
• FakeDNS must be enabled

macOS

MITM requires tun mode

nami install mad ca.txthinking
sudo mad install --ca ~/.nami/bin/ca.pem

Windows

MITM requires tun mode

nami install mad ca.txthinking

Open GitBash as administrator

mad install --ca ~/.nami/bin/ca.pem

iOS

https://www.youtube.com/watch?v=uctNsfl3lio

Android

Android has system CA and user CA, which must be installed into the system CA after ROOT

Rule

One protocol and address per line

• Protocols support http:// and https://
• The address is the host and port, do not include the path
• Do not include the domain name in the bypass list

Example

http://ipip.ooo:80
https://ipip.ooo:443

Suffix matches mode: ipip.ooo:80, xxx.ipip.ooo:80, xxx.xxx.ipip.ooo:80 ..., ipip.ooo:443, xxx.ipip.ooo:443, xxx.xxx.ipip.ooo:443 ...

https://txthinking.github.io/bypass/mitm.txt

Script

• tengo
• Builtin Functions
• Standard Library

request

request Represents an HTTP Request, which is a map

{
	"Method": "GET", // string, request method
	"URL": "https://ipip.ooo/", // string, request url
	"Body": bytes, // bytes, request body
	"...": "...",
	"User-Agent": "...", // string, all other keys are request header
	"...": "..."
}

response

response Represents an HTTP Rsponse, which is a map

{
	"StatusCode": 200, // int, response status code
	"Body": bytes, // bytes, request body
	"...": "...",
	"Server": "txthinking", // string, all other keys are response header
	"...": "..."
}

How it works

1. Brook first matches the rule address, and then prepares data according to the protocol corresponding to the address in the rule
2. Brook passes request to the script, and response is now undefined. The script can choose:
   • Modify or not modify request and return request
   • Returns a new response. End.
3. Brook sends the request returned by the script to the server
4. Brook gets the response from the server
5. Brook passes response to the script, request is now the request of the step 1 returned, the script must: modify or not modify response and return response

MITM with Body

If off

• request["Body"] passed to script in step 2 is empty
  • The request["Body"] returned by the script will be ignored. The body of the original request is still used to send to the server
  • Or response["Body"] will also be ignored. Only respond to client with StatusCode and headers
• The response["Body"] and request["Body"] passed to the script in step 5 are empty. The response["Body"] returned by the script will also be ignored. The body of the original response is still used to respond to the client

If on

• request["Body"] passed to the script in step 2 is not empty
  • The request["Body"] returned by the script is sent to the server as the body of the request
  • Or response["Body"] is sent to the client as the body of the response
• The response["Body"] and request["Body"] passed to the script in step 5 are not empty. The response["Body"] returned by the script will be sent to the client as the body of the response

Example

text := import("text")
_ := (func(request, response) {

    // Begin
    if(!response){
        if(text.has_prefix(request["URL"], "http://ipip.ooo")){
            return {
                "StatusCode": 301,
                "Location": text.replace(request["URL"], "http://", "https://", 1)
            }
        }
        if(text.has_prefix(request["URL"], "https://ipip.ooo")){
            request["User-Agent"] = "curl/7.79.1"
            return request
        }
        return request
    }
    return response
    // End

})(request, response)

Debugging

You can use mitmproxy helper and Wireshark Helper to capture packets to determine what to modify. The difference of mobile phone packet capture software

You can use tun2brook to debug the script, so you can print data inside the script

Log

macOS and Windows need to enable tun mode

It is recommended to enable it only when necessary. Prevent the log file from being too large.

Apple push problem

To use Apple Push Notification Service (APNs), your macOS, iOS, tvOS, and watchOS devices need a persistent connection to Apple's servers over Ethernet, cellular data (if capable), or Wi-Fi.

https://support.apple.com/en-us/HT210060

https://support.apple.com/en-us/HT210060

Domain

apple.com
icloud.com
cdn-apple.com
mzstatic.com
entrust.net
digicert.com
verisign.net

CIDR4

17.0.0.0/8
103.81.148.0/22
103.81.148.0/24
103.81.149.0/24

CIDR6

2620:149:a44::/48
2403:300:a42::/48
2403:300:a51::/48
2a01:b740:a42::/48

Windows IPv6 tun mode

If your Windows supports IPv6. If something wrong, turn off IPv6 networking. reboot

Resources

• https://talks.txthinking.com
• https://www.youtube.com/txthinking
• https://txthinking.github.io/brook/
• https://github.com/txthinking/brook
• https://github.com/txthinking/brook/discussions
• https://github.com/txthinking/bypass
• https://t.me/brookgroup
• https://t.me/txthinking_news
• https://ipip.ooo
• https://chrome.google.com/webstore/detail/hnpgnjkeaobghpjjhaiemlahikgmnghb
• https://chrome.google.com/webstore/detail/ipvbar/copjmgogifdfjkaenpallapiidcpkjbm
• https://github.com/txthinking/joker
• https://github.com/txthinking/jinbe
• https://github.com/txthinking/nico
• https://github.com/txthinking
• https://www.txthinking.com