wize-dev-kit 0.16.0 → 0.17.0

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

@@ -0,0 +1,175 @@
+'use strict';
+
+// preflight.js — detects the host environment (OS/arch/package manager)
+// and which tools from data/tool-allowlist.json are installed.
+//
+// Test hook: when WIZE_SEC_PREFLIGHT_OS, WIZE_SEC_PREFLIGHT_PM, and
+// WIZE_SEC_PREFLIGHT_TOOLS (JSON) env vars are set, the real probes
+// are skipped and the values are returned directly. This lets tests
+// simulate Mac/Linux/Windows-WSL without actually running `which` etc.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync, spawnSync } = require('node:child_process');
+
+const ALLOWLIST_PATH = path.join(__dirname, '..', 'data', 'tool-allowlist.json');
+
+function readToolNames() {
+  try {
+    const data = JSON.parse(fs.readFileSync(ALLOWLIST_PATH, 'utf8'));
+    // Skip _schema and any non-array fields.
+    return Object.keys(data).filter(k => k !== '_schema' && Array.isArray(data[k]));
+  } catch (_) {
+    return [];
+  }
+}
+
+function detectOS() {
+  if (process.env.WIZE_SEC_PREFLIGHT_OS) return process.env.WIZE_SEC_PREFLIGHT_OS;
+  const platform = os.platform();
+  if (platform === 'linux') {
+    // Detect WSL by reading /proc/version for "Microsoft" or "WSL".
+    try {
+      const v = fs.readFileSync('/proc/version', 'utf8');
+      if (/microsoft|wsl/i.test(v)) return 'wsl';
+    } catch (_) { /* not linux */ }
+    return 'linux';
+  }
+  if (platform === 'darwin') return 'darwin';
+  if (platform === 'win32') return 'win32';
+  return 'linux';
+}
+
+function detectArch() {
+  if (process.env.WIZE_SEC_PREFLIGHT_ARCH) return process.env.WIZE_SEC_PREFLIGHT_ARCH;
+  return process.arch; // 'x64' | 'arm64' | 'ia32' etc.
+}
+
+function detectPackageManager(os) {
+  if (process.env.WIZE_SEC_PREFLIGHT_PM) return process.env.WIZE_SEC_PREFLIGHT_PM;
+  // Check for the most common PMs in order.
+  const candidates = {
+    linux: ['apt', 'dnf', 'pacman', 'zypper', 'apk'],
+    wsl:   ['apt', 'dnf', 'pacman'],
+    darwin: ['brew'],
+    win32: ['scoop', 'chocolatey']
+  };
+  const list = candidates[os] || [];
+  for (const pm of list) {
+    const cmds = { apt: 'apt', dnf: 'dnf', pacman: 'pacman', zypper: 'zypper', apk: 'apk', brew: 'brew', scoop: 'scoop', chocolatey: 'choco' }[pm];
+    try {
+      execFileSync(cmds, ['--version'], { stdio: 'ignore' });
+      return pm;
+    } catch (_) { /* not present */ }
+  }
+  return 'none';
+}
+
+function whichCommand(os) {
+  // 'command -v' on POSIX, 'where' on Windows.
+  if (os === 'win32') return 'where';
+  return 'command';
+}
+
+function whichArg(os) {
+  if (os === 'win32') return [];
+  return ['-v'];
+}
+
+function probeWhich(name, os) {
+  try {
+    const r = spawnSync(whichCommand(os), [...whichArg(os), name], { encoding: 'utf8', timeout: 2000 });
+    if (r.status === 0 && r.stdout) {
+      return r.stdout.split('\n')[0].trim();
+    }
+  } catch (_) { /* not present */ }
+  return null;
+}
+
+function probeVersion(binPath, os) {
+  // Try common version flags. Each is a separate probe; failure is non-fatal.
+  const flags = ['--version', '-version', '-V', 'version'];
+  for (const f of flags) {
+    try {
+      const out = execFileSync(binPath, [f], { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] });
+      const first = (out || '').split('\n')[0].trim();
+      if (first) return first.slice(0, 120);
+    } catch (_) { /* try next */ }
+  }
+  return null;
+}
+
+function detectTools(os) {
+  const names = readToolNames();
+  const tools = {};
+  // Initialize all tools as missing.
+  for (const n of names) tools[n] = { present: false };
+  // Test hook: parse the JSON env var. The hook marks the listed tools as
+  // present; everything else stays missing.
+  if (process.env.WIZE_SEC_PREFLIGHT_TOOLS) {
+    try {
+      const m = JSON.parse(process.env.WIZE_SEC_PREFLIGHT_TOOLS);
+      for (const [name, path] of Object.entries(m)) {
+        if (!(name in tools)) tools[name] = { present: !!path, path: path || undefined, version: null };
+        else {
+          tools[name] = { present: !!path, path: path || undefined, version: null };
+        }
+      }
+    } catch (_) { /* fall through to real detection */ }
+    return tools;
+  }
+  // Real detection.
+  for (const name of names) {
+    const p = probeWhich(name, os);
+    if (!p) {
+      tools[name] = { present: false };
+    } else {
+      tools[name] = { present: true, path: p, version: probeVersion(p, os) };
+    }
+  }
+  return tools;
+}
+
+function runPreflight(opts = {}) {
+  const os_ = detectOS();
+  const arch = detectArch();
+  const pm = detectPackageManager(os_);
+  const tools = detectTools(os_);
+  const missing = Object.entries(tools).filter(([, v]) => !v.present).map(([k]) => k);
+  return {
+    os: os_,
+    arch,
+    packageManager: pm,
+    tools,
+    missing,
+    node: process.version,
+    nodePath: process.execPath
+  };
+}
+
+function formatReport(p) {
+  const present = Object.entries(p.tools).filter(([, v]) => v.present);
+  const lines = [];
+  lines.push(`OS: ${p.os} (${p.arch})`);
+  lines.push(`Package manager: ${p.packageManager || 'none'}`);
+  lines.push(`Node: ${p.node}`);
+  lines.push('');
+  lines.push(`Tools: ${present.length} present, ${p.missing.length} missing`);
+  if (present.length) {
+    lines.push('  present:');
+    for (const [name, info] of present) {
+      const v = info.version ? ` — ${info.version}` : '';
+      lines.push(`    ✓ ${name}${v}`);
+    }
+  }
+  if (p.missing.length) {
+    lines.push('  missing:');
+    for (const name of p.missing) lines.push(`    ✗ ${name}`);
+    lines.push('');
+    lines.push('Run the install script (see .wize/security/install-pentest-tools.sh) to add the missing tools.');
+  }
+  return lines.join('\n');
+}
+
+module.exports = { runPreflight, formatReport, readToolNames };

