http-attack 0.0.0-stage → 1.0.0

package/skills/http-attack/scripts/lib/args.mjs

@@ -0,0 +1,190 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { UsageError } from './errors.mjs';
+
+export const HELP = `http-attack: adversarial probes against an HTTP API running on this machine.
+
+usage: node http-attack.mjs <base-url> [options]
+
+Routes
+  --write "<METHOD> <path> <body>"   a request that creates or changes state, with a legitimate body. The body is JSON
+                                     (starts with { or [), a form (a=1&b=2) or @file to read it from a file (use a file in
+                                     Windows PowerShell 5.1, which strips the quotes of inline JSON). Repeatable.
+  --read "<path>"                    a request that returns data, with its query if any (?limit=10). Repeatable.
+  --search "<path> <param>"          a read with a free-text search parameter. Repeatable.
+  --unique "<METHOD> <path> <body>"  a create guarded by a unique key: N identical requests are sent at once. Repeatable.
+  --item-path "/items/{id}"          where a created item is read back when the create answers no Location.
+  --vary "<json-pointer | field>"    the body field that keeps requests apart (default: the first string with an @, else
+                                     the first string), e.g. /item/email for {"item":{"email":...}}.
+  --content-type <type>              the media type of every write body (default application/json, or a form).
+
+Credentials
+  --header "Name: value"             sent on every request (user A). Repeatable.
+  --auth-env <VAR>                   sends "Authorization: Bearer $VAR" without the token on the command line.
+  --auth-header-name <name>          a custom header that carries credentials (X-Auth-Token): removed in the no-credentials rows.
+  --other-header "Name: value"       user B's credentials, for the ownership (IDOR) rows. Repeatable.
+  --other-auth-env <VAR>             user B's bearer token from an environment variable.
+
+Expectations
+  --common-headers "A, B"            headers every response must carry, parser errors included.
+  --raw-exempt "<why>"               parser errors are answered by a proxy before the app: skip the common-header check there.
+  --body-limit <bytes>               the documented body limit.
+  --csrf                             the app authenticates with cookies: cross-origin writes must be refused.
+  --config <file>                    per-route expectations and suppressions (default ./http-attack.config.json if present).
+
+Faults and durability
+  --fault-sqlite <file>              holds BEGIN EXCLUSIVE on the app's SQLite file while the first --write is sent.
+                                     Any other fault (docker pause db) is a shell command and is only read from the config
+                                     file (faultCmd, faultRestore), never from the command line.
+  --persist-save <file>              create one item through the first --write, save how to read it back, then stop.
+  --persist-verify <file>            after a restart, read the saved item back and compare it.
+
+Tuning
+  --race-count <n>                   identical requests per race (default 8).
+  --race-attempts <n>                races to try before concluding (default 1).
+  --hang-ms <ms>                     how long a never-ending body is waited for (default 6000).
+  --format text|json                 report format (default text).
+  --help                             this text.
+
+Exit codes: 0 no findings (after suppressions) · 1 findings · 2 the run could not complete (crash, bad argument, app
+down, zero probes run, probes not run).`;
+
+const need = (cond, msg) => { if (!cond) throw new UsageError(msg); };
+
+const intFlag = (flag, text, min, max) => {
+  const n = Number(text);
+  need(text !== '' && Number.isInteger(n) && n >= min && n <= max, `${flag} wants a whole number between ${min} and ${max}, got "${text}".`);
+  return n;
+};
+
+// Git Bash and MSYS2 rewrite "/path" into a Windows path before node sees it. The path is restored when its prefix is a
+// known install root; a path given without the leading slash is also accepted.
+const unixRoots = (env) => [env.EXEPATH, env.MSYSTEM_PREFIX && resolve(env.MSYSTEM_PREFIX, '..'), 'C:\\msys64', 'C:\\msys32']
+  .filter(Boolean).map((p) => p.replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase());
+export const unmangle = (value, env = process.env) => {
+  const text = String(value);
+  if (!/^[A-Za-z]:[\\/]/.test(text)) return text;
+  const slashed = text.replace(/\\/g, '/');
+  for (const root of unixRoots(env)) if (slashed.toLowerCase().startsWith(`${root}/`)) return slashed.slice(root.length);
+  return slashed.replace(/^[A-Za-z]:\/.*?\/(?:Git|msys64|msys32)\//i, '/');
+};
+// A request path is printable ASCII: a space or a non-ASCII character would crash the HTTP client, so it is rejected here.
+export const toPath = (value, env) => {
+  const path = '/' + unmangle(value, env).replace(/^\/+/, '');
+  if (/[^\x21-\x7e]/.test(path)) throw new UsageError(`"${path}" is not a valid request path: percent-encode spaces and non-ASCII characters (a%20b).`);
+  return path;
+};
+
+const HEADER_NAME = /^[a-z0-9!#$%&'*+.^_`|~-]+$/;
+const headerInto = (target, line, flag) => {
+  const at = String(line).indexOf(':');
+  const key = String(line).slice(0, at).trim().toLowerCase();
+  need(at > 0 && HEADER_NAME.test(key), `${flag} wants "Name: value", got "${line}".`);
+  target[key] = String(line).slice(at + 1).trim();
+};
+
+export const readBodyFile = (name, cwd, flag) => {
+  try { return readFileSync(resolve(cwd, name), 'utf8').replace(/^\uFEFF/, '').trim(); }
+  catch (e) { throw new UsageError(`${flag}: cannot read the body file "${name}": ${e.code ?? e.message}`); }
+};
+
+// A body that looks like JSON (or is sent as a JSON media type) must parse: a mangled body never goes out silently.
+// Where a JSON parse error is, without the text around it (a file may hold secrets).
+export const errorPosition = (e) => {
+  const m = String(e.message).match(/position (\d+)(?: \(line (\d+) column (\d+)\))?/);
+  return m ? `at position ${m[1]}${m[2] ? ` (line ${m[2]}, column ${m[3]})` : ''}` : 'at an unknown position';
+};
+
+// `source` names a file when the body came from one: the message then shows the position, never the content.
+export const checkBody = (body, contentType, flag, source) => {
+  if (!body) return;
+  if (!/^[{[]/.test(body) && !/json/i.test(contentType ?? '')) return;
+  try { JSON.parse(body); } catch (e) {
+    throw new UsageError(source
+      ? `${flag}: ${source} is not valid JSON, ${errorPosition(e)}.`
+      : `${flag}: the body is not valid JSON, ${errorPosition(e)}.\nreceived: ${body.slice(0, 300)}\n`
+        + 'PowerShell 5.1 strips the quotes of inline JSON: put the body in a file and pass "<METHOD> <path> @body.json".');
+  }
+};
+
+export const requestSpec = (text, flag, { cwd, env, contentType }) => {
+  const [method, path, ...rest] = String(text ?? '').split(' ');
+  need(method && path, `${flag} wants "<METHOD> <path> <body>", got "${text ?? ''}".`);
+  need(/^[A-Za-z]+$/.test(method), `${flag}: "${method}" is not an HTTP method.`);
+  let body = rest.join(' ');
+  const fromFile = body.startsWith('@') ? body.slice(1) : null;
+  if (fromFile) body = readBodyFile(fromFile, cwd, flag);
+  checkBody(body, contentType, flag, fromFile && `the body file "${fromFile}"`);
+  return { method: method.toUpperCase(), path: toPath(path, env), body, contentType };
+};
+
+export const FLAGS_WITH_VALUE = new Set(['--write', '--read', '--search', '--unique', '--item-path', '--vary', '--content-type', '--header',
+  '--auth-env', '--auth-header-name', '--other-header', '--other-auth-env', '--common-headers', '--raw-exempt', '--body-limit', '--config',
+  '--fault-sqlite', '--persist-save', '--persist-verify', '--race-count', '--race-attempts',
+  '--hang-ms', '--format']);
+
+const LOOPBACK = /^(localhost|127(?:\.\d{1,3}){3}|\[::1\]|[\w-]+\.localhost)$/i;
+
+export const parseBase = (text, env = process.env) => {
+  need(/^https?:\/\//i.test(text ?? ''), 'The first argument is the base URL, e.g. http://127.0.0.1:3000.');
+  let base;
+  try { base = new URL(text); } catch { throw new UsageError(`"${text}" is not a valid URL.`); }
+  need(base.protocol === 'http:', 'Only plain http is supported: probe the app behind its TLS terminator.');
+  // Loopback is not "local": a tunnel (kubectl port-forward, ssh -L, a cloud SQL proxy) passes this check.
+  need(LOOPBACK.test(base.hostname) || env.HTTP_ATTACK_ALLOW_REMOTE === '1',
+    `${base.hostname} is not loopback. These probes create and delete data: run them only against an app you own.`);
+  return base;
+};
+
+export function parseArgs(argv, { cwd = process.cwd(), env = process.env } = {}) {
+  const opt = {
+    writes: [], reads: [], searches: [], uniques: [], common: [], headers: {}, otherHeaders: {}, authHeaderNames: [],
+    csrf: false, format: 'text', help: false, raceCount: 8, raceAttempts: 1, hangMs: 6000,
+  };
+  if (argv.includes('--help') || argv.includes('-h')) return { help: true, opt: { ...opt, help: true } };
+  const base = parseBase(argv[0], env);
+  // Bodies are parsed after the loop, so --content-type may come after --write.
+  const pendingRequests = [];
+  for (let i = 1; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === '--csrf') { opt.csrf = true; continue; }
+    need(FLAGS_WITH_VALUE.has(flag), `Unknown option ${flag}. See --help.`);
+    need(i + 1 < argv.length, `${flag} needs a value.`);
+    const value = argv[++i];
+    switch (flag) {
+      case '--write': pendingRequests.push(['writes', flag, value]); break;
+      case '--unique': pendingRequests.push(['uniques', flag, value]); break;
+      case '--read': opt.reads.push(toPath(value, env)); break;
+      case '--search': {
+        const [path, param] = unmangle(value, env).split(' ');
+        need(path && param, '--search wants "<path> <param>".');
+        opt.searches.push({ path: toPath(path, env), param });
+        break;
+      }
+      case '--header': headerInto(opt.headers, value, flag); break;
+      case '--other-header': headerInto(opt.otherHeaders, value, flag); break;
+      case '--auth-env': need(env[value], `--auth-env ${value}: the variable is empty or unset.`); opt.headers.authorization = `Bearer ${env[value]}`; break;
+      case '--other-auth-env': need(env[value], `--other-auth-env ${value}: the variable is empty or unset.`); opt.otherHeaders.authorization = `Bearer ${env[value]}`; break;
+      case '--auth-header-name': need(HEADER_NAME.test(value.toLowerCase()), `--auth-header-name: "${value}" is not a header name.`); opt.authHeaderNames.push(value.toLowerCase()); break;
+      case '--item-path': opt.itemPath = toPath(value, env); need(opt.itemPath.includes('{id}'), '--item-path must contain {id}.'); break;
+      case '--vary': opt.vary = value; break;
+      case '--content-type': need(/^[\w.+-]+\/[\w.+-]+/.test(value), `--content-type: "${value}" is not a media type.`); opt.contentType = value; break;
+      case '--common-headers': opt.common = value.split(',').map((h) => h.trim().toLowerCase()).filter(Boolean); break;
+      case '--raw-exempt': opt.rawExempt = value; break;
+      case '--body-limit': opt.bodyLimit = intFlag(flag, value, 16, 2 ** 31); break;
+      case '--config': opt.config = value; break;
+      case '--fault-sqlite': opt.faultSqlite = value; break;
+      case '--persist-save': opt.persistSave = value; break;
+      case '--persist-verify': opt.persistVerify = value; break;
+      case '--race-count': opt.raceCount = intFlag(flag, value, 2, 64); break;
+      case '--race-attempts': opt.raceAttempts = intFlag(flag, value, 1, 20); break;
+      case '--hang-ms': opt.hangMs = intFlag(flag, value, 100, 600_000); break;
+      case '--format': need(value === 'text' || value === 'json', `--format wants text or json, got "${value}".`); opt.format = value; break;
+      default: throw new UsageError(`Unknown option ${flag}.`);
+    }
+  }
+  need(!Object.keys(opt.otherHeaders).length || !Object.entries(opt.otherHeaders).every(([k, v]) => opt.headers[k] === v),
+    'The credentials for user B are the same credentials as user A: the ownership rows would prove nothing.');
+  for (const [list, flag, value] of pendingRequests) opt[list].push(requestSpec(value, flag, { cwd, env, contentType: opt.contentType }));
+  return { help: false, base, opt };
+}

package/skills/http-attack/scripts/lib/body.mjs

@@ -0,0 +1,101 @@
+// Request bodies: parsing, the per-run variation that keeps requests apart, and edits to one string field.
+
+export const FORM = 'application/x-www-form-urlencoded';
+export const JSON_TYPE = 'application/json';
+
+const RUN = Date.now().toString(36).slice(-5);
+let counter = 0;
+export const nextCounter = () => ++counter;
+
+// A value a format rule would reject if suffixed: no letters (a number, a date) or a UUID.
+const FORMATTED = /^[^\p{L}]*$|^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+const isFree = (v) => typeof v === 'string' && !FORMATTED.test(v);
+
+export const isJsonBody = (w) => /^\s*[{[]/.test(w.body) || /json/i.test(w.contentType ?? '');
+
+const unescapePointer = (s) => s.replace(/~1/g, '/').replace(/~0/g, '~');
+// "/item/email" or "item.email" or "email" => ['item','email']
+export const pointerPath = (p) => (p.startsWith('/') ? p.slice(1).split('/').map(unescapePointer) : p.split('.'));
+
+const getAt = (root, path) => path.reduce((o, k) => (o !== null && typeof o === 'object' ? o[k] : undefined), root);
+const setAt = (root, path, value) => {
+  const parent = getAt(root, path.slice(0, -1));
+  parent[path.at(-1)] = value;
+};
+
+// Every string leaf of a JSON value, as a path.
+const stringLeaves = (value, path = [], out = []) => {
+  if (typeof value === 'string') out.push(path);
+  else if (value && typeof value === 'object') for (const [k, v] of Object.entries(value)) stringLeaves(v, [...path, Array.isArray(value) ? Number(k) : k], out);
+  return out;
+};
+
+// The field that keeps requests apart: the explicit one, else the first free string containing @, else the first free string.
+const chooseVaryPath = (value, vary) => {
+  if (vary) {
+    const path = pointerPath(vary);
+    return typeof getAt(value, path) === 'string' ? path : null;
+  }
+  const leaves = stringLeaves(value).filter((p) => isFree(getAt(value, p)));
+  return leaves.find((p) => getAt(value, p).includes('@')) ?? leaves[0] ?? null;
+};
+const tagged = (v, tag) => (v.includes('@') ? v.replace('@', `${tag}@`) : `${v}${tag}`);
+
+// The legitimate body of a write with its varying field suffixed (`-<run><n>`, before the @ of an email), so a uniqueness
+// rule never answers in place of the defense under test, in this run or the next.
+// Returns { text, type, path, varied, error }; `path` is the string field the probes edit.
+export function wire(w, settings = {}, n = nextCounter()) {
+  const tag = `-${RUN}${n}`;
+  const type = w.contentType ?? settings.contentType ?? (isJsonBody(w) ? JSON_TYPE : FORM);
+  if (!isJsonBody(w)) {
+    const entries = [...new URLSearchParams(w.body)];
+    const key = settings.vary ? entries.find(([k]) => k === settings.vary)?.[0] : (entries.find(([, v]) => isFree(v) && v.includes('@')) ?? entries.find(([, v]) => isFree(v)))?.[0];
+    const out = entries.map(([k, v]) => [k, k === key ? tagged(v, tag) : v]);
+    return { text: new URLSearchParams(out).toString(), type, form: true, path: key ? [key] : null, varied: key !== undefined };
+  }
+  let value;
+  try { value = JSON.parse(w.body); } catch { return { text: w.body, type, path: null, varied: false, error: 'the body is not valid JSON' }; }
+  const path = chooseVaryPath(value, settings.vary);
+  if (path) setAt(value, path, tagged(getAt(value, path), tag));
+  const fieldPath = path ?? stringLeaves(value)[0] ?? null;
+  return { text: JSON.stringify(value), type, path: fieldPath, varied: path !== null, value,
+    error: settings.vary && !path ? `--vary "${settings.vary}" does not point at a string in the body` : undefined };
+}
+
+// The same wire body with one string field replaced by `make(current)`. Returns null when the body has no string field.
+export function withField(p, make) {
+  if (!p.path) return null;
+  if (p.form) {
+    const entries = [...new URLSearchParams(p.text)];
+    return new URLSearchParams(entries.map(([k, v]) => [k, k === p.path[0] ? make(v) : v])).toString();
+  }
+  const value = JSON.parse(p.text);
+  setAt(value, p.path, make(getAt(value, p.path)));
+  return JSON.stringify(value);
+}
+
+// Every string field of the wire body as a path (JSON only): wrong-type probes try them all.
+export const stringFields = (p) => (p.value && !p.form ? stringLeaves(p.value) : []);
+
+// The wire body with one string field replaced by a non-string value (JSON only).
+export function withValueAt(p, path, replacement) {
+  const value = JSON.parse(p.text);
+  setAt(value, path, replacement);
+  return JSON.stringify(value);
+}
+
+// The wire body with the field replaced by a non-string value (JSON only).
+export function withValue(p, replacement) {
+  if (!p.path || p.form) return null;
+  const value = JSON.parse(p.text);
+  setAt(value, p.path, replacement);
+  return JSON.stringify(value);
+}
+
+// Bytes of the body with a MARKER inside a string field, so raw bytes can replace it.
+export function splitAtField(p) {
+  const text = withField(p, () => 'MARKER');
+  return text === null ? null : text.split('MARKER');
+}
+
+export const caseVariant = (type) => `${type.split(';')[0].trim().replace(/(^|[/+.-])([a-z])/g, (m, sep, ch) => sep + ch.toUpperCase())}; charset=utf-8`;

package/skills/http-attack/scripts/lib/cli.mjs

@@ -0,0 +1,113 @@
+import { HELP, parseArgs } from './args.mjs';
+import { applyIgnores, loadConfig, unusedRoutes } from './config.mjs';
+import { UsageError } from './errors.mjs';
+import { createClient } from './http.mjs';
+import { EXIT } from './registry.mjs';
+import { exitCode, renderJson, renderText, summarize } from './report.mjs';
+import { Run } from './run.mjs';
+import { accessProbes, csrfProbes, inferTemplate, legitWrite, notRunDependents, readsWithoutCredentials } from './probes/auth.mjs';
+import { faultProbe } from './probes/fault.mjs';
+import { malformedInput } from './probes/input.mjs';
+import { parserProbes } from './probes/parser.mjs';
+import { pathProbes } from './probes/paths.mjs';
+import { checkPersistPath, persistSave, persistVerify } from './probes/persist.mjs';
+import { raceProbe } from './probes/race.mjs';
+import { resourceProbes } from './probes/resources.mjs';
+import { searchProbes } from './probes/search.mjs';
+
+const MAX_MISSING_LISTED = 10;
+
+// Command-line options and the config file, merged: the command line wins, lists are concatenated.
+function mergeOptions(opt, config) {
+  const lower = (list) => list.map((h) => String(h).trim().toLowerCase()).filter(Boolean);
+  return {
+    ...opt,
+    writes: [...config.writes, ...opt.writes],
+    uniques: [...config.uniques, ...opt.uniques],
+    reads: [...config.reads, ...opt.reads],
+    searches: [...config.searches, ...opt.searches],
+    common: opt.common.length ? opt.common : lower(config.commonHeaders ?? []),
+    rawExempt: opt.rawExempt ?? config.rawExempt,
+    faultCmd: config.faultCmd,
+    faultRestore: config.faultRestore,
+    authHeaderNames: [...new Set([...lower(config.authHeaderNames ?? []), ...opt.authHeaderNames])],
+    itemPath: opt.itemPath ?? config.itemPath,
+  };
+}
+
+async function runAll(run) {
+  const { opts, client } = run;
+  const first = await client.send('GET', '/', { common: false });
+  if (first.s === null) throw new UsageError(`The app does not answer at ${client.base.origin}: ${first.err}`);
+  run.itemPath = opts.itemPath;
+  run.itemTemplate = opts.itemPath;
+  run.state = {};
+
+  const ready = [];
+  const legits = new Map();
+  for (const w of opts.writes) {
+    const legit = await legitWrite(run, w);
+    legits.set(w, legit);
+    if (legit.ok && legit.item && !run.itemTemplate) run.itemTemplate = inferTemplate(legit.item, legit.res);
+    if (legit.ok) ready.push(w);
+    else notRunDependents(run, w, legit.res ? `answered ${legit.res.s}` : 'no usable answer');
+  }
+  // Before the probes that delete (IDOR) or store oversized rows, so the list still holds the legitimate rows.
+  const createdBodies = ready.map((w) => w.body);
+  for (const s of opts.searches) await searchProbes(run, s, createdBodies);
+  for (const w of ready) await accessProbes(run, w, legits.get(w));
+  await readsWithoutCredentials(run);
+  for (const w of ready) await malformedInput(run, w);
+  await pathProbes(run, { writes: opts.writes, itemTemplate: run.itemTemplate });
+  await parserProbes(run, { writes: opts.writes });
+  for (const w of ready) await resourceProbes(run, w);
+  for (const u of opts.uniques) await raceProbe(run, u);
+  if (opts.csrf) for (const w of ready) await csrfProbes(run, w);
+  if (opts.faultSqlite || opts.faultCmd) await faultProbe(run, ready[0]);
+
+  if (opts.common.length) {
+    const wanted = `every response carries ${opts.common.join(', ')}`;
+    const missing = client.missesByRoute(run.itemTemplate);
+    for (const [route, { headers, statuses }] of [...missing].sort(([x], [y]) => x.localeCompare(y))) {
+      const spec = { group: 'headers', probe: 'common-headers', target: route, name: `${route}: ${wanted}` };
+      run.fail('headers-missing', spec, [...statuses].join(','), wanted, `answered ${[...statuses].join(', ')} without ${[...headers].join(', ')}`);
+    }
+    if (!missing.size) run.pass({ group: 'headers', probe: 'common-headers', target: 'responses', name: wanted }, 'all', wanted);
+  }
+}
+
+// Returns the exit code; output goes through `io` so tests can capture it.
+export async function main(argv, io = {}) {
+  const out = io.stdout ?? ((s) => process.stdout.write(s));
+  const err = io.stderr ?? ((s) => process.stderr.write(s));
+  const env = io.env ?? process.env;
+  const cwd = io.cwd ?? process.cwd();
+  try {
+    const parsed = parseArgs(argv, { cwd, env });
+    if (parsed.help) { out(`${HELP}\n`); return EXIT.OK; }
+    const config = loadConfig(parsed.opt.config, { cwd, env });
+    const opts = mergeOptions(parsed.opt, config);
+    const client = createClient(parsed.base, opts);
+    const run = new Run({ client, opts, config });
+
+    if (opts.persistSave || opts.persistVerify) {
+      checkPersistPath(opts.persistSave ?? opts.persistVerify, config, cwd);
+      run.itemPath = opts.itemPath;
+      if (!(await client.alive())) throw new UsageError(`The app does not answer at ${parsed.base.origin}.`);
+      const result = opts.persistSave ? await persistSave(run, opts.persistSave) : await persistVerify(run, opts.persistVerify);
+      out(opts.format === 'json' ? `${JSON.stringify({ schemaVersion: 1, ok: result.ok, ...result.data }, null, 2)}\n` : `${result.message}\n`);
+      return result.ok ? EXIT.OK : EXIT.FINDINGS;
+    }
+
+    await runAll(run);
+    const unusedIgnores = applyIgnores(run.rows, config.ignore);
+    const summary = summarize(run.rows);
+    const report = { base: parsed.base.origin, rows: run.rows, summary, unusedIgnores, unusedRoutes: unusedRoutes(config) };
+    out(`${opts.format === 'json' ? renderJson(report) : renderText(report)}\n`);
+    return exitCode(summary);
+  } catch (e) {
+    if (e instanceof UsageError) err(`http-attack: ${e.message}\n`);
+    else err(`http-attack crashed: ${e?.stack ?? e}\n`);
+    return EXIT.ERROR;
+  }
+}

package/skills/http-attack/scripts/lib/config.mjs

@@ -0,0 +1,142 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { UsageError } from './errors.mjs';
+import { RULES } from './registry.mjs';
+import { checkBody, errorPosition, readBodyFile, toPath } from './args.mjs';
+
+export const DEFAULT_CONFIG_FILE = 'http-attack.config.json';
+
+// Settings that describe the app and may be given for every route at once.
+const GENERAL_KEYS = ['bodyLimit', 'maxHeaderBytes', 'invalidUtf8', 'vary', 'contentType'];
+// Settings that relax a check: only for one route, and only with the reason written down (they act as suppressions).
+const RELAXING_KEYS = ['public', 'idempotentCreate'];
+const ROUTE_KEYS = [...GENERAL_KEYS, ...RELAXING_KEYS, 'reason'];
+const TOP_KEYS = [...GENERAL_KEYS, 'routes', 'ignore', 'commonHeaders', 'rawExempt', 'authHeaderNames', 'itemPath', 'persistIgnore',
+  'persistDir', 'faultCmd', 'faultRestore', 'writes', 'reads', 'searches', 'uniques'];
+
+const fail = (file, msg) => { throw new UsageError(`${file}: ${msg}`); };
+
+const checkRoute = (file, where, s, { top }) => {
+  if (s === null || typeof s !== 'object' || Array.isArray(s)) fail(file, `${where} must be an object.`);
+  const known = top ? GENERAL_KEYS : ROUTE_KEYS;
+  for (const k of Object.keys(s)) {
+    if (top && (RELAXING_KEYS.includes(k) || k === 'reason')) fail(file, `${where}: "${k}" is only allowed inside "routes", for one route, with a "reason".`);
+    if (!known.includes(k)) fail(file, `${where}: unknown setting "${k}" (known: ${known.join(', ')}).`);
+  }
+  for (const k of RELAXING_KEYS) if (k in s && typeof s[k] !== 'boolean') fail(file, `${where}.${k} must be true or false.`);
+  if (!top && RELAXING_KEYS.some((k) => s[k] === true) && !(typeof s.reason === 'string' && s.reason.trim())) {
+    fail(file, `${where} sets ${RELAXING_KEYS.filter((k) => s[k]).join('/')} and needs a non-empty "reason".`);
+  }
+  for (const k of ['bodyLimit', 'maxHeaderBytes']) if (k in s && !(Number.isInteger(s[k]) && s[k] > 0)) fail(file, `${where}.${k} must be a positive integer.`);
+  if ('invalidUtf8' in s && !['reject', 'replace'].includes(s.invalidUtf8)) fail(file, `${where}.invalidUtf8 must be "reject" or "replace".`);
+  for (const k of ['vary', 'contentType', 'reason']) if (k in s && typeof s[k] !== 'string') fail(file, `${where}.${k} must be a string.`);
+};
+
+const requestOf = (file, where, r, cwd, env) => {
+  if (!r || typeof r !== 'object' || typeof r.path !== 'string') fail(file, `${where} needs a "path".`);
+  let body = r.body ?? '';
+  const fromFile = typeof body === 'string' && body.startsWith('@') ? body.slice(1) : null;
+  if (typeof body === 'object') body = JSON.stringify(body);
+  else if (fromFile) body = readBodyFile(fromFile, cwd, `${file} ${where}`);
+  else if (typeof body !== 'string') fail(file, `${where}.body must be an object, a string or "@file".`);
+  checkBody(body, r.contentType, `${file} ${where}`, fromFile && `the body file "${fromFile}"`);
+  return { method: String(r.method ?? 'POST').toUpperCase(), path: toPath(r.path, env), body, contentType: r.contentType };
+};
+
+// An ignore id is a finding id or a prefix ending in *, always starting with a known rule: a bare "*" silences everything.
+const checkIgnore = (file, entry, i) => {
+  if (typeof entry?.id !== 'string' || !entry.id.trim()) fail(file, `ignore[${i}] needs an "id" (a finding id, a rule name, or "<rule>:<prefix>*").`);
+  if (typeof entry.reason !== 'string' || !entry.reason.trim()) fail(file, `ignore[${i}] ("${entry.id}") needs a non-empty "reason": a suppression without a reason is not accepted.`);
+  const rule = entry.id.split(':')[0];
+  if (!(rule in RULES)) fail(file, `ignore[${i}]: "${entry.id}" does not start with a known rule (known: ${Object.keys(RULES).join(', ')}).`);
+  if (rule === 'not-run' && !/^not-run:[^*:]/.test(entry.id)) fail(file, `ignore[${i}]: "${entry.id}" would hide every probe that could not run: name the probe, as "not-run:<probe>" or "not-run:<probe>:<target>".`);
+};
+
+export function loadConfig(file, { cwd = process.cwd(), env = process.env } = {}) {
+  const explicit = file !== undefined;
+  const path = resolve(cwd, file ?? DEFAULT_CONFIG_FILE);
+  const empty = { settings: {}, routes: {}, usedRoutes: new Set(), ignore: [], persistIgnore: [], writes: [], reads: [], searches: [], uniques: [], path: null };
+  if (!explicit && !existsSync(path)) return empty;
+  let raw;
+  try { raw = readFileSync(path, 'utf8').replace(/^\uFEFF/, ''); } catch (e) { fail(path, `cannot read the config file: ${e.code ?? e.message}`); }
+  let json;
+  try { json = JSON.parse(raw); } catch (e) { fail(path, `not valid JSON, ${errorPosition(e)}.`); }
+  if (json === null || typeof json !== 'object' || Array.isArray(json)) fail(path, 'the top level must be an object.');
+  for (const k of Object.keys(json)) {
+    if (TOP_KEYS.includes(k)) continue;
+    if (ROUTE_KEYS.includes(k)) fail(path, `"${k}" is only allowed inside "routes", for one route, with a "reason".`);
+    fail(path, `unknown key "${k}" (known: ${TOP_KEYS.join(', ')}).`);
+  }
+  checkRoute(path, 'top level', Object.fromEntries(Object.entries(json).filter(([k]) => GENERAL_KEYS.includes(k))), { top: true });
+  const routes = {};
+  for (const [k, v] of Object.entries(json.routes ?? {})) {
+    checkRoute(path, `routes["${k}"]`, v, { top: false });
+    const m = k.match(/^([A-Za-z]+) (.+)$/);
+    routes[m ? `${m[1].toUpperCase()} ${toPath(m[2], env)}` : toPath(k, env)] = v;
+  }
+  const ignore = json.ignore ?? [];
+  if (!Array.isArray(ignore)) fail(path, '"ignore" must be a list.');
+  ignore.forEach((entry, i) => checkIgnore(path, entry, i));
+  for (const k of ['faultCmd', 'faultRestore', 'persistDir']) if (k in json && typeof json[k] !== 'string') fail(path, `"${k}" must be a string.`);
+  if (json.faultRestore && !json.faultCmd) fail(path, '"faultRestore" needs "faultCmd".');
+  const list = (k) => { const v = json[k] ?? []; if (!Array.isArray(v)) fail(path, `"${k}" must be a list.`); return v; };
+  const requests = (k) => list(k).map((r, i) => requestOf(path, `${k}[${i}]`, r, cwd, env));
+  return {
+    path,
+    settings: Object.fromEntries(Object.entries(json).filter(([k]) => GENERAL_KEYS.includes(k))),
+    routes,
+    usedRoutes: new Set(),
+    ignore,
+    persistIgnore: list('persistIgnore'),
+    persistDir: json.persistDir ? resolve(cwd, json.persistDir) : undefined,
+    faultCmd: json.faultCmd, faultRestore: json.faultRestore,
+    commonHeaders: json.commonHeaders, rawExempt: json.rawExempt, authHeaderNames: json.authHeaderNames, itemPath: json.itemPath,
+    writes: requests('writes'), uniques: requests('uniques'),
+    reads: list('reads').map((r) => toPath(r, env)),
+    searches: list('searches').map((s, i) => {
+      if (typeof s?.path !== 'string' || typeof s.param !== 'string') fail(path, `searches[${i}] needs "path" and "param".`);
+      return { path: toPath(s.path, env), param: s.param };
+    }),
+  };
+}
+
+// A route key matches a path literally, or as a template: "/items/{id}" matches "/items/42".
+const keyMatches = (keyPath, path) => keyPath === path
+  || (keyPath.includes('{') && new RegExp(`^${keyPath.split(/\{[^}]*\}/).map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('[^/]+')}$`).test(path));
+
+// Settings for one route: top-level defaults, then the matching path keys, then "METHOD path"; the command line wins over the defaults.
+export const routeSettings = (config, flags, method, path) => {
+  const bare = path.split('?')[0];
+  const merged = {
+    ...config.settings,
+    ...(flags.bodyLimit ? { bodyLimit: flags.bodyLimit } : {}),
+    ...(flags.vary ? { vary: flags.vary } : {}),
+  };
+  const take = (key) => { config.usedRoutes?.add(key); Object.assign(merged, config.routes[key]); };
+  const keys = Object.keys(config.routes);
+  for (const key of keys) if (!/^[A-Z]+ /.test(key) && keyMatches(key, bare)) take(key);
+  for (const key of keys) {
+    const m = key.match(/^([A-Z]+) (.+)$/);
+    if (m && m[1] === method.toUpperCase() && keyMatches(m[2], bare)) take(key);
+  }
+  return merged;
+};
+
+export const unusedRoutes = (config) => Object.keys(config.routes).filter((k) => !config.usedRoutes.has(k));
+
+// A pattern is an id, a rule, "<rule>:<probe>" (every target of that probe) or an id prefix ending in *.
+const matches = (pattern, row) => pattern === row.id || pattern === row.rule || row.id.startsWith(`${pattern}:`)
+  || (pattern.endsWith('*') && row.id.startsWith(pattern.slice(0, -1)));
+
+// A suppression keeps the row, marked with its reason; it no longer counts as a finding or a gap.
+export function applyIgnores(rows, ignore) {
+  const used = new Set();
+  for (const row of rows) {
+    if (row.verdict !== 'fail' && row.verdict !== 'not-run') continue;
+    const hit = ignore.find((entry) => matches(entry.id, row));
+    if (!hit) continue;
+    used.add(hit);
+    Object.assign(row, { was: row.verdict, verdict: 'suppressed', suppressedBy: hit.reason });
+  }
+  return ignore.filter((entry) => !used.has(entry));
+}

package/skills/http-attack/scripts/lib/errors.mjs

@@ -0,0 +1,2 @@
+// A problem with how the tool was invoked or configured. The CLI reports it and exits 2.
+export class UsageError extends Error {}