wize-dev-kit 0.4.1 → 0.6.0

package/src/security-overlay/_shared/cvss.js

@@ -0,0 +1,108 @@
+'use strict';
+
+// cvss.js — zero-dep CVSS v3.1 score calculator. Implements the official
+// formula from FIRST.org. Tested against the 5 canonical vectors from
+// the spec. Returns the base score (0.0-10.0) and the severity label.
+
+class InvalidVectorError extends Error {
+  constructor(message) { super(message); this.name = 'InvalidVectorError'; }
+}
+
+// --- metric value tables (per CVSS v3.1 spec) -----------------------------
+
+const AV = { N: 0.85, A: 0.62, L: 0.55, P: 0.2 };
+const AC = { L: 0.77, H: 0.44 };
+const PR_U = { N: 0.85, L: 0.62, H: 0.27 };  // PR and UI share values when scope=U
+const PR_C = { N: 0.85, L: 0.68, H: 0.5 };   // PR changes when scope=C
+const UI_U = { N: 0.85, R: 0.62 };
+const UI_C = { N: 0.85, R: 0.68 };
+const CIA = { H: 0.56, L: 0.22, N: 0 };
+
+// --- parse --------------------------------------------------------------
+
+function parse(vector) {
+  if (typeof vector !== 'string') throw new InvalidVectorError('vector must be a string');
+  let v = vector.trim();
+  if (v.startsWith('CVSS:3.1/')) v = v.slice('CVSS:3.1/'.length);
+  if (v.startsWith('CVSS:3.0/')) throw new InvalidVectorError('CVSS v3.0 vectors are not supported');
+
+  const m = {};
+  for (const part of v.split('/')) {
+    const idx = part.indexOf(':');
+    if (idx < 0) throw new InvalidVectorError(`bad metric segment: ${part}`);
+    const key = part.slice(0, idx);
+    const val = part.slice(idx + 1);
+    if (val.length !== 1) throw new InvalidVectorError(`bad metric value: ${val}`);
+    m[key] = val;
+  }
+
+  // Validate required metrics.
+  for (const k of ['AV', 'AC', 'PR', 'UI', 'S', 'C', 'I', 'A']) {
+    if (!(k in m)) throw new InvalidVectorError(`missing metric: ${k}`);
+  }
+  // Validate values.
+  if (!(m.AV in AV)) throw new InvalidVectorError(`invalid AV: ${m.AV}`);
+  if (!(m.AC in AC)) throw new InvalidVectorError(`invalid AC: ${m.AC}`);
+  if (!(m.PR in { N: 1, L: 1, H: 1 })) throw new InvalidVectorError(`invalid PR: ${m.PR}`);
+  if (!(m.UI in { N: 1, R: 1 })) throw new InvalidVectorError(`invalid UI: ${m.UI}`);
+  if (!(m.S in { U: 1, C: 1 })) throw new InvalidVectorError(`invalid S: ${m.S}`);
+  for (const k of ['C', 'I', 'A']) {
+    if (!(m[k] in CIA)) throw new InvalidVectorError(`invalid ${k}: ${m[k]}`);
+  }
+  // Scope C requires PR/UI to be in the {N,L,H}/{N,R} sets.
+  if (m.S === 'C' && !(m.PR in { N: 1, L: 1, H: 1 })) {
+    throw new InvalidVectorError(`invalid PR for scope C: ${m.PR}`);
+  }
+  return m;
+}
+
+// --- formula ------------------------------------------------------------
+
+function roundUpTo1Decimal(n) {
+  // CVSS rounds UP to 1 decimal place. JS banker rounding rounds half to
+  // even, which is wrong for CVSS — we use ceiling-to-1-decimal.
+  return Math.ceil(n * 10) / 10;
+}
+
+function compute(vector) {
+  const m = parse(vector);
+  const scopeChanged = m.S === 'C';
+  const PR = scopeChanged ? PR_C[m.PR] : PR_U[m.PR];
+  const UI = scopeChanged ? UI_C[m.UI] : UI_U[m.UI];
+
+  // Impact.
+  const issBase = 1 - ((1 - CIA[m.C]) * (1 - CIA[m.I]) * (1 - CIA[m.A]));
+  let impact = scopeChanged
+    ? 7.52 * (issBase - 0.029) - 3.25 * Math.pow(issBase - 0.02, 15)
+    : 6.42 * issBase;
+  if (impact < 0) impact = 0;
+  impact = roundUpTo1Decimal(impact);
+
+  // Exploitability.
+  const exploit = 8.22 * AV[m.AV] * AC[m.AC] * PR * UI;
+  const explRounded = roundUpTo1Decimal(exploit);
+
+  // Base score.
+  let base;
+  if (impact <= 0) {
+    base = 0;
+  } else if (scopeChanged) {
+    base = 1.08 * (impact + explRounded);
+  } else {
+    base = impact + explRounded;
+  }
+  base = roundUpTo1Decimal(base);
+  if (base > 10) base = 10;
+
+  return { score: base, severity: severityFromScore(base) };
+}
+
+function severityFromScore(score) {
+  if (score === 0) return 'None';
+  if (score < 4.0) return 'Low';
+  if (score < 7.0) return 'Medium';
+  if (score < 9.0) return 'High';
+  return 'Critical';
+}
+
+module.exports = { compute, severityFromScore, parse, InvalidVectorError };

