@bugb-technologies/bravos 1.0.0 → 1.0.2

package/dist/cli.js

@@ -859,9 +859,9 @@ export function buildProgram(io, result) {
         }
         const row = (f) => `  ${(f.severity ?? '').toLowerCase().padEnd(8)} ${f.rule ?? '?'}  ${f.file ?? '?'}:${f.line ?? '?'}${f.route ? `  ${f.route}` : f.entryPoint ? `  via ${f.entryPoint}` : ''}`;
         lines.push(`SAST run ${c.run}${c.sha ? ` at ${String(c.sha).slice(0, 9)}` : ''}${opts.all ? '' : ' (reachable only; --all for the rest)'}`);
-        lines.push('', `Joined to a claim (${c.joined.length}) — taint evidence for bravos-templatize and bravos-prove:`, ...c.joined.map((f) => `${row(f)}  [${f.claimState}]`));
+        lines.push('', `Joined to a claim (${c.joined.length}) — taint evidence for bravos-templatize and bravos-prove:`, ...c.joined.map((f) => `${row(f)}  [${lib.claimLabel(f.claimState)}]`));
         lines.push('', `Not in the threat model yet (${c.unjoined.length}) — leads for bravos-annotate:`, ...c.unjoined.map(row));
-        lines.push('', `Dependencies (${c.dependencies.length}):`, ...c.dependencies.map((f) => `${row(f)}  vulnerable function reached: ${String(f.vulnerableFunctionReached ?? 'unknown')}`));
+        lines.push('', `Dependencies (${c.dependencies.length}):`, ...c.dependencies.map((f) => `${row(f)}  vulnerable function reached: ${lib.reachLabel(f.vulnerableFunctionReached)}`));
         lines.push('', `Secrets (${c.secrets.length}) — rotate; never pentest candidates:`, ...c.secrets.map((f) => `  ${f.rule ?? '?'}  ${f.file ?? '?'}:${f.line ?? '?'}${f.inHistory ? '  (in git history)' : ''}`));
     }));
     program

package/dist/guide.js

@@ -120,7 +120,7 @@ export const GUIDE_TOPICS = [
             { name: 'Is this exposure real?', skills: ['bravos-templatize', 'bravos-env', 'bravos-prove'], body: ['Template → authorized target → run. Only a reproduced run confirms; reading code never does.'] },
             { name: 'I fixed a finding', skills: ['bravos-recheck'], body: ['Re-verifies stale claims, replays the retest kit, and checks the fix added no new exposure.'] },
             { name: 'I am about to open a PR', skills: ['bravos-ship'], body: ['The no-mistakes gate: validate, lint since the merge base, disclose new exposure, block confirmed exploits on changed paths.'] },
-            { name: 'Find the routes, callers or blast radius', skills: ['bravos-codegraph'], body: ['One bounded question to the code graph instead of grepping. Needs codegraph-mcp (pip install bravos; licence-free). With it, other skills get sharper on their own: bravos-templatize targets the route and auth that actually reach each sink, bravos-recheck follows a fix\'s callers and blast radius into other files, bravos-context drafts the real public surface, and bravos-prove tests the most reachable exposures first. Without it they read the code and say so.'] },
+            { name: 'Find the routes, callers or blast radius', skills: ['bravos-codegraph'], body: ['One bounded question to the code graph instead of grepping. Team plan: bravos setup --codegraph stages codegraph-mcp, then bravos graph build . indexes the repository. With it, other skills get sharper on their own: bravos-templatize targets the route and auth that actually reach each sink, bravos-recheck follows a fix\'s callers and blast radius into other files, bravos-context drafts the real public surface, and bravos-prove tests the most reachable exposures first. Without it they read the code and say so.'] },
             { name: 'Scan for dependency CVEs, secrets, IaC', skills: ['bravos-sast'], body: ['Licensed bravos-cli: Semgrep rules, request-to-sink taint over the code graph, dependency CVEs with whether the vulnerable function is reached, secrets (git history too) and IaC. It reads the GuardLink threat model as input, so annotate first. Says plainly when it is unavailable.'] },
             { name: 'What did SAST find, and what happens to it', skills: ['bravos-sast', 'bravos-annotate', 'bravos-templatize', 'bravos-prove', 'bravos-recheck'], body: ['bravos sast candidates (free, no model) reads the newest run in .bravos/sast/: reachable findings joined to a claim feed bravos-templatize and bravos-prove (the route and taint path to target, tested first); reachable findings not in the threat model are leads for bravos-annotate; bravos-recheck rescans the changed files after a fix. A static finding is a lead, never a confirmation; only a run confirms. The briefing\'s SAST line shows the latest run, or that SAST is unavailable.'] },
             { name: 'Keep it fresh while I work, or nightly', skills: ['bravos-schedule'], body: ['An in-session /loop from .claude/loop.md, the nightly workflow, or a cloud task you create. Loops never send test traffic.'] },

package/dist/report/data.js

@@ -182,7 +182,7 @@ export async function gatherEvidence(root, env, opts) {
                 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')}` : ''}`,
+                summary: `${group}: ${f.rule ?? '?'} ${f.severity ?? ''} ${f.file ?? '?'}:${f.line ?? '?'}${f.route ? ` (${f.route})` : ''}${group === 'dependency' ? ` vulnerable function reached: ${sastLib.reachLabel(f.vulnerableFunctionReached)}` : ''}`,
                 file: f.file,
                 line: num(f.line),
             });

