# Extension SDK 1.4.0

> The CatSuite 1.4.0 extension SDK: where to download it, what is in the package, the global cat object, the examples, the workflow templates and CatBridge capabilities.

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

The **CatSuite extension SDK** brings together everything to build app plugins: the full API contract in TypeScript, the reference runtime, the file schemas, **fifteen editable examples** and **six workflow templates**. This is version **1.4.0 · API v1**, compatible with every earlier API version. This page shows where to download it, what is in the package and how the API is organized.

| Resource | Address |
|---|---|
| Download the SDK (ZIP) | [catsuite-sdk-1.4.0.zip](https://github.com/netcattest/catsuite/releases/download/sdk-1.4.0/catsuite-sdk-1.4.0.zip) |
| Checksums | [SHA256SUMS.txt](https://github.com/netcattest/catsuite/releases/download/sdk-1.4.0/SHA256SUMS.txt) |
| Source code on GitHub | [sdk folder](https://github.com/netcattest/catsuite/tree/main/sdk) |
| Write in VS Code | [CatSuite Studio](https://netcattest.com/catsuite/en/docs/extensions/vscode) |
| Write in the browser | [Web IDE](https://netcattest.com/catsuite/en/ide) |

> [!NOTE]
> You do not need to install the SDK on the device: the **QuickJS** engine runs inside the app and the global `cat` object is already available. The SDK package is for writing and validating on your computer, with the types, the examples and the schemas.

## What is in the package

The ZIP extracts a `catsuite-sdk` folder with:

| File or folder | Use |
|---|---|
| `catsuite.d.ts` | The full API contract and types for the editor. |
| `sdk.js` | The reference runtime loaded by CatSuite's QuickJS host. |
| `sdk.json` | The SDK version and structure. |
| `esquemas` | Schemas for `manifest.json`, project, `.catflow` and `.catdata`. |
| `capability-contracts.json` | Typed contracts for the CatBridge capabilities. |
| `exemplos` | Fifteen editable projects, with manifests and fixtures. |
| `fluxos` | Six workflow templates and fictional inputs. |

> [!IMPORTANT]
> Do not include `sdk.js` in the extension script: the app already provides the global `cat` object. There is no Node.js, DOM, `fetch`, shell or general access to the device's files.

## Getting started

1. Install [CatSuite Studio](https://netcattest.com/catsuite/en/docs/extensions/vscode) in VS Code and extract the SDK.
2. Open an `exemplos` folder as a project, for example `exemplos/painel`.
3. Edit the file pointed to by `entry` in `manifest.json`. Type `cat.` to explore the API.
4. Run **CatSuite: Validate project** and the Studio's local preview.
5. Build the signed `.catplug` and import it into a CatSuite version with compatible extensions. Review the permissions before enabling it.

If you prefer not to install anything, use the [web IDE](https://netcattest.com/catsuite/en/ide): it brings the same types into autocomplete.

## The global `cat` object

The whole SDK is exposed on the global `cat` object. Below are the API v1 groups.

### Identity

- `cat.apiVersion` — always `1`.
- `cat.sdkVersion` — the SDK version, `"1.4.0"` in this release.

### Events and traffic mutation

- `cat.events.on(name, handler)` — observes `http.request`, `http.response` and `http.complete`.
- `cat.proxy.onRequest(handler)` and `cat.proxy.onResponse(handler)` — change the message before forwarding. Returning a `CatMessage` replaces the original; returning nothing keeps it.

Mutation handlers are **synchronous** and have a **100 ms** deadline. Every message reports its `source`, such as `proxy`, `network_proxy`, `repetir`, `intruso`, `descobridor`, `extension` and `laboratory`.

### HTTP sends and external APIs

- `cat.http.send(request)` — sends a request to a declared and approved destination.
- `cat.http.cancel(id)` — cancels a send by its `id`.
- `cat.http.parseUrl(url)` — splits `scheme`, `hostname`, `port`, `pathname` and `query`.
- `cat.laboratory.capture(request)` — captures a request in the lab, with no real network.
- `cat.external.call(options)` — calls an external API with a protected credential (`credentialId`).

### Interface

- `cat.ui.menu.register(options)` — adds items to a message menu, in the `request` or `response` contexts.
- `cat.ui.tab.register(options)` — creates a native tab with a list of components.
- `cat.ui.update(id, components)` — updates a tab's components.

Components are rendered natively, with no HTML or visual JavaScript. See the full list in [Interface, data and findings](https://netcattest.com/catsuite/en/docs/extensions/ui-and-data).

### Data, settings and resources

- `cat.storage.get(key)`, `cat.storage.set(key, value)` and `cat.storage.delete(key)` — per-extension storage, with up to 10 MiB and 128 KiB per value.
- `cat.settings.get(key)` — reads a setting declared in the manifest.
- `cat.resources.get(path, mode)` — reads a package resource as text or bytes.

### Findings, commands and utilities

- `cat.findings.add(finding)` — records a finding with severity, confidence, URL and evidence.
- `cat.commands.register(id, title, handler)` and `cat.commands.execute(id, args)` — register and run commands.
- `cat.tools.repeater.open(request)` — opens a request in the Repeater module.
- `cat.i18n.locale` and `cat.i18n.text(value)` — current language and resolution of a bilingual `CatText`.
- `cat.bytes.fromText(text)` and `cat.bytes.toText(bytes)` — conversion between UTF-8 text and bytes.
- `cat.log(message, level)` — logs a message to the extension console.

## Main types

- `CatText` — a bilingual text in the `{"pt-BR": "...", en: "..."}` format.
- `CatMessage` — an HTTP message, with `headers`, `body`, `url`, `method`, `status`, source and, when it comes from another extension, `pluginOrigin` and `extensionTrail`.
- `CatBody` — the message body, with `bytes`, `complete`, `truncated`, `available`, `mutable` and, when applicable, `representation` (`wire` or `decoded`), `sha256` and `reference`.
- `CatRequest` — a request for `cat.http.send` or `cat.external.call`.
- `CatFinding` — a finding, with `severity` (`info`, `low`, `medium`, `high`, `critical`), `confidence` (`observed`, `confirmed`, `hypothesis`) and `status` (`open`, `resolved`, `false_positive`).
- `CatComponent` — an interface component. See the table below.

### Interface components

| Component | Fields | Since |
|---|---|---|
| `text` | `text` | v1 |
| `button` | `label`, `command`, `args` | v1 |
| `field` and `filter` | `id`, `label`, `value` | v1 |
| `list` | `items` | v1 |
| `table` | `columns`, `rows` | v1 |
| `http` | `message` | v1 |
| `progress` | `value` | v1 |
| `json` | `label`, `value` | SDK 1.2 |
| `diff` | `label`, `before`, `after` | SDK 1.2 |
| `timeline` | `label`, `items` with `title`, `detail` and `time` | SDK 1.2 |
| `chart` | `label`, `values` with `label` and `value` | SDK 1.2 |
| `graph` | `label`, `nodes` and `edges` with `from` and `to` | SDK 1.2 |

## Visual workflows

SDK 1.2 added the workflow steps and parsers:

- `cat.pipeline.registerStep(options, handler)` — registers a step that receives input artifacts and emits output artifacts.
- `cat.parsers.register(options, handler)` — registers a parser for specific MIME types.

The `handler` receives a `CatStepContext` with `inputs`, `config`, `runId`, `nodeId`, `revisionId`, `protection`, `restored`, `signal`, and the `checkpoint(state)`, `emit(kind, data)` and `progress(value)` methods. The step must watch `ctx.signal.aborted` and can resume from the state saved in `ctx.restored`. The `checkpoint` accepts a JSON of up to 32 KiB.

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

See the artifact formats, the nodes and the templates in [Visual workflows with .catflow](https://netcattest.com/catsuite/en/docs/workflows).

## CatBridge capabilities

SDK 1.3 added the typed [CatBridge](https://netcattest.com/catsuite/en/docs/catbridge) capabilities:

- `cat.connectors.capabilities(connectorId)` — reads the connector's capability catalog.
- `cat.connectors.run(options)` — runs a typed capability (for example `http.probe`) with the approved parameters.
- `cat.connectors.cancel(id)` — cancels a task by its `id`.

Declare `connector.run` and `requiresSdk: "1.3.0"` or later in the manifest. SDK 1.4 extends the catalog with the ecosystem adapters (asset discovery, DNS, ports, typed fuzzing, TLS, JWT and code analysis), which require `.catflow` 5 and contract 2. See [Capabilities and tools](https://netcattest.com/catsuite/en/docs/catbridge/tools).

## Included examples

The fifteen examples are editable projects, with manifests and fixtures:

- **Essentials:** panel and commands, traffic analysis, headers, workflow step and JSON parser.
- **Aurora:** capture, mutation, send, analysis, menu, tab, persistence, simulated API and findings.
- **Identity:** JWT, secret candidates, authorization hypotheses and report.
- **APIs:** static JavaScript analysis, endpoints and OpenAPI comparison.
- **CatBridge:** HTTP probing and result provenance. Real execution requires a connection, an available tool and approval; the Studio preview uses simulation.

The six workflow templates come with fictional inputs. Importing a template does not broaden the scope or authorize sends; the fixtures use fictional data.

> [!WARNING]
> The fixtures and labs use fictional data and do not access the network. JWT analysis does not verify signatures, and authorization hints do not demonstrate improper access. Treat every signal as evidence for review.

## Next step

- [JavaScript API reference](https://netcattest.com/catsuite/en/docs/extensions/api)
- [Interface, data and findings](https://netcattest.com/catsuite/en/docs/extensions/ui-and-data)
- [The .catplug package manifest](https://netcattest.com/catsuite/en/docs/extensions/manifest)
- [CatSuite Studio for VS Code](https://netcattest.com/catsuite/en/docs/extensions/vscode)