wize-dev-kit 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ Format inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.6.0] — 2026-06-20
+
+### Added
+
+- **`security-overlay` — AI Pentester (novo profile opcional).** Pipeline file-first de pentest que roda no harness do usuário (zero runtime próprio, zero dependência npm nova). Selecionável no instalador como `security-overlay`.
+  - **Persona `red-teamer`** + orquestradora `wize-sec-pentest` que encadeia recon → enumerate → SAST → DAST → report.
+  - **Gate de escopo** (`.wize/security/scope.md`, allowlist assinada com SHA-256): toda ação ofensiva é verificada por fase; alvo fora do escopo é recusado e auditado em `.refusals.log`. Default passivo; exploit ativo só com `--active`.
+  - **Allowlist de flags por ferramenta** (`data/tool-allowlist.json`): `--dump`/`--os-shell` e afins nunca chegam ao `execFile`, independente do input.
+  - **SAST**: secrets via gitleaks (com redação `***REDACTED***`) + dependências vulneráveis via osv-scanner/grype (CVE + CVSS).
+  - **DAST**: nuclei, nikto (safe checks), sqlmap e ffuf (content discovery), gated por `--active` quando ofensivos.
+  - **CVSS v3.1** zero-dep + tagger **OWASP Top 10 (2021)**.
+  - **Relatório** `report.md` + `report.html` self-contained (CSS inline, offline, WCAG 2.2 AA): risk score 0–100, briefing executivo, plano de ação P0/P1/P2, cobertura honesta do teste (audit confidence), recomendação por finding.
+  - **AI insights**: o renderer consome `ai-insights.json` escrito pelo LLM do harness (briefing + recomendações), sem chamada externa — dados ficam locais.
+  - **Preflight** (Epic 08): detecta SO/arch/package-manager e gera `install-pentest-tools.sh` com a fonte correta por ferramenta (apt para nmap/nikto/sqlmap; GitHub release para gitleaks/nuclei/ffuf/osv-scanner; script oficial para grype).
+- Documentação completa do overlay em `.wize/planning` e `.wize/solutioning` (brief, PRD, tech-vision, NFR, architecture, 4 ADRs, 8 epics, 26+ stories).
+
 ## [0.5.0] — 2026-06-17
 
 ### Added

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wize-dev-kit",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Full-lifecycle AI-assisted development kit with Test Architect and Whiteport Design Studio embedded. Inspired by BMAD Method and WDS.",
   "keywords": [
     "ai",

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

@@ -0,0 +1,154 @@
+'use strict';
+
+// allowlist.js — gate that filters arguments for an external pentest tool
+// before they are passed to child_process.execFile. The list of allowed
+// flags per tool lives in src/security-overlay/data/tool-allowlist.json.
+//
+// Schema (per tool, array of strings):
+//   "-foo"        switch with no value
+//   "-foo:"       switch that consumes the next argv as its value
+//   "-foo=bar"    switch with a fixed value (only the literal "bar" is allowed)
+//   "--flag="     switch that consumes a value joined by '=' (e.g. --level=1)
+//
+// Invariant: args NOT in the allowlist (or args that look like values for
+// flags not in the allowlist) are dropped. Positional args (targets, URLs)
+// pass through unchanged.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class UnknownToolError extends Error {
+  constructor(tool) {
+    super(`Unknown tool "${tool}" — not in tool-allowlist.json. Refusing to invoke.`);
+    this.name = 'UnknownToolError';
+    this.tool = tool;
+  }
+}
+
+const DEFAULT_ALLOWLIST_PATH = path.join(__dirname, '..', 'data', 'tool-allowlist.json');
+
+let _cache = null;
+function _loadDefault() {
+  if (_cache) return _cache;
+  const raw = fs.readFileSync(DEFAULT_ALLOWLIST_PATH, 'utf8');
+  _cache = JSON.parse(raw);
+  return _cache;
+}
+
+function loadAllowlist(filePath) {
+  const fp = filePath || DEFAULT_ALLOWLIST_PATH;
+  return JSON.parse(fs.readFileSync(fp, 'utf8'));
+}
+
+// Heuristic for "is this arg a flag?": starts with '-' and is more than 1 char
+// (a bare "-" is sometimes used as stdin, treat as positional).
+function isFlag(arg) {
+  return typeof arg === 'string' && arg.length > 1 && arg[0] === '-';
+}
+
+// Classify one allowlist token into one of:
+//   { kind: 'switch' }                       — no value
+//   { kind: 'colon',   prefix: '-foo' }      — consumes next argv (e.g. -f path)
+//   { kind: 'equals',  prefix: '--flag=' }   — consumes value joined by '=' (e.g. --level=1)
+//   { kind: 'literal', full: '-foo=bar' }    — only the exact form is allowed
+//
+// When matching an arg, we try in order: literal, then colon (exact prefix
+// match, e.g. arg === '-u'), then equals (arg starts with prefix, e.g.
+// arg === '--level=1'), then switch (exact equality).
+function classify(token) {
+  if (token.endsWith(':')) {
+    return { kind: 'colon', prefix: token.slice(0, -1) };
+  }
+  if (token.endsWith('=') && token.startsWith('--')) {
+    return { kind: 'equals', prefix: token };
+  }
+  if (token.includes('=') && !token.endsWith('=')) {
+    return { kind: 'literal', full: token };
+  }
+  return { kind: 'switch' };
+}
+
+// Given a flag arg, find the first allowlist token that matches it.
+function matchFlag(toolData, arg) {
+  // Literal first (most specific).
+  for (const tok of toolData) {
+    if (classify(tok).kind === 'literal' && arg === tok) return { consumeNext: false };
+  }
+  // Then colon (exact prefix match) — e.g. arg === '-u'.
+  for (const tok of toolData) {
+    if (classify(tok).kind === 'colon' && arg === classify(tok).prefix) return { consumeNext: true };
+  }
+  // Then equals — e.g. arg starts with '--level='.
+  for (const tok of toolData) {
+    if (classify(tok).kind === 'equals' && arg.startsWith(classify(tok).prefix)) return { consumeNext: false };
+  }
+  // Then switch.
+  for (const tok of toolData) {
+    if (classify(tok).kind === 'switch' && tok === arg) return { consumeNext: false };
+  }
+  return null;
+}
+
+// filterArgs(tool, args, allowlist) — keep only args allowed by the tool's
+// allowlist, handling value-bearing flags correctly.
+function filterArgs(tool, args, allowlist) {
+  const data = allowlist || _loadDefault();
+  if (!Object.prototype.hasOwnProperty.call(data, tool)) {
+    throw new UnknownToolError(tool);
+  }
+  const toolData = data[tool];
+
+  const out = [];
+  let i = 0;
+  const list = args || [];
+  while (i < list.length) {
+    const arg = list[i];
+    if (!isFlag(arg)) {
+      // Positional: target, URL, output path.
+      out.push(arg);
+      i++;
+      continue;
+    }
+    const m = matchFlag(toolData, arg);
+    if (!m) {
+      // Unknown flag — drop the flag. We do NOT also drop the next arg,
+      // because a positional after a stripped flag is still a positional
+      // (caller may have intended both to pass). However, common patterns
+      // are value-bearing: e.g. `--script vuln` — if the flag is dropped,
+      // "vuln" is also dropped to avoid leaking. This is the safe default.
+      if (looksLikeValueArg(list[i + 1])) {
+        // Consume the next arg as part of the dropped flag's expected value.
+        i += 2;
+      } else {
+        i++;
+      }
+      continue;
+    }
+    out.push(arg);
+    if (m.consumeNext) {
+      // Value-bearing: the next argv is the value. Pass it through.
+      if (i + 1 < list.length) {
+        out.push(list[i + 1]);
+        i += 2;
+      } else {
+        i++;
+      }
+    } else {
+      i++;
+    }
+  }
+  return out;
+}
+
+// A value arg is one that does NOT start with '-' (or is the bare "-").
+function looksLikeValueArg(arg) {
+  return arg !== undefined && (typeof arg !== 'string' || arg.length === 0 || arg[0] !== '-');
+}
+
+module.exports = {
+  filterArgs,
+  loadAllowlist,
+  UnknownToolError,
+  classify,
+  matchFlag
+};

