Extension SDK 1.4.0

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.

What is in the package #

The ZIP extracts a catsuite-sdk folder with:

Getting started #

1. Install CatSuite Studio 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: 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.

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 #

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.

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.

CatBridge capabilities #

SDK 1.3 added the typed 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.

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.

Next step #

• JavaScript API reference
• Interface, data and findings
• The .catplug package manifest
• CatSuite Studio for VS Code