# Install and pair CatBridge

> How to download CatBridge for Windows or Linux, start the service, pair your phone with the 24-digit numeric code, use the flags and revoke devices safely.

- Language: en
- Canonical URL: https://netcattest.com/catsuite/en/docs/catbridge/install
- Section: CatBridge
- Updated: 2026-10-06
- Other language (pt-BR): https://netcattest.com/catsuite/docs/catbridge/instalar

**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](https://netcattest.com/catsuite/en/docs/catbridge).

> [!IMPORTANT]
> Use CatBridge only on targets you own or are authorized to test. The connector does not change your firewall, does not install tools and grants no access to arbitrary commands.

## 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:

| System | Download |
|---|---|
| Windows 64-bit | [catbridge-windows-amd64.zip](https://github.com/netcattest/catsuite/releases/download/tools-1.2.0/catbridge-windows-amd64.zip) |
| Linux 64-bit | [catbridge-linux-amd64.tar.gz](https://github.com/netcattest/catsuite/releases/download/tools-1.2.0/catbridge-linux-amd64.tar.gz) |
| Checksums | [SHA256SUMS.txt](https://github.com/netcattest/catsuite/releases/download/tools-1.2.0/SHA256SUMS.txt) |
| Source code | [catbridge folder on GitHub](https://github.com/netcattest/catsuite/tree/main/catbridge) |

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`.

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

```bash
sha256sum -c --ignore-missing SHA256SUMS.txt
```

> [!WARNING]
> Download only from the official address `github.com/netcattest/catsuite`. If the hash does not match, delete the file and download it again: a tampered executable can compromise your computer and your lab.

### 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.

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

```bash
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.

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

```bash
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:

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

```bash
./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:

```text
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

| Option | Default | What it does |
|---|---|---|
| `-state` | the user's default `CatBridge` folder | Identity folder. Use the **same folder** in every command. |
| `-listen` | `127.0.0.1:8743` | Local address and port the service listens on. Use `0.0.0.0:8743` or the local network IP to accept the phone. |
| `-public` | `https://127.0.0.1:8743` | Address the **phone** uses to reach the Bridge. It is stored in the identity. |
| `-scope` | empty | Allowed destinations, separated by commas. The device scope and the connector scope are **intersected**. |
| `-nuclei` | empty | Absolute path to the Nuclei executable. |
| `-templates` | empty | Manifest of the reviewed Nuclei templates. |
| `-tool-lock` | empty | Signed manifest of the prepared executors. |
| `-tool-key` | empty | Fingerprint of the key that signed the executor manifest. |
| `-docker-host` | empty | Docker endpoint defined by the administrator. |
| `-runtime-network` | `bridge` | Egress network of the executors' network broker. |
| `-upstream-ca` | empty | Additional trusted CA for the broker. |
| `-device` | empty | Device identifier, used by the `revoke` command. |
| `-lang` | `pt-BR` | Language of the terminal messages: `pt-BR` or `en`. |

> [!NOTE]
> With the default `-listen 127.0.0.1:8743`, the service only accepts connections from the computer itself. To pair a phone on the network, pass `0.0.0.0:8743` or the local IP and open the port in your firewall; CatBridge does not change the firewall.

## 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:

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

```bash
./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:

```powershell
.\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](https://netcattest.com/catsuite/en/docs/workflows), when the extension declares `connector.run`. The code example is in [CatBridge, the optional connector](https://netcattest.com/catsuite/en/docs/catbridge) and the full catalog in [Capabilities and tools](https://netcattest.com/catsuite/en/docs/catbridge/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:

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

```bash
./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:

```bash
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`:

```powershell
.\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](https://netcattest.com/catsuite/en/docs/catbridge/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

| Item | Status |
|---|---|
| Numeric pairing | Requires CatSuite 1.3.7+100 or later. The Bridge only generates new numeric codes. |
| Existing Protocol 2 connections | Keep working, with no new pairing. |
| Legacy signed pairing data channel | Remains compatible. |
| SDK | SDK 1.3 capabilities and the SDK 1.4 ecosystem adapters. |
| Protocol 1 | Not accepted. |

## 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](https://netcattest.com/catsuite/en/docs/catbridge/tools)
- [Visual workflows](https://netcattest.com/catsuite/en/docs/workflows)
- [Downloads and SDK](https://netcattest.com/catsuite/en/docs/downloads)