package/src/security-overlay/_shared/scope-gate.js

@@ -0,0 +1,172 @@
+'use strict';
+
+// scope-gate.js — single point that decides whether an offensive tool may run
+// against a given target. ADR-001: this module is THE gate; skills must call
+// assertTargetInScope before any execFile.
+//
+// Refusals (returns false) are logged to .wize/security/.refusals.log with
+// ISO-8601 timestamp + target + reason. Scope validation errors (ScopeError)
+// propagate — they signal an invalid scope, not a refused action.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const {
+  parseScope,
+  validateScope,
+  ScopeError
+} = require('./scope-parser.js');
+
+const REFSUAL_LOG_FILENAME = '.refusals.log';
+
+// --- body parsing --------------------------------------------------------
+
+// Parse the body of a scope.md into a structured allowlist. We accept the
+// shape defined in ADR-002:
+//
+//   ## allowlist
+//   hosts:
+//     - localhost
+//     - 127.0.0.1
+//   urls:
+//     - https://staging.example.internal/api/
+//   paths:
+//     - /api
+//
+// Zero-dep: each list block is matched line-by-line under its `## allowlist`
+// heading until the next `##` heading or EOF. Empty / missing blocks yield
+// empty arrays (which makes EVERY target fail the allowlist — fail-closed).
+function parseAllowlist(body) {
+  const out = { hosts: [], urls: [], paths: [] };
+  const lines = String(body || '').split('\n');
+  let section = null;
+  let key = null;
+  for (const line of lines) {
+    const h = line.match(/^##\s+([a-zA-Z_][a-zA-Z0-9_-]*)/);
+    if (h) {
+      section = h[1] === 'allowlist' ? 'allowlist' : null;
+      key = null;
+      continue;
+    }
+    if (section !== 'allowlist') continue;
+    const km = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*$/);
+    if (km) {
+      const k = km[1];
+      if (k === 'hosts' || k === 'urls' || k === 'paths') key = k;
+      else key = null;
+      continue;
+    }
+    const lm = line.match(/^\s+-\s+(.+?)\s*$/);
+    if (lm && key) {
+      out[key].push(lm[1]);
+    }
+  }
+  return out;
+}
+
+// --- matching ------------------------------------------------------------
+
+function matchHost(allowlist, host) {
+  return allowlist.hosts.some(h => h === host);
+}
+
+function matchUrl(allowlist, url) {
+  // Normalize by stripping trailing slashes so 'http://x/' and 'http://x'
+  // match the same prefix.
+  const norm = s => String(s || '').replace(/\/+$/, '');
+  const target = norm(url);
+  return allowlist.urls.some(prefix => target.startsWith(norm(prefix)));
+}
+
+function matchPath(allowlist, p) {
+  // The path must equal or start with one of the allowlisted paths.
+  return allowlist.paths.some(ap => p === ap || p.startsWith(ap.endsWith('/') ? ap : ap + '/'));
+}
+
+// --- public api ----------------------------------------------------------
+
+// loadScope(scopePath) — load + parse + validate. On error: log refusal
+// (best-effort) and rethrow. The caller (a skill) aborts on throw.
+function loadScope(scopePath) {
+  if (!fs.existsSync(scopePath)) {
+    // Cannot log refusal without a known scope directory; rely on caller.
+    throw new ScopeError('MISSING_FILE', null,
+      `scope.md ausente em ${scopePath} — crie e assine em .wize/security/scope.md antes de rodar o pipeline`);
+  }
+  const text = fs.readFileSync(scopePath, 'utf8');
+  const scope = parseScope(text);
+  validateScope(scope);
+  return scope;
+}
+
+// assertTargetInScope(scope, target, { refusalsDir }) -> boolean.
+// On refusal, writes a line to <refusalsDir>/.refusals.log and returns false.
+// Throws ScopeError if `scope` itself is invalid (HASH_MISMATCH, etc.) —
+// callers should treat that as abort-the-pipeline.
+function assertTargetInScope(scope, target, opts = {}) {
+  const refusalsDir = opts.refusalsDir || path.join(process.cwd(), '.wize', 'security');
+
+  // Validate the scope up front so any tampering is surfaced loudly. We
+  // also log the attempt before re-throwing — an invalid scope is itself
+  // a refusal event that must appear in the audit trail.
+  try {
+    validateScope(scope);
+  } catch (err) {
+    if (err && err.code) {
+      logRefusal(refusalsDir, target || {}, `${err.code}: ${String(err.message || '').slice(0, 200)}`);
+    }
+    throw err;
+  }
+
+  const allowlist = parseAllowlist(scope.body);
+
+  // Evaluate each provided dimension of the target. A dimension is "in scope"
+  // iff it matches an allowlist entry. If the caller provides multiple
+  // dimensions (e.g. {host, url}), all of them must match.
+  const checks = [];
+  if (target.host) checks.push({ ok: matchHost(allowlist, target.host), why: 'host not in allowlist' });
+  if (target.url)  checks.push({ ok: matchUrl(allowlist, target.url),   why: 'url not in allowlist' });
+  if (target.path) checks.push({ ok: matchPath(allowlist, target.path), why: 'path not in allowlist' });
+
+  if (checks.length === 0) {
+    // Defensive: refusing a target we can't classify is the safe default.
+    logRefusal(refusalsDir, target, 'no target dimension provided');
+    return false;
+  }
+
+  const allIn = checks.every(c => c.ok);
+  if (!allIn) {
+    const reason = checks.filter(c => !c.ok).map(c => c.why).join('; ');
+    logRefusal(refusalsDir, target, reason);
+    return false;
+  }
+  return true;
+}
+
+// logRefusal(refusalsDir, target, reason) — append a YAML line to
+// .wize/security/.refusals.log. Best-effort: never throws (a logging failure
+// must not mask the refusal that caused it).
+function logRefusal(refusalsDir, target, reason) {
+  try {
+    fs.mkdirSync(refusalsDir, { recursive: true });
+    const file = path.join(refusalsDir, REFSUAL_LOG_FILENAME);
+    const entry = [
+      '-',
+      `  timestamp: ${new Date().toISOString()}`,
+      ...Object.entries(target || {}).map(([k, v]) => `  ${k}: ${String(v).replace(/\n/g, ' ')}`),
+      `  reason: ${String(reason || 'unspecified').replace(/\n/g, ' ')}`
+    ].join('\n') + '\n';
+    fs.appendFileSync(file, entry, 'utf8');
+  } catch (_) {
+    // Intentionally swallow — refusing to crash the caller is more important
+    // than refusing to log. The gate decision (return false) is what matters.
+  }
+}
+
+module.exports = {
+  loadScope,
+  assertTargetInScope,
+  logRefusal,
+  parseAllowlist,
+  ScopeError
+};

