@clear-capabilities/agentic-security-scanner 0.134.0 → 0.136.9

package/src/posture/auditor-walkthrough.js

@@ -8,6 +8,8 @@
 //
 //   nist-csf-2          NIST Cybersecurity Framework 2.0
 //   nist-ai-600-1       NIST AI Risk Management Framework, GenAI profile
+//   nist-privacy-1-1    NIST Privacy Framework 1.1 (see posture/privacy-framework.js
+//                       for the assessment + remediation layer over it)
 //   owasp-asvs-5        OWASP Application Security Verification Standard 5.0
 //   owasp-llm-top-10    OWASP Top 10 for LLM Applications 2025
 //   eu-ai-act           EU AI Act (Regulation 2024/1689)
@@ -32,9 +34,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath, stateWritesEnabled } from './state-dir.js';
 const BUNDLED_DIR = path.join(path.dirname(new URL(import.meta.url).pathname), 'compliance-frameworks');
-const STATE = '.agentic-security';
-
 function _readJson(fp) {
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
 }
@@ -52,7 +53,7 @@ export function listFrameworks(scanRoot) {
     }
   } catch {}
   if (scanRoot) {
-    const projDir = path.join(scanRoot, STATE, 'compliance');
+    const projDir = statePath(scanRoot, 'compliance');
     if (fs.existsSync(projDir)) {
       try {
         for (const sub of fs.readdirSync(projDir)) {
@@ -73,7 +74,7 @@ export function listFrameworks(scanRoot) {
  */
 export function loadFramework(scanRoot, id) {
   if (scanRoot) {
-    const projFp = path.join(scanRoot, STATE, 'compliance', id, 'controls.json');
+    const projFp = statePath(scanRoot, 'compliance', id, 'controls.json');
     if (fs.existsSync(projFp)) return _readJson(projFp);
   }
   for (const fn of fs.readdirSync(BUNDLED_DIR)) {
@@ -97,11 +98,69 @@ export function loadFramework(scanRoot, id) {
  *   'absent'    — no signal / open critical findings on every mapsTo family
  *   'manual'    — control has no mapsTo (requires manual attestation)
  */
+// Stage 6 correctness audit: several compliance frameworks map controls to
+// `family:auth-missing` / `family:authz`, but no detector in this codebase
+// ever emits those literal family strings — the real missing-auth/authz
+// detectors use `broken-access-control` (generic), `fastapi-missing-auth`,
+// `springboot-missing-authz`, `laravel-missing-auth`, `quarkus-missing-authz`
+// (framework-specific). Without this alias, a control mapped to
+// auth-missing/authz read "present" (vacuously — the family bucket was
+// always empty) even with a critical, unauthenticated route open. Listed
+// under both compliance-side names since `broken-access-control` covers
+// both "nobody checked" (missing auth) and "checked wrong" (broken authz)
+// and it is strictly safer to over-count a real finding against both than
+// to keep silently excluding it from either.
+// CMP-1 (Stage 6 follow-up): grown incrementally by cross-referencing every
+// `family:` string the bundled compliance-frameworks/*.json files reference
+// against what src/sast + src/posture actually emit (a small, closed
+// problem — only the strings a control actually maps to, not a universal
+// vocabulary registry). k8s-admission.js's real rule id is
+// `k8s-pod-privileged`; `nist-csf-2.json`/`hipaa-security-rule.json` map to
+// the compliance-side spelling `k8s-pod-security-privileged`, which no
+// detector ever emitted.
+const COMPLIANCE_FAMILY_ALIAS = {
+  'auth-missing': ['broken-access-control', 'fastapi-missing-auth', 'springboot-missing-authz', 'laravel-missing-auth', 'quarkus-missing-authz'],
+  'authz': ['broken-access-control', 'idor', 'springboot-missing-authz', 'quarkus-missing-authz'],
+  'k8s-pod-security-privileged': ['k8s-pod-privileged'],
+};
+
+// CMP-1 audit trail: every `family:` string referenced by the bundled
+// compliance-frameworks/*.json files was cross-checked against real
+// detector output; entries above are the confirmed naming mismatches with a
+// real detector to alias, and `mcp-audit.js`/`sca/dep-confusion.js` were
+// fixed at the SOURCE (they now set `family` explicitly) rather than
+// aliased, since the finding constructors themselves were the root cause.
+// Four references have no matching detector at all — not a naming
+// mismatch, a genuine coverage gap that would need a new rule, out of
+// scope for an alias table: `crypto-tls-version` (crypto-protocol.js checks
+// verify-disabled, not minimum-TLS-version — the file's own header comment
+// even names the never-implemented `crypto-tls-min-version` rule id),
+// `nosql-injection` (referenced by cross-lang-meta.js's chain-detection
+// list, but no dedicated NoSQL-injection detector exists), `pii-exposure`
+// and `data-exposure` (both referenced only by consumers — threat-model-
+// auto.js's classifier and a Juliet-benchmark answer-key label
+// respectively — with no producer). Every control mapped to one of these
+// four reads `manual`/`engine-gap` rather than a false `present`, which is
+// the safe failure mode this whole mechanism exists to guarantee.
 export function evaluateFramework(scanRoot, fw, scan) {
+  // CMP-2: last-scan.json (what this is actually handed in production) carries
+  // findings across four separate channels — SAST (`findings`), secrets,
+  // business-logic, and SCA (`supplyChain`) — because report/index.js's
+  // normalizeFindings keeps them apart too. Reading only `scan.findings` made
+  // every secrets/logic/SCA finding invisible to every framework's family:
+  // mappings, e.g. a critical hardcoded secret never counted against a
+  // control mapped to family:hardcoded-secret. Each channel's family default
+  // mirrors normalizeFindings' own fallback for that channel so the two stay
+  // in agreement about what family an untagged finding belongs to.
   const findings = (scan && Array.isArray(scan.findings)) ? scan.findings : [];
+  const secrets = ((scan && Array.isArray(scan.secrets)) ? scan.secrets : [])
+    .map(s => ({ ...s, family: s.family || 'hardcoded-secret' }));
+  const logicVulns = (scan && Array.isArray(scan.logicVulns)) ? scan.logicVulns : [];
+  const supplyChain = ((scan && Array.isArray(scan.supplyChain)) ? scan.supplyChain : [])
+    .map(sc => ({ ...sc, family: sc.family || 'vulnerable-dep' }));
   const components = (scan && Array.isArray(scan.components)) ? scan.components : [];
   const families = new Map();
-  for (const f of findings) {
+  for (const f of [...findings, ...secrets, ...logicVulns, ...supplyChain]) {
     const k = f.family || 'unknown';
     if (!families.has(k)) families.set(k, []);
     families.get(k).push(f);
@@ -121,15 +180,43 @@ export function evaluateFramework(scanRoot, fw, scan) {
 
     let allCleared = true;
     let anySignal = false;
+    // Tracks whether ANY family:/module: mapping in this control actually
+    // passed (distinct from allCleared, which asks whether EVERY one did).
+    // Feeds the 'absent' vs 'partial' distinction below: a control where
+    // nothing at all checks out is a materially different auditor story
+    // ("no evidence") than one that's mostly clean with one open gap
+    // ("evidence with a gap") — both used to render as the same 'partial'.
+    let anyCleared = false;
+    // CMP-2: a rule: mapping's own observation says "verify manually" — it
+    // is deliberately not code-checked. It used to set anySignal=true and
+    // leave allCleared untouched, so a control whose ONLY mapping was rule:
+    // resolved to 'present' (fully evidenced), the same status as a control
+    // with real, checked evidence. Any rule: mapping present caps the
+    // control at 'partial' — never 'present' — regardless of what the
+    // family:/module: mappings in the same control found.
+    let hasUnverifiableMapping = false;
     for (const m of maps) {
       if (m.startsWith('family:')) {
-        const fam = m.slice('family:'.length).split(':')[0];
-        const open = (families.get(fam) || []).filter(f => !f.intentSuppressed && !f.pastDecision && (f.severity === 'critical' || f.severity === 'high'));
+        // `family:X` and the subfamily-qualified `family:X:Y` (used by
+        // owasp-llm-top-10 for LLM02/LLM06/LLM07) both used to collapse to
+        // just `X` here — the `:Y` qualifier was parsed and then silently
+        // dropped, so any finding of family X counted against every control
+        // mapped to X regardless of which subfamily the control actually
+        // named (four LLM controls flagged off one credential-in-prompt
+        // finding). Detectors that emit a subfamily always set it, so
+        // filtering is safe; findings with no subfamily set still count
+        // (recall-preserving default — same precedent as relevance.js).
+        const [fam, subfam] = m.slice('family:'.length).split(':');
+        const aliasFams = COMPLIANCE_FAMILY_ALIAS[fam] || [];
+        const candidates = [fam, ...aliasFams].flatMap(k => families.get(k) || []);
+        const scoped = subfam ? candidates.filter(f => !f.subfamily || f.subfamily === subfam) : candidates;
+        const open = scoped.filter(f => !f.intentSuppressed && !f.pastDecision && (f.severity === 'critical' || f.severity === 'high'));
         if (open.length) {
           allCleared = false;
           obs.push(`${open.length} open ${fam} finding(s) at high/critical.`);
         } else {
           obs.push(`✓ ${fam}: no open critical/high findings.`);
+          anyCleared = true;
         }
         anySignal = true;
       } else if (m.startsWith('module:')) {
@@ -164,15 +251,16 @@ export function evaluateFramework(scanRoot, fw, scan) {
         // A '.../' sentinel marks a source-relative artifact (project source,
         // e.g. a hook or agent file) — resolve it against the scan root itself.
         // Everything else is a runtime artifact under the STATE dir. Without
-        // this, `path.join(scanRoot, STATE, '.../x')` never resolves and the
+        // this, `statePath(scanRoot, '.../x')` never resolves and the
         // control falsely reads "not present" for every project.
         const resolved = !target ? null
           : target.startsWith('.../') ? path.join(scanRoot, target.slice(4))
-          : path.join(scanRoot, STATE, target);
+          : statePath(scanRoot, target);
         const label = target ? target.replace(/^\.\.\.\//, '') : '(unmapped)';
         if (resolved && fs.existsSync(resolved)) {
           obs.push(`✓ ${mod}: ${label} present.`);
           anySignal = true;
+          anyCleared = true;
         } else {
           obs.push(`✗ ${mod}: expected ${label} not present.`);
           allCleared = false;
@@ -181,11 +269,23 @@ export function evaluateFramework(scanRoot, fw, scan) {
         // Could check whether a custom rule fires zero — leave a hint for now.
         obs.push(`(rule mapping) ${m} — verify manually that the bodyguard rule is enabled.`);
         anySignal = true;
+        hasUnverifiableMapping = true;
       }
     }
 
+    // 'absent' was documented (see the docstring above) as a fourth,
+    // distinct status — a control where NOTHING passed at all — but the
+    // assignment below never produced it; every non-present, non-manual
+    // control rendered as 'partial' regardless of whether it was "mostly
+    // clean with one gap" or "completely unevidenced". Only introduced for
+    // the fully-automated case (no rule: mapping) to avoid reclassifying
+    // any control that already reads 'partial' because of an inherently
+    // unverifiable rule: mapping — that precedent (rule: caps at 'partial',
+    // never reaching 'present' OR 'absent') is unchanged.
     if (!anySignal) status = 'manual';
+    else if (hasUnverifiableMapping) status = 'partial';
     else if (allCleared) status = 'present';
+    else if (!anyCleared) status = 'absent';
     else status = 'partial';
 
     results.push({ control: c, status, observations: obs });
@@ -251,7 +351,8 @@ export function renderWalkthrough(fw, evaluation, opts = {}) {
  * Persist the walkthrough at .agentic-security/auditor-walkthroughs/<id>.md
  */
 export function persistWalkthrough(scanRoot, fw, body) {
-  const dir = path.join(scanRoot, STATE, 'auditor-walkthroughs');
+  const dir = statePath(scanRoot, 'auditor-walkthroughs');
+  if (!stateWritesEnabled()) return null;
   try { fs.mkdirSync(dir, { recursive: true }); } catch {}
   const fp = path.join(dir, `${fw.id}.md`);
   try { fs.writeFileSync(fp, body); } catch {}

package/src/posture/auth-posture-import.js

@@ -27,6 +27,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './state-dir.js';
 const KNOWN_GOOD = new Set([
   'session+csrf', 'session+admin', 'session+claim', 'session',
   'jwt+verify', 'oauth+pkce', 'mtls',
@@ -41,15 +42,15 @@ const FAMILIES_GATEABLE_BY_AUTH = new Set([
 ]);
 
 const CANDIDATE_PATHS = [
-  '.agentic-security/auth-posture.json',
-  '.agentic-security/auth-posture.yml',
-  '.agentic-security/auth-posture.yaml',
+  'auth-posture.json',
+  'auth-posture.yml',
+  'auth-posture.yaml',
 ];
 
 export function loadAuthPosture(scanRoot) {
   const root = scanRoot || process.cwd();
   for (const rel of CANDIDATE_PATHS) {
-    const fp = path.join(root, rel);
+    const fp = statePath(root, rel);
     if (!fs.existsSync(fp)) continue;
     try {
       const text = fs.readFileSync(fp, 'utf8');

package/src/posture/autopilot.js

@@ -110,7 +110,14 @@ export async function runAutopilot({
   for (const f of inScope) {
     const key = f.stableId || `${f.file}:${f.line}:${f.vuln}`;
     const prior = resume ? state.findings[key] : null;
-    if (prior?.outcome) { results.push(prior); continue; }
+    // A cached VERIFIED_FIXED whose patch was gated (not written) on a prior
+    // apply:false run is not a terminal outcome once the caller asks for
+    // apply:true — replaying it verbatim would silently never call
+    // applyFix on the exact two-step workflow (preview, then --apply) this
+    // gate exists to support. Everything else cached IS terminal and is
+    // replayed as before.
+    const gatedOnlyByApply = prior?.outcome === 'VERIFIED_FIXED' && prior.applied !== true && apply === true;
+    if (prior?.outcome && !gatedOnlyByApply) { results.push(prior); continue; }
 
     const rec = { key, file: f.file, line: f.line, vuln: f.vuln, severity: f.severity };
 

package/src/posture/calibration-drift.js

@@ -57,12 +57,18 @@ export function computeDrift(scanRoot, opts = {}) {
   const fb = loadTriageFeedback(scanRoot);
   if (!fb.length) return { alarms: [], note: 'no-feedback-data' };
 
-  // Group by family. Each entry should carry: family, verdict ('tp'|'fp'|'wai'),
-  // reportedConfidence (0..1), ts.
+  // Group by family. Each entry should carry: family, verdict ('tp'|'fp'|'wontfix'),
+  // reportedConfidence (0..1), at.
+  // Field names/verdict values here previously didn't match the real
+  // producer (commands/triage.md's Step 2): it writes `at`, not `ts`, and
+  // never wrote `reportedConfidence` at all (fixed there alongside this —
+  // Stage 2 measurement-completeness audit) or a `'wai'` verdict (it only
+  // ever writes 'tp'|'fp'|'wontfix'), so this alarm could never fire against
+  // real triage data regardless of how badly calibration had drifted.
   const byFamily = new Map();
   for (const e of fb) {
-    if (!e || !e.family || !inWindow(e.ts, window)) continue;
-    if (!['tp', 'fp', 'wai'].includes(e.verdict)) continue;
+    if (!e || !e.family || !inWindow(e.at, window)) continue;
+    if (!['tp', 'fp', 'wontfix'].includes(e.verdict)) continue;
     if (typeof e.reportedConfidence !== 'number') continue;
     if (!byFamily.has(e.family)) byFamily.set(e.family, []);
     byFamily.get(e.family).push(e);
@@ -75,7 +81,7 @@ export function computeDrift(scanRoot, opts = {}) {
     const reportedAcc = entries.reduce((acc, e) => acc + e.reportedConfidence, 0) / entries.length;
     const divergence = Math.abs(reportedAcc - realizedAcc);
     if (divergence < threshold) continue;
-    const firstTs = entries.map(e => e.ts).filter(Boolean).sort()[0];
+    const firstTs = entries.map(e => e.at).filter(Boolean).sort()[0];
     alarms.push({
       alarm: true,
       since: firstTs,

package/src/posture/calibration.js

@@ -121,15 +121,37 @@ export function loadCalibrationHistory(scanRoot) {
   };
   if (seed) merge(seed);
   if (customer) merge(customer);
-  // Merge triage-derived TP/FP counts (auto-feedback loop)
+  // Merge triage-derived TP/FP counts (auto-feedback loop).
+  //
+  // EA-01: only a state a human actually chose is a real signal. triage.js's
+  // syncWithScan sets every new finding to 'open' with no human involved, and
+  // auto-closes any finding the scanner stops seeing to 'fixed' with
+  // `automatic:true` on the transition — neither reflects a judgment that the
+  // finding was real. Counting them as TP made the "true positive" column
+  // entirely machine-generated while the FP column required an explicit human
+  // false-positive mark, so calibrated confidence trended toward 1.0 for any
+  // family with enough scan volume regardless of actual accuracy. Only a
+  // manual 'fixed' transition (confirmed real, now resolved) counts as TP;
+  // only 'false-positive' counts as FP. 'open', 'in-progress', 'wont-fix',
+  // and an automatically-reached 'fixed' contribute to neither bucket.
   try {
     const triage = _readJsonMaybe(statePath(scanRoot, 'triage.json'));
     if (triage && triage.findings) {
+      const lastFixedIsAutomatic = new Map();
+      for (const t of triage.transitions || []) {
+        if (t && t.to === 'fixed') lastFixedIsAutomatic.set(t.id, t.automatic === true);
+      }
       const triageFams = {};
       for (const f of Object.values(triage.findings)) {
         const fam = f.family || 'unknown';
         if (!triageFams[fam]) triageFams[fam] = { tp: 0, fp: 0 };
-        if (f.state === 'fixed' || f.state === 'open' || f.state === 'in-progress') triageFams[fam].tp++;
+        // Require POSITIVE proof of a manual transition (=== false), not
+        // merely the absence of proof of an automatic one (!== true) — the
+        // latter fails OPEN: a finding with no transition record at all
+        // (lastFixedIsAutomatic.get returns undefined) counted as a manual
+        // TP by default, exactly the machine-generated-signal failure mode
+        // this whole block's comment states it exists to prevent.
+        if (f.state === 'fixed' && lastFixedIsAutomatic.get(f.id) === false) triageFams[fam].tp++;
         else if (f.state === 'false-positive') triageFams[fam].fp++;
       }
       merge({ families: triageFams });