Writing a Custom Vigolium JS Extension

You're authoring a single-file JavaScript extension that the vigolium scanner will load and run. Two output paths from here:

1. Hand the file path or inline source to run_extension to execute it immediately and get back findings.
2. Write the file to disk (e.g. into the session dir) for the operator to reuse later via vigolium scan --ext path/to/script.js.

You do not need a build step. Vigolium's embedded JS engine (Sobek) runs the script directly. ES2017 features work; no import / export, use module.exports.

Module Shape

Every extension exports one object via module.exports. The shape decides whether it runs as a passive or active scanner module.

Passive (read-only, runs against stored HTTP records)

module.exports = {
  id: "kebab-case-id",                // unique within the run
  name: "Human-readable name",
  description: "1, 2 sentence purpose",
  type: "passive",                     // required
  severity: "low",                     // critical|high|medium|low|info
  confidence: "tentative",             // certain|firm|tentative
  scope: "response",                   // request|response|both, what to read
  tags: ["exposure", "light"],         // free-form classification
  scanTypes: ["per_request"],          // only "per_request" for passive

  scanPerRequest: function(ctx) {
    // ctx.request:  { url, method, headers, body, ... }
    // ctx.response: { status, headers, body, ... }
    // ctx.record:   { uuid, addRemarks(tags) }  (DB-backed records only)
    //
    // Return null when there's nothing to report, OR an array of finding
    // objects (see "Finding shape" below). Throwing is fine, vigolium
    // catches per-record errors and continues.
  }
};

Active (sends new requests; can mutate inputs and probe)