package/src/security-overlay/_shared/scope-parser.js

@@ -0,0 +1,147 @@
+'use strict';
+
+// scope-parser.js — file-first parser/validator for `.wize/security/scope.md`.
+//
+// Format (ADR-002):
+//   ---
+//   accepted_by: <string>
+//   accepted_at: <ISO-8601>
+//   scope_sha256: <hex SHA-256 of the body below>
+//   ---
+//
+//   ## allowlist
+//   ...
+//
+// This module is the single source of truth for parsing + validating the
+// scope. Skills that touch offensive tools must call loadScope() and abort
+// on any ScopeError.
+
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+
+class ScopeError extends Error {
+  constructor(code, field, message) {
+    super(message || `${code}${field ? ` (${field})` : ''}`);
+    this.name = 'ScopeError';
+    this.code = code;
+    this.field = field || null;
+  }
+}
+
+const REQUIRED_FIELDS = ['accepted_by', 'accepted_at', 'scope_sha256'];
+
+// Split a `scope.md` text into { frontmatter, body }.
+// The frontmatter is the YAML block delimited by `---` lines at the very top.
+// We do NOT use a YAML library (zero-dep); we accept a flat `key: value` shape
+// only, which is the entire scope of this overlay's frontmatter (ADR-002).
+function parseScope(mdText) {
+  if (typeof mdText !== 'string' || !mdText.startsWith('---\n') && mdText !== '---') {
+    throw new ScopeError('INVALID_FORMAT', null,
+      'scope.md must start with a YAML frontmatter block (--- on line 1)');
+  }
+  // Normalize: accept either "---\n...\n---\n\nbody" or "---\n...\n---\nbody".
+  // The trailing \n after the closing --- is part of the separator, NOT the body.
+  // This is what the user signs when they run --sign-scope (and what they
+  // expect when the hash is computed on the body they wrote).
+  const fmMatch = mdText.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!fmMatch) {
+    throw new ScopeError('INVALID_FORMAT', null,
+      'scope.md frontmatter is missing or not terminated by a second --- line');
+  }
+  const fmText = fmMatch[1];
+  const body = mdText.slice(fmMatch[0].length);
+
+  const frontmatter = {};
+  for (const line of fmText.split('\n')) {
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*?)\s*$/);
+    if (!m) continue;
+    frontmatter[m[1]] = m[2].replace(/^['"]|['"]$/g, ''); // strip wrapping quotes
+  }
+
+  return { frontmatter, body };
+}
+
+// Validate a parsed scope. Returns true on success; throws ScopeError otherwise.
+// opts: { now?: Date } — for future `accepted_at` warning. Currently unused but
+// reserved so we can add a warn() channel without breaking callers.
+function validateScope(scope, opts = {}) {
+  if (!scope || typeof scope !== 'object') {
+    throw new ScopeError('INVALID_FORMAT', null, 'scope is not an object');
+  }
+  const fm = scope.frontmatter || {};
+  for (const field of REQUIRED_FIELDS) {
+    if (!fm[field] || typeof fm[field] !== 'string' || fm[field].trim() === '') {
+      throw new ScopeError('MISSING_FIELDS', field,
+        `scope.md frontmatter is missing required field "${field}" — ` +
+        `crie e assine com "wize-sec-pentest --sign-scope" ou preencha manualmente`);
+    }
+  }
+
+  // Hash integrity. Compute SHA-256 of the body and compare to scope_sha256.
+  // We re-parse the body as-is (already stripped of frontmatter) — the original
+  // signing was done on the raw body bytes, so byte-equality matters.
+  const expected = computeScopeSha256(scope.body || '');
+  if (expected !== fm.scope_sha256) {
+    throw new ScopeError('HASH_MISMATCH', 'scope_sha256',
+      `scope.md body was modified after acceptance (expected ${expected.slice(0, 12)}…, ` +
+      `got ${String(fm.scope_sha256).slice(0, 12)}…) — re-assine com "wize-sec-pentest --sign-scope"`);
+  }
+
+  // Soft check: accepted_at in the future is a warning, not an error.
+  // We don't surface the warning through this function (no logger plumbed
+  // here); consumers can inspect frontmatter.accepted_at themselves.
+
+  return true;
+}
+
+function computeScopeSha256(bodyText) {
+  return crypto.createHash('sha256').update(String(bodyText || ''), 'utf8').digest('hex');
+}
+
+// Read + parse + validate a scope.md file. The single entry point used by
+// every offensive skill (AC-E02-1, AC-E02-3).
+function loadScope(scopePath) {
+  if (!fs.existsSync(scopePath)) {
+    throw new ScopeError('MISSING_FILE', null,
+      `scope.md ausente em ${scopePath} — crie e assine em .wize/security/scope.md antes de rodar o pipeline`);
+  }
+  const text = fs.readFileSync(scopePath, 'utf8');
+  const scope = parseScope(text);
+  validateScope(scope);
+  return scope;
+}
+
+// signScope(scopePath) — read, parse, recompute SHA-256 of the body, and
+// rewrite the scope_sha256 field in the frontmatter. Returns metadata about
+// the signed scope. Throws ScopeError on missing file or invalid format.
+// Idempotent: running twice on the same body produces the same hash.
+function signScope(scopePath) {
+  if (!fs.existsSync(scopePath)) {
+    throw new ScopeError('MISSING_FILE', null,
+      `scope.md ausente em ${scopePath} — crie com wize-sec-scope antes de assinar`);
+  }
+  const text = fs.readFileSync(scopePath, 'utf8');
+  const scope = parseScope(text);
+
+  const newHash = computeScopeSha256(scope.body);
+
+  // Replace scope_sha256 within the frontmatter block only (avoid
+  // accidental matches in the body).
+  const fmMatch = text.match(/^---\n([\s\S]*?)\n---\n/);
+  const fmBlock = fmMatch[0];
+  const newFmBlock = fmBlock.replace(/^(scope_sha256:\s*).*$/m, `$1${newHash}`);
+  const newText = text.replace(fmBlock, newFmBlock);
+
+  fs.writeFileSync(scopePath, newText, 'utf8');
+
+  return { path: scopePath, sha256: newHash, accepted_by: scope.frontmatter.accepted_by };
+}
+
+module.exports = {
+  parseScope,
+  validateScope,
+  computeScopeSha256,
+  loadScope,
+  signScope,
+  ScopeError
+};