package/src/security-overlay/_shared/detect.js

@@ -0,0 +1,125 @@
+'use strict';
+
+// detect.js — cache-aware detector for external pentest tools.
+//
+// detectTools(names, { cacheDir }) -> { name: { present, path?, version? } }
+//   - present = false when the tool is not on PATH (the common case for users
+//     who haven't installed the toolchain yet). detectTools NEVER throws on
+//     a missing tool — the calling skill is expected to degrade gracefully.
+//   - path    = full path to the binary (when present).
+//   - version = best-effort version string from `<bin> --version`; null if
+//     the version probe failed (timeout, non-zero exit, no output).
+//
+// The result is cached at <cacheDir>/.tools.json so a long pipeline
+// (recon -> enumerate -> exploit -> report) calls `command -v` at most
+// once per tool per session. The overlay is single-threaded per
+// invocation, so we don't lock the cache file.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync, spawnSync } = require('node:child_process');
+
+const CACHE_FILENAME = '.tools.json';
+const VERSION_TIMEOUT_MS = 2000;
+
+function cachePath(cacheDir) {
+  return path.join(cacheDir || path.join(process.cwd(), '.wize', 'security'), CACHE_FILENAME);
+}
+
+function readCache(cacheDir) {
+  const p = cachePath(cacheDir);
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_) {
+    return {};
+  }
+}
+
+function writeCache(cacheDir, data) {
+  const dir = cacheDir || path.join(process.cwd(), '.wize', 'security');
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(cachePath(cacheDir), JSON.stringify(data, null, 2), 'utf8');
+  } catch (_) {
+    // best-effort; a write failure does not invalidate the in-memory result
+  }
+}
+
+function which(name) {
+  // Use `command -v` (POSIX) — returns 0 and prints the path if found.
+  // Falls back to `which` for systems without `command` (Windows cmd).
+  try {
+    const r = spawnSync('command', ['-v', name], { encoding: 'utf8', timeout: 1000 });
+    if (r.status === 0 && r.stdout) {
+      return r.stdout.split('\n')[0].trim();
+    }
+  } catch (_) { /* fall through */ }
+  try {
+    const r = spawnSync('which', [name], { encoding: 'utf8', timeout: 1000 });
+    if (r.status === 0 && r.stdout) return r.stdout.split('\n')[0].trim();
+  } catch (_) { /* fall through */ }
+  return null;
+}
+
+function probeVersion(binPath) {
+  // Try the most common version flags in order. Each is a separate probe;
+  // a failure is non-fatal (we return null).
+  const flags = ['--version', '-version', '-V', 'version'];
+  for (const f of flags) {
+    try {
+      const out = execFileSync(binPath, [f], {
+        encoding: 'utf8',
+        timeout: VERSION_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'ignore']
+      });
+      const first = (out || '').split('\n')[0].trim();
+      if (first) return first.slice(0, 120);
+    } catch (_) {
+      // try next flag
+    }
+  }
+  return null;
+}
+
+function probeOne(name) {
+  const p = which(name);
+  if (!p) return { present: false };
+  return { present: true, path: p, version: probeVersion(p) };
+}
+
+// detectTools(names, opts?) -> { name: {present, path?, version?} }
+// opts.cacheDir: where to read/write the cache file (default .wize/security).
+function detectTools(names, opts = {}) {
+  const cacheDir = opts.cacheDir;
+  const cache = readCache(cacheDir);
+  const out = {};
+  let mutated = false;
+
+  for (const name of names || []) {
+    if (cache[name]) {
+      out[name] = cache[name];
+      continue;
+    }
+    const entry = probeOne(name);
+    out[name] = entry;
+    cache[name] = entry;
+    mutated = true;
+  }
+
+  if (mutated) writeCache(cacheDir, cache);
+  return out;
+}
+
+function clearToolCache(opts = {}) {
+  const p = cachePath(opts.cacheDir);
+  try {
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  } catch (_) { /* ignore */ }
+}
+
+module.exports = {
+  detectTools,
+  clearToolCache,
+  CACHE_FILENAME
+};

