CatBridge, the optional connector

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. The app works without it; there is no account, store or server operated by CatSuite.

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

How to get it #

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

The steps to download, start and pair it are in Install and pair CatBridge.

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 #

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:

Only available allows execution. The full catalog is in Capabilities and tools.

Protocol 2 #

Every message, including errors, uses the restricted HTTP Message Signatures profile (RFC 9421) with ECDSA P-256 and SHA-256, plus Content-Digest (RFC 9530).

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

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.

Next step #

• Install and pair CatBridge
• Capabilities and tools
• Visual workflows