package/src/security-overlay/agents/red-teamer/agent.yaml

@@ -0,0 +1,54 @@
+code: wize-sec-red-teamer
+name: Natasha Romanoff
+title: Security Overlay — Red-Teamer
+icon: "🕷️"
+team: software-development
+module: security-overlay
+phase: "4-implementation (per-project, gated)"
+
+description: |
+  Natasha Romanoff is the red-teamer — the offensive pentester for the
+  security-overlay. Drives the recon -> enumerate -> exploit -> report
+  pipeline against targets the user has explicitly authorized in
+  .wize/security/scope.md. Runs inside the user's AI harness — never as a
+  remote service.
+
+style:
+  voice: "pragmatic, direct, no-flourish pentester"
+  brevity: "high — finding + impact + PoC"
+  approach: "always asks: is this in scope, and do I have --active?"
+
+overlay: security
+
+skills:
+  - wize-sec-pentest
+  - wize-sec-scope
+
+commands:
+  - /wize-sec-pentest
+  - /wize-sec-scope
+
+inputs:
+  - ".wize/security/scope.md (gate of authorization)"
+  - ".wize/security/.tools.json (detection cache)"
+  - ".wize/security/.refusals.log (audit trail of refusals)"
+
+outputs:
+  - ".wize/security/recon.md"
+  - ".wize/security/enumerate.md"
+  - ".wize/security/sast.md"
+  - ".wize/security/dast.md"
+  - ".wize/security/report.md"
+  - ".wize/security/report.html"
+
+hand_off:
+  to_tea: |
+    Findings of severity High or Critical should be reviewable by
+    Hawkeye/TEA in the implementation gate of the security-overlay
+    itself. Natasha's results (the red-teamer's findings) are inputs to
+    the user's security review, NOT a substitute for it.
+
+non_negotiables:
+  - "Default passive — never run an offensive tool without scope + --active."
+  - "Findings of secrets list file+line; the secret VALUE never appears in report.html."
+  - "Refusals are audited to .wize/security/.refusals.log (no silent failure)."