package/src/security-overlay/_shared/cli-runner.js

@@ -0,0 +1,87 @@
+'use strict';
+
+// cli-runner.js — small helper so each phase script can be invoked
+// either as a module (import + call) or as a CLI (with --securityDir /
+// --scope / --active argv). The invoke-phase helper spawns the script
+// as a Node subprocess; this module bridges that to the per-phase
+// `runX` function exported by each script.
+//
+// Usage from a script:
+//   const { runX } = require('./run-x');
+//   module.exports = { runX };
+//   if (require.main === module) {
+//     require('../../../_shared/cli-runner.js').runFromArgv({
+//       fn: runX,
+//       argMap: { securityDir: 'securityDir', scopePath: 'scopePath', active: 'active' }
+//     });
+//   }
+//
+// argv shape: --securityDir=PATH --scope=PATH --active [script-specific]
+// The function `fn` is called with the parsed object spread.
+
+function parseArgv(argv) {
+  const out = {};
+  for (let i = 0; i < (argv || []).length; i++) {
+    const a = argv[i];
+    if (a === '--active') { out.active = true; continue; }
+    const eq = a.indexOf('=');
+    if (eq > 0) {
+      const key = a.slice(0, eq).replace(/^--/, '');
+      const val = a.slice(eq + 1);
+      out[camel(key)] = val;
+      continue;
+    }
+    if (a.startsWith('--') && i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+      out[camel(a.slice(2))] = argv[i + 1];
+      i++;
+    }
+  }
+  return out;
+}
+
+function camel(s) {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+async function runFromArgv({ fn, argMap = {} }) {
+  const argv = process.argv.slice(2);
+  const parsed = parseArgv(argv);
+  // Map --securityDir -> securityDir, --scope -> scopePath, etc.
+  const opts = {};
+  for (const [cliKey, optKey] of Object.entries(argMap)) {
+    if (cliKey in parsed) opts[optKey] = parsed[cliKey];
+  }
+  // Also accept any unprefixed camelCase keys directly.
+  for (const [k, v] of Object.entries(parsed)) {
+    if (!(k in opts)) opts[k] = v;
+  }
+  if (!('active' in opts)) opts.active = false;
+  // The phase script may also export its own CLI flags (--target for recon).
+  // We forward remaining --flags as a target-agnostic extraArgs-style list.
+  const extras = {};
+  for (const a of argv) {
+    if (a === '--active') continue;
+    const m = a.match(/^--([a-z0-9-]+)/);
+    if (m && !argMap[m[1]] && !argMap[camel(m[1])]) {
+      // Stash any flag the script might want to read itself.
+      extras[m[1]] = a.includes('=') ? a.slice(a.indexOf('=') + 1) : true;
+    }
+  }
+  Object.assign(opts, extras);
+  try {
+    const r = await fn(opts);
+    if (r && typeof r === 'object') {
+      // Print a one-line summary the orchestrator can show in its summary.
+      const summary = r.partialStatus
+        ? `${process.argv[1].split('/').pop().replace(/\.js$/, '')}: partial_status=${r.partialStatus} mode=${r.mode || 'passive'}`
+        : '';
+      if (summary) process.stdout.write(summary + '\n');
+    }
+    process.exit(0);
+  } catch (e) {
+    process.stderr.write(`✖ ${process.argv[1]}: ${e && e.message ? e.message : e}\n`);
+    process.exit(2);
+  }
+}
+
+module.exports = { parseArgv, runFromArgv };

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
+};