# The .catplug package manifest

> Structure of the .catplug file, manifest.json fields, validation rules, permissions, destinations, SHA-256 hashes and format 2.

- Language: en
- Canonical URL: https://netcattest.com/catsuite/en/docs/extensions/manifest
- Section: Extensions
- Updated: 2026-10-06
- Other language (pt-BR): https://netcattest.com/catsuite/docs/extensoes/manifesto

## Package structure

A `.catplug` is a ZIP file with `manifest.json` at the root and the files listed in `hashes`.

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

## Complete example

```json
{
  "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"
  }
}
```

## Fields

| Field | Type | Rule |
|---|---|---|
| `formatVersion` | number | `1` or `2` |
| `apiVersion` | number | `1` |
| `id` | text | `[a-z][a-z0-9.-]{2,63}`, stable across versions |
| `version` | text | `MAJOR.MINOR.PATCH`, for example `1.0.0` |
| `author` | text | required |
| `entry` | text | a `.js` file inside the package, up to 128 KiB |
| `name` | object | `pt-BR` and `en` required |
| `description` | object | `pt-BR` and `en` required |
| `permissions` | list | known capabilities, no duplicates |
| `targets` | list | destinations for `cat.http.send`, up to 100 |
| `externalHosts` | list | destinations for `cat.external.call`, up to 100 |
| `settings` | object | initial values read by `cat.settings.get` |
| `settingsSchema` | object | optional, up to 32 fields |
| `hashes` | object | SHA-256 of every file except the manifest |

> [!IMPORTANT]
> Names, descriptions and interface texts need both `pt-BR` and `en`. IDs and commands are stable in both languages. Without both translations the package is rejected with `E_TRANSLATION`.

## Permissions

| Capability | Unlocks |
|---|---|
| `traffic.read` | `cat.events.on` and HTTP content in menus |
| `traffic.modify` | `cat.proxy.onRequest` and `cat.proxy.onResponse` |
| `http.send` | `cat.http.send` and `cat.http.cancel` |
| `external.call` | `cat.external.call` |
| `ui.menu` | `cat.ui.menu.register` |
| `ui.tab` | `cat.ui.tab.register` and `cat.ui.update` |
| `storage` | `cat.storage` |
| `findings` | `cat.findings.add` |
| `repeater` | `cat.tools.repeater.open` |
| `commands` | `cat.commands.register` and `cat.commands.execute` |
| `pipeline.step` | `cat.pipeline.registerStep` |
| `parsers` | `cat.parsers.register` |
| `connector.run` | `cat.connectors` inside approved workflows |

> [!NOTE]
> Menus that receive HTTP content require `traffic.read` in addition to `ui.menu` and `commands`. Repeater only receives approved destinations.

## Destinations

`targets` and `externalHosts` accept IDNA domains, decimal IPv4, bracketed IPv6 and explicit ports, with optional scheme and path.

| Example | Reach |
|---|---|
| `api.example.test` | exact domain, HTTP or HTTPS, any port |
| `https://api.example.test` | HTTPS only on port 443 |
| `https://api.example.test:8443` | HTTPS only on port 8443 |
| `https://api.example.test/v1` | HTTPS only under `/v1` |
| `*.example.test` | subdomains of `example.test`, excluding the domain itself |

Credentials in the URL, `?`, `#`, `%`, spaces, global wildcards, wildcards on IPs, paths with `..` and encoded slashes are rejected. Paths require a scheme. Private networks and loopback need explicit scope, and DNS and redirects are revalidated: a public domain cannot suddenly point to a private address.

## Hashes

Every package file except the manifest needs an entry in `hashes` with the lowercase hexadecimal SHA-256 of its bytes. The number of hashes must match the number of files. The [web IDE](https://netcattest.com/catsuite/en/docs/extensions/ide) computes everything automatically on export, and in [CatSuite Studio](https://netcattest.com/catsuite/en/docs/extensions/vscode) the **CatSuite: Update manifest hashes** command does the same in VS Code.

## Settings with settingsSchema

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

Accepted types: `string`, `boolean`, `integer`, `number` and `credential`. The `secret` alias means a credential reference, never its content. `enum` accepts 1 to 50 values and keys follow `[a-zA-Z0-9_.-]{1,64}`.

## Format 2

`formatVersion: 2` adds UUID `revisionId` and `lineageId`, `parentHash`, `requiresSdk` (from `1.0.0` to `1.4.0`), an optional Ed25519 signature over canonical JSON and optional password protection. Editing in the app removes the old signature and creates a new revision; exporting signs with the local identity. See [Security, vault and data protection](https://netcattest.com/catsuite/en/docs/security).

## Package limits

| Item | Limit |
|---|---|
| `.catplug` file | 10 MiB |
| Expanded content | 40 MiB |
| Files | 500 |
| `manifest.json` | 64 KiB |
| Each file | 4 MiB |
| Paths | relative, up to 200 characters, no leading `/`, `\`, `:` or `..` |

Symbolic links and duplicate files are rejected with `E_PATH`.