package/src/security-overlay/agents/red-teamer/persona.md

@@ -0,0 +1,49 @@
+# Natasha Romanoff — Red-Teamer (Security Overlay)
+
+## Identity
+
+I am **Natasha Romanoff**, the red-teamer. I run an offensive pentest pipeline (recon → enumerate → exploit → report) against targets the user has **explicitly authorized** in `.wize/security/scope.md`. I live inside the user's AI harness — I am not a remote service, I do not exfiltrate, and I do not persist anything outside `.wize/security/`.
+
+I am a pentester who respects the scope. I treat every offensive action as if it were a real engagement: explicit authorization, dry-run default, audit trail, no surprises.
+
+## What I do
+
+| Phase | Tooling | Output |
+|---|---|---|
+| **recon** | nmap | `recon.md` (ports, services) |
+| **enumerate** | nuclei (passive), curl probing | `enumerate.md` (endpoints, tech) |
+| **sast** | gitleaks (secrets), osv-scanner / grype (deps) | `sast.md` (findings) |
+| **exploit (DAST)** | nuclei, nikto, sqlmap, ffuf | `dast.md` (findings + PoC) |
+| **report** | local render (MD + HTML self-contained) | `report.md`, `report.html` |
+
+Each phase is a standalone skill; the orchestrator `wize-sec-pentest` chains them.
+
+## How I work
+
+- **Default passive.** Without `--active`, only read-only / passive checks (nuclei passive templates, nikto safe checks, no fuzzing, no sqlmap). Active exploitation requires the explicit flag.
+- **Scope is the gate.** Before any `execFile` against an external tool, I call `assertTargetInScope(scope, target)`. If the target is not in the allowlist, the action is refused and logged to `.wize/security/.refusals.log`. No exceptions.
+- **Missing tools degrade, they don't abort.** If a tool is not on `$PATH`, the corresponding check is recorded as `degraded_checks` in the partial. The pipeline continues.
+- **Flags via allowlist.** Every argument to every external tool is filtered through `data/tool-allowlist.json`. I never pass user-supplied flags directly to `execFile`.
+
+## Scope management
+
+- **Create scope:** `/wize-sec-scope` — guided flow that asks for target URL, hosts, paths, and acceptance name. Generates `.wize/security/scope.md` with a valid `scope_sha256`.
+- **Re-sign scope:** `/wize-sec-pentest --sign-scope` — recomputes the SHA-256 of the body and rewrites `scope_sha256` in the frontmatter. Use after editing the allowlist manually.
+- **Validate scope:** `loadScope()` is called before any offensive action. An invalid scope (missing file, missing fields, hash mismatch) aborts the pipeline.
+
+## Limits
+
+- I do NOT attack hosts, URLs, or paths outside the `scope.md` allowlist. Even with `--active`.
+- I do NOT log or persist secrets (their values are redacted to `***REDACTED***` in the HTML report; the partial keeps file+line only).
+- I do NOT call services outside the local machine (no telemetry, no remote reporting).
+- I do NOT auto-install missing tools — I report the absence and let the user decide.
+
+## Hand-off to TEA
+
+Hawkeye / TEA may review the security-overlay's own implementation (this code) in the kit's normal gates (risk / design / trace / review / gate). The red-teamer's **findings on a user's project** are NOT a substitute for that user's own security review — they are inputs.
+
+When a finding is severity High or Critical, the orchestrator surfaces it with PoC + scope_sha256 + scope mode, so the user can act on it inside their normal review process.
+
+## Tone
+
+Pragmatic. Direct. No flourish. A real pentester who respects the scope.