package/dist/setup.js

@@ -3,7 +3,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { bundleEnvironment, hostTarget, install, missingPaths, staged, VERSIONS } from './artifacts.js';
-import { graphBin } from './codegraph.js';
+import { graphBin, graphEnv } from './codegraph.js';
 import { whichBin } from './guardlink.js';
 import { findAnalyzer } from './graphbin.js';
 import { licenceLib, requireFeature } from './licence.js';
@@ -74,14 +74,16 @@ export async function runSetup(env, opts, io) {
     }
     return lines;
 }
-// @comment -- "A staged bundle proves it runs: codegraph-build --ladder, bravos-cli --version, each under the bundle's own environment. A bundle that verifies but does not run is reported, not hidden."
+// @comment -- "A staged bundle proves it runs: codegraph-build --version, bravos-cli --version, codegraph-mcp --help (it has no --version and answers with its usage), each under the bundle's own environment. A bundle that verifies but does not run is reported, not hidden."
 export function selfTest(kind, dir, env) {
     const out = [];
-    const bins = kind === 'analyzer' ? [['bravos-cli', ['--version']]] : [['codegraph-build', ['--ladder']], ['codegraph-mcp', ['--help']]];
+    const bins = kind === 'analyzer' ? [['bravos-cli', ['--version']]] : [['codegraph-build', ['--version']], ['codegraph-mcp', ['--help']]];
     for (const [name, args] of bins) {
         const r = spawnSync(join(dir, name), args, { env: bundleEnvironment(dir, env), encoding: 'utf8', timeout: 60000, stdio: ['ignore', 'pipe', 'pipe'] });
-        const ok = r.status === 0 || (name === 'codegraph-mcp' && (r.stdout + r.stderr).includes('usage'));
-        out.push(`  ${ok ? '✔' : '✘'} ${name}${ok ? ` ${(r.stdout || r.stderr).trim().split('\n')[0].slice(0, 80)}` : ` did not run: ${(r.stderr || r.error?.message || '').trim().split('\n')[0]}`}`);
+        const isMcp = name === 'codegraph-mcp';
+        const ok = r.status === 0 || (isMcp && (r.stdout + r.stderr).includes('usage'));
+        const said = isMcp ? 'runs' : (r.stdout || r.stderr).trim().split('\n')[0].slice(0, 80);
+        out.push(`  ${ok ? '✔' : '✘'} ${name}${ok ? ` ${said}` : ` did not run: ${(r.stderr || r.error?.message || '').trim().split('\n')[0]}`}`);
     }
     return out;
 }
