SDK de extensões 1.4.0

O SDK de extensões do CatSuite reúne tudo para criar plugins do aplicativo: o contrato completo da API em TypeScript, o runtime de referência, os esquemas dos arquivos, quinze exemplos editáveis e seis modelos de fluxo. Esta é a versão 1.4.0 · API v1, compatível com todas as versões anteriores da API. Esta página mostra onde baixar, o que vem no pacote e como a API está organizada.

O que vem no pacote #

O ZIP extrai a pasta catsuite-sdk com:

Começar #

1. Instale o CatSuite Studio no VS Code e extraia o SDK.
2. Abra uma pasta de exemplos como projeto, por exemplo exemplos/painel.
3. Edite o arquivo indicado por entry no manifest.json. Digite cat. para explorar a API.
4. Rode CatSuite: Validar projeto e a prévia local do Studio.
5. Gere o .catplug assinado e importe-o em uma versão do CatSuite com extensões compatíveis. Revise as permissões antes de ativar.

Se preferir não instalar nada, use a IDE web: ela traz os mesmos tipos no autocompletar.

O objeto global cat #

Todo o SDK é exposto no objeto global cat. A seguir, os grupos da API v1.

Identidade #

• cat.apiVersion — sempre 1.
• cat.sdkVersion — a versão do SDK, "1.4.0" nesta entrega.

Eventos e alteração de tráfego #

• cat.events.on(name, handler) — observa http.request, http.response e http.complete.
• cat.proxy.onRequest(handler) e cat.proxy.onResponse(handler) — alteram a mensagem antes do encaminhamento. Devolver uma CatMessage substitui a original; não devolver nada a mantém.

Os handlers de alteração são síncronos e têm prazo de 100 ms. Cada mensagem informa a source (origem), como proxy, network_proxy, repetir, intruso, descobridor, extension e laboratory.

Envios HTTP e APIs externas #

• cat.http.send(request) — envia uma request para um destino declarado e aprovado.
• cat.http.cancel(id) — cancela um envio pelo id.
• cat.http.parseUrl(url) — separa scheme, hostname, port, pathname e query.
• cat.laboratory.capture(request) — captura uma request no laboratório, sem rede real.
• cat.external.call(options) — consulta uma API externa com uma credencial protegida (credentialId).

Interface #

• cat.ui.menu.register(options) — adiciona itens ao menu de uma mensagem, nos contextos request ou response.
• cat.ui.tab.register(options) — cria uma aba nativa com uma lista de componentes.
• cat.ui.update(id, components) — atualiza os componentes de uma aba.

Os componentes são renderizados de forma nativa, sem HTML nem JavaScript visual. Veja a lista completa em Interface, dados e achados.

Dados, configurações e recursos #

• cat.storage.get(key), cat.storage.set(key, value) e cat.storage.delete(key) — armazenamento por extensão, com até 10 MiB e 128 KiB por valor.
• cat.settings.get(key) — lê uma configuração declarada no manifesto.
• cat.resources.get(path, mode) — lê um recurso do pacote como texto ou bytes.

Achados, comandos e utilidades #

• cat.findings.add(finding) — registra um achado com severidade, confiança, URL e evidência.
• cat.commands.register(id, title, handler) e cat.commands.execute(id, args) — registram e executam comandos.
• cat.tools.repeater.open(request) — abre uma request no módulo Repetir.
• cat.i18n.locale e cat.i18n.text(value) — idioma atual e resolução de um texto bilíngue CatText.
• cat.bytes.fromText(text) e cat.bytes.toText(bytes) — conversão entre texto UTF-8 e bytes.
• cat.log(message, level) — registra uma mensagem no console da extensão.

Tipos principais #

• CatText — um texto bilíngue no formato {"pt-BR": "...", en: "..."}.
• CatMessage — uma mensagem HTTP, com headers, body, url, method, status, origem e, quando vem de outra extensão, pluginOrigin e extensionTrail.
• CatBody — o corpo da mensagem, com bytes, complete, truncated, available, mutable e, quando aplicável, representation (wire ou decoded), sha256 e reference.
• CatRequest — uma request para cat.http.send ou cat.external.call.
• CatFinding — um achado, com severity (info, low, medium, high, critical), confidence (observed, confirmed, hypothesis) e status (open, resolved, false_positive).
• CatComponent — um componente de interface. Veja a tabela a seguir.

Componentes de interface #

Fluxos visuais #

O SDK 1.2 adicionou as etapas e os parsers de fluxo:

• cat.pipeline.registerStep(options, handler) — registra uma etapa que recebe artefatos de entrada e emite artefatos de saída.
• cat.parsers.register(options, handler) — registra um parser para tipos MIME específicos.

O handler recebe um CatStepContext com inputs, config, runId, nodeId, revisionId, protection, restored, signal, e os métodos checkpoint(state), emit(kind, data) e progress(value). A etapa deve observar ctx.signal.aborted e pode retomar do estado salvo em ctx.restored. O checkpoint aceita um JSON de até 32 KiB.

cat.pipeline.registerStep({
  id: 'exemplo.retomar',
  title: {'pt-BR': 'Retomar', en: 'Resume'},
  inputs: ['record'],
  outputs: ['record']
}, async ctx => {
  let feitos = ctx.restored?.feitos || 0;
  for (; feitos < ctx.inputs.length; feitos++) {
    if (ctx.signal.aborted) return;
    ctx.emit('record', ctx.inputs[feitos].data);
    await ctx.checkpoint({feitos: feitos + 1});
  }
});

Veja os formatos de artefato, os nós e os modelos em Fluxos visuais com .catflow.

Capacidades do CatBridge #

O SDK 1.3 adicionou as capacidades tipadas do CatBridge:

• cat.connectors.capabilities(connectorId) — lê o catálogo de capacidades do conector.
• cat.connectors.run(options) — executa uma capacidade tipada (por exemplo http.probe) com os parâmetros aprovados.
• cat.connectors.cancel(id) — cancela uma tarefa pelo id.

Declare connector.run e requiresSdk: "1.3.0" ou superior no manifesto. O SDK 1.4 amplia o catálogo com os adaptadores do ecossistema (descoberta de ativos, DNS, portas, fuzzing tipado, TLS, JWT e análise de código), que exigem .catflow 5 e contrato 2. Veja Capacidades e ferramentas.

Exemplos incluídos #

Os quinze exemplos são projetos editáveis, com manifestos e fixtures:

• Essenciais: painel e comandos, análise de tráfego, headers, etapa de fluxo e parser JSON.
• Aurora: captura, alteração, envio, análise, menu, aba, persistência, API simulada e achados.
• Identidade: JWT, candidatos a segredos, hipóteses de autorização e relatório.
• APIs: análise estática de JavaScript, endpoints e comparação com OpenAPI.
• CatBridge: sondagem HTTP e proveniência dos resultados. A execução real exige conexão, ferramenta disponível e aprovação; a prévia do Studio usa simulação.

Os seis modelos de fluxo acompanham entradas fictícias. Importar um modelo não amplia o escopo nem autoriza envios; as fixtures usam dados fictícios.

Continue #

• Referência da API JavaScript
• Interface, dados e achados
• Manifesto do pacote .catplug
• CatSuite Studio para VS Code