Brook GUI Documentation

https://www.txthinking.com/talks/
Updated at: 2023-04-01
cloud@txthinking.com

Table of Contents

• Software for which this article applies
• Intel Mac GUI proxy mode, Windows GUI proxy mode, Linux GUI proxy mode
• iOS/M1 Mac GUI, Android GUI, Intel Mac GUI tun mode, Windows GUI tun mode, Linux GUI tun mode
• Configuration Introduction
• Programmable
  • Introduction to incoming variables
  • in_guiconfig
  • in_dnsquery
  • in_address
  • in_httprequest
  • in_httpresponse
  • How to write Tengo script
  • How to debug script
• Why and How to Turn Off System and Browser Security DNS
• Install CA
  • iOS
  • Android
  • macOS
  • Windows
• Apple Push Problem
• Other resources

Software for which this article applies

• Brook
• Brook Plus
• Shiliew
• tun2brook

Intel Mac GUI proxy mode, Windows GUI proxy mode, Linux GUI proxy mode

This mode is very simple, will create:

• Socks5 proxy: socks5://[::1]:1080 or socks5://127.0.0.1:1080
• HTTP proxy: http://[::1]:8010 or http://127.0.0.1:8010
• PAC: http://127.0.0.1:1093/proxy.pac or http://[::1]:1093/proxy.pac based on Bypass Domain list
• Intel Mac GUI, Windows GUI set PAC to system proxy。Linux GUI can work with Socks5 Configurator
• What is socks5 and http proxy? Article and Video

iOS/M1 Mac GUI, Android GUI, Intel Mac GUI tun mode, Windows GUI tun mode, Linux GUI tun mode

The so-called Internet connection is IP to IP connection, not domain name connection. Therefore, the domain name will be resolved into IP before deciding how to connect.

Configuration Introduction

Programmable

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

Take full control of your own network

• Like turning off IPv6 by blocking AAAA
• Block system/browser built-in secure DNS
• Override DST
• Flexible and finer rules
• Directly bypass the domain name regardless of whether the resolved IP is in Bypass
• MITM decrypt HTTPS
• Packet capture
• Packet modify
• Disable HTTP3
• more and more...

Introduction to incoming variables

in_guiconfig

out, if it is error type will be recorded in the log. Ignored if not of type map, if it is map then explicitly specify each configuration item.

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

in_httprequest

out, must be set to a request or response

in_httpresponse

out, must be set to a response

How to write Tengo script

Tengo Language Syntax

Library

• text: regular expressions, string conversion, and manipulation
• math: mathematical constants and functions
• times: time-related functions
• rand: random functions
• fmt: formatting functions
• json: JSON functions
• enum: Enumeration functions
• hex: hex encoding and decoding functions
• base64: base64 encoding and decoding functions

• brook: brook module

  Constants
  
  * os: string, linux/darwin/windows/ios/android. If ios app run on mac, it is ios
  * iosapponmac: bool, ios app run on mac
  
  Functions
  
  * splithostport(address string) => map/error: splits a network address of the form "host:port" to { "host": "xxx", "port": "xxx" }
  * country(ip string) => string/error: get country code from ip
  * cidrcontainsip(cidr string, ip string) => bool/error: reports whether the network includes ip
  * parseurl(url string) => map/error: parses a raw url into a map, keys: scheme/host/path/rawpath/rawquery
  * parsequery(query string) => map/error: parses a raw query into a kv map
  * map2query(kv map) => string/error: convert map{string:string} into a query string
  * bytes2ints(b bytes) => array/error: convert bytes into [int]
  * ints2bytes(ints array) => bytes/error: convert [int] into bytes
  * bytescompare(a bytes, b bytes) => int/error: returns an integer comparing two bytes lexicographically. The result will be 0 if a == b, -1 if a < b, and +1 if a > b
  * bytescontains(b bytes, sub bytes) => bool/error: reports whether sub is within b
  * byteshasprefix(s bytes, prefix bytes) => bool/error: tests whether the bytes s begins with prefix
  * byteshassuffix(s bytes, suffix bytes) => bool/error: tests whether the bytes s ends with suffix
  * bytesindex(s bytes, sep bytes) => int/error: returns the index of the first instance of sep in s, or -1 if sep is not present in s
  * byteslastindex(s bytes, sep bytes) => int/error: returns the index of the last instance of sep in s, or -1 if sep is not present in s
  * bytesreplace(s bytes, old bytes, new bytes, n int) => bytes/error: returns a copy of the s with the first n non-overlapping instances of old replaced by new. If n < 0, there is no limit on the number of replacements
  * pathescape(s string) => string/error: escapes the string so it can be safely placed inside a URL path segment, replacing special characters (including /) with %XX sequences as needed
  * pathunescape(s string) => string/error: does the inverse transformation of pathescape
  * queryescape(s string) => string/error: escapes the string so it can be safely placed inside a URL query
  * queryunescape(s string) => string/error: does the inverse transformation of queryescape
  * hexdecode(s string) => bytes/error: returns the bytes represented by the hexadecimal string s
  * hexencode(s string) => string/error: returns the hexadecimal encoding of src
  

Example

https://github.com/txthinking/bypass/blob/master/example_script.tengo

How to debug script

• It is recommended to use tun2brook on desktop to debug with print
• It is recommended to use mitmproxy helper and Wireshark Helper to capture packets to determine what to modify

Why and How to Turn Off System and Browser Security DNS

Because if Security DNS is turned on, the Fake DNS will not work. So we have to turn it off:

• 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

Other systems and software, please find out whether it exists and how to close it

Install CA

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

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

Open GitBash

nami install mad ca.txthinking

Then open GitBash with admin

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

Note that software such as GitBash or Firefox may not read the system CA, you can use the system Edge browser to test after installation

Apple Push Problem

To receive push, Apple Server only allows Ethernet, cellular data, Wi-Fi connections. So you need to Bypass the relevant domain name and IP. Reference link

Other resources

• Brook Documentation
• Brook GitHub
• TxThinking Talks
• TxThinking YouTube
• TxThinking News
• Telegram