@@ -100,20 +102,32 @@ export async function runSast(root, env, opts = {}) {
     const runDir = join(base, run);
     mkdirSync(runDir, { recursive: true });
     const sha = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', timeout: 5000 }).stdout?.trim() || null;
-    const codegraph = opts.codegraph ?? (graphBin('codegraph-mcp', env) ? 'reuse' : 'off');
-    const argv = ['analyze', root, '--ci', '--fail-on', 'never', '--allow-incomplete-analysis', '--codegraph', codegraph, '--scip', opts.scip ?? 'off', '-f', 'json,sarif', '-o', join(runDir, 'report')];
-    if (opts.scope?.length)
-        argv.push('--scope', opts.scope.join(','));
-    if (opts.exclude?.length)
-        argv.push('--exclude', opts.exclude.join(','));
-    if (opts.minSeverity)
-        argv.push('--min-severity', opts.minSeverity);
-    if (opts.timeoutS)
-        argv.push('--timeout', String(Math.max(1, opts.timeoutS - 1)));
-    const runEnv = dir ? bundleEnvironment(dir, env) : env;
-    const r = spawnSync(bin, argv, { cwd: root, env: runEnv, encoding: 'utf8', timeout: (opts.timeoutS ?? 1800) * 1000, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+    let codegraph = opts.codegraph ?? (graphBin('codegraph-mcp', env) ? 'reuse' : 'off');
+    const argvFor = (graph) => {
+        const a = ['analyze', root, '--ci', '--fail-on', 'never', '--allow-incomplete-analysis', '--codegraph', graph, '--scip', opts.scip ?? 'off', '-f', 'json,sarif', '-o', join(runDir, 'report')];
+        if (opts.scope?.length)
+            a.push('--scope', opts.scope.join(','));
+        // @comment -- ".bravos/ is always excluded: it holds the hooks bravos init copied into the repository and the SAST runs themselves, which are bravos's code, not the customer's, and would otherwise surface as findings 'not in the threat model'."
+        a.push('--exclude', ['.bravos', ...(opts.exclude ?? []).filter((p) => p !== '.bravos')].join(','));
+        if (opts.minSeverity)
+            a.push('--min-severity', opts.minSeverity);
+        if (opts.timeoutS)
+            a.push('--timeout', String(Math.max(1, opts.timeoutS - 1)));
+        return a;
+    };
+    // @comment -- "The analyzer reads the code graph from the same store bravos graph build writes to, so it runs with BRAVOS_CODEGRAPH_DIR set (graphEnv): without it, --codegraph reuse looks in the analyzer's own default store and finds no graph even when one was just built."
+    const runEnv = dir ? bundleEnvironment(dir, graphEnv(env)) : graphEnv(env);
+    const spawn = (graph) => spawnSync(bin, argvFor(graph), { cwd: root, env: runEnv, encoding: 'utf8', timeout: (opts.timeoutS ?? 1800) * 1000, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'] });
+    let r = spawn(codegraph);
+    const notes = [];
+    // No graph built for this commit yet: reuse refuses outright. Scan without reachability rather than fail, and say how to get it.
+    if (codegraph === 'reuse' && r.status === 3 && /CodeGraph unavailable|No CodeGraph/i.test(`${r.stdout}\n${r.stderr}`)) {
+        notes.push('  no code graph for this commit yet, so the scan ran without reachability; bravos graph build . --scip no-exec first, then bravos sast run again, to see which findings are reached');
+        codegraph = 'off';
+        r = spawn(codegraph);
+    }
     writeFileSync(join(runDir, 'meta.json'), JSON.stringify({ sha, base: null, scope: opts.scope?.length ? opts.scope.join(',') : 'all', exit: r.status, at: new Date().toISOString(), analyzer: bin, codegraph }, null, 2) + '\n');
-    const lines = [`SAST run ${run}: bravos-cli exited ${r.status ?? 'by signal'} (0 clean at the level, 1 findings, 3 licence refused or analysis failed, 4 a stage failed)`, `  report: ${join(runDir, 'report.json')}`];
+    const lines = [`SAST run ${run}: bravos-cli exited ${r.status ?? 'by signal'} (0 clean at the level, 1 findings, 3 licence refused or analysis failed, 4 a stage failed)`, `  report: ${join(runDir, 'report.json')}`, ...notes];
     if (r.status !== 0 && r.status !== 1)
         lines.push(`  ${(r.stderr || r.stdout || '').trim().split('\n').slice(-3).join('\n  ')}`);
     lines.push('  next: bravos sast candidates');

package/docs/GUIDE.md

@@ -144,7 +144,7 @@ The no-mistakes gate: validate, lint since the merge base, disclose new exposure
 
 Skills: `/bravos-codegraph`
 
-One bounded question to the code graph instead of grepping. Needs codegraph-mcp (pip install bravos; licence-free). With it, other skills get sharper on their own: bravos-templatize targets the route and auth that actually reach each sink, bravos-recheck follows a fix's callers and blast radius into other files, bravos-context drafts the real public surface, and bravos-prove tests the most reachable exposures first. Without it they read the code and say so.
+One bounded question to the code graph instead of grepping. Team plan: bravos setup --codegraph stages codegraph-mcp, then bravos graph build . indexes the repository. With it, other skills get sharper on their own: bravos-templatize targets the route and auth that actually reach each sink, bravos-recheck follows a fix's callers and blast radius into other files, bravos-context drafts the real public surface, and bravos-prove tests the most reachable exposures first. Without it they read the code and say so.
 
 ### Scan for dependency CVEs, secrets, IaC
 

package/hooks/lib/sast.mjs

@@ -111,6 +111,22 @@ export function sastCandidates(root, { all = false } = {}) {
   return out;
 }
 
+// @comment -- "One line for the claim a SAST finding joined: the analyzer's guardlink_join is an object ({asset, threat, declared_at, …}) in current reports and was a plain state string in older ones; both read as text, never as [object Object]."
+export function claimLabel(cs) {
+  if (cs == null) return 'claim';
+  if (typeof cs !== 'object') return String(cs);
+  const what = cs.asset && cs.threat ? `#${cs.asset} → #${cs.threat}` : cs.threat ? `#${cs.threat}` : 'claim';
+  return cs.declared_at ? `${what} at ${cs.declared_at}` : what;
+}
+
+// @comment -- "One phrase for whether a dependency advisory's vulnerable function is reached: the analyzer reports {state, reason, …}; older reports carried a boolean or nothing."
+export function reachLabel(v) {
+  if (v == null) return 'unknown';
+  if (typeof v !== 'object') return String(v);
+  const state = v.state ?? 'unknown';
+  return v.reason ? `${state} (${String(v.reason).replace(/_/g, ' ')})` : state;
+}
+
 // @comment -- "The Python bravos CLI (siete) on PATH, as `bravos` or renamed to `bravos-py`, and never this package's own `bravos` bin: an npm shim is a script that execs node on dist/cli.js, and skipping it keeps the hooks pointed at the Python install's analyzer and graph until phase 3 makes this CLI carry them."
 export function pythonBravos(env = process.env) {
   // Its own name first, then bravos-py: the name it keeps once it is renamed so `bravos` means this CLI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bugb-technologies/bravos",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Skills pack and installer that make Claude Code and Codex power users of guardlink (threat-model-as-code) and cert-x-gen (pentest-as-code).",
   "keywords": [
     "security",