# CatBridge, o conector opcional

> O que é o CatBridge, como baixar para Windows e Linux, como parear com o código numérico, a arquitetura isolada e o Protocol 2 com mensagens assinadas.

- Idioma: pt-BR
- URL canônica: https://netcattest.com/catsuite/docs/catbridge
- Seção: CatBridge
- Atualizado: 2026-10-06
- Outro idioma (en): https://netcattest.com/catsuite/en/docs/catbridge

O **CatBridge** é um conector opcional e portátil, escrito em Go, que roda no **seu** computador ou servidor e executa ferramentas de linha de comando revisadas a pedido de um [fluxo visual](https://netcattest.com/catsuite/docs/fluxos) aprovado. O aplicativo funciona sem ele; não há conta, loja nem servidor administrado pelo CatSuite.

> [!IMPORTANTE]
> A extensão nunca escolhe binários, argumentos, caminhos ou imagens. Ela pede uma **capacidade tipada** (por exemplo `http.probe`) e recebe resultados normalizados. O supervisor do CatBridge monta o comando, valida o escopo e devolve apenas JSON verificado.

## Quando usar

- Você quer reforçar um fluxo com ferramentas consagradas sem sair do CatSuite.
- O alvo é seu ou você tem autorização explícita, e os destinos cabem num escopo fechado.
- Você consegue rodar um processo no computador e deixá-lo acessível ao celular na mesma rede.

Se precisa apenas observar e alterar tráfego, criar abas, salvar dados ou registrar achados, nada disso exige o CatBridge: use a [API do SDK](https://netcattest.com/catsuite/docs/extensoes/api) diretamente.

## Como obter

O CatBridge é distribuído pronto para uso no repositório oficial do CatSuite, sem exigir Go:

| Sistema | Download |
|---|---|
| Windows 64 bits | [catbridge-windows-amd64.zip](https://github.com/netcattest/catsuite/releases/download/tools-1.2.0/catbridge-windows-amd64.zip) |
| Linux 64 bits | [catbridge-linux-amd64.tar.gz](https://github.com/netcattest/catsuite/releases/download/tools-1.2.0/catbridge-linux-amd64.tar.gz) |
| Somas de verificação | [SHA256SUMS.txt](https://github.com/netcattest/catsuite/releases/download/tools-1.2.0/SHA256SUMS.txt) |
| Código-fonte | [Pasta catbridge no GitHub](https://github.com/netcattest/catsuite/tree/main/catbridge) |

O passo a passo para baixar, iniciar e parear está em [Instalar e parear o CatBridge](https://netcattest.com/catsuite/docs/catbridge/instalar).

## Pareamento por código numérico

O pareamento não usa QR Code. Ao iniciar, o CatBridge mostra no terminal o endereço e um **código de 24 números em seis grupos**. No CatSuite, abra **Extensões → Conexões → Parear CatBridge**, informe o endereço e cole ou digite o código.

- O código vale **dois minutos** e autoriza **um único aparelho**.
- O aplicativo verifica a identidade do Bridge **antes** de enviar o código, pelo canal HTTPS autenticado.
- O código não fica salvo, e um código errado não instala a conexão.
- Cada aparelho recebe um certificado próprio, e o TLS do conector é fixado pela impressão digital.

## Arquitetura em camadas

| Camada | Papel |
|---|---|
| Extensão (QuickJS) | Pede uma capacidade tipada dentro de uma etapa de fluxo aprovada. Não recebe socket, shell nem rede. |
| Aplicativo CatSuite | Aprova a revisão, assina a autorização, interseca escopos e valida cada resposta antes de qualquer efeito. |
| Supervisor do CatBridge | Monta o comando tipado, reserva orçamento e controla os executores. Único componente com acesso ao Docker. |
| Intermediário confiável | Único acesso de rede das ferramentas: valida método, caminho, escopo, DNS, redirecionamentos, taxa e TLS. |
| Executor (container) | Roda a ferramenta sem privilégios, com filesystem somente leitura, rede desativada e IPC restrito. |

Redirecionamentos e descobertas **não** ampliam o escopo. O certificado interno da tarefa nunca é apresentado como o certificado do alvo, e o intermediário valida separadamente o TLS do servidor original.

## Catálogo de capacidades

O Bridge publica um catálogo assinado com as capacidades, os executores fixados por versão e hash e o estado de cada uma no seu computador:

| Estado | Significado |
|---|---|
| `available` | Pronta para executar. |
| `not-installed` | O executor ainda não foi preparado neste host. |
| `incompatible` | O executor presente não corresponde ao contrato esperado. |
| `not-authorized` | A capacidade não está autorizada para esta conexão. |
| `unavailable` | Indisponível no momento. |
| `planned` | Prevista, mas não disponível neste Bridge. |

Somente `available` permite execução. O catálogo completo está em [Capacidades e ferramentas](https://netcattest.com/catsuite/docs/catbridge/ferramentas).

## Protocol 2

Todas as mensagens, inclusive erros, usam o perfil restrito de **HTTP Message Signatures** ([RFC 9421](https://www.rfc-editor.org/rfc/rfc9421.html)) com ECDSA P-256 e SHA-256, mais `Content-Digest` ([RFC 9530](https://www.rfc-editor.org/rfc/rfc9530.html)).

- A assinatura cobre método, destino, corpo, identidade, mensagem e o vínculo entre request e response.
- Nonce aleatório e validade de até 60 segundos bloqueiam repetição; o diário do Bridge persiste entre reinícios.
- A assinatura e o digest são verificados **antes** do JSON e de qualquer efeito.
- O Protocol 1 é recusado. Conexões existentes do Protocol 2 continuam funcionando.
- A autorização assinada vincula aparelho, tarefa, Flow ID, revisão, etapa, capacidade, destinos, dados e orçamento. Mudar qualquer item revoga a aprovação.

A chave do aparelho fica no Android Keystore; a chave do servidor, na pasta de identidade do computador. O estado local do Bridge é criptografado com AES-256-GCM.

## Usar em uma etapa

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

Declare `connector.run` e `requiresSdk: "1.3.0"` ou superior no manifesto. A configuração do bloco precisa declarar o mesmo conector, capacidade, ferramenta e parâmetros da chamada. Para interromper uma tarefa, use `cat.connectors.cancel(id)` com o mesmo identificador passado em `run`. IDs idempotentes não repetem tarefas após uma reconexão.

## Continuidade

- Tarefas privadas dependem de uma autorização renovada periodicamente; se ela deixa de ser renovada, a tarefa pausa.
- Ao sair do aplicativo, o CatSuite pausa os fluxos e solicita a pausa das tarefas remotas.
- Depois de um reinício do servidor, uma tarefa de resultado desconhecido fica interrompida e só é repetida com escolha explícita.

## Resultados

Os resultados chegam em páginas assinadas de até 50 registros ou 512 KiB, com recibos verificáveis, versões e hashes do executável. Valores de credenciais e parâmetros reconhecidos como secretos são ocultados.

> [!NOTA]
> Um sinal de ferramenta é evidência para revisão, não prova de exploração. O CatBridge não concede acesso a comandos arbitrários e não atualiza ferramentas automaticamente.

## Próximo passo

- [Instalar e parear o CatBridge](https://netcattest.com/catsuite/docs/catbridge/instalar)
- [Capacidades e ferramentas](https://netcattest.com/catsuite/docs/catbridge/ferramentas)
- [Fluxos visuais](https://netcattest.com/catsuite/docs/fluxos)