wize-dev-kit 0.16.0 → 0.16.1

package/src/security-overlay/skills/wize-sec-pentest/skill.md

@@ -0,0 +1,54 @@
+---
+
+code: wize-sec-pentest
+description: "Use quando o scope de segurança estiver definido e precisar executar o pipeline completo de pentest (recon → enumerate → exploit → report)."
+name: wize-sec-pentest
+overlay: security
+module: security-overlay
+owner: wize-sec-red-teamer  # Natasha Romanoff
+status: ready
+---
+
+# wize-sec-pentest — Orchestrator (Security Overlay)
+
+End-to-end security pipeline. Chains **recon → enumerate → sast → dast → report** through the four phase skills (`wize-sec-recon`, `wize-sec-enumerate`, `wize-sec-exploit`, `wize-sec-report`). Loads `.wize/security/scope.md` first; aborts the whole pipeline if the scope is missing or invalid.
+
+## Usage
+
+```bash
+# Default (passive — read-only checks only)
+/wize-sec-pentest
+
+# Active exploitation (sqlmap, ffuf active fuzzing) — requires scope acceptance
+/wize-sec-pentest --active
+
+# Custom scope path (default: .wize/security/scope.md)
+/wize-sec-pentest --scope=/path/to/scope.md
+```
+
+## Phases (in order)
+
+1. **recon** — nmap (passive) → `recon.md`
+2. **enumerate** — nuclei passive, HTTP probing → `enumerate.md`
+3. **sast** — gitleaks (secrets) + osv-scanner/grype (deps) → `sast.md` (run inside `wize-sec-recon` per the architecture decision)
+4. **dast** — nuclei + nikto (passive) + sqlmap/ffuf (gated by `--active`) → `dast.md`
+5. **report** — render `report.md` + `report.html` from all partials
+
+Each phase produces a partial. The report phase consumes them. A phase that fails is marked `partial_status: skipped` and the pipeline continues with the next one.
+
+## Gate
+
+Before any phase, the orchestrator calls `loadScope()` (the shared gate). An invalid scope aborts the whole pipeline with the error code from `ScopeError`. The gate is the single source of truth — phases do not re-validate.
+
+## Propagation
+
+`--active` is read from argv and passed to every phase invocation. Each phase that supports active checks (currently `wize-sec-exploit`) decides what changes in active mode.
+
+## Output
+
+- `recon.md`, `enumerate.md`, `sast.md`, `dast.md` — partials (one per phase)
+- `report.md`, `report.html` — final consolidated report
+- `.refusals.log` — audit trail of out-of-scope refusals
+- `.tools.json` — detection cache for the toolchain
+
+Exits 0 if at least one phase ran; 1 if all phases failed; 2 if the scope gate aborted.

package/src/security-overlay/skills/wize-sec-recon/scripts/run-gitleaks.js