package/src/security-overlay/_shared/install-script.js

@@ -0,0 +1,205 @@
+'use strict';
+
+// install-script.js — generates a self-contained install script for the
+// security-overlay pentest tools, using the CORRECT install source per
+// tool. Most security tools are NOT in apt/brew: they are Go binaries
+// shipped as GitHub releases. Treating everything as a PM package
+// produces a script that fails (apt has no `gitleaks`/`nuclei`/`ffuf`/
+// `osv-scanner`/`grype`). So each tool declares its real method:
+//
+//   - 'pm'       : available in the OS package manager (nmap, nikto, sqlmap, curl)
+//   - 'github'   : a GitHub release asset (gitleaks, nuclei, ffuf, osv-scanner)
+//   - 'script'   : an official installer script (grype)
+//
+// The generated bash script is idempotent and installs only what's missing.
+
+const HEADER = `#!/usr/bin/env bash
+# security-overlay — install pentest tools
+# Generated by wize-sec-preflight. Safe to re-run (idempotent).
+#
+# Most of these tools are NOT in apt/brew — they are GitHub release
+# binaries. This script installs each from its correct source.
+# GitHub binaries go to ~/.local/bin (no sudo needed for those).
+set -euo pipefail
+
+LOCAL_BIN="\${HOME}/.local/bin"
+mkdir -p "\${LOCAL_BIN}"
+case ":\${PATH}:" in
+  *":\${LOCAL_BIN}:"*) : ;;
+  *) echo "NOTE: add \${LOCAL_BIN} to your PATH (e.g. in ~/.bashrc):"
+     echo '      export PATH="$HOME/.local/bin:$PATH"' ;;
+esac
+
+# Detect arch for GitHub release downloads.
+ARCH="$(uname -m)"
+case "\${ARCH}" in
+  x86_64|amd64) GH_ARCH="amd64"; GH_ARCH_ALT="x64" ;;
+  aarch64|arm64) GH_ARCH="arm64"; GH_ARCH_ALT="arm64" ;;
+  *) GH_ARCH="amd64"; GH_ARCH_ALT="x64" ;;
+esac
+OS_LC="$(uname -s | tr '[:upper:]' '[:lower:]')"
+
+# Helper: download a tar.gz GitHub release and install one binary from it.
+gh_targz() { # $1=url $2=binary-name-inside-archive
+  local url="$1" bin="$2" tmp
+  tmp="$(mktemp -d)"
+  echo "  ↓ \${bin} <- \${url}"
+  curl -fsSL "\${url}" -o "\${tmp}/a.tgz"
+  tar -xzf "\${tmp}/a.tgz" -C "\${tmp}"
+  install -m 0755 "\${tmp}/\${bin}" "\${LOCAL_BIN}/\${bin}"
+  rm -rf "\${tmp}"
+}
+
+gh_zip() { # $1=url $2=binary-name-inside-archive
+  local url="$1" bin="$2" tmp
+  tmp="$(mktemp -d)"
+  echo "  ↓ \${bin} <- \${url}"
+  curl -fsSL "\${url}" -o "\${tmp}/a.zip"
+  unzip -q -o "\${tmp}/a.zip" -d "\${tmp}"
+  install -m 0755 "\${tmp}/\${bin}" "\${LOCAL_BIN}/\${bin}"
+  rm -rf "\${tmp}"
+}
+`;
+
+// Per-tool install recipe. Versions are pinned to known-good releases; the
+// user can bump them. {GH_ARCH}/{GH_ARCH_ALT}/{OS} are substituted by the
+// bash script's own variables at run time (we emit them as shell vars).
+const TOOL_RECIPES = {
+  // --- package-manager tools ---
+  nmap:   { via: 'pm' },
+  nikto:  { via: 'pm' },
+  sqlmap: { via: 'pm' },
+  curl:   { via: 'pm' },
+
+  // --- GitHub release binaries ---
+  gitleaks: {
+    via: 'github',
+    // gitleaks_8.18.4_linux_x64.tar.gz  (note: x64/arm64, not amd64)
+    cmd: 'gh_targz "https://github.com/gitleaks/gitleaks/releases/download/v8.18.4/gitleaks_8.18.4_${OS_LC}_${GH_ARCH_ALT}.tar.gz" gitleaks'
+  },
+  nuclei: {
+    via: 'github',
+    // nuclei_3.3.7_linux_amd64.zip
+    cmd: 'gh_zip "https://github.com/projectdiscovery/nuclei/releases/download/v3.3.7/nuclei_3.3.7_${OS_LC}_${GH_ARCH}.zip" nuclei'
+  },
+  ffuf: {
+    via: 'github',
+    // ffuf_2.1.0_linux_amd64.tar.gz
+    cmd: 'gh_targz "https://github.com/ffuf/ffuf/releases/download/v2.1.0/ffuf_2.1.0_${OS_LC}_${GH_ARCH}.tar.gz" ffuf'
+  },
+  'osv-scanner': {
+    via: 'github',
+    // osv-scanner_linux_amd64 (raw binary, not archived)
+    cmd: 'echo "  ↓ osv-scanner"; curl -fsSL "https://github.com/google/osv-scanner/releases/download/v2.0.2/osv-scanner_${OS_LC}_${GH_ARCH}" -o "${LOCAL_BIN}/osv-scanner"; chmod 0755 "${LOCAL_BIN}/osv-scanner"'
+  },
+
+  // --- official installer script ---
+  grype: {
+    via: 'script',
+    cmd: 'curl -fsSL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b "${LOCAL_BIN}"'
+  }
+};
+
+const TOOL_URLS = {
+  nmap: 'https://nmap.org/download.html',
+  nuclei: 'https://github.com/projectdiscovery/nuclei',
+  gitleaks: 'https://github.com/gitleaks/gitleaks',
+  'osv-scanner': 'https://github.com/google/osv-scanner',
+  grype: 'https://github.com/anchore/grype',
+  nikto: 'https://github.com/sullo/nikto',
+  sqlmap: 'https://github.com/sqlmapproject/sqlmap',
+  ffuf: 'https://github.com/ffuf/ffuf'
+};
+
+const PM_INSTALL = {
+  apt:        (pkgs) => `sudo apt-get update && sudo apt-get install -y ${pkgs.join(' ')}`,
+  dnf:        (pkgs) => `sudo dnf install -y ${pkgs.join(' ')}`,
+  pacman:     (pkgs) => `sudo pacman -Syu --noconfirm ${pkgs.join(' ')}`,
+  zypper:     (pkgs) => `sudo zypper install -y ${pkgs.join(' ')}`,
+  apk:        (pkgs) => `sudo apk add ${pkgs.join(' ')}`,
+  brew:       (pkgs) => `brew install ${pkgs.join(' ')}`,
+  scoop:      (pkgs) => `scoop install ${pkgs.join(' ')}`,
+  chocolatey: (pkgs) => `choco install -y ${pkgs.join(' ')}`
+};
+
+function generateInstallScript(preflight) {
+  const { os, arch, packageManager, missing = [] } = preflight;
+  const lines = [HEADER];
+
+  lines.push(`# OS: ${os} (${arch})`);
+  lines.push(`# Package manager: ${packageManager || 'none'}`);
+  lines.push(`# Missing tools: ${missing.length === 0 ? '(none)' : missing.join(', ')}`);
+  lines.push('');
+
+  if (missing.length === 0) {
+    lines.push('echo "All tools are already installed. Nothing to do."');
+    return lines.join('\n');
+  }
+
+  // Bucket the missing tools by install method.
+  const pmTools = [];
+  const ghTools = [];
+  const scriptTools = [];
+  const unknownTools = [];
+  for (const tool of missing) {
+    const r = TOOL_RECIPES[tool];
+    if (!r) { unknownTools.push(tool); continue; }
+    if (r.via === 'pm') pmTools.push(tool);
+    else if (r.via === 'github') ghTools.push(tool);
+    else if (r.via === 'script') scriptTools.push(tool);
+  }
+
+  // 1. Package-manager tools (need a known PM).
+  if (pmTools.length) {
+    const pmFn = PM_INSTALL[packageManager];
+    if (pmFn) {
+      lines.push(`echo "==> Installing via ${packageManager}: ${pmTools.join(', ')}"`);
+      lines.push(pmFn(pmTools));
+    } else {
+      lines.push(`echo "==> These need a package manager (none detected): ${pmTools.join(', ')}"`);
+      for (const t of pmTools) lines.push(`echo "    ${t}: ${TOOL_URLS[t] || ''}"`);
+    }
+    lines.push('');
+  }
+
+  // 2. GitHub release binaries.
+  if (ghTools.length) {
+    lines.push(`echo "==> Installing GitHub-release binaries to \${LOCAL_BIN}: ${ghTools.join(', ')}"`);
+    for (const t of ghTools) {
+      lines.push(TOOL_RECIPES[t].cmd);
+    }
+    lines.push('');
+  }
+
+  // 3. Official installer scripts.
+  if (scriptTools.length) {
+    lines.push(`echo "==> Installing via official scripts: ${scriptTools.join(', ')}"`);
+    for (const t of scriptTools) {
+      lines.push(TOOL_RECIPES[t].cmd);
+    }
+    lines.push('');
+  }
+
+  // 4. Anything we don't have a recipe for.
+  if (unknownTools.length) {
+    lines.push(`echo "==> Manual install required for: ${unknownTools.join(', ')}"`);
+    for (const t of unknownTools) {
+      lines.push(`echo "    ${t}: ${TOOL_URLS[t] || 'https://www.google.com/search?q=' + encodeURIComponent(t + ' install')}"`);
+    }
+    lines.push('');
+  }
+
+  // Verification.
+  lines.push('echo ""');
+  lines.push('echo "==> Verifying..."');
+  for (const tool of missing) {
+    lines.push(`command -v ${tool} >/dev/null 2>&1 && echo "  ✓ ${tool}" || echo "  ✗ ${tool} (not on PATH yet)"`);
+  }
+  lines.push('');
+  lines.push('echo "Done. If any tool shows ✗, ensure ~/.local/bin is on your PATH and re-open the shell."');
+  lines.push('echo "Then run /wize-sec-pentest."');
+
+  return lines.join('\n');
+}
+
+module.exports = { generateInstallScript, TOOL_RECIPES, TOOL_URLS, PM_INSTALL };

