@bugb-technologies/bravos 0.0.0-stage → 1.0.1

package/dist/report/check.js

@@ -0,0 +1,252 @@
+import { LEVEL_LABEL, SECRET_PATTERNS } from './data.js';
+const LEVEL_RANK = { reproduced: 0, held: 1, 'code-review': 2, suspected: 3 };
+// @comment -- "bravos report check: the deterministic gate on a report.md the agent wrote. It reads the headings and field labels the bravos-report templates define and fails on a missing or out-of-order section, a finding missing a field, a missing or duplicate F-id, an evidence label stronger than the cited evidence supports, a cited id the bundle does not hold, a percentage without its denominator, a secret-shaped string, or a CVSS score without its vector; it warns on long paragraphs and vague titles. Pure: text and bundle in, a verdict out."
+export const SECTIONS = {
+    assessment: [
+        'executive assessment',
+        'scope and limitations',
+        'system and threat context',
+        'coverage and approach',
+        'principal attack narratives',
+        'findings',
+        'remediation roadmap',
+        'retest results and appendices',
+    ],
+    brief: ['executive assessment', 'main risks', 'decisions needed', 'what this rests on'],
+    retest: ['retest summary', 'original finding', 'retest', 'residual exposure'],
+    finding: [],
+};
+/**
+ * The parts every finding must carry. Each is satisfied by a bold field (**Label:**) or by a heading inside the
+ * finding whose text contains one of the words, so a finding can be written as labelled fields or as a plain,
+ * team-readable write-up with headings ("What the attacker needs", "Reproduce it by hand", "How to fix it").
+ */
+export const FINDING_PARTS = [
+    { name: 'prerequisites', fields: ['Prerequisites'], headings: ['prerequisite', 'need', 'attacker'] },
+    { name: 'reproduction steps', fields: ['Reproduction', 'Steps to reproduce'], headings: ['reproduc'] },
+    { name: 'root cause', fields: ['Root cause'], headings: ['root cause', 'what we found', 'cause'] },
+    { name: 'impact', fields: ['Impact'], headings: ['impact'] },
+    { name: 'remediation', fields: ['Remediation', 'Fix'], headings: ['fix', 'remediat'] },
+    { name: 'verification', fields: ['Verification'], headings: ['verif', 'check the fix', 'check that the fix', 'how to check'] },
+];
+/** Kept for compatibility: the classic field labels. */
+export const FINDING_FIELDS = ['Evidence', 'Severity', 'Prerequisites', 'Reproduction', 'Root cause', 'Impact', 'Remediation', 'Verification'];
+const STATUS_FIELDS = ['Status', 'Evidence'];
+export const RETEST_FIELDS = ['Retested build', 'Replay', 'Result', 'Bypass variants', 'Legitimate behaviour'];
+const SEVERITIES = ['critical', 'high', 'medium', 'low', 'informational', 'info'];
+/** Ids a report may cite: EXP-n, LED-<hex>, SAST-n, CTL-n, BND-n, ACC-n, RUN-n and RUN-n/F|X|H|N-m, EDGE-n and UNR-n; in a workspace report each may carry its service as a prefix (orders:EXP-3). */
+export const ID_RE = /(?<![\w:-])(?:[a-z0-9][a-z0-9._-]{0,40}:)?(?:RUN-\d+(?:\/[FXHN]-\d+)?|(?:EXP|SAST|CTL|BND|ACC|EDGE|UNR)-\d+|LED-[a-f0-9]{8})\b/g;
+const FINDING_HEADING = /^(#{2,4})\s+(F-\d{2,3})\s*(?:—|–|-|:)\s*(.+?)\s*$/;
+const norm = (h) => h.replace(/^\d+\.\s*/, '').trim().toLowerCase();
+/** The value of a `**Label:**` / `**Label**:` / `- **Label:**` line, or a `| Label | value |` table row, within lines; null when absent. */
+function field(lines, label) {
+    const l = label.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const bold = new RegExp(`^\\s*(?:[-*]\\s+)?\\*\\*${l}(?::\\*\\*|\\*\\*\\s*:)\\s*(.*)$`, 'i');
+    const row = new RegExp(`^\\s*\\|\\s*\\**${l}\\**\\s*\\|\\s*(.*?)\\s*\\|?\\s*$`, 'i');
+    for (let i = 0; i < lines.length; i++) {
+        const m = bold.exec(lines[i]) ?? row.exec(lines[i]);
+        if (m) {
+            // A label alone on its line (e.g. Reproduction) takes the following lines as its value.
+            let value = m[1].trim();
+            for (let j = i + 1; !value && j < lines.length && !/^\s*(?:\*\*|#|\|)/.test(lines[j]); j++)
+                value = lines[j].trim();
+            return { value, line: i };
+        }
+    }
+    return null;
+}
+// @comment -- "Reads an evidence value: which of the four labels it starts with (word for word, any case), and the ids it cites."
+export function parseEvidence(value) {
+    const v = value.trim().toLowerCase();
+    const level = Object.keys(LEVEL_LABEL).find((k) => v.startsWith(LEVEL_LABEL[k])) ?? null;
+    return { level, ids: [...new Set(value.match(ID_RE) ?? [])] };
+}
+// @comment -- "Checks one report against its bundle; see the module comment for the rules."
+export function checkReport(md, bundle, kind) {
+    const errors = [];
+    const warnings = [];
+    const lines = md.split('\n');
+    const supports = new Map(bundle.items.map((i) => [i.id, i.supports]));
+    const err = (rule, message, line = null) => errors.push({ rule, message, line: line === null ? null : line + 1 });
+    const warn = (rule, message, line = null) => warnings.push({ rule, message, line: line === null ? null : line + 1 });
+    // Code fences are kept for the secret scan but skipped for prose rules.
+    const inFence = [];
+    let fence = false;
+    for (const l of lines) {
+        if (/^\s*```/.test(l)) {
+            inFence.push(true);
+            fence = !fence;
+            continue;
+        }
+        inFence.push(fence);
+    }
+    const titleLine = lines.findIndex((l, i) => !inFence[i] && /^#\s+\S/.test(l));
+    const title = titleLine >= 0 ? lines[titleLine].replace(/^#\s+/, '').trim() : null;
+    if (!title)
+        err('title', 'the report has no "# " title line');
+    // Sections, in order.
+    const headings = lines.map((l, i) => (!inFence[i] && /^##\s+/.test(l) && !FINDING_HEADING.test(l) ? { text: norm(l.replace(/^##\s+/, '')), line: i } : null)).filter((h) => !!h);
+    let at = -1;
+    for (const want of SECTIONS[kind]) {
+        const found = headings.find((h) => h.text === want);
+        if (!found) {
+            err('section', `missing section "## ${want[0].toUpperCase()}${want.slice(1)}"`);
+            continue;
+        }
+        if (found.line < at)
+            err('section-order', `section "${want}" is out of order`, found.line);
+        at = found.line;
+    }
+    // Findings: "### F-nn — title" blocks; a finding report may instead be one plain write-up (the whole document).
+    const fStarts = lines.map((l, i) => (!inFence[i] ? FINDING_HEADING.exec(l) : null) && i).filter((i) => typeof i === 'number');
+    const findings = [];
+    const seen = new Set();
+    const headingIn = (block, from, words) => block.some((l, i) => !inFence[from + i] && /^#{2,6}\s/.test(l) && words.some((w) => l.toLowerCase().includes(w)));
+    // Validates one finding's lines (block starts at line `from` of the document).
+    const checkFinding = (id, ftitle, block, from, at) => {
+        if (ftitle.split(/\s+/).length < 5)
+            warn('finding-title', `${id}'s title is short; say who can do what to what`, at);
+        // Status: every **Status:** / **Evidence:** line must start with an evidence label; a level above "suspected"
+        // must be supported by an id cited on one of those lines (a short status line may defer to the Evidence section).
+        const statusLines = [];
+        block.forEach((l, i) => {
+            if (inFence[from + i])
+                return;
+            for (const f of STATUS_FIELDS) {
+                const v = field([l], f);
+                if (v)
+                    statusLines.push({ value: v.value, line: from + i });
+            }
+        });
+        let level = null;
+        let evidenceIds = [];
+        if (!statusLines.length)
+            err('finding-field', `${id} has no "**Status:**" (or "**Evidence:**") line naming its evidence level`, at);
+        for (const s of statusLines) {
+            const p = parseEvidence(s.value);
+            if (!p.level)
+                err('evidence-label', `${id}'s status does not start with one of: ${Object.values(LEVEL_LABEL).join('; ')}`, s.line);
+            else if (!level || LEVEL_RANK[p.level] < LEVEL_RANK[level])
+                level = p.level;
+            evidenceIds = [...new Set([...evidenceIds, ...p.ids])];
+        }
+        if (level && level !== 'suspected') {
+            if (!evidenceIds.length)
+                err('evidence-ids', `${id} says "${LEVEL_LABEL[level]}" but cites no evidence id on a Status or Evidence line`, statusLines[0]?.line ?? at);
+            else if (!evidenceIds.some((x) => supports.get(x)?.includes(level)))
+                err('evidence-level', `${id} says "${LEVEL_LABEL[level]}" but none of ${evidenceIds.join(', ')} supports it; use the level the bundle computed`, statusLines[0]?.line ?? at);
+        }
+        const sev = field(block, 'Severity');
+        const sevWord = sev ? (sev.value.toLowerCase().match(/[a-z]+/)?.[0] ?? '') : '';
+        if (!sev)
+            err('finding-field', `${id} has no "**Severity:**" line`, at);
+        else if (!SEVERITIES.includes(sevWord))
+            err('severity', `${id}'s severity "${sev.value}" is not one of critical, high, medium, low, informational`, from + sev.line);
+        for (const part of FINDING_PARTS) {
+            if (!part.fields.some((f) => field(block, f)) && !headingIn(block, from, part.headings))
+                err('finding-field', `${id} says nothing under ${part.name}: add a "**${part.fields[0]}:**" line or a heading about it`, at);
+        }
+        // Impact must say what was shown and what was not.
+        const impField = field(block, 'Impact');
+        const impHead = block.findIndex((l, i) => !inFence[from + i] && /^#{2,6}\s/.test(l) && l.toLowerCase().includes('impact'));
+        const impStart = impField ? impField.line : impHead;
+        if (impStart >= 0) {
+            let impEnd = block.length;
+            for (let i = impStart + 1; i < block.length; i++)
+                if (/^#{2,6}\s/.test(block[i]) || (impField && /^\s*\*\*[^*]+:\*\*/.test(block[i]) && !/^\s*\*\*(?:What|Demonstrated|Supported|Uncertain)/i.test(block[i]))) {
+                    impEnd = i;
+                    break;
+                }
+            const text = block.slice(impStart, impField ? Math.min(impEnd, impStart + 8) : impEnd).join(' ').toLowerCase();
+            if (!/demonstrated|we showed|what we showed|reproduced/.test(text))
+                err('impact', `${id}'s impact does not say what was demonstrated`, from + impStart);
+            if (!/uncertain|did not|not run|not shown|not demonstrated|not established|limited/.test(text))
+                err('impact', `${id}'s impact does not say what remains uncertain or was not shown`, from + impStart);
+        }
+        findings.push({ id, title: ftitle, level, severity: sev ? sevWord : null, priority: field(block, 'Priority')?.value.match(/P\d/i)?.[0].toUpperCase() ?? null, evidence: evidenceIds, line: at + 1 });
+    };
+    fStarts.forEach((start, k) => {
+        const m = FINDING_HEADING.exec(lines[start]);
+        const depth = m[1].length;
+        let end = lines.length;
+        for (let i = start + 1; i < lines.length; i++) {
+            const h = /^(#{1,6})\s/.exec(lines[i]);
+            if (!inFence[i] && h && (h[1].length <= depth || FINDING_HEADING.test(lines[i]))) {
+                end = i;
+                break;
+            }
+        }
+        if (k + 1 < fStarts.length)
+            end = Math.min(end, fStarts[k + 1]);
+        const id = m[2];
+        if (seen.has(id))
+            err('finding-id', `${id} is used twice`, start);
+        seen.add(id);
+        checkFinding(id, m[3], lines.slice(start + 1, end), start + 1, start);
+    });
+    // A finding report with no F-nn block is one write-up: the title is the finding, the document its body.
+    if (kind === 'finding' && fStarts.length === 0 && title)
+        checkFinding('F-01', title, lines.slice(titleLine + 1), titleLine + 1, titleLine);
+    if (kind === 'finding' && findings.length !== 1)
+        err('finding-count', `a finding report holds one finding (one "### F-nn — title" block, or none and the title is the finding); this one has ${findings.length}`);
+    if (kind === 'retest') {
+        if (findings.length < 1)
+            err('finding-count', 'a retest report quotes its original finding as an F-nn block');
+        const retestAt = headings.find((h) => h.text === 'retest');
+        const nextAt = headings.find((h) => retestAt && h.line > retestAt.line);
+        if (retestAt) {
+            const block = lines.slice(retestAt.line + 1, nextAt ? nextAt.line : lines.length);
+            for (const f of RETEST_FIELDS)
+                if (!field(block, f))
+                    err('retest-field', `the Retest section has no "**${f}:**" field`, retestAt.line);
+            const res = field(block, 'Result');
+            if (res) {
+                const p = parseEvidence(res.value);
+                if (!p.level)
+                    err('evidence-label', 'the retest Result does not start with one of the four evidence labels', retestAt.line + 1 + res.line);
+                else if (p.level !== 'suspected' && !p.ids.some((x) => supports.get(x)?.includes(p.level)))
+                    err('evidence-level', `the retest Result says "${LEVEL_LABEL[p.level]}" but no cited id supports it`, retestAt.line + 1 + res.line);
+            }
+        }
+    }
+    // Line rules: cited ids exist, percentages carry a denominator, CVSS carries its vector.
+    lines.forEach((l, i) => {
+        for (const x of l.match(ID_RE) ?? [])
+            if (!supports.has(x))
+                err('unknown-id', `${x} is not in evidence.json`, i);
+        if (inFence[i])
+            return;
+        if (/\b\d{1,3}(?:\.\d+)?\s?%/.test(l) && !/\b[\d,]+\s*(?:\/|of|out of)\s*[\d,]+\b/i.test(l))
+            err('denominator', 'a percentage without its denominator (write "83%, 1,417 of 1,712 files")', i);
+        if (/\bCVSS\b/i.test(l) && /\b(?:10(?:\.0)?|\d\.\d)\b/.test(l.replace(/CVSS:\d\.\d/gi, '')) && !/CVSS:[234]\.\d\/[A-Z]{1,3}:/.test(l))
+            err('cvss', 'a CVSS score without its version and vector (CVSS:4.0/AV:…)', i);
+    });
+    // Secrets anywhere, code included.
+    for (const p of SECRET_PATTERNS) {
+        for (const m of md.matchAll(new RegExp(p.re.source, p.re.flags.includes('g') ? p.re.flags : p.re.flags + 'g'))) {
+            const line = md.slice(0, m.index).split('\n').length - 1;
+            err('secret', `looks like a ${p.name}; redact it and cite where it is instead`, line);
+        }
+    }
+    // Paragraph length.
+    let para = [];
+    let paraStart = 0;
+    const flush = () => {
+        const words = para.join(' ').split(/\s+/).filter(Boolean).length;
+        if (words > 120)
+            warn('paragraph', `a ${words}-word paragraph; keep paragraphs to three to five sentences`, paraStart);
+        para = [];
+    };
+    lines.forEach((l, i) => {
+        const prose = !inFence[i] && l.trim() && !/^\s*(?:#|\||[-*]\s|\d+\.\s|>|\*\*[^*]+:\*\*)/.test(l);
+        if (prose) {
+            if (!para.length)
+                paraStart = i;
+            para.push(l);
+        }
+        else
+            flush();
+    });
+    flush();
+    return { ok: errors.length === 0, title, errors, warnings, findings };
+}

package/dist/report/data.js

@@ -0,0 +1,401 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join, relative } from 'node:path';
+import { graphBin } from '../codegraph.js';
+import { version } from '../paths.js';
+import { graphDetail, lib, parseJson, runner } from '../watch.js';
+import { BravosError } from '../types.js';
+import { META_SCHEMA, REPORTS_DIR, reportDir, writeMeta } from './meta.js';
+export { META_SCHEMA, REPORTS_DIR, listReports, readMeta, reportDir, resolveReport, writeMeta } from './meta.js';
+// @comment -- "bravos report data: gathers the facts a white-box VAPT write-up may cite into one evidence bundle (.bravos/reports/<id>/evidence.json): the threat model, the hypothesis and boundary ledgers, every cxg run under .guardlink/pentest-findings, SAST, the code graph, intent, scope, proving and versions. Every fact gets a stable id, and each exposure's evidence level is computed here from the ledger, runs and SAST, never chosen by the model that writes the prose. Read-only towards the repository except the report folder it creates."
+export const EVIDENCE_SCHEMA = 'bravos.report-evidence/v1';
+export const REPORT_KINDS = ['assessment', 'finding', 'retest', 'brief'];
+export const LEVEL_LABEL = {
+    reproduced: 'reproduced at runtime',
+    held: 'control held at runtime',
+    'code-review': 'established by code or configuration review',
+    suspected: 'suspected, awaiting validation',
+};
+const arr = (v) => (Array.isArray(v) ? v : []);
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+const strip = (s) => String(s ?? '').replace(/^#/, '');
+/** Secret-shaped strings: JWTs, bearer tokens, AWS keys, private keys, key=value credentials. Shared with the report check. */
+export const SECRET_PATTERNS = [
+    { name: 'jwt', re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g },
+    { name: 'bearer token', re: /\bBearer\s+(?!<)[A-Za-z0-9._~+/-]{20,}=*/g },
+    { name: 'aws access key', re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
+    { name: 'private key', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g },
+    { name: 'credential assignment', re: /\b(?:api[_-]?key|secret[_-]?key|password|passwd|access[_-]?token|auth[_-]?token)\s*[:=]\s*["']?(?!<)[A-Za-z0-9/+_.-]{12,}/gi },
+];
+// @comment -- "Replaces secret-shaped substrings with <redacted:kind> so evidence.json and the report never carry a live token, even locally."
+export function redact(text) {
+    let out = text;
+    for (const p of SECRET_PATTERNS)
+        out = out.replace(p.re, `<redacted:${p.name}>`);
+    return out;
+}
+const red = (v, max = 1200) => redact(String(v ?? '')).slice(0, max);
+const key8 = (k) => k.replace(/[^a-f0-9]/gi, '').slice(0, 8);
+// @comment -- "Reads every cxg result under .guardlink/pentest-findings (depth 3, JSON only): a pentest run report (confirmed_findings, mitigation_verifications, not_run, auth_skipped, probe_refusals) or a cxg scan output (findings, executions). Each becomes RUN-n with its findings, executions and not-run causes as items; unreadable files are skipped and named as a gap."
+export function readRuns(root, items, gaps) {
+    const base = join(root, '.guardlink', 'pentest-findings');
+    if (!existsSync(base))
+        return [];
+    const files = [];
+    const walk = (dir, depth) => {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            const p = join(dir, e.name);
+            if (e.isDirectory() && depth < 3)
+                walk(p, depth + 1);
+            else if (e.isFile() && e.name.endsWith('.json'))
+                files.push(p);
+        }
+    };
+    walk(base, 0);
+    const runs = [];
+    let n = 0;
+    for (const file of files.sort()) {
+        let j;
+        try {
+            j = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            gaps.push(`unreadable run file ${relative(root, file)}`);
+            continue;
+        }
+        const pentest = j && (Array.isArray(j.confirmed_findings) || Array.isArray(j.mitigation_verifications));
+        const scan = j && typeof j.scan_id === 'string' && Array.isArray(j.findings) && Array.isArray(j.executions);
+        if (!pentest && !scan)
+            continue;
+        n += 1;
+        const id = `RUN-${n}`;
+        const rel = relative(root, file);
+        const findings = pentest ? arr(j.confirmed_findings) : arr(j.findings);
+        findings.forEach((f, k) => {
+            items.push({
+                id: `${id}/F-${k + 1}`,
+                kind: 'run-finding',
+                supports: ['reproduced'],
+                summary: red(f.title ?? f.description ?? f.vuln_class ?? 'finding', 300),
+                data: {
+                    template: f.template_id ?? null,
+                    severity: f.severity ?? null,
+                    endpoint: f.endpoint ?? f.target ?? null,
+                    cwe: arr(f.cwe_ids),
+                    claimKey: f.claim_key ?? null,
+                    threat: f.threat ?? f.threat_id ?? null,
+                    request: red(f.evidence?.request ?? f.evidence?.observed?.request ?? f.payload ?? ''),
+                    response: red(f.evidence?.response ?? f.evidence?.observed ?? ''),
+                    proofStatus: f.proof_status ?? null,
+                    triage: f.triage ?? null,
+                },
+            });
+        });
+        const executions = pentest ? arr(j.probe_executions) : arr(j.executions);
+        executions.forEach((x, k) => {
+            const status = String(x.status ?? '?');
+            items.push({
+                id: `${id}/X-${k + 1}`,
+                kind: 'run-execution',
+                supports: status === 'confirmed' ? ['reproduced'] : status === 'refuted' ? ['held'] : [],
+                summary: `${x.template_id ?? x.template ?? '?'}: ${status}`,
+                data: { template: x.template_id ?? x.template ?? null, status, detail: x.detail ?? x.reason ?? null },
+            });
+        });
+        const held = pentest ? arr(j.mitigation_verifications) : [];
+        held.forEach((h, k) => items.push({ id: `${id}/H-${k + 1}`, kind: 'run-execution', supports: ['held'], summary: red(h.title ?? h.template_id ?? 'mitigation held', 300), data: { template: h.template_id ?? null } }));
+        const notRun = pentest ? [...arr(j.not_run), ...arr(j.auth_skipped), ...arr(j.probe_refusals)] : [];
+        notRun.forEach((x, k) => items.push({ id: `${id}/N-${k + 1}`, kind: 'run-not-run', supports: [], summary: `${x.template ?? '?'} not run: ${x.cause ?? x.reason_kind ?? x.status ?? 'unknown'} — ${red(x.reason ?? '', 200)}` }));
+        const summary = {
+            id,
+            path: rel,
+            kind: pentest ? 'pentest' : 'scan',
+            scanId: j.scan_id ?? null,
+            at: j.completed_at ?? j.started_at ?? null,
+            target: j.target ?? findings[0]?.target ?? null,
+            authProfiles: arr(j.auth_profiles),
+            confirmed: findings.length + executions.filter((x) => x.status === 'confirmed' && !findings.length).length,
+            held: held.length + executions.filter((x) => x.status === 'refuted').length,
+            notRun: notRun.length,
+            caveats: arr(j.caveats).map((c) => red(typeof c === 'string' ? c : JSON.stringify(c), 300)),
+        };
+        items.push({ id, kind: 'run', supports: [], summary: `${summary.kind} ${summary.scanId ?? ''} at ${summary.at ?? '?'} against ${summary.target ?? '?'}: ${summary.confirmed} confirmed, ${summary.held} held, ${summary.notRun} not run`, file: rel });
+        runs.push(summary);
+    }
+    return runs;
+}
+// @comment -- "The level an exposure's evidence supports: a ledger confirmation is reproduced, a refutation is a held control, a reachable SAST finding joined to its file is code review, anything else open is suspected."
+export function levelFor(state, sastCorroborated) {
+    if (state === 'confirmed' || state === 'retest')
+        return 'reproduced';
+    if (state === 'refuted')
+        return 'held';
+    return sastCorroborated ? 'code-review' : 'suspected';
+}
+const slugOf = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
+// @comment -- "Builds the evidence bundle for root: runs guardlink parse, hypothesis list and boundaries, the tool versions and git concurrently (argv, no shell, bounded), reads runs, SAST, intent, scope and proving, optionally asks the code graph, and links each exposure to its ledger record, controls and SAST. Pure apart from those read-only calls; writes nothing."
+export async function gatherEvidence(root, env, opts) {
+    const run = await runner();
+    const now = opts.now ?? new Date();
+    const o = { cwd: root, env, timeoutMs: 60000 };
+    const quick = { cwd: root, env, timeoutMs: 10000 };
+    const gaps = [];
+    const [parseR, ledgerR, boundR, glV, cxgV, brV, graph] = await Promise.all([
+        run('guardlink', ['parse', '.'], o),
+        run('guardlink', ['hypothesis', 'list', '--json', '.'], o),
+        run('guardlink', ['hypothesis', 'boundaries', '--json', '.'], o),
+        run('guardlink', ['--version'], quick),
+        run('cxg', ['--version'], quick),
+        (() => { const b = graphBin('codegraph-build', env); return b ? run(b, ['--version'], quick) : Promise.resolve(null); })(),
+        opts.graph === false ? Promise.resolve(null) : graphDetail(root, env),
+    ]);
+    const git = (args) => {
+        const r = spawnSync('git', args, { cwd: root, env, encoding: 'utf8', timeout: 5000, stdio: ['ignore', 'pipe', 'ignore'] });
+        return r.status === 0 ? r.stdout.trim() : null;
+    };
+    const model = parseJson(parseR);
+    if (!model)
+        gaps.push(parseR.missing ? 'guardlink is not installed: no threat model' : 'guardlink parse failed: no threat model');
+    const ledgerJ = parseJson(ledgerR);
+    const boundJ = parseJson(boundR);
+    if (!ledgerJ)
+        gaps.push('guardlink hypothesis list failed: tested states unknown');
+    const items = [];
+    const runs = readRuns(root, items, gaps);
+    if (!runs.length)
+        gaps.push('no cxg run results under .guardlink/pentest-findings: nothing was exercised at runtime');
+    // SAST: the candidates' reachable findings corroborate an exposure in the same file.
+    const sastLib = await lib('sast.mjs');
+    const sastSummary = sastLib.readSast(root, env);
+    const cands = sastLib.sastCandidates(root, { all: false });
+    if (!sastSummary)
+        gaps.push('no SAST run in .bravos/sast');
+    const sastFiles = new Set();
+    let s = 0;
+    for (const [group, list] of [['joined', cands?.joined], ['unjoined', cands?.unjoined], ['dependency', cands?.dependencies], ['secret', cands?.secrets]]) {
+        for (const f of arr(list)) {
+            s += 1;
+            const reached = group !== 'dependency' || f.vulnerableFunctionReached === true;
+            if (group !== 'dependency' && f.file)
+                sastFiles.add(String(f.file));
+            items.push({
+                id: `SAST-${s}`,
+                kind: 'sast',
+                supports: reached ? ['code-review'] : [],
+                summary: `${group}: ${f.rule ?? '?'} ${f.severity ?? ''} ${f.file ?? '?'}:${f.line ?? '?'}${f.route ? ` (${f.route})` : ''}${group === 'dependency' ? ` vulnerable function reached: ${String(f.vulnerableFunctionReached ?? 'unknown')}` : ''}`,
+                file: f.file,
+                line: num(f.line),
+            });
+        }
+    }
+    // Ledger records by file:line:threat, to join each exposure to its tested state.
+    const ledgerBy = new Map();
+    for (const r of arr(ledgerJ?.records)) {
+        ledgerBy.set(`${r.file}:${r.line}:${strip(r.threat)}`, r);
+        if (r.outcome) {
+            const outcome = String(r.outcome.outcome ?? r.state);
+            items.push({
+                id: `LED-${key8(String(r.key))}`,
+                kind: 'ledger',
+                supports: outcome === 'confirmed' ? ['reproduced'] : outcome === 'refuted' ? ['held'] : [],
+                summary: `${r.claim ?? `${r.asset} to ${r.threat}`}: ${outcome} by ${r.outcome.by ?? '?'} at ${r.outcome.at ?? '?'}${r.state === 'retest' ? ' (code changed since: retest due)' : ''}`,
+                file: r.file,
+                line: num(r.line),
+                data: { evidence: red(r.outcome.evidence ?? '', 2000), source: r.outcome.source ?? null, state: r.state, previous: r.previous ?? null },
+            });
+        }
+    }
+    const mitigations = arr(model?.mitigations);
+    mitigations.forEach((m, k) => items.push({ id: `CTL-${k + 1}`, kind: 'control', supports: [], summary: `${m.control} mitigates ${m.threat} on ${m.asset}: ${red(m.description, 300)}`, file: m.location?.file, line: num(m.location?.line) }));
+    arr(boundJ?.records).forEach((b, k) => {
+        const st = String(b.state ?? 'unverified');
+        items.push({ id: `BND-${k + 1}`, kind: 'boundary', supports: st === 'supported' ? ['held'] : st === 'contradicted' ? ['reproduced'] : [], summary: `${b.claim ?? b.id}: ${st}`, file: b.file, line: num(b.line) });
+    });
+    arr(model?.acceptances).forEach((a, k) => items.push({ id: `ACC-${k + 1}`, kind: 'acceptance', supports: [], summary: `${a.threat} on ${a.asset} accepted by ${a.accepted_by ?? '?'}${a.expires ? ` until ${a.expires}` : ''}: ${red(a.description, 300)}`, file: a.location?.file, line: num(a.location?.line) }));
+    const candidates = [];
+    arr(model?.exposures).forEach((e, k) => {
+        const file = String(e.location?.file ?? '?');
+        const line = num(e.location?.line);
+        const threat = strip(e.threat);
+        const asset = strip(e.asset);
+        const rec = ledgerBy.get(`${file}:${line}:${threat}`);
+        const state = String(rec?.state ?? e.hypothesis?.state ?? 'untested');
+        const level = levelFor(state, sastFiles.has(file));
+        const id = `EXP-${k + 1}`;
+        const ctl = mitigations
+            .map((m, j) => (strip(m.threat) === threat && strip(m.asset) === asset ? `CTL-${j + 1}` : null))
+            .filter((x) => !!x);
+        const evidence = [id];
+        if (rec?.outcome)
+            evidence.push(`LED-${key8(String(rec.key))}`);
+        for (const it of items)
+            if (it.kind === 'sast' && it.file === file && it.supports.length)
+                evidence.push(it.id);
+        // The exposure's level comes from its tested state in the ledger (or SAST), so citing the exposure supports that level.
+        items.push({ id, kind: 'exposure', supports: level === 'suspected' ? ['suspected'] : [level, 'suspected'], summary: `${asset} exposed to ${threat} [${e.severity ?? 'unset'}]: ${red(e.description, 400)}`, file, line });
+        candidates.push({
+            id,
+            threat,
+            asset,
+            severity: String(e.severity ?? 'unset'),
+            cwe: arr(e.external_refs).filter((r) => /^cwe:/i.test(r)).map((r) => r.replace(/^cwe:/i, '')),
+            file,
+            line,
+            symbol: e.location?.parent_symbol ?? null,
+            description: red(e.description, 600),
+            claimKey: rec?.key ?? null,
+            state,
+            level,
+            retestDue: state === 'retest',
+            mitigatedBy: ctl,
+            evidence,
+            previous: rec?.previous ? { outcome: String(rec.previous.outcome), by: String(rec.previous.by ?? '?'), at: String(rec.previous.at ?? '?') } : null,
+        });
+    });
+    let narrowed = candidates;
+    if (opts.kind === 'finding' && opts.finding) {
+        const f = opts.finding;
+        narrowed = candidates.filter((c) => (c.claimKey && c.claimKey.startsWith(f)) || `${c.file}:${c.line}` === f || c.id === f);
+        if (!narrowed.length)
+            throw new BravosError(`no exposure matches ${f}; give a claim key prefix, file:line or EXP id from bravos report data --json`);
+    }
+    if (opts.kind === 'retest')
+        narrowed = candidates.filter((c) => c.previous || c.state === 'retest' || c.state === 'refuted' || c.state === 'confirmed');
+    const intentFile = join(root, '.guardlink', 'intent.md');
+    const intentText = existsSync(intentFile) ? readFileSync(intentFile, 'utf8') : null;
+    const briefing = await lib('briefing.mjs');
+    const intent = briefing.readIntent(root);
+    if (!intentText)
+        gaps.push('no .guardlink/intent.md: severities are not calibrated to the product');
+    const scopeFile = ['.guardlink/scope.yaml', '.guardlink/scope.yml'].find((p) => existsSync(join(root, p)));
+    const autopilot = await lib('autopilot.mjs');
+    const proving = autopilot.readProving(root);
+    const sha = git(['rev-parse', 'HEAD']);
+    const porcelain = git(['status', '--porcelain']);
+    const kindSlug = opts.kind === 'finding' && opts.finding ? `-${slugOf(narrowed[0]?.threat ?? opts.finding)}` : '';
+    const stamp = now.toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 13);
+    const firstLine = (r) => (r.status === 0 ? r.stdout.trim().split('\n')[0] : null);
+    if (graph === null && opts.graph !== false)
+        gaps.push('code graph unavailable: reach not established from entry points');
+    const s0 = model?.coverage;
+    return {
+        schema: EVIDENCE_SCHEMA,
+        id: opts.id ?? `${stamp}-${opts.kind}${kindSlug}`,
+        kind: opts.kind,
+        finding: opts.finding ?? null,
+        generatedAt: now.toISOString(),
+        repo: basename(root),
+        git: { sha, short: sha ? sha.slice(0, 9) : null, branch: git(['rev-parse', '--abbrev-ref', 'HEAD']), dirtyFiles: porcelain === null ? null : porcelain.split('\n').filter(Boolean).length, base: git(['symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD']) },
+        tools: { bravos: version(), guardlink: firstLine(glV), cxg: firstLine(cxgV), codegraph: brV ? firstLine(brV) : null },
+        intent: { status: intent.status, text: intentText },
+        scope: scopeFile ? { path: scopeFile, text: redact(readFileSync(join(root, scopeFile), 'utf8')).slice(0, 6000) } : null,
+        proving,
+        model: model
+            ? {
+                assets: arr(model.assets).length,
+                threats: arr(model.threats).length,
+                controls: arr(model.controls).length,
+                actors: arr(model.actors).length,
+                flows: arr(model.flows).length,
+                boundaries: arr(model.boundaries).length,
+                mitigations: mitigations.length,
+                exposures: arr(model.exposures).length,
+                confirmed: arr(model.confirmed).length,
+                acceptances: arr(model.acceptances).length,
+                annotations: num(model.annotations_parsed) ?? 0,
+            }
+            : null,
+        coverage: model
+            ? { annotatedFiles: arr(model.annotated_files).length, sourceFiles: arr(model.annotated_files).length + arr(model.unannotated_files).length, percent: num(s0?.coverage_percent), annotations: num(s0?.annotation_count) }
+            : null,
+        ledger: ledgerJ?.summary ? { untested: Number(ledgerJ.summary.untested) || 0, confirmed: Number(ledgerJ.summary.confirmed) || 0, refuted: Number(ledgerJ.summary.refuted) || 0, retest: Number(ledgerJ.summary.retest) || 0 } : null,
+        boundaryLedger: boundJ?.summary ? { unverified: Number(boundJ.summary.unverified) || 0, supported: Number(boundJ.summary.supported) || 0, contradicted: Number(boundJ.summary.contradicted) || 0, retest: Number(boundJ.summary.retest) || 0 } : null,
+        candidates: narrowed,
+        items,
+        runs,
+        sast: sastSummary,
+        graph: graph && 'notBuilt' in graph ? 'not-built' : graph,
+        gaps,
+    };
+}
+// @comment -- "Writes the bundle as .bravos/reports/<id>/evidence.json and a fresh meta.json, creating .bravos/reports/.gitignore (*) first so reports, which quote request and response evidence, are never committed by accident."
+export function writeEvidence(root, bundle) {
+    const base = join(root, REPORTS_DIR);
+    mkdirSync(base, { recursive: true });
+    const ignore = join(base, '.gitignore');
+    if (!existsSync(ignore))
+        writeFileSync(ignore, '*\n');
+    const dir = reportDir(root, bundle.id);
+    mkdirSync(dir, { recursive: true });
+    const evidence = join(dir, 'evidence.json');
+    writeFileSync(evidence, JSON.stringify(bundle, null, 2) + '\n');
+    const metaFile = join(dir, 'meta.json');
+    if (!existsSync(metaFile))
+        writeMeta(root, { schema: META_SCHEMA, id: bundle.id, kind: bundle.kind, createdAt: bundle.generatedAt, sha: bundle.git.sha, title: null, check: null, exports: {} });
+    return { dir, evidence };
+}
+export function readEvidence(root, id) {
+    const file = join(reportDir(root, id), 'evidence.json');
+    if (!existsSync(file))
+        throw new BravosError(`no evidence for report ${id}: run bravos report data first`);
+    const b = JSON.parse(readFileSync(file, 'utf8'));
+    if (b?.schema !== EVIDENCE_SCHEMA)
+        throw new BravosError(`${relative(root, file)} is not a ${EVIDENCE_SCHEMA} bundle`);
+    return b;
+}
+// @comment -- "Prefixes every id a member's bundle carries (items, candidates and their evidence, runs) with the member name, so ids from different services cannot collide in one report: orders:EXP-3, gateway:RUN-1/F-1."
+export function prefixBundle(member, b) {
+    const p = (id) => `${member}:${id}`;
+    return {
+        ...b,
+        candidates: b.candidates.map((c) => ({ ...c, id: p(c.id), evidence: c.evidence.map(p), mitigatedBy: c.mitigatedBy.map(p), file: `${member}/${c.file}` })),
+        items: b.items.map((i) => ({ ...i, id: p(i.id), ...(i.file ? { file: `${member}/${i.file}` } : {}) })),
+        runs: b.runs.map((r) => ({ ...r, id: p(r.id), path: `${member}/${r.path}` })),
+    };
+}
+// @comment -- "The evidence bundle for a whole bravos workspace: gatherEvidence in every member concurrently, each prefixed with its member name, merged into one bundle with the services' own git, coverage and ledger kept per member, plus EDGE-n items for the cross-service edges and UNR-n items for unresolved references from the cached bravos export. Read-only towards the members."
+export async function gatherWorkspaceEvidence(root, env, ws, opts) {
+    const now = opts.now ?? new Date();
+    const per = await Promise.all(ws.members.map((m) => gatherEvidence(m.path, env, { ...opts, now, kind: opts.kind === 'finding' ? 'assessment' : opts.kind }).then((b) => ({ m, b: prefixBundle(m.name, b) }))));
+    const items = per.flatMap(({ b }) => b.items);
+    const edges = (ws.edges ?? []).map((e, k) => ({ id: `EDGE-${k + 1}`, ...e }));
+    for (const e of edges)
+        items.push({ id: e.id, kind: 'boundary', supports: [], summary: `${e.srcMember}:${e.src} calls ${e.dstMember}:${e.dst}${e.mechanism ? ` via ${e.mechanism}` : ''} (declared in ${e.declaredIn})` });
+    const unresolved = ws.unresolved.map((u, k) => ({ id: `UNR-${k + 1}`, ...u }));
+    for (const u of unresolved)
+        items.push({ id: u.id, kind: 'boundary', supports: [], summary: `${u.member}: ${u.reference} names nothing any service defines` });
+    const gaps = per.flatMap(({ m, b }) => b.gaps.map((g) => `${m.name}: ${g}`));
+    if (!ws.edges)
+        gaps.push('cross-service edges unknown: run bravos workspace show');
+    const stamp = now.toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 13);
+    const first = per[0]?.b;
+    return {
+        schema: EVIDENCE_SCHEMA,
+        id: opts.id ?? `${stamp}-${opts.kind}-${ws.name}`,
+        kind: opts.kind,
+        finding: null,
+        generatedAt: now.toISOString(),
+        repo: ws.name,
+        git: { sha: null, short: null, branch: null, dirtyFiles: null, base: null },
+        tools: first?.tools ?? { bravos: version(), guardlink: null, cxg: null, codegraph: null },
+        intent: { status: per.map(({ m, b }) => `${m.name}: ${b.intent.status}`).join(', '), text: per.map(({ m, b }) => (b.intent.text ? `## ${m.name}\n\n${b.intent.text}` : '')).filter(Boolean).join('\n\n') || null },
+        scope: null,
+        proving: null,
+        model: null,
+        coverage: null,
+        ledger: null,
+        boundaryLedger: null,
+        candidates: per.flatMap(({ b }) => b.candidates),
+        items,
+        runs: per.flatMap(({ b }) => b.runs),
+        sast: null,
+        graph: null,
+        gaps,
+        workspace: {
+            name: ws.name,
+            members: per.map(({ m, b }) => ({ name: m.name, path: m.path, url: m.url, git: b.git, coverage: b.coverage, ledger: b.ledger, model: b.model, runs: b.runs.length, gaps: b.gaps })),
+            edges,
+            unresolved,
+        },
+    };
+}