@@ -0,0 +1,139 @@
+'use strict';
+
+// run-gitleaks.js — SAST secrets via gitleaks. Runs inside the
+// wize-sec-recon skill (per the architecture decision that recon hosts
+// the no-app-running checks). Writes a redaction into sast.md and stores
+// the full gitleaks report in the security dir for the user to inspect.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { execFileSync } = require('node:child_process');
+
+const { filterArgs } = require('../../../_shared/allowlist.js');
+const { writePartial, loadPartial } = require('../../../_shared/partial.js');
+
+const REDACTED = '***REDACTED***';
+
+// runGitleaks({ securityDir, scope, active, execFn?, detectFn?, reportFilename? })
+//   -> { ok, partialStatus, findingsCount }
+async function runGitleaks(opts = {}) {
+  const sec = opts.securityDir;
+  const scope = opts.scope;
+  const active = opts.active === true;
+  const reportFilename = opts.reportFilename || 'gitleaks-report.json';
+  // The project to scan is the parent of `.wize/security/`. The scripts run
+  // with cwd = the kit, so we MUST point gitleaks at the target repo, not '.'.
+  const projectRoot = opts.projectRoot || (sec ? path.resolve(sec, '..', '..') : process.cwd());
+
+  const execFn = opts.execFn || ((bin, args) => {
+    return execFileSync(bin, args, { encoding: 'utf8', timeout: 5 * 60 * 1000 });
+  });
+  const detectFn = opts.detectFn || require('../../../_shared/detect.js').detectTools;
+
+  const tools = detectFn(['gitleaks'], { cacheDir: sec });
+  const present = !!(tools.gitleaks && tools.gitleaks.present);
+
+  if (!present) {
+    // Update or create sast.md with the degraded_checks entry.
+    mergeSast(sec, scope, active, tools, {
+      degraded: '- secrets: gitleaks ausente — instale gitleaks e re-rode para scan completo.'
+    });
+    return { ok: true, partialStatus: 'incomplete', findingsCount: 0 };
+  }
+
+  const reportPath = path.join(sec, reportFilename);
+  // gitleaks 8.18: `-s/--source` is the scan path, `-f/--report-format` is
+  // the output format (json), `-r/--report-path` is the file. (Earlier
+  // versions used `-f` for the path — do NOT use that here.)
+  const args = filterArgs('gitleaks', [
+    'detect', '--no-banner', '-s', projectRoot, '-f', 'json', '-r', reportPath, '--exit-code', '0'
+  ]);
+  // gitleaks exits non-zero when it FINDS leaks (default exit-code 1). That
+  // is the success path for us, not an error — so we pass --exit-code 0 and
+  // also swallow any non-zero status defensively (we read the JSON report
+  // regardless).
+  try {
+    execFn('gitleaks', args, { timeout: 5 * 60 * 1000 });
+  } catch (_) {
+    // Leaks found (or gitleaks returned non-zero) — the report file is still
+    // written; we parse it below.
+  }
+
+  // Read the JSON report gitleaks wrote. It is an array of findings.
+  let findings = [];
+  if (fs.existsSync(reportPath)) {
+    try {
+      findings = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+    } catch (_) {
+      findings = [];
+    }
+  }
+
+  // Build the secrets section from findings — ONLY redacted values.
+  const secretLines = findings.map(f => {
+    const file = f.File || f.file || '<unknown>';
+    const line = f.StartLine || f.startLine || '?';
+    const rule = f.RuleID || f.ruleID || 'unknown';
+    return `- **${file}** line ${line} rule \`${rule}\` — redacted_value: \`${REDACTED}\``;
+  });
+
+  // Merge into existing sast.md (preserve other sections like deps from E05-S02).
+  mergeSast(sec, scope, active, tools, {
+    secrets: secretLines.length ? secretLines.join('\n') : '_(nenhum secret encontrado)_'
+  });
+  return { ok: true, partialStatus: secretLines.length ? 'complete' : 'incomplete', findingsCount: secretLines.length };
+}
+
+// Helper: load existing sast.md, update the relevant section, and write back.
+// Preserves sections that other SAST scripts (e.g. run-osv) added.
+function mergeSast(sec, scope, active, tools, update) {
+  const existing = loadPartial({ securityDir: sec, phase: 'sast' });
+  const sections = {};
+  let mergedTools = Object.assign({}, tools);
+  if (existing) {
+    if (existing.body) {
+      // Extract known section bodies from the existing partial.
+      const re = /## ([a-z_]+)\n\n([\s\S]*?)(?=\n## |$)/g;
+      let m;
+      while ((m = re.exec(existing.body)) !== null) {
+        sections[m[1]] = m[2].trim();
+      }
+    }
+    // Preserve tools detected by sibling SAST scripts (gitleaks + osv each
+    // run separately; neither should clobber the other's tools block).
+    if (existing.frontmatter && existing.frontmatter.tools) {
+      mergedTools = Object.assign({}, existing.frontmatter.tools, tools);
+    }
+  }
+  // Apply updates.
+  if (update.degraded) {
+    // Append to degraded_checks if present, else create.
+    if (sections.degraded_checks) sections.degraded_checks += '\n' + update.degraded;
+    else sections.degraded_checks = update.degraded;
+  }
+  if (update.secrets !== undefined) sections.secrets = update.secrets;
+
+  const status = sections.degraded_checks ? 'incomplete' : 'complete';
+  writePartial({
+    securityDir: sec,
+    phase: 'sast',
+    mode: active ? 'active' : 'passive',
+    scope,
+    status,
+    tools: mergedTools,
+    sections
+  });
+}
+
+module.exports = { runGitleaks, mergeSast, REDACTED };
+
+if (require.main === module) {
+  require('../../../_shared/cli-runner.js').runFromArgv({
+    fn: ({ securityDir, scopePath, active, reportFilename } = {}) => {
+      const { loadScope } = require('../../../_shared/scope-gate.js');
+      const scope = loadScope(scopePath);
+      return runGitleaks({ securityDir, scope, active, reportFilename });
+    },
+    argMap: { 'securityDir': 'securityDir', 'scope': 'scopePath', 'active': 'active', 'reportFilename': 'reportFilename' }
+  });
+}

