# CatBridge, the optional connector

> What CatBridge is, how to download it for Windows and Linux, how numeric code pairing works, the isolated architecture and Protocol 2 with signed messages.

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

**CatBridge** is an optional, portable connector written in Go that runs on **your** computer or server and executes reviewed command-line tools on behalf of an approved [visual workflow](https://netcattest.com/catsuite/en/docs/workflows). The app works without it; there is no account, store or server operated by CatSuite.

> [!IMPORTANT]
> An extension never chooses binaries, arguments, paths or images. It asks for a **typed capability** (for example `http.probe`) and receives normalized results. The CatBridge supervisor builds the command, validates the scope and returns only verified JSON.

## When to use it

- You want to strengthen a workflow with well-known tools without leaving CatSuite.
- The target is yours or you have explicit authorization, and the destinations fit a closed scope.
- You can run a process on your computer and make it reachable by the phone on the same network.

If you only need to observe and change traffic, create tabs, save data or record findings, none of that requires CatBridge: use the [SDK API](https://netcattest.com/catsuite/en/docs/extensions/api) directly.

## How to get it

CatBridge is distributed ready to use in the official CatSuite repository, with no Go required:

| 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 steps to download, start and pair it are in [Install and pair CatBridge](https://netcattest.com/catsuite/en/docs/catbridge/install).

## Numeric code pairing

Pairing does not use a QR Code. On start, CatBridge shows the address and a **24-digit code in six groups** in the terminal. In CatSuite, open **Extensions → Connections → Pair CatBridge**, enter the address and paste or type the code.

- The code 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, and an incorrect code cannot install a connection.
- Every device gets its own certificate, and the connector's TLS is pinned by fingerprint.

## Layered architecture

| Layer | Role |
|---|---|
| Extension (QuickJS) | Asks for a typed capability inside an approved workflow step. It gets no socket, shell or network. |
| CatSuite app | Approves the revision, signs the authorization, intersects scopes and validates every response before any effect. |
| CatBridge supervisor | Builds the typed command, reserves the budget and controls the executors. The only component with Docker access. |
| Trusted broker | The tools' only network path: it validates method, path, scope, DNS, redirects, rate and TLS. |
| Executor (container) | Runs the tool unprivileged, with a read-only file system, networking disabled and restricted IPC. |

Redirects and discoveries **do not** broaden the scope. The task's internal certificate is never presented as the target's certificate, and the broker separately validates the original server's TLS.

## Capability catalog

The Bridge publishes a signed catalog with the capabilities, the executors pinned by version and hash, and the state of each one on your computer:

| State | Meaning |
|---|---|
| `available` | Ready to run. |
| `not-installed` | The executor has not been prepared on this host yet. |
| `incompatible` | The executor present does not match the expected contract. |
| `not-authorized` | The capability is not authorized for this connection. |
| `unavailable` | Unavailable right now. |
| `planned` | Expected, but not available on this Bridge. |

Only `available` allows execution. The full catalog is in [Capabilities and tools](https://netcattest.com/catsuite/en/docs/catbridge/tools).

## Protocol 2

Every message, including errors, uses the restricted **HTTP Message Signatures** profile ([RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html)) with ECDSA P-256 and SHA-256, plus `Content-Digest` ([RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html)).

- The signature covers method, target, body, identity, message and the request–response binding.
- A random nonce and a validity of up to 60 seconds block replays; the Bridge journal persists across restarts.
- Signature and digest are verified **before** JSON parsing and before any effect.
- Protocol 1 is rejected. Existing Protocol 2 connections keep working.
- The signed authorization binds device, task, Flow ID, revision, step, capability, targets, data and budget. Changing any item revokes the approval.

The device key lives in the Android Keystore; the server key lives in the computer's identity folder. The Bridge's local state is encrypted with AES-256-GCM.

## Using it in a step

```js
cat.pipeline.registerStep({
  id: 'lab.probe',
  title: {'pt-BR': 'Sondar serviços', en: 'Probe services'},
  inputs: ['endpoint'],
  outputs: ['analysis']
}, async ctx => {
  const catalog = await cat.connectors.capabilities(ctx.config.connector);
  const capability = catalog.catalog.find(item => item.id === 'http.probe');
  if (!capability || capability.state !== 'available') throw new Error('E_CAPABILITY_UNAVAILABLE');
  const result = await cat.connectors.run({
    connector: ctx.config.connector,
    capability: 'http.probe',
    tool: 'httpx',
    id: 'probe-1',
    targets: ctx.inputs.map(item => item.data.url).filter(Boolean),
    parameters: ctx.config.parameters
  });
  ctx.emit('analysis', result);
});
```

Declare `connector.run` and `requiresSdk: "1.3.0"` or later in the manifest. The block configuration must declare the same connector, capability, tool and parameters as the call. To stop a task, use `cat.connectors.cancel(id)` with the same identifier passed to `run`. Idempotent IDs do not repeat tasks after a reconnection.

## Continuity

- Private tasks depend on an authorization that is renewed periodically; if it stops being renewed, the task pauses.
- When you leave the app, CatSuite pauses the workflows and asks the remote tasks to pause.
- After a server restart, a task with an unknown outcome stays interrupted and is only repeated by explicit choice.

## Results

Results arrive in signed pages of up to 50 records or 512 KiB, with verifiable receipts, versions and executable hashes. Credential values and parameters recognized as secret are redacted.

> [!NOTE]
> A tool signal is evidence for review, not proof of exploitation. CatBridge grants no access to arbitrary commands and does not update tools automatically.

## Next step

- [Install and pair CatBridge](https://netcattest.com/catsuite/en/docs/catbridge/install)
- [Capabilities and tools](https://netcattest.com/catsuite/en/docs/catbridge/tools)
- [Visual workflows](https://netcattest.com/catsuite/en/docs/workflows)