package/src/security-overlay/_shared/invoke-phase.js

@@ -0,0 +1,86 @@
+'use strict';
+
+// invoke-phase.js — single point that spawns a phase skill as a Node
+// subprocess. The orchestrator (wize-sec-pentest) calls invokePhase to
+// run each phase in sequence. Failures return {ok:false, code} — the
+// orchestrator decides whether to continue or abort.
+//
+// Security invariants (enforced by the canary test in
+// test/security-overlay/invoke-phase.test.js):
+//   - NEVER uses shell:true (no command-injection escape).
+//   - Skill names cannot escape the kit root via path traversal.
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes per phase
+
+// resolvePhaseScript(skill, { kitRoot }) -> absolute path.
+// Convention: src/security-overlay/skills/<skill>/scripts/<last-segment>.js
+// E.g. wize-sec-recon -> .../skills/wize-sec-recon/scripts/recon.js.
+// The path is computed even if the file does not exist (callers that want
+// to verify existence should call fs.existsSync on the result).
+function resolvePhaseScript(skill, opts = {}) {
+  if (typeof skill !== 'string' || !skill) return null;
+  // Reject anything that tries to escape via ../
+  if (skill.includes('..') || skill.includes('/') || skill.includes('\\') || path.isAbsolute(skill)) {
+    throw new Error(`phase-skill-name-traversal: refused ${JSON.stringify(skill)}`);
+  }
+  const kitRoot = opts.kitRoot || path.resolve(__dirname, '..', '..', '..');
+  // Convention: src/security-overlay/skills/<skill>/scripts/<scriptName>
+  // where scriptName is the explicit opts.scriptName (must include .js)
+  // if given, otherwise 'run-<lastSegment>.js'.
+  const scriptName = opts.scriptName || `run-${skill.split('-').pop()}.js`;
+  return path.join(kitRoot, 'src', 'security-overlay', 'skills', skill, 'scripts', scriptName);
+}
+
+// invokePhase(skill, opts) -> Promise<{ok, code, stdout, stderr, error?}>.
+// opts: { kitRoot?, active?, extraArgs?: string[], timeout?: ms }
+// Does NOT throw on subprocess failure — returns {ok:false, code, error}.
+function invokePhase(skill, opts = {}) {
+  return new Promise(resolve => {
+    let script;
+    try {
+      script = resolvePhaseScript(skill, opts);
+    } catch (e) {
+      return resolve({ ok: false, code: -1, stdout: '', stderr: '', error: String(e.message || e) });
+    }
+    if (!script || !fs.existsSync(script)) {
+      return resolve({ ok: false, code: -1, stdout: '', stderr: '', error: `phase script not found for ${skill}` });
+    }
+
+    const argv = [];
+    if (opts.active) argv.push('--active');
+    if (opts.securityDir) argv.push(`--securityDir=${opts.securityDir}`);
+    if (opts.scopePath) argv.push(`--scope=${opts.scopePath}`);
+    if (Array.isArray(opts.extraArgs)) argv.push(...opts.extraArgs);
+
+    const child = spawn(process.execPath, [script, ...argv], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // shell: false is the default in spawn(); we do not set it.
+      timeout: opts.timeout || DEFAULT_TIMEOUT_MS
+    });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', d => { stdout += d.toString(); });
+    child.stderr.on('data', d => { stderr += d.toString(); });
+
+    child.on('error', err => {
+      resolve({ ok: false, code: -1, stdout, stderr, error: String(err.message || err) });
+    });
+    child.on('close', code => {
+      resolve({ ok: code === 0, code: code == null ? -1 : code, stdout, stderr });
+    });
+  });
+}
+
+// Exposed for tests that need to introspect the spawn call.
+function _spawnForTest(...args) { return spawn(...args); }
+
+module.exports = {
+  invokePhase,
+  resolvePhaseScript,
+  _spawnForTest
+};

