Como criar extensões JavaScript .catplug para o CatSuite

Uma extensão do CatSuite é um pacote de código JavaScript, manifesto e recursos que acrescenta capacidades ao laboratório Android. Ela pode observar tráfego, registrar comandos, criar abas e produzir achados usando a API cat, dentro das permissões aprovadas. Para começar, a IDE web permite escrever, validar e simular um projeto com dados fictícios, sem realizar conexões externas.

Guia publicado em 6 de outubro de 2026. A capa é uma ilustração conceitual original, não uma captura do aplicativo nem evidência de teste.

Este tutorial cria um observador pequeno de headers de cache. O objetivo é aprender o ciclo de desenvolvimento, não declarar automaticamente uma vulnerabilidade. Você pode usar a IDE de extensões no navegador ou o CatSuite Studio para VS Code. A visão geral do aplicativo situa esses recursos no restante da suíte.

Extensão, fluxo e conexão são coisas diferentes

Uma extensão não precisa do Bridge para criar uma aba ou analisar uma mensagem já capturada. Da mesma forma, ter uma conexão pareada não dá ao código acesso livre a comandos do computador. O fluxo e as aprovações definem o que pode ser executado.

Comece pela pergunta que o plugin responde

No laboratório Aurora, a API de perfil retorna dados fictícios e um header de cache. Queremos guardar uma observação quando a response declarar a diretiva public. Esse sinal merece revisão no contexto da aplicação: uma configuração pública pode ser adequada a um recurso público e inadequada a outro conteúdo.

O plugin não tentará explorar um cache, enviar requests adicionais ou ler credenciais. Suas permissões serão apenas observar tráfego, criar uma aba explicativa e registrar achados. Essa delimitação ajuda a entender o comportamento antes de adicionar novos poderes.

Crie os arquivos na IDE

1. Abra a IDE e escolha Criar do zero ou um exemplo próximo do seu objetivo.
2. Informe nome, identidade e autor; confira os textos em português e inglês.
3. Abra manifest.json e ajuste permissões, destino e modo laboratório.
4. Abra main.js para escrever o script.
5. Adicione fixtures.json para preparar as respostas fictícias.
6. Valide o projeto e confira o painel de problemas antes de executar.

A estrutura inicial do manifesto pode ser esta. hashes ainda está vazio porque a exportação calcula o SHA-256 dos recursos. Este JSON é uma entrada de edição, não um pacote final pronto para instalar.

{
  "formatVersion": 1,
  "apiVersion": 1,
  "id": "lab.cache-observador",
  "version": "1.0.0",
  "author": "Equipe Aurora",
  "entry": "main.js",
  "name": {"pt-BR": "Observador de cache", "en": "Cache observer"},
  "description": {
    "pt-BR": "Registra uma diretiva de cache para revisão.",
    "en": "Records a cache directive for review."
  },
  "permissions": ["traffic.read", "findings", "ui.tab"],
  "targets": ["https://api.aurora.test"],
  "externalHosts": [],
  "settings": {"laboratory": true},
  "hashes": {}
}

O guia do manifesto .catplug detalha formato, traduções, caminhos, hashes e destinos. Escolher HTTPS e um host exato deixa o alcance mais claro do que liberar domínios amplos. O exemplo não solicita http.send nem external.call.

Escreva um observador pequeno e preciso

O script abaixo verifica host, etapa e headers antes de registrar a diretiva observada. O fingerprint inclui host e caminho para consolidar repetições do mesmo sinal. A severidade informativa e a confiança observada descrevem o que o código efetivamente constatou.

cat.ui.tab.register({
  id: 'cache.painel',
  title: {'pt-BR': 'Cache', en: 'Cache'},
  components: [{
    type: 'text',
    text: {
      'pt-BR': 'Diretivas públicas serão registradas para revisão.',
      en: 'Public directives will be recorded for review.'
    }
  }]
});

cat.events.on('http.response', async mensagem => {
  if (mensagem.stage !== 'response') return;
  const destino = cat.http.parseUrl(mensagem.url);
  if (destino.hostname !== 'api.aurora.test') return;
  const cabecalhos = mensagem.headers || [];
  const publica = cabecalhos.some(cabecalho => {
    if (cabecalho.name.toLowerCase() !== 'cache-control') return false;
    return cabecalho.value.split(',').some(item => item.trim().toLowerCase() === 'public');
  });
  if (!publica) return;
  await cat.findings.add({
    fingerprint: 'cache-publico:' + destino.hostname + destino.pathname,
    title: {'pt-BR': 'Diretiva de cache público observada', en: 'Public cache directive observed'},
    description: {
      'pt-BR': 'Revise a diretiva no contexto deste recurso. Exposição de dados não foi demonstrada.',
      en: 'Review the directive in this resource context. Data exposure was not demonstrated.'
    },
    severity: 'info',
    confidence: 'observed',
    url: mensagem.url,
    evidence: {request: mensagem.request, response: mensagem}
  });
});

