wize-dev-kit 0.5.0 → 0.6.0

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

@@ -0,0 +1,176 @@
+'use strict';
+
+// run-nuclei.js — DAST nuclei phase. Default is passive (info disclosure,
+// misconfig, headers). Active mode is gated by --active (sqlmap/ffuf
+// come in separate stories).
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { execFileSync } = require('node:child_process');
+
+const { assertTargetInScope } = require('../../../_shared/scope-gate.js');
+const { filterArgs } = require('../../../_shared/allowlist.js');
+const { writePartial } = require('../../../_shared/partial.js');
+const { tagOwasp } = require('../../../_shared/owasp.js');
+
+// Build the nuclei args list. Returns the raw argv (before filterArgs).
+// Kept as a separate function so tests can assert on the raw list.
+function filterNucleiArgs(targetUrl, active, outputPath) {
+  // nuclei v3: there is no `-t passive` template path. We run the default
+  // template set and filter by severity. Passive = lower-impact severities
+  // + aggressive rate limit; active = full severity range. Output is JSONL
+  // (-jsonl), disable update check (-duc), non-colored (-nc), silent.
+  const args = [
+    '-u', targetUrl,
+    '-severity', active ? 'info,low,medium,high,critical' : 'info,low,medium',
+    '-rl', '10',
+    '-jsonl', '-o', outputPath,
+    '-duc', '-nc', '-silent'
+  ];
+  return args;
+}
+
+// Parse line-delimited nuclei JSON output (one finding per line).
+function parseNucleiJson(text) {
+  const out = [];
+  for (const line of String(text || '').split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const f = JSON.parse(trimmed);
+      out.push(f);
+    } catch (_) { /* skip malformed lines */ }
+  }
+  return out;
+}
+
+// Build a nuclei finding object (flat) with template_id, severity, owasp, etc.
+function normalizeFinding(raw) {
+  const templateId = raw['template-id'] || raw.templateID || raw.template || '<unknown>';
+  const info = raw.info || {};
+  const severity = (info.severity || raw.severity || 'unknown').toString().toLowerCase();
+  const name = info.name || raw.name || templateId;
+  const matchedAt = raw['matched-at'] || raw.matched || raw.host || '<unknown>';
+  // CVSS: nuclei sometimes nests it.
+  let cvss = raw.cvss;
+  if (typeof cvss !== 'number' && info && info.classification && info.classification.cvss_score) {
+    cvss = Number(info.classification.cvss_score);
+  }
+  if (typeof cvss !== 'number') cvss = null;
+  const owasp = tagOwasp({ rule: templateId, cve: raw['cve-id'] || raw.cve });
+  return { template_id: templateId, name, severity, cvss, matched_at: matchedAt, owasp };
+}
+
+// runNuclei({securityDir, scope, active, execFn?, detectFn?}) -> {ok, partialStatus}
+async function runNuclei(opts = {}) {
+  const sec = opts.securityDir;
+  const scope = opts.scope;
+  const active = opts.active === true;
+
+  const execFn = opts.execFn || ((bin, args) => {
+    return execFileSync(bin, args, { encoding: 'utf8', timeout: 10 * 60 * 1000 });
+  });
+  const detectFn = opts.detectFn || require('../../../_shared/detect.js').detectTools;
+
+  const tools = detectFn(['nuclei'], { cacheDir: sec });
+  const present = !!(tools.nuclei && tools.nuclei.present);
+
+  // 1. Target resolution — prefer scope body's ## dast_target.url.
+  let targetUrl = null;
+  const lines = (scope.body || '').split('\n');
+  let inDast = false;
+  for (const line of lines) {
+    if (/^## dast_target/.test(line)) { inDast = true; continue; }
+    if (inDast && /^url:\s*(.+?)\s*$/.test(line)) { targetUrl = line.match(/^url:\s*(.+?)\s*$/)[1]; break; }
+    if (inDast && /^## /.test(line)) break;
+  }
+  if (!targetUrl) {
+    writePartial({
+      securityDir: sec,
+      phase: 'dast',
+      mode: active ? 'active' : 'passive',
+      scope,
+      status: 'incomplete',
+      tools,
+      sections: { degraded_checks: '- nuclei: dast_target.url ausente no scope.md' }
+    });
+    return { ok: true, partialStatus: 'incomplete' };
+  }
+
+  // 2. Gate — target must be in scope.
+  const urlObj = new URL(targetUrl);
+  const inScope = assertTargetInScope(scope, { host: urlObj.hostname, url: targetUrl }, { refusalsDir: sec });
+  if (!inScope) {
+    writePartial({
+      securityDir: sec,
+      phase: 'dast',
+      mode: active ? 'active' : 'passive',
+      scope,
+      status: 'incomplete',
+      tools,
+      sections: { degraded_checks: `- nuclei: target ${targetUrl} recusado pelo gate` }
+    });
+    return { ok: false, partialStatus: 'incomplete' };
+  }
+
+  // 3. Missing tool -> degraded.
+  if (!present) {
+    writePartial({
+      securityDir: sec,
+      phase: 'dast',
+      mode: active ? 'active' : 'passive',
+      scope,
+      status: 'incomplete',
+      tools,
+      sections: { degraded_checks: '- nuclei: nuclei ausente — instale nuclei e re-rode a fase.' }
+    });
+    return { ok: true, partialStatus: 'incomplete' };
+  }
+
+  // 4. happy path.
+  const outPath = path.join(sec, '.nuclei.json');
+  const rawArgs = filterNucleiArgs(targetUrl, active, outPath);
+  const args = filterArgs('nuclei', rawArgs);
+  // nuclei may exit non-zero on some template errors; the JSONL output is
+  // still written for whatever ran. Read it regardless of exit status.
+  try {
+    execFn('nuclei', args, { timeout: 10 * 60 * 1000 });
+  } catch (_) { /* partial results still in outPath */ }
+
+  let findings = [];
+  if (fs.existsSync(outPath)) {
+    try {
+      findings = parseNucleiJson(fs.readFileSync(outPath, 'utf8'));
+    } catch (_) {
+      findings = [];
+    }
+  }
+  const normalized = findings.map(normalizeFinding);
+  const bodyLines = normalized.length
+    ? normalized.map(f => `- **${f.template_id}** (\`${f.name}\`) severity=${f.severity} owasp=\`${f.owasp}\`${f.cvss != null ? ` cvss=${f.cvss}` : ''} matched_at: ${f.matched_at}`)
+    : ['_(nenhum finding do nuclei)_'];
+
+  writePartial({
+    securityDir: sec,
+    phase: 'dast',
+    mode: active ? 'active' : 'passive',
+    scope,
+    status: normalized.length ? 'complete' : 'incomplete',
+    tools,
+    sections: { nuclei: bodyLines.join('\n') }
+  });
+  return { ok: true, partialStatus: normalized.length ? 'complete' : 'incomplete' };
+}
+
+module.exports = { runNuclei, filterNucleiArgs, parseNucleiJson, normalizeFinding };
+
+if (require.main === module) {
+  require('../../../_shared/cli-runner.js').runFromArgv({
+    fn: ({ securityDir, scopePath, active, target } = {}) => {
+      const { loadScope } = require('../../../_shared/scope-gate.js');
+      const scope = loadScope(scopePath);
+      return runNuclei({ securityDir, scope, active, target });
+    },
+    argMap: { 'securityDir': 'securityDir', 'scope': 'scopePath', 'active': 'active', 'target': 'target' }
+  });
+}

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

@@ -0,0 +1,139 @@
+'use strict';
+
+// run-sqlmap.js — DAST sqlmap. GATED by --active (ADR-004). Without
+// --active, sqlmap is NOT invoked even if the tool is installed.
+// filterArgs() blocks --dump and --os-shell (exfiltration / shell) —
+// they're not in the allowlist.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { execFileSync } = require('node:child_process');
+
+const { assertTargetInScope } = require('../../../_shared/scope-gate.js');
+const { filterArgs } = require('../../../_shared/allowlist.js');
+const { writePartial, loadPartial } = require('../../../_shared/partial.js');
+const { tagOwasp } = require('../../../_shared/owasp.js');
+
+const TIMEOUT_MS = 5 * 60 * 1000;
+
+function defaultArgs(targetUrl) {
+  // Conservative defaults. filterArgs() drops --dump, --os-shell, --level>1,
+  // --risk>1, etc. — they're not in the allowlist.
+  return ['-u', targetUrl, '--batch', '--level=1', '--risk=1', '--threads=2', '--timeout=10', '--retries=1', '--random-agent'];
+}
+
+// Parse a slice of sqlmap stdout into findings. Sqlmap's output is fairly
+// free-form; we use a relaxed parser that looks for the canonical
+// "Parameter: <name> ... Type: ..." block.
+function parseSqlmapStdout(stdout) {
+  const findings = [];
+  const lines = String(stdout || '').split('\n');
+  let current = null;
+  for (const line of lines) {
+    const pm = line.match(/Parameter:\s*(\S+).*Type:\s*(\S+)/i);
+    if (pm) {
+      if (current) findings.push(current);
+      current = { parameter: pm[1], type: pm[2] };
+      continue;
+    }
+    const dm = line.match(/DBMS:\s*(.+?)\s*$/i);
+    if (dm && current) current.dbms = dm[1];
+    const pm2 = line.match(/Payload:\s*(.+?)\s*$/i);
+    if (pm2 && current) current.payload = pm2[1];
+    const reqm = line.match(/^\s*Type:\s*UNION.*query/i);
+    if (reqm && current) current.kind = 'union';
+  }
+  if (current) findings.push(current);
+  return findings;
+}
+
+async function runSqlmap(opts = {}) {
+  const sec = opts.securityDir;
+  const scope = opts.scope;
+  const active = opts.active === true;
+
+  const execFn = opts.execFn || ((bin, args) => {
+    return execFileSync(bin, args, { encoding: 'utf8', timeout: TIMEOUT_MS });
+  });
+  const detectFn = opts.detectFn || require('../../../_shared/detect.js').detectTools;
+
+  const tools = detectFn(['sqlmap'], { cacheDir: sec });
+  const present = !!(tools.sqlmap && tools.sqlmap.present);
+
+  // Resolve dast_target.url.
+  let targetUrl = null;
+  for (const line of (scope.body || '').split('\n')) {
+    const m = line.match(/^url:\s*(.+?)\s*$/);
+    if (m && line.indexOf('url') === 0) { targetUrl = m[1]; break; }
+  }
+
+  function mergeDast(sections, status) {
+    const existing = loadPartial({ securityDir: sec, phase: 'dast' });
+    const merged = {};
+    if (existing && existing.body) {
+      const re = /## ([a-z_]+)\n\n([\s\S]*?)(?=\n## |$)/g;
+      let m;
+      while ((m = re.exec(existing.body)) !== null) {
+        merged[m[1]] = m[2].trim();
+      }
+    }
+    Object.assign(merged, sections);
+    const finalStatus = merged.degraded_checks ? 'incomplete' : status;
+    writePartial({
+      securityDir: sec, phase: 'dast', mode: active ? 'active' : 'passive',
+      scope, status: finalStatus, tools, sections: merged
+    });
+  }
+
+  // 1. Not active -> degraded with [sqlmap-pasive].
+  if (!active) {
+    mergeDast({ degraded_checks: '- sqlmap-pasive: --active ausente — sqlmap não é invocado sem opt-in explícito.' }, 'incomplete');
+    return { ok: true, partialStatus: 'incomplete' };
+  }
+
+  if (!targetUrl) {
+    mergeDast({ degraded_checks: '- sqlmap: dast_target.url ausente' }, 'incomplete');
+    return { ok: true, partialStatus: 'incomplete' };
+  }
+
+  // 2. Gate first.
+  const urlObj = new URL(targetUrl);
+  const inScope = assertTargetInScope(scope, { host: urlObj.hostname, url: targetUrl }, { refusalsDir: sec });
+  if (!inScope) {
+    mergeDast({ degraded_checks: `- sqlmap: target ${targetUrl} recusado pelo gate` }, 'incomplete');
+    return { ok: false, partialStatus: 'incomplete' };
+  }
+
+  // 3. Missing tool.
+  if (!present) {
+    mergeDast({ degraded_checks: '- sqlmap: sqlmap ausente — instale sqlmap e re-rode com --active.' }, 'incomplete');
+    return { ok: true, partialStatus: 'incomplete' };
+  }
+
+  // 4. happy path (active + present + in scope).
+  const rawArgs = defaultArgs(targetUrl);
+  const args = filterArgs('sqlmap', rawArgs);
+  const r = execFn('sqlmap', args, { timeout: TIMEOUT_MS });
+  const stdout = r && r.stdout ? r.stdout : '';
+  const findings = parseSqlmapStdout(stdout);
+  const findingsWithOwasp = findings.map(f => ({ ...f, owasp: tagOwasp({ rule: f.type || 'sqlmap' }) }));
+  const body = findingsWithOwasp.length
+    ? findingsWithOwasp.map(f => `- **${f.parameter || '?'}** (\`${f.type || '?'}\`) dbms=\`${f.dbms || '?'}\` owasp=\`${f.owasp}\` payload: ${f.payload || 'n/a'}`).join('\n')
+    : '_(nenhum finding do sqlmap)_';
+
+  mergeDast({ sqlmap: body }, findingsWithOwasp.length ? 'complete' : 'incomplete');
+  return { ok: true, partialStatus: findingsWithOwasp.length ? 'complete' : 'incomplete' };
+}
+
+module.exports = { runSqlmap, defaultArgs, parseSqlmapStdout };
+
+if (require.main === module) {
+  require('../../../_shared/cli-runner.js').runFromArgv({
+    fn: ({ securityDir, scopePath, active, target } = {}) => {
+      const { loadScope } = require('../../../_shared/scope-gate.js');
+      const scope = loadScope(scopePath);
+      return runSqlmap({ securityDir, scope, active, target });
+    },
+    argMap: { 'securityDir': 'securityDir', 'scope': 'scopePath', 'active': 'active', 'target': 'target' }
+  });
+}

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

@@ -0,0 +1,157 @@
+'use strict';
+
+// run-pipeline.js — the orchestrator for the security-overlay. Chains
+// the four phase skills (recon -> enumerate -> exploit -> report) and
+// propagates --active. This module exposes a `runPipeline(opts)` function
+// so the test suite can drive it directly; the SKILL.md entrypoint
+// (wize-sec-pentest) is a thin wrapper that just calls runPipeline with
+// argv-derived options.
+
+const path = require('node:path');
+const fs = require('node:fs');
+
+// Default kit root when running from the kit itself. Tests inject their own.
+const DEFAULT_KIT_ROOT = path.resolve(__dirname, '..', '..', '..', '..', '..');
+
+const PHASES = ['wize-sec-recon', 'wize-sec-enumerate', 'wize-sec-exploit', 'wize-sec-report'];
+
+// Per-phase script manifests. Each phase can run one or more scripts.
+// Scripts in the same phase run sequentially and any failure (or skip)
+// marks the phase as incomplete, but does not abort the pipeline.
+const PHASE_SCRIPTS = {
+  'wize-sec-recon':     ['recon', 'gitleaks', 'osv'],
+  'wize-sec-enumerate': ['enumerate'],
+  'wize-sec-exploit':   ['nuclei', 'nikto', 'sqlmap', 'ffuf'],
+  'wize-sec-report':    ['report']
+};
+
+function parseArgv(argv) {
+  const out = { active: false, scopePath: null, kitRoot: DEFAULT_KIT_ROOT };
+  for (let i = 0; i < (argv || []).length; i++) {
+    const a = argv[i];
+    if (a === '--active') out.active = true;
+    else if (a === '--scope' && argv[i + 1]) { out.scopePath = argv[i + 1]; i++; }
+    else if (a.startsWith('--scope=')) out.scopePath = a.slice('--scope='.length);
+  }
+  if (!out.scopePath) out.scopePath = path.join(process.cwd(), '.wize', 'security', 'scope.md');
+  return out;
+}
+
+// runPipeline({ scopePath, active, kitRoot?, loadScopeFn?, invokePhase? })
+//   - loadScopeFn defaults to the real scope-gate loadScope.
+//   - invokePhase defaults to the real invokePhase (subprocess).
+// Both are injectable for testing. We resolve the defaults lazily via a
+// small indirection (a getter) so a test that mutates the real module's
+// exports before loading this file sees the mocked value.
+async function runPipeline(opts = {}) {
+  const scopePath = opts.scopePath;
+  const active = opts.active === true;
+  const kitRoot = opts.kitRoot || DEFAULT_KIT_ROOT;
+  const securityDir = opts.securityDir || path.join(process.cwd(), '.wize', 'security');
+
+  // Lazy default resolution — must read at call time, not destructured at
+  // module load, so a test that swaps the real module's exports is honored.
+  const loadScopeFn = opts.loadScopeFn
+    || require('../../../_shared/scope-gate.js').loadScope;
+  const invokePhase = opts.invokePhase
+    || require('../../../_shared/invoke-phase.js').invokePhase;
+
+  // 0. Preflight (permissive — always continues, but writes the install
+  // script if anything is missing). In test mode the env vars short-
+  // circuit the real probes so the result is deterministic.
+  const preflight = opts.preflight
+    || require('../../../_shared/preflight.js').runPreflight({ kitRoot });
+  if (preflight.missing.length > 0 && opts.writeInstallScript !== false) {
+    const { generateInstallScript } = require('../../../_shared/install-script.js');
+    const script = generateInstallScript(preflight);
+    try {
+      const scriptPath = path.join(securityDir, 'install-pentest-tools.sh');
+      // Don't clobber a user-edited script.
+      if (!fs.existsSync(scriptPath)) {
+        fs.mkdirSync(securityDir, { recursive: true });
+        fs.writeFileSync(scriptPath, script, 'utf8');
+        try { fs.chmodSync(scriptPath, 0o755); } catch (_) { /* best-effort */ }
+      }
+    } catch (_) { /* best-effort: a write failure here does not block the pipeline */ }
+  }
+
+  // 1. Gate first — if the scope is invalid, abort the whole pipeline.
+  const scope = loadScopeFn(scopePath);
+
+  const results = {};
+  const skipped = [];
+
+  for (const phase of PHASES) {
+    const scripts = PHASE_SCRIPTS[phase] || [phase.split('-').pop()];
+    const phaseResults = [];
+    for (const sub of scripts) {
+      // Naming convention: scripts in the skill dir are run-<sub>.js, except
+      // for the report phase which is render-report.js.
+      const baseName = phase === 'wize-sec-report' ? `render-${sub}` : `run-${sub}`;
+      const scriptName = baseName.endsWith('.js') ? baseName : baseName + '.js';
+      try {
+        const r = await invokePhase(phase, { kitRoot, active, securityDir, scopePath, scriptName });
+        phaseResults.push({ sub, ...r });
+        if (!r.ok) skipped.push(`${phase}/${sub}`);
+      } catch (_) {
+        phaseResults.push({ sub, ok: false, code: -1, stdout: '', stderr: '', error: 'invoke-threw' });
+        skipped.push(`${phase}/${sub}`);
+      }
+    }
+    // Phase is OK if at least one sub-script succeeded.
+    const anyOk = phaseResults.some(r => r && r.ok);
+    results[phase] = { ok: anyOk, subs: phaseResults };
+  }
+
+  const anyOk = Object.values(results).some(r => r && r.ok);
+  return {
+    ok: anyOk,
+    scopePath,
+    active,
+    preflight,
+    results,
+    skipped
+  };
+}
+
+// Entry point when invoked as a subprocess (the SKILL.md frontmatter
+// declares commands: [run-pipeline.js]). The harness's adapter renders
+// this file as the skill body and runs `node run-pipeline.js` when the
+// user invokes `/wize-sec-pentest`.
+async function main() {
+  const args = parseArgv(process.argv.slice(2));
+  let result;
+  try {
+    // Derive the securityDir from the scopePath's parent (the .wize/security
+    // directory) so the preflight's install script lands next to the scope.
+    const secDir = path.dirname(args.scopePath);
+    result = await runPipeline({
+      scopePath: args.scopePath,
+      active: args.active,
+      kitRoot: args.kitRoot,
+      securityDir: secDir
+    });
+  } catch (err) {
+    console.error('✖ wize-sec-pentest aborted:', err && err.message ? err.message : err);
+    process.exit(2);
+  }
+
+  // Minimal stdout surface — the partials already carry detail.
+  for (const phase of PHASES) {
+    const r = result.results[phase];
+    if (!r) { console.log(`= ${phase}: (no result)`); continue; }
+    const mark = r.ok ? '✓' : '✗';
+    const subs = (r.subs || []).map(s => `${s.sub}:${s.ok ? 'ok' : 'fail'}`).join(',');
+    console.log(`${mark} ${phase}: ${subs}`);
+  }
+  if (result.skipped.length) {
+    console.log(`! skipped: ${result.skipped.join(', ')}`);
+  }
+  process.exit(result.ok ? 0 : 1);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { runPipeline, parseArgv, PHASES };

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

@@ -0,0 +1,52 @@
+---
+code: wize-sec-pentest
+name: wize-sec-pentest
+overlay: security
+module: security-overlay
+owner: red-teamer
+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' }
+  });
+}