Write your first plugin

01The plugin model

A Crusader extension is a JavaScript file. There's no build step and no SDK to vendor: you write against globals the runtime injects — crusader (the hooks you register) and api (the host surface you call). During development the runtime hot-reloads on save, so you edit, hit save, and re-run a check without reinstalling.

Community plugins are Free. Authoring, installing, and running a plugin needs no license. Most capability keys are Free too. A handful of advanced API capabilities are gated to Hunter Pro — scanner findings, signed identity replay, hosted Beacon, MCP tools, report packaging, active scanning, mobile/Frida, and the JA3 transport — and they're listed plainly in section 05. Free is a real daily driver here, not a teaser.

The contract is built around consent before capability. A plugin declares everything it wants in a capabilities array; Crusader shows you that manifest before anything runs; sensitive permissions always require an explicit yes. Nothing reaches the network, your history, or your identities unless you approved the capability that gates it.

02A minimal scan-check plugin

Here's a complete, runnable-looking plugin: a passive scan check that flags responses still served over cleartext http. It does no probing — it reads exchanges Crusader already captured and raises a finding through crusader.report. Note the capabilities declaration at the top: a passive check that only reads and reports needs nothing sensitive.

// cleartext-check.js — passive scan check, Free capabilities only

crusader.capabilities = ["history"];   // read captured exchanges

crusader.scanCheck({
  name: "Cleartext transport",
  // run() is called per in-scope exchange; return nothing to stay quiet
  run(exchange) {
    // exchange exposes the captured request/response
    if (exchange.scheme !== "http") return;

    crusader.report({
      title: "Response served over cleartext HTTP",
      severity: "low",
      url: exchange.url,
      evidence: `${exchange.method} ${exchange.url} → ${exchange.status}`,
      remediation: "Redirect to HTTPS and set HSTS.",
    });
  },
});

That's the whole plugin. Drop it in the Extensions screen as a local file (or install it from the CLI), browse your target through the proxy, and run a passive scan — every cleartext exchange becomes a Low finding in Scanner → Findings. Because passive analysis is Free, this check runs on every tier.

03Registration hooks

You extend Crusader by registering callbacks on the crusader object. Each hook plugs into one part of the workstation. Register only what you need — every hook maps to a capability you'll declare and the user will approve.

04The host api.* surface

Where crusader.* registers behavior, api.* is how your plugin reaches into the host — sending requests, reading the project's data, asking about the license, drawing UI. Each call is gated by a capability; calling one you didn't declare (or one locked on your tier) returns a structured refusal rather than throwing — see section 07.

The reads — api.sql, api.history, api.sitemap, api.identities — are the backbone of analysis plugins: pull what Crusader already captured, reason over it, and report. There's also api.transport.request for the JA3 / browser-fingerprint transport, which is Pro (ja3-transport).

05Capabilities & permissions

Every plugin declares a capabilities array. This is the permission manifest: it's what preview surfaces, what you approve at install, and what the runtime enforces at call time. Declare the minimum — a passive analysis plugin usually needs only history and maybe sitemap.

Most capabilities are Free (sensitive ones still require explicit consent on install). A set of advanced capabilities is gated to Hunter Pro. Both are listed here so you know which side of the line your plugin sits on before you build it.

06Preview, then install

Always preview before you install — yours or anyone's. Preview parses the plugin and prints its capability manifest without running it, so you see exactly what it asks for and how it behaves on your license:

# inspect a plugin's capabilities without installing it
crusader plugin preview ./cleartext-check.js
# or straight from a URL
crusader plugin preview https://example.com/some-plugin.js

The manifest shows, per capability, whether it's allowed on your tier and what consent it needs. Look for three fields:

Once you're satisfied, install it. A plugin that requests review-required capabilities needs --approve-capabilities on the CLI to confirm you've seen the manifest:

# install, approving the sensitive capabilities you saw in preview
crusader plugin install ./cleartext-check.js --approve-capabilities

You can also load a local file directly from the Extensions screen, where the same consent prompt appears in the UI. During development, leave the file installed and just keep editing — hot reload picks up each save so you iterate without reinstalling.

07How locked APIs behave

This is the part that makes one plugin work on every tier. When a plugin calls a Pro-gated API on Free, the call does not throw. It returns a structured requires_upgrade result — the same shape the MCP server returns for gated tools — so your code can branch on it cleanly:

// a hosted-Beacon call on Free returns a result, not an exception
const r = api.beacon({ module: "ssrf", tag: "probe" });

if (r.ok === false && r.code === "requires_upgrade") {
  // r also carries: feature, feature_name, required_tier, message, hint, license
  api.output(`${r.feature_name} needs ${r.required_tier} — ${r.hint}`);
  return;   // degrade gracefully; the plugin stays installed and running
}
// …use r normally when ok

The consequences are worth stating plainly:

• The plugin stays installable and runnable on Free. Gated capabilities are inert, not fatal — the rest of the plugin works.
• You branch, you don't catch. Check r.ok / r.code === "requires_upgrade" rather than wrapping calls in try/catch.
• The result is self-describing. It carries feature, feature_name, required_tier, a human message, a hint (e.g. run crusader license status), and a license snapshot — enough to tell the user what to do.

Write plugins that degrade gracefully: do the Free work unconditionally, and treat Pro APIs as enhancements that announce themselves when locked. That way the same file ships to everyone and quietly does more on Hunter Pro.

Want a guide that isn't here yet? Email hello@crusaderproxy.com.