Instalar e parear o CatBridge

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.

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:

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.

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

sha256sum -c --ignore-missing SHA256SUMS.txt

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.

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

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.

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

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:

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

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

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 #

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:

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

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

.\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 aprovada, quando a extensão declara connector.run. O código de exemplo está em CatBridge, o conector opcional e o catálogo completo em Capacidades e 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:

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

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

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:

.\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).

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 #

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
• Fluxos visuais
• Downloads e SDK