package/src/security-overlay/_shared/owasp.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// owasp.js — maps a finding (rule id / cve / poc) to an OWASP Top 10 (2021)
+// category. Zero-dep: the category table is loaded from
+// src/security-overlay/data/owasp-top10.json.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DATA_PATH = path.join(__dirname, '..', 'data', 'owasp-top10.json');
+
+let _cache = null;
+function _load() {
+  if (_cache) return _cache;
+  const raw = fs.readFileSync(DATA_PATH, 'utf8');
+  const parsed = JSON.parse(raw);
+  _cache = parsed.categories || [];
+  return _cache;
+}
+
+function listOwaspCategories() {
+  return _load().slice();
+}
+
+function listOwaspCategoryIds() {
+  return _load().map(c => c.id);
+}
+
+// Ordered rules: the FIRST match wins. We check cve before generic rule
+// because a finding with a CVE is unambiguously A06 (vulnerable components).
+const RULES = [
+  { match: f => !!f.cve,                                 to: 'A06:2021' },
+  { match: f => /sqli|sql[-_ ]?injection|injection/i.test(f.rule || ''), to: 'A03:2021' },
+  { match: f => /\bxss\b/i.test(f.rule || ''),           to: 'A03:2021' },
+  { match: f => /\bauth[-_ ]?bypass|auth[-_ ]?bypass|session/i.test(f.rule || ''), to: 'A07:2021' },
+  { match: f => /\btls|cert|cipher|\bssl\b/i.test(f.rule || ''), to: 'A02:2021' },
+  { match: f => /\bcors|\bcsp|headers?|\bhttponly/i.test(f.rule || ''), to: 'A05:2021' },
+  { match: f => /\bexposed|\bdisclosed|server-status|admin\b/i.test(f.rule || ''), to: 'A05:2021' },
+  { match: f => /\bssrf|redirect/i.test(f.rule || ''),   to: 'A10:2021' }
+];
+
+function tagOwasp(finding) {
+  if (!finding || typeof finding !== 'object') return 'UNKNOWN';
+  for (const r of RULES) {
+    try {
+      if (r.match(finding)) return r.to;
+    } catch (_) { /* defensive: never throw from a tagger */ }
+  }
+  return 'UNKNOWN';
+}
+
+module.exports = {
+  tagOwasp,
+  listOwaspCategories,
+  listOwaspCategoryIds
+};