Install and pair CatBridge

CatBridge is a portable program that runs on your computer or server and connects CatSuite to the command-line tools you authorize. The app works without it; there is no account, store or server operated by CatSuite. You download the connector, choose the scope and pair each phone with a 24-digit numeric code, with no QR Code. See the overview in CatBridge, the optional connector.

Before you start #

• A CatSuite version with numeric pairing (CatSuite 1.3.7+100 or later), with the extension module enabled.
• A computer reachable by the phone on the same network or on a private network you configure.
• The ready-made distribution does not require Go. Go 1.26 or later is only needed to build from source.
• External tools are optional: CatBridge starts without any tool. In that state, pairing and the capability query work, and missing executors show up as unavailable.

1. Download CatBridge #

CatBridge is distributed ready to use, as a portable package, in the official CatSuite repository:

The package includes the executable, instructions in both languages, the licenses, the capability contract catalog, template examples and the executor preparation scripts.

Check the integrity #

Before running it, compare the SHA-256 of the downloaded file with the value published in SHA256SUMS.txt.

Get-FileHash .\catbridge-windows-amd64.zip -Algorithm SHA256

sha256sum -c --ignore-missing SHA256SUMS.txt

Extract and open the folder #

On Windows, the package extracts a CatBridge folder with the catbridge.exe executable. On Linux, a catbridge folder with the catbridge executable.

Expand-Archive .\catbridge-windows-amd64.zip -DestinationPath .
Set-Location .\CatBridge

tar -xzf catbridge-linux-amd64.tar.gz
cd catbridge

Build from source (optional) #

If you prefer to build it, clone the repository and generate the executable inside the catbridge folder. It requires Go 1.26 or later.

git clone https://github.com/netcattest/catsuite.git
Set-Location .\catsuite\catbridge
go build -buildvcs=false -trimpath -ldflags="-s -w" -o catbridge.exe .

git clone https://github.com/netcattest/catsuite.git
cd catsuite/catbridge
go build -buildvcs=false -trimpath -ldflags="-s -w" -o catbridge .

2. Start the service #

Choose your computer's local address that the phone can reach and start the service with the serve command:

.\catbridge.exe serve -state .\private-state -listen 0.0.0.0:8743 -public https://192.168.1.20:8743 -lang en

./catbridge serve -state ./private-state -listen 0.0.0.0:8743 -public https://192.168.1.20:8743 -lang en

Replace 192.168.1.20 with your computer's IP. On the first run, the identity folder and certificates are created locally. A system lock prevents two servers from using the same folder at once. The -lang en option shows the terminal messages in English.

On start, the terminal shows the address and the pairing code in six groups of four digits:

Address: https://192.168.1.20:8743
Pairing code: 4821 0937 5512 6604 1879 3346
Open Extensions > Connections > Pair CatBridge. The code expires in two minutes and works once.

Command-line options #

3. Pair the phone #

1. In CatSuite, enable the extension module in Settings → Extensions.
2. Open Extensions → Connections → Pair CatBridge.
3. Enter the address shown in the terminal, for example https://192.168.1.20:8743.
4. Paste or type the 24-digit code. Spaces between the groups are accepted.
5. Confirm. The app installs the connection and issues the device certificate.

No QR Code, account or third-party service is needed.

How pairing protects the connection #

• The code is cryptographically random, lasts two minutes and pairs a single device.
• The app authenticates the Bridge identity first, and only then sends the code through the authenticated HTTPS channel.
• The code is not retained with the installed connection.
• An incorrect code cannot install a connection.
• The Bridge limits attempts: 16 per IP address and 128 in total per 60-second window. Beyond that, it answers with the E_PAIRING_RATE error.

After pairing, every operation uses mTLS: the device presents the certificate issued by the local CA, and Android validates the hostname, validity and pin of the server certificate.

Generate a new code #

The code expires in two minutes. To generate another one without stopping the server, open another terminal in the same folder and run the pair command with the same identity folder and address:

.\catbridge.exe pair -state .\private-state -public https://192.168.1.20:8743 -lang en

./catbridge pair -state ./private-state -public https://192.168.1.20:8743 -lang en

Pair the Android emulator #

The standard Android emulator reaches the computer at 10.0.2.2. Use a separate identity folder for it:

.\catbridge.exe serve -state .\private-emulator -listen 127.0.0.1:8743 -public https://10.0.2.2:8743 -lang en

Change the Bridge address #

Keep -public equal to the address the device uses: the Bridge identity contains that address. If you need to change the hostname or the public IP, use a new identity folder and pair again.

4. Use it in a workflow #

With the device paired, open Extensions → Connections to see the connection state and the available capabilities. Capabilities only run inside an approved workflow step, when the extension declares connector.run. The code example is in CatBridge, the optional connector and the full catalog in Capabilities and tools.

Revoke a device #

Removing the connection in the app revokes the certificate when the Bridge is reachable and always deletes the local key. To revoke a disconnected device, use the revoke command on the computer:

.\catbridge.exe revoke -state .\private-state -public https://192.168.1.20:8743 -device DEVICE_IDENTIFIER

./catbridge revoke -state ./private-state -public https://192.168.1.20:8743 -device DEVICE_IDENTIFIER

Server-side revocation blocks that device immediately on the next operations.

Linux executors (optional) #

The http.probe, web.crawl and api.schema.test tools and the ecosystem adapters run in Linux containers, behind a network broker. Use Docker Desktop with the Linux engine on Windows or Docker Engine on a Linux server of yours. Only the trusted supervisor touches Docker; the containers get no Docker socket, no general folders and no host network.

Preparation is an administrative host operation, done by you and never by the app. It requires Docker with the Linux engine, Python 3.12 or later and the cryptography library. The script already ships in the package's runtime folder:

python runtime/prepare.py --output runtime/prepared --go go --docker docker

Preparation verifies the official tool checksums, pins the base image by digest, generates dependencies with hashes and installs offline. Then start the service with the signed manifest and the fingerprint stored in runtime/prepared/author.sha256:

.\catbridge.exe serve -state .\private-state -listen 0.0.0.0:8743 -public https://192.168.1.20:8743 -scope https://api.example.test -tool-lock .\runtime\prepared\tools.lock.json -tool-key FINGERPRINT

Approvals use digests, not mutable tags. Any change to the images, the binary or the supervisor produces a new identity and requires reviewing the affected approvals. For local Nuclei, add -nuclei with the absolute path and -templates with the reviewed manifest (see Capabilities and tools).

Protect the identity #

• The device key lives in the Android Keystore; the server key lives in the computer's identity folder.
• CatBridge local state is encrypted with AES-256-GCM. Grant access to the identity folder only to the responsible user.
• Keep the state folder, keys, certificates, codes and logs in a private location and restrict server access to the network you need.
• API credentials and pairings are excluded from portable backups.

Compatibility #

Common problems #

The code expired. Each code lasts two minutes. Generate another with the pair command in a second terminal, without stopping the server.

The app reports E_PAIRING_RATE. There were too many attempts in a short time. Wait a minute and try again with a new code.

The phone cannot reach the Bridge. Check that -listen is not 127.0.0.1, that both devices are on the same network and that the port is open in the firewall.

I changed the computer's IP. The identity stores the -public address. Use a new identity folder and pair again.

Capabilities show up as unavailable. The Bridge started without tools. Prepare the executors or provide Nuclei and the reviewed templates.

Next step #

• Capabilities and tools
• Visual workflows
• Downloads and SDK