package/src/security-overlay/skills/wize-sec-recon/scripts/run-osv.js

@@ -0,0 +1,227 @@
+'use strict';
+
+// run-osv.js — SAST dependencies via osv-scanner (primary) or grype (fallback).
+// Auto-detects common manifest files in the project root and emits findings
+// into sast.md (composing with secrets from run-gitleaks.js).
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { execFileSync } = require('node:child_process');
+
+const { filterArgs } = require('../../../_shared/allowlist.js');
+const { writePartial, loadPartial } = require('../../../_shared/partial.js');
+
+const MANIFEST_FILES = [
+  'package.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+  'requirements.txt', 'Pipfile', 'Pipfile.lock', 'pyproject.toml', 'poetry.lock',
+  'go.mod', 'go.sum',
+  'Cargo.toml', 'Cargo.lock',
+  'composer.json', 'composer.lock',
+  'Gemfile', 'Gemfile.lock'
+];
+
+function detectManifests(root) {
+  const found = [];
+  for (const m of MANIFEST_FILES) {
+    if (fs.existsSync(path.join(root, m))) found.push(m);
+  }
+  return found;
+}
+
+function parseOsvReport(report) {
+  // osv-scanner JSON shape (simplified): { results: [{ packages: [{ package: {name, version}, vulnerabilities: [{id, severity, cvss: {score}}] }] }] }
+  const out = [];
+  const results = report && report.results ? report.results : [];
+  // Map a CVSS base score to a coarse severity label.
+  const sevFromScore = s => {
+    const n = parseFloat(s);
+    if (isNaN(n)) return null;
+    if (n === 0) return 'None';
+    if (n < 4) return 'Low';
+    if (n < 7) return 'Medium';
+    if (n < 9) return 'High';
+    return 'Critical';
+  };
+  for (const r of results) {
+    for (const p of (r.packages || [])) {
+      const name = p.package && p.package.name;
+      const version = p.package && p.package.version;
+      // osv-scanner v2 groups vulnerabilities and exposes a max_severity
+      // (CVSS) + aliases (CVE ids) per group. Prefer that; fall back to
+      // the raw vulnerabilities array for older shapes.
+      const groups = Array.isArray(p.groups) ? p.groups : [];
+      if (groups.length) {
+        for (const g of groups) {
+          const ids = g.aliases && g.aliases.length ? g.aliases : g.ids || [];
+          const cve = ids.find(x => /^CVE-/.test(x)) || ids[0] || '?';
+          const cvss = g.max_severity ? parseFloat(g.max_severity) : null;
+          out.push({ package: name, version, cve, severity: sevFromScore(g.max_severity) || 'UNKNOWN', cvss });
+        }
+      } else {
+        for (const v of (p.vulnerabilities || [])) {
+          const cve = v.id || '?';
+          const cvss = v.cvss && (typeof v.cvss === 'number' ? v.cvss : v.cvss.score);
+          out.push({ package: name, version, cve, severity: sevFromScore(cvss) || 'UNKNOWN', cvss });
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function parseGrypeReport(report) {
+  // grype JSON shape: { matches: [{ artifact: {name, version}, vulnerability: {id, severity, cvss:[{metrics:{baseScore}}]} }] }
+  const out = [];
+  for (const m of (report && report.matches ? report.matches : [])) {
+    const name = m.artifact && m.artifact.name;
+    const version = m.artifact && m.artifact.version;
+    const v = m.vulnerability || {};
+    const cve = v.id || '?';
+    const severity = v.severity || 'UNKNOWN';
+    let cvss = null;
+    if (Array.isArray(v.cvss) && v.cvss[0] && v.cvss[0].metrics) {
+      cvss = v.cvss[0].metrics.baseScore;
+    } else if (typeof v.cvss === 'number') {
+      cvss = v.cvss;
+    }
+    out.push({ package: name, version, cve, severity, cvss });
+  }
+  return out;
+}
+
+function renderDepsSection(findings) {
+  if (!findings.length) return '_(nenhuma dep vulnerável encontrada)_';
+  return findings.map(f => {
+    const cvss = f.cvss != null ? ` cvss=${f.cvss}` : '';
+    return `- **${f.package}@${f.version || '?'}** \`${f.cve}\` severity=${f.severity}${cvss}`;
+  }).join('\n');
+}
+
+// runOsv({ securityDir, scope, active, execFn?, detectFn?, manifestRoot?, reportFilename? })
+async function runOsv(opts = {}) {
+  const sec = opts.securityDir;
+  const scope = opts.scope;
+  const active = opts.active === true;
+  // The project to scan is the parent of `.wize/security/`. Scripts run with
+  // cwd = the kit, so default to the target repo, not process.cwd().
+  const manifestRoot = opts.manifestRoot
+    || (sec ? path.resolve(sec, '..', '..') : process.cwd());
+  const osvReportName = 'osv-report.json';
+  const grypeReportName = 'grype-report.json';
+
+  const execFn = opts.execFn || ((bin, args) => {
+    return execFileSync(bin, args, { encoding: 'utf8', timeout: 5 * 60 * 1000 });
+  });
+  const detectFn = opts.detectFn || require('../../../_shared/detect.js').detectTools;
+
+  const tools = detectFn(['osv-scanner', 'grype'], { cacheDir: sec });
+  const osvPresent = !!(tools['osv-scanner'] && tools['osv-scanner'].present);
+  const grypePresent = !!(tools.grype && tools.grype.present);
+
+  // No tools at all -> degraded.
+  if (!osvPresent && !grypePresent) {
+    mergeSast(sec, scope, active, tools, {
+      degraded: '- deps: osv-scanner e grype ausentes — instale um dos dois e re-rode.'
+    });
+    return { ok: true, partialStatus: 'incomplete', tool: null, findings: [] };
+  }
+
+  // Manifest detection: warn if the project root has no known manifest.
+  const manifests = detectManifests(manifestRoot);
+  if (manifests.length === 0) {
+    mergeSast(sec, scope, active, tools, {
+      degraded: `- deps: nenhum manifesto encontrado em ${manifestRoot} (procurando package.json, requirements.txt, go.mod, Cargo.toml, pyproject.toml, composer.json, Gemfile).`
+    });
+    return { ok: true, partialStatus: 'incomplete', tool: null, findings: [] };
+  }
+
+  // Pick tool. Prefer osv-scanner; fallback to grype.
+  let findings = [];
+  let tool = null;
+  if (osvPresent) {
+    tool = 'osv-scanner';
+    const reportPath = path.join(sec, osvReportName);
+    // osv-scanner v2 needs explicit lockfiles (`-L <path>`); recursive
+    // directory scan misses composer.lock/package-lock.json. We pass each
+    // detected lockfile we found. Non-zero exit = vulns found (success).
+    const LOCKFILES = ['composer.lock', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml',
+      'requirements.txt', 'Pipfile.lock', 'poetry.lock', 'go.sum', 'Cargo.lock', 'Gemfile.lock'];
+    const lockArgs = [];
+    for (const lf of LOCKFILES) {
+      if (fs.existsSync(path.join(manifestRoot, lf))) {
+        lockArgs.push('-L', path.join(manifestRoot, lf));
+      }
+    }
+    const args = lockArgs.length
+      ? filterArgs('osv-scanner', ['scan', 'source', ...lockArgs, '--format', 'json', '--output-file', reportPath])
+      : filterArgs('osv-scanner', ['scan', 'source', '-r', '--format', 'json', '--output-file', reportPath, manifestRoot]);
+    try {
+      execFn('osv-scanner', args, { timeout: 5 * 60 * 1000 });
+    } catch (_) { /* vulns found -> non-zero exit; report still written */ }
+    if (fs.existsSync(reportPath)) {
+      try { findings = parseOsvReport(JSON.parse(fs.readFileSync(reportPath, 'utf8'))); }
+      catch (_) { findings = []; }
+    }
+  } else if (grypePresent) {
+    tool = 'grype';
+    const reportPath = path.join(sec, grypeReportName);
+    const args = filterArgs('grype', ['dir:' + manifestRoot, '-o', 'json']);
+    execFn('grype', args, { timeout: 5 * 60 * 1000 });
+    if (fs.existsSync(reportPath)) {
+      try { findings = parseGrypeReport(JSON.parse(fs.readFileSync(reportPath, 'utf8'))); }
+      catch (_) { findings = []; }
+    }
+  }
+
+  mergeSast(sec, scope, active, tools, {
+    deps: renderDepsSection(findings)
+  });
+  return { ok: true, partialStatus: 'complete', tool, findings };
+}
+
+function mergeSast(sec, scope, active, tools, update) {
+  const existing = loadPartial({ securityDir: sec, phase: 'sast' });
+  const sections = {};
+  let mergedTools = Object.assign({}, tools);
+  if (existing) {
+    if (existing.body) {
+      const re = /## ([a-z_]+)\n\n([\s\S]*?)(?=\n## |$)/g;
+      let m;
+      while ((m = re.exec(existing.body)) !== null) {
+        sections[m[1]] = m[2].trim();
+      }
+    }
+    if (existing.frontmatter && existing.frontmatter.tools) {
+      mergedTools = Object.assign({}, existing.frontmatter.tools, tools);
+    }
+  }
+  if (update.degraded) {
+    sections.degraded_checks = sections.degraded_checks
+      ? sections.degraded_checks + '\n' + update.degraded
+      : update.degraded;
+  }
+  if (update.deps !== undefined) sections.deps = update.deps;
+  const status = sections.degraded_checks ? 'incomplete' : 'complete';
+  writePartial({
+    securityDir: sec,
+    phase: 'sast',
+    mode: active ? 'active' : 'passive',
+    scope,
+    status,
+    tools: mergedTools,
+    sections
+  });
+}
+
+module.exports = { runOsv, parseOsvReport, parseGrypeReport, detectManifests, MANIFEST_FILES };
+
+if (require.main === module) {
+  require('../../../_shared/cli-runner.js').runFromArgv({
+    fn: ({ securityDir, scopePath, active, manifestRoot, reportFilename } = {}) => {
+      const { loadScope } = require('../../../_shared/scope-gate.js');
+      const scope = loadScope(scopePath);
+      return runOsv({ securityDir, scope, active, manifestRoot, reportFilename });
+    },
+    argMap: { 'securityDir': 'securityDir', 'scope': 'scopePath', 'active': 'active', 'manifestRoot': 'manifestRoot', 'reportFilename': 'reportFilename' }
+  });
+}

package/src/security-overlay/skills/wize-sec-recon/scripts/run-recon.js

@@ -0,0 +1,162 @@
+'use strict';
+
+// run-recon.js — the nmap portion of the wize-sec-recon skill.
+// SAST (gitleaks, osv/grype) is implemented in E05 and lives in
+// scripts/run-sast.js (sibling). The orchestrator (wize-sec-pentest) and
+// any caller can invoke either script directly; this file only handles
+// recon.
+
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { assertTargetInScope, ScopeError } = require('../../../_shared/scope-gate.js');
+const { filterArgs } = require('../../../_shared/allowlist.js');
+const { writePartial } = require('../../../_shared/partial.js');
+
+// Default argument list for nmap. filterArgs() will drop anything not in
+// the tool-allowlist, so this list is intentionally explicit and minimal.
+function defaultArgs(active) {
+  const args = ['-Pn', '-T4'];
+  if (active) args.push('-sV');
+  else args.push('-sn'); // passive: ping scan only — no port scan, no service detection.
+  return args;
+}
+
+// Parse a greppable nmap stdout into a markdown list. We only care about
+// lines that look like `PORT/PROTO  SERVICE  VERSION`. Ports whose service
+// nmap could not fingerprint (`?`, unknown, tcpwrapped, or empty version)
+// are flagged for manual investigation — an unidentified open port is a
+// medium-priority unknown, not just inventory.
+function parseNmapGreppable(stdout) {
+  const lines = String(stdout || '').split('\n');
+  const out = [];
+  for (const line of lines) {
+    const m = line.match(/^(\d+\/[a-z]+)\s+(\S+)\s+(.*)$/);
+    if (!m) continue;
+    const port = m[1];
+    const service = m[2];
+    const version = m[3].trim();
+    const unidentified = /\?$/.test(service) || /^(unknown|tcpwrapped)$/i.test(service) || version === '';
+    if (unidentified) {
+      out.push(`- **${port}** \`${service}\` — ⚠️ serviço não identificado. **Investigar:** \`lsof -i :${port.split('/')[0]}\` · \`docker ps\` · \`ss -tulpn | grep ${port.split('/')[0]}\``);
+    } else {
+      out.push(`- **${port}** \`${service}\` — ${version}`);
+    }
+  }
+  return out.join('\n');
+}
+
+// runRecon({ securityDir, scope, target, active, execFn?, detectFn? }) ->
+//   { ok, partialStatus, mode }
+// dependencies are injectable for tests.
+async function runRecon(opts = {}) {
+  const sec = opts.securityDir;
+  const scope = opts.scope;
+  const target = opts.target;
+  const active = opts.active === true;
+
+  const execFn = opts.execFn || ((bin, args, opt) => {
+    return execFileSync(bin, args, { encoding: 'utf8', timeout: 60_000 });
+  });
+  const detectFn = opts.detectFn || require('../../../_shared/detect.js').detectTools;
+
+  // Gate — propagates ScopeError if scope is invalid.
+  const tools = detectFn(['nmap'], { cacheDir: sec });
+  const nmapTool = tools.nmap || { present: false };
+
+  // 1. nmap missing -> degraded partial, exit 0.
+  if (!nmapTool.present) {
+    writePartial({
+      securityDir: sec,
+      phase: 'recon',
+      mode: active ? 'active' : 'passive',
+      scope,
+      status: 'incomplete',
+      tools,
+      sections: {
+        degraded_checks: 'nmap ausente — instale nmap e re-rode a fase para resultados completos.'
+      }
+    });
+    return { ok: true, partialStatus: 'incomplete', mode: active ? 'active' : 'passive' };
+  }
+
+  // 2. target out of scope -> degraded partial, ok=false (gate refused).
+  const inScope = assertTargetInScope(scope, { host: target }, { refusalsDir: sec });
+  if (!inScope) {
+    writePartial({
+      securityDir: sec,
+      phase: 'recon',
+      mode: active ? 'active' : 'passive',
+      scope,
+      status: 'incomplete',
+      tools,
+      sections: {
+        degraded_checks: `target ${target} recusado pelo gate (host not in allowlist) — ver .wize/security/.refusals.log`
+      }
+    });
+    return { ok: false, partialStatus: 'incomplete', mode: active ? 'active' : 'passive' };
+  }
+
+  // 3. happy path: filterArgs + execFile.
+  const args = filterArgs('nmap', [...defaultArgs(active), target]);
+  const out = execFn('nmap', args, { timeout: 60_000 });
+  const portsText = parseNmapGreppable(out && out.stdout ? out.stdout : out);
+  const body = portsText || '_(nmap returned no parseable ports)_';
+
+  writePartial({
+    securityDir: sec,
+    phase: 'recon',
+    mode: active ? 'active' : 'passive',
+    scope,
+    status: 'complete',
+    tools,
+    sections: { open_ports: body }
+  });
+  return { ok: true, partialStatus: 'complete', mode: active ? 'active' : 'passive' };
+}
+
+// --- CLI entrypoint ------------------------------------------------------
+
+function parseArgv(argv) {
+  const out = { active: false, securityDir: null, scopePath: null, target: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--active') out.active = true;
+    else if (a === '--target' && argv[i + 1]) { out.target = argv[i + 1]; i++; }
+    else if (a.startsWith('--target=')) out.target = a.slice('--target='.length);
+    else if (a === '--scope' && argv[i + 1]) { out.scopePath = argv[i + 1]; i++; }
+    else if (a.startsWith('--scope=')) out.scopePath = a.slice('--scope='.length);
+    else if (a === '--securityDir' && argv[i + 1]) { out.securityDir = argv[i + 1]; i++; }
+    else if (a.startsWith('--securityDir=')) out.securityDir = a.slice('--securityDir='.length);
+  }
+  if (!out.securityDir) out.securityDir = path.join(process.cwd(), '.wize', 'security');
+  if (!out.scopePath) out.scopePath = path.join(process.cwd(), '.wize', 'security', 'scope.md');
+  if (!out.target) {
+    // Default to scope.md dast_target.url host if available.
+    out.target = 'localhost';
+  }
+  return out;
+}
+
+async function main() {
+  const args = parseArgv(process.argv.slice(2));
+  const { loadScope } = require('../../../_shared/scope-gate.js');
+  const scope = loadScope(args.scopePath);
+  const r = await runRecon({
+    securityDir: args.securityDir,
+    scope,
+    target: args.target,
+    active: args.active
+  });
+  console.log(`recon: partial_status=${r.partialStatus} mode=${r.mode}`);
+  process.exit(r.ok ? 0 : 1);
+}
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error('✖ wize-sec-recon:', err && err.message ? err.message : err);
+    process.exit(2);
+  });
+}
+
+module.exports = { runRecon, defaultArgs, parseNmapGreppable };

package/src/security-overlay/skills/wize-sec-recon/skill.md

@@ -0,0 +1,37 @@
+---
+
+code: wize-sec-recon
+description: "Use quando o scope de segurança estiver autorizado e precisar executar reconhecimento passivo (nmap) nos alvos."
+name: wize-sec-recon
+overlay: security
+module: security-overlay
+owner: wize-sec-red-teamer  # Natasha Romanoff
+status: ready
+---
+
+# wize-sec-recon — Recon (nmap)
+
+Runs nmap against the targets in the `scope.md` allowlist and writes `recon.md`. **Default passive** (ping scan only); `--active` enables `-sV` service detection.
+
+## Usage
+
+```bash
+/wize-sec-recon
+/wize-sec-recon --active
+/wize-sec-recon --target=staging.example.internal
+```
+
+## Behavior
+
+- Loads `.wize/security/scope.md` first; aborts loudly on invalid scope (HASH_MISMATCH / MISSING_FIELDS).
+- Detects nmap via `command -v`. If absent, writes a `partial_status: incomplete` recon.md with a `degraded_checks` section and exits 0 — the pipeline continues.
+- Calls `assertTargetInScope` for the target. Out-of-scope targets produce an `incomplete` partial and a refusal entry in `.refusals.log`; nmap is **not** invoked.
+- Active vs passive flag set is recorded in the partial's `mode:` frontmatter.
+- The SAST portion of recon (gitleaks, osv/grype) is implemented in a sibling script `scripts/run-sast.js` and is invoked separately or by the orchestrator — see E05.
+
+## Output
+
+- `.wize/security/recon.md` — partial with `## open_ports` (or `## degraded_checks` on missing tool / out-of-scope target).
+- `.wize/security/.refusals.log` — appended on out-of-scope targets.
+
+Exits 0 on success or graceful degradation; 1 when the gate refused the target; 2 on scope error.