Manifesto do pacote .catplug

Estrutura do pacote #

Um .catplug é um arquivo ZIP com manifest.json na raiz e os arquivos listados em hashes.

Texto

auditor.catplug
├── manifest.json
├── main.js
├── fixtures.json
├── README.pt-BR.md
└── README.en.md

Exemplo completo #

manifest.jsonJSON

{
  "formatVersion": 1,
  "apiVersion": 1,
  "id": "lab.auditor",
  "version": "1.0.0",
  "author": "NetCatTest",
  "entry": "main.js",
  "name": {"pt-BR": "Auditor de respostas", "en": "Response auditor"},
  "description": {"pt-BR": "Audita cabeçalhos de cache.", "en": "Audits cache headers."},
  "permissions": ["traffic.read", "traffic.modify", "findings", "commands", "ui.tab"],
  "targets": ["api.aurora.test"],
  "externalHosts": [],
  "settings": {"laboratory": true},
  "hashes": {
    "main.js": "84f7f8620e4ccde480b3a929483f51a0d051c2fe89443ecd4409faea663e071b"
  }
}

Campos #

Campo	Tipo	Regra
`formatVersion`	número	`1` ou `2`
`apiVersion`	número	`1`
`id`	texto	`[a-z][a-z0-9.-]{2,63}`, estável entre versões
`version`	texto	`MAIOR.MENOR.CORREÇÃO`, por exemplo `1.0.0`
`author`	texto	obrigatório
`entry`	texto	arquivo `.js` do próprio pacote, até 128 KiB
`name`	objeto	`pt-BR` e `en` obrigatórios
`description`	objeto	`pt-BR` e `en` obrigatórios
`permissions`	lista	capacidades conhecidas, sem repetição
`targets`	lista	destinos de `cat.http.send`, até 100
`externalHosts`	lista	destinos de `cat.external.call`, até 100
`settings`	objeto	valores iniciais lidos por `cat.settings.get`
`settingsSchema`	objeto	opcional, até 32 campos
`hashes`	objeto	SHA-256 de cada arquivo, exceto o manifesto

Permissões #

Capacidade	Libera
`traffic.read`	`cat.events.on` e conteúdo HTTP em menus
`traffic.modify`	`cat.proxy.onRequest` e `cat.proxy.onResponse`
`http.send`	`cat.http.send` e `cat.http.cancel`
`external.call`	`cat.external.call`
`ui.menu`	`cat.ui.menu.register`
`ui.tab`	`cat.ui.tab.register` e `cat.ui.update`
`storage`	`cat.storage`
`findings`	`cat.findings.add`
`repeater`	`cat.tools.repeater.open`
`commands`	`cat.commands.register` e `cat.commands.execute`
`pipeline.step`	`cat.pipeline.registerStep`
`parsers`	`cat.parsers.register`
`connector.run`	`cat.connectors` dentro de fluxos aprovados

Destinos #

targets e externalHosts aceitam domínio em IDNA, IPv4 decimal, IPv6 entre colchetes e porta explícita, com esquema e caminho opcionais.

Exemplo	Alcance
`api.exemplo.test`	domínio exato, HTTP ou HTTPS, qualquer porta
`https://api.exemplo.test`	somente HTTPS na porta 443
`https://api.exemplo.test:8443`	somente HTTPS na porta 8443
`https://api.exemplo.test/v1`	somente HTTPS em `/v1` e abaixo
`*.exemplo.test`	subdomínios de `exemplo.test`, sem incluir o próprio domínio

São recusados credenciais na URL, ?, #, %, espaços, curinga global, curinga em IP, caminhos com .. e barras codificadas. Caminhos exigem esquema. Redes privadas e loopback precisam de escopo explícito, e DNS e redirecionamentos são revalidados: um domínio público não pode passar a apontar para um endereço privado.

Hashes #

Cada arquivo do pacote, exceto o manifesto, precisa de uma entrada em hashes com o SHA-256 dos seus bytes em hexadecimal minúsculo. A quantidade de hashes deve ser igual à quantidade de arquivos. A IDE web calcula tudo automaticamente na exportação, e no CatSuite Studio o comando CatSuite: Atualizar hashes do manifesto faz o mesmo no VS Code.

Configurações com settingsSchema #

JSON

{
  "settingsSchema": {
    "laboratory": {"title": {"pt-BR": "Modo laboratório", "en": "Laboratory mode"}, "type": "boolean"},
    "limite": {"title": {"pt-BR": "Limite", "en": "Limit"}, "type": "integer", "minimum": 1, "maximum": 50},
    "chave": {"title": {"pt-BR": "Credencial", "en": "Credential"}, "type": "credential"}
  }
}

Tipos aceitos: string, boolean, integer, number e credential. O alias secret significa referência a credencial, não o seu conteúdo. enum aceita de 1 a 50 valores e as chaves seguem [a-zA-Z0-9_.-]{1,64}.

Formato 2 #

formatVersion: 2 acrescenta revisionId e lineageId em UUID, parentHash, requiresSdk (de 1.0.0 a 1.4.0), assinatura Ed25519 opcional sobre JSON canônico e proteção opcional com senha. Editar no aplicativo remove a assinatura antiga e cria uma nova revisão; exportar assina com a identidade local. Veja Segurança, cofre e proteção de dados.

Limites do pacote #

Item	Limite
Arquivo `.catplug`	10 MiB
Conteúdo expandido	40 MiB
Arquivos	500
`manifest.json`	64 KiB
Cada arquivo	4 MiB
Caminhos	relativos, até 200 caracteres, sem `/` inicial, `\`, `:` ou `..`

Links simbólicos e arquivos duplicados são recusados com E_PATH.

Idioma

Ajustes deste navegador