# CatSuite extensions

> How .catplug extensions work: isolated QuickJS engine, permissions, lifecycle, integration points and API v1 limits.

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

Extensions are `.catplug` packages with JavaScript code run by **QuickJS 2026-06-04**, embedded through JNI in an isolated Android service. Every extension has its own environment, its own SQLite data and its own permissions.

## What an extension can do

- Observe requests and responses with `cat.events.on`.
- Change messages before they are forwarded with `cat.proxy.onRequest` and `cat.proxy.onResponse`.
- Send requests to declared destinations with `cat.http.send`.
- Call external APIs with protected credentials using `cat.external.call`.
- Register commands, message menus and native tabs.
- Store data and record findings with evidence.
- Take part in [visual workflows](https://netcattest.com/catsuite/en/docs/workflows) as steps and parsers.

## What an extension cannot do

There is no Node.js, DOM, `fetch`, general file access or process execution. Use `cat.http.parseUrl` for URLs and `cat.bytes` for UTF-8 conversion. TLS uses Android certificate validation and the SDK cannot disable it.

## Integration points

Hooks cover the proxy, Network Proxy, Repeater, Intruder and Discoverer. Every message reports its origin in `source`:

| `source` | Origin |
|---|---|
| `proxy` | Intercepted browser traffic |
| `network_proxy` | Network Proxy session |
| `repetir` | Repeater sends |
| `intruso` | Intruder sends |
| `descobridor` | Discoverer sends |
| `extension` | Requests sent by extensions |
| `laboratory` | Simulated laboratory traffic |

Requests from an extension never return to its own handlers; other extensions may process them according to their scope. When extensions process proxy traffic, applicable replacement rules run before the handlers, and manual editing takes precedence.

## Lifecycle

1. **Create or import** — in **Settings → Extensions**, use Create (basic template or the Aurora example), import a `.catplug` or build the package in the [web IDE](https://netcattest.com/catsuite/en/docs/extensions/ide) or in [CatSuite Studio for VS Code](https://netcattest.com/catsuite/en/docs/extensions/vscode).
2. **Validate** — package, manifest and code are validated before anything is replaced.
3. **Approve** — installs start disabled. When enabling, you review capabilities and destinations.
4. **Run** — hooks, commands, menus and tabs come alive.
5. **Update** — broader permissions or destinations require new approval.

> [!WARNING]
> Three consecutive failures suspend the extension. Disabling or removing it clears every registered handler and component.

## API v1 limits

| Resource | Limit |
|---|---|
| Active extensions | 4 |
| Memory per environment | 32 MiB |
| Mutation handler | 100 ms, synchronous |
| Concurrent HTTP calls | 2 per extension |
| Total HTTP timeout | 120 seconds |
| HTTP response | up to 8 MiB, with a preview for JavaScript |
| Editable preview | up to 32 KiB |
| Entry script | up to 128 KiB |
| Package | 10 MiB compressed, 40 MiB expanded and 500 files |
| Data per extension | 10 MiB, with 128 KiB per value |

Larger, incomplete, compressed or continuous bodies are read-only. SSE and WebSocket keep their transport, and HTTPS tunnels without decryption do not provide HTTP content.

## Your first extension

```js
cat.commands.register('lab.hello', {'pt-BR': 'Dizer olá', en: 'Say hello'}, () => {
  cat.log({'pt-BR': 'Olá do laboratório.', en: 'Hello from the lab.'});
  return {ok: true};
});
```

Declare the `commands` permission in the [manifest](https://netcattest.com/catsuite/en/docs/extensions/manifest) and run the command in the simulator of the [extension IDE](https://netcattest.com/catsuite/en/ide).

## Keep going

- [Extension SDK 1.4.0](https://netcattest.com/catsuite/en/docs/extensions/sdk)
- [The .catplug package manifest](https://netcattest.com/catsuite/en/docs/extensions/manifest)
- [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)