Observe a verificação por diretiva: procurar apenas a substring public poderia confundir palavras maiores ou valores sem o significado pretendido. Headers são uma lista ordenada e podem aparecer mais de uma vez; o código examina todas as entradas Cache-Control. A referência da API descreve o contrato das mensagens.

Prepare fixtures e casos negativos

Adicione respostas problemáticas, adequadas e sem o header. O exemplo de fixture usa apenas o cenário fictício e não aponta para serviços públicos.

{
  "scenario": "fictional",
  "routes": [
    {
      "url": "https://api.aurora.test/api/perfil",
      "status": 200,
      "cacheControl": "public, max-age=600",
      "body": {"id": "cliente-ficticio-001", "scenario": "fictional"}
    },
    {
      "url": "https://api.aurora.test/api/perfil-privado",
      "status": 200,
      "cacheControl": "private, no-store",
      "body": {"scenario": "fictional"}
    }
  ]
}

Execute o script e use a área Laboratório para capturar as rotas simuladas. Confira os registros e a área Achados. A rota pública deve produzir uma observação; a privada não deve produzir esse sinal. Repita a primeira rota para conferir a consolidação pelo fingerprint. Acrescente também um host diferente e um valor como x-public para testar a delimitação.

O simulador é uma ferramenta de desenvolvimento, não uma captura de uma API externa. Conectores do CatBridge não executam no navegador. A documentação da IDE explica esses limites e o isolamento do código.

Observar e modificar têm requisitos distintos

O observador do tutorial pode ser assíncrono. Um hook de alteração do proxy tem regras mais restritas: deve ser síncrono, rápido e não realizar envios ou tarefas demoradas no caminho do encaminhamento. Acrescentar modificação exige a permissão correspondente e uma nova revisão do alcance.

Corpos completos, truncados, indisponíveis ou somente leitura precisam ser tratados explicitamente. Não tente editar o preview de um fluxo contínuo como se ele fosse a mensagem inteira. Comece por headers em um laboratório, depois consulte o contrato antes de alterar dados binários, compressão ou enquadramento HTTP.

Por que .catplug às vezes abre em um inspetor?

O pacote distribuído é um arquivo compactado com manifesto e recursos, não um script JavaScript comum. No desenvolvimento, edite main.js e os arquivos do projeto. O CatSuite Studio também oferece scripts textuais CatPlug e .catjs, com sugestões ao digitar cat.. Um pacote compilado precisa ser inspecionado ou importado para um projeto antes de editar seus arquivos.

O guia do CatSuite Studio explica criação, sugestões, preview local e geração de pacote assinado. Código de uma extensão não recebe automaticamente APIs do navegador, Node.js ou Flutter: use as funções publicadas no SDK.

Exporte, revise e instale sem ampliar permissões

1. Valide o projeto e teste os casos positivos e negativos.
2. Exporte o .catplug pela IDE ou gere um pacote assinado no Studio.
3. No aplicativo, habilite o módulo em Configurações → Extensões se ele estiver desativado.
4. Importe o pacote e confira identidade, integridade, permissões e destinos.
5. Se a origem não estiver verificada, faça a revisão solicitada pelo aplicativo antes da assinatura local.
6. Ative explicitamente a extensão e teste novamente no laboratório.

Uma assinatura válida comprova vínculo com uma chave e integridade do material assinado. Ela não substitui a leitura do código nem garante que o autor seja confiável. Revise também dados incluídos nas evidências e nos backups. Consulte segurança e cofre e interface, armazenamento e achados.

Próximo projeto: uma etapa reutilizável

Depois de dominar um observador, transforme uma análise específica em etapa de fluxo. O guia de fluxos e CatBridge mostra como combinar capacidades e manter proveniência. Para continuar agora, abra a IDE ou instale o CatSuite Studio, mantendo as permissões pequenas e o objetivo explícito.

Escrito por

Daniel Felipe

Daniel Felipe é criador do NetCatTest e produz conteúdos sobre cibersegurança, privacidade digital, OSINT, laboratórios autorizados e ferramentas para estudo técnico responsável.

Perfil e publicações [email protected] YouTube GitHub LinkedIn