# Instalar e parear o CatBridge

> Como baixar o CatBridge para Windows ou Linux, iniciar o serviço, parear o celular com o código numérico de 24 dígitos e revogar aparelhos com segurança.

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

O **CatBridge** é um programa portátil que roda no **seu** computador ou servidor e conecta o CatSuite às ferramentas de linha de comando que você autorizar. O aplicativo funciona sem ele; não há conta, loja nem servidor administrado pelo CatSuite. Você baixa o conector, escolhe o escopo e pareia cada celular com um **código numérico de 24 dígitos**, sem QR Code. Veja a visão geral em [CatBridge, o conector opcional](https://netcattest.com/catsuite/docs/catbridge).

> [!IMPORTANTE]
> Use o CatBridge apenas em alvos que você possui ou está autorizado a testar. O conector não altera o firewall, não instala ferramentas e não concede acesso a comandos arbitrários.

## Antes de começar

- Uma versão do CatSuite com o **pareamento numérico** (CatSuite 1.3.7+100 ou posterior), com o módulo de extensões ativado.
- Um computador alcançável pelo celular na **mesma rede** ou em uma rede privada configurada por você.
- Para usar a distribuição pronta, **não é preciso Go**. O Go 1.26 ou superior só é necessário para compilar a partir do código.
- Ferramentas externas são opcionais: o CatBridge **inicia sem nenhuma ferramenta**. Nesse estado, o pareamento e a consulta de capacidades funcionam, e os executores ausentes aparecem como indisponíveis.

## 1. Baixe o CatBridge

O CatBridge é distribuído pronto para uso, como pacote portátil, no repositório oficial do CatSuite:

| 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 pacote inclui o executável, instruções nos dois idiomas, as licenças, o catálogo de contratos das capacidades, exemplos de templates e os scripts de preparação dos executores.

### Confira a integridade

Antes de executar, compare o SHA-256 do arquivo baixado com o valor publicado em `SHA256SUMS.txt`.

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

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

> [!AVISO]
> Baixe somente do endereço oficial `github.com/netcattest/catsuite`. Se o hash não bater, apague o arquivo e baixe de novo: um executável alterado pode comprometer o seu computador e o seu laboratório.

### Extraia e abra a pasta

No Windows, o pacote extrai a pasta `CatBridge` com o executável `catbridge.exe`. No Linux, a pasta `catbridge` com o executável `catbridge`.

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

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

### Compilar a partir do código (opcional)

Se preferir compilar, clone o repositório e gere o executável dentro da pasta `catbridge`. Requer Go 1.26 ou superior.

```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. Inicie o serviço

Escolha o endereço local do computador que o celular consegue alcançar e inicie o serviço com o comando `serve`:

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

```bash
./catbridge serve -state ./private-state -listen 0.0.0.0:8743 -public https://192.168.1.20:8743
```

Troque `192.168.1.20` pelo IP do seu computador. Na primeira execução, a pasta de identidade e os certificados são criados localmente. Um bloqueio do sistema impede dois servidores de usarem a mesma pasta ao mesmo tempo.

Ao iniciar, o terminal mostra o endereço e o código de pareamento em seis grupos de quatro números:

```text
Endereço: https://192.168.1.20:8743
Código de pareamento: 4821 0937 5512 6604 1879 3346
Abra Extensões > Conexões > Parear CatBridge. O código expira em dois minutos e funciona uma vez.
```

### Opções da linha de comando

| Opção | Padrão | O que faz |
|---|---|---|
| `-state` | pasta `CatBridge` padrão do usuário | Pasta de identidade. Use a **mesma pasta** em todos os comandos. |
| `-listen` | `127.0.0.1:8743` | Endereço e porta locais em que o serviço escuta. Use `0.0.0.0:8743` ou o IP da rede local para aceitar o celular. |
| `-public` | `https://127.0.0.1:8743` | Endereço que o **celular** usa para chegar ao Bridge. Fica gravado na identidade. |
| `-scope` | vazio | Destinos permitidos, separados por vírgula. O escopo do aparelho e o do conector são **intersectados**. |
| `-nuclei` | vazio | Caminho absoluto do executável do Nuclei. |
| `-templates` | vazio | Manifesto dos templates revisados do Nuclei. |
| `-tool-lock` | vazio | Manifesto assinado dos executores preparados. |
| `-tool-key` | vazio | Impressão digital da chave que assinou o manifesto dos executores. |
| `-docker-host` | vazio | Endpoint Docker definido pelo administrador. |
| `-runtime-network` | `bridge` | Rede de saída do intermediário de rede dos executores. |
| `-upstream-ca` | vazio | CA adicional confiável para o intermediário. |
| `-device` | vazio | Identificador do aparelho, usado pelo comando `revoke`. |
| `-lang` | `pt-BR` | Idioma das mensagens do terminal: `pt-BR` ou `en`. |

> [!NOTA]
> Com o padrão `-listen 127.0.0.1:8743`, o serviço só aceita conexões do próprio computador. Para parear um celular na rede, informe `0.0.0.0:8743` ou o IP local e libere a porta no seu firewall; o CatBridge não altera o firewall.

## 3. Pareie o celular

1. No CatSuite, ative o módulo de extensões em **Configurações → Extensões**.
2. Abra **Extensões → Conexões → Parear CatBridge**.
3. Informe o **endereço** exibido no terminal, por exemplo `https://192.168.1.20:8743`.
4. Cole ou digite o **código de 24 números**. Os espaços entre os grupos são aceitos.
5. Confirme. O aplicativo instala a conexão e emite o certificado do aparelho.

Não é necessário QR Code, conta ou serviço de terceiros.

### Como o pareamento protege a conexão

- O código é gerado de forma **criptograficamente aleatória**, vale por **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** na conexão instalada.
- Uma tentativa com código errado **não instala** a conexão.
- O Bridge limita as tentativas: **16 por endereço IP e 128 no total a cada janela de 60 segundos**. Acima disso, responde com o erro `E_PAIRING_RATE`.

Depois do pareamento, cada operação usa mTLS: o aparelho apresenta o certificado emitido pela CA local, e o Android valida hostname, validade e o **pin** do certificado do servidor.

### Gerar um novo código

O código expira em dois minutos. Para gerar outro sem parar o servidor, abra **outro terminal** na mesma pasta e use o comando `pair` com a mesma pasta de identidade e o mesmo endereço:

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

```bash
./catbridge pair -state ./private-state -public https://192.168.1.20:8743
```

### Parear o emulador Android

O emulador padrão do Android acessa o computador pelo endereço `10.0.2.2`. Use uma pasta de identidade separada para ele:

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

### Mudar o endereço do Bridge

Mantenha `-public` igual ao endereço que o aparelho usa: a identidade do Bridge contém esse endereço. Se precisar mudar o hostname ou o IP público, use uma **nova pasta de identidade** e faça um novo pareamento.

## 4. Use em um fluxo

Com o aparelho pareado, abra **Extensões → Conexões** para ver o estado da conexão e as capacidades disponíveis. As capacidades só executam dentro de uma [etapa de fluxo](https://netcattest.com/catsuite/docs/fluxos) aprovada, quando a extensão declara `connector.run`. O código de exemplo está em [CatBridge, o conector opcional](https://netcattest.com/catsuite/docs/catbridge) e o catálogo completo em [Capacidades e ferramentas](https://netcattest.com/catsuite/docs/catbridge/ferramentas).

## Revogar um aparelho

Remover a conexão no aplicativo revoga o certificado quando o Bridge está alcançável e sempre apaga a chave local. Para revogar um aparelho desconectado, use o comando `revoke` no computador:

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

```bash
./catbridge revoke -state ./private-state -public https://192.168.1.20:8743 -device IDENTIFICADOR_DO_APARELHO
```

A revogação no servidor bloqueia aquele aparelho imediatamente nas próximas operações.

## Executores Linux (opcional)

As ferramentas `http.probe`, `web.crawl` e `api.schema.test` e os adaptadores do ecossistema rodam em containers Linux, atrás de um intermediário de rede. Use **Docker Desktop com engine Linux** no Windows ou **Docker Engine** em um servidor Linux seu. Apenas o supervisor confiável acessa o Docker; os containers não recebem o socket do Docker, pastas gerais nem a rede do host.

A preparação é uma operação administrativa do host, feita por você e nunca pelo aplicativo. Ela exige Docker com engine Linux, Python 3.12 ou superior e a biblioteca `cryptography`. O script já vem na pasta `runtime` do pacote:

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

A preparação verifica os checksums oficiais das ferramentas, fixa a imagem base por digest, gera as dependências com hashes e faz a instalação offline. Depois, inicie o serviço com o manifesto assinado e a impressão digital gravada em `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.exemplo.test -tool-lock .\runtime\prepared\tools.lock.json -tool-key IMPRESSAO_DIGITAL
```

As aprovações usam **digests**, não tags mutáveis. Qualquer mudança nas imagens, no binário ou no supervisor gera uma nova identidade e exige revisar as aprovações afetadas. Para o Nuclei local, adicione `-nuclei` com o caminho absoluto e `-templates` com o manifesto revisado (veja [Capacidades e ferramentas](https://netcattest.com/catsuite/docs/catbridge/ferramentas)).

## Proteja a identidade

- A chave do aparelho fica no **Android Keystore**; a chave do servidor, na **pasta de identidade** do computador.
- O estado local do CatBridge é criptografado com **AES-256-GCM**. Dê acesso à pasta de identidade apenas ao usuário responsável.
- Mantenha a pasta de estado, chaves, certificados, códigos e logs em local privado e restrinja o acesso ao servidor à rede necessária.
- Credenciais de APIs e pareamentos **não** entram em backups portáteis.

## Compatibilidade

| Item | Situação |
|---|---|
| Pareamento numérico | Requer CatSuite 1.3.7+100 ou posterior. O Bridge gera apenas códigos numéricos novos. |
| Conexões existentes do Protocol 2 | Continuam funcionando, sem novo pareamento. |
| Canal legado de dados de pareamento assinados | Permanece compatível. |
| SDK | Capacidades do SDK 1.3 e adaptadores do ecossistema do SDK 1.4. |
| Protocol 1 | Não é aceito. |

## Problemas comuns

**O código expirou.** Cada código vale dois minutos. Gere outro com o comando `pair` em um segundo terminal, sem parar o servidor.

**O aplicativo informa `E_PAIRING_RATE`.** Houve tentativas demais em pouco tempo. Aguarde um minuto e tente de novo com um código novo.

**O celular não alcança o Bridge.** Confira se `-listen` não está em `127.0.0.1`, se os dois aparelhos estão na mesma rede e se a porta está liberada no firewall.

**Mudei o IP do computador.** A identidade guarda o endereço de `-public`. Use uma nova pasta de identidade e pareie de novo.

**As capacidades aparecem como indisponíveis.** O Bridge iniciou sem ferramentas. Prepare os executores ou informe o Nuclei e os templates revisados.

## Próximo passo

- [Capacidades e ferramentas](https://netcattest.com/catsuite/docs/catbridge/ferramentas)
- [Fluxos visuais](https://netcattest.com/catsuite/docs/fluxos)
- [Downloads e SDK](https://netcattest.com/catsuite/docs/downloads)