@clear-capabilities/agentic-security-scanner 0.147.0 → 0.148.0

package/dist/frontend/styles/tokens.css

@@ -0,0 +1,128 @@
+/*
+ * Data Flow Explorer design tokens (PRD §8.1). Dark is the reference theme.
+ * Values are copied verbatim from the PRD — do not adjust without a
+ * deliberate, separately-reviewed change.
+ */
+
+:root {
+  /* Surfaces */
+  --surface-canvas: #061625;
+  --surface-panel: #0B1E2F;
+  --surface-elevated: #102A40;
+  --border-default: #28445A;
+
+  /* Text */
+  --text-primary: #F3F7FA;
+  --text-secondary: #9FB3C5;
+
+  /* Selection / focus */
+  --accent-selection: #3DA9FF;
+
+  /* Protection verdict status */
+  --status-protected: #59D17D;
+  --status-unprotected: #FF625C;
+  --status-unknown: #F5B83D;
+
+  /* Text color for content painted directly on a status token background
+     (e.g. the coverage banner). NOT the same as --text-primary, which is
+     sized against --surface-canvas/--surface-panel, not against a status
+     color. Verified with lib/contrast.js's contrastRatio(): #061625 on
+     dark --status-unknown (#F5B83D) is 10.27:1. See the light-theme block
+     below for the light-theme value and its own verified ratio. */
+  --status-banner-text: #061625;
+
+  /* AI processing context */
+  --context-ai: #B47AFF;
+
+  /* Data class overlays */
+  --class-pii: #28D1C5;
+  --class-phi: #A97BFF;
+  --class-pci: #4CA7FF;
+
+  /* Spacing (8px grid, PRD §7.7) */
+  --space-1: 8px;
+  --space-2: 16px;
+  --space-3: 24px;
+  --space-4: 32px;
+
+  /* Radius / border (PRD §8.2) */
+  --radius-default: 8px;
+  --border-width: 1px;
+
+  /* Typography (PRD §8.2) — bundled system stack; never a remote/CDN font */
+  --font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --font-size-view-title: 23px;
+  --font-size-panel-title: 15px;
+  --font-size-node-title: 14px;
+  --font-size-body: 13px;
+  --font-size-code: 12.5px;
+
+  /* Motion (PRD §8.2 — focus/topology change only, no ambient animation) */
+  --motion-duration: 200ms;
+  --motion-duration-reduced: 0ms;
+
+  /* Shell region sizing (PRD §7.7) */
+  --header-height: 56px;
+  --view-tabs-height: 44px;
+  --left-rail-width: 248px;
+  --left-rail-collapsed-width: 56px;
+  --right-inspector-width: 360px;
+  --context-rail-height: 72px;
+}
+
+/* Light theme — same semantic tokens, WCAG-AA-equivalent contrast (PRD §8.1/§23) */
+:root[data-theme="light"] {
+  --surface-canvas: #FFFFFF;
+  --surface-panel: #F4F7FA;
+  --surface-elevated: #E7EEF3;
+  --border-default: #C7D3DC;
+
+  --text-primary: #0B1E2F;
+  --text-secondary: #3E5568;
+
+  --accent-selection: #1B6FC2;
+
+  /* status-protected and status-unknown darkened slightly from their
+     original values (#1E8A4C, #9A6B00) — Milestone 3, sub-project A11y,
+     found via test/tokens-contrast.test.js that both originals failed
+     WCAG AA (4.5:1) against --surface-panel (#F4F7FA): 4.07:1 and 4.36:1
+     respectively. Verified with lib/contrast.js's contrastRatio() against
+     BOTH backgrounds a status color plausibly renders on: --status-
+     protected (#1C8047) is 4.97:1 on --surface-canvas / 4.62:1 on
+     --surface-panel; --status-unknown (#956700) is 4.98:1 / 4.63:1. Both
+     now clear AA with margin (>=4.6) rather than sitting at the exact
+     4.50 boundary, which is fragile against hex-rounding. --status-
+     unprotected was already compliant (5.26:1 / 4.89:1), unchanged. */
+  --status-protected: #1C8047;
+  --status-unprotected: #C7362D;
+  --status-unknown: #956700;
+
+  /* Verified with lib/contrast.js's contrastRatio(): #FFFFFF on light
+     --status-unknown (#956700) is 4.98:1 (>= 4.5:1 AA). The dark-block
+     value (#061625, --surface-canvas's own dark value) is 3.90:1 here --
+     below AA -- which is the bug this token pair fixes: shell.css must
+     never hardcode dark theme's value and expect it to also work in
+     light theme. */
+  --status-banner-text: #FFFFFF;
+
+  --context-ai: #6E38B8;
+
+  --class-pii: #0E7C73;
+  --class-phi: #6E44B8;
+  --class-pci: #1C63A8;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --motion-duration: var(--motion-duration-reduced);
+  }
+}
+
+body {
+  background: var(--surface-canvas);
+  color: var(--text-primary);
+  font-family: var(--font-family);
+  font-size: var(--font-size-body);
+  margin: 0;
+}

package/dist/frontend/styles/trace-view.css

@@ -0,0 +1,95 @@
+.trace-view {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  max-width: 640px;
+}
+
+.trace-step {
+  display: flex;
+  gap: var(--space-2);
+  padding: var(--space-2);
+  background: var(--surface-panel);
+  border: var(--border-width) solid var(--border-default);
+  border-radius: var(--radius-default);
+}
+
+.trace-step-number {
+  flex: 0 0 auto;
+  width: 24px;
+  height: 24px;
+  border-radius: 50%;
+  background: var(--surface-elevated);
+  color: var(--text-primary);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: var(--font-size-code);
+  font-weight: 600;
+}
+
+.trace-step-body {
+  flex: 1 1 auto;
+}
+
+.trace-step-kind {
+  color: var(--text-secondary);
+  font-size: var(--font-size-code);
+  text-transform: uppercase;
+}
+
+.trace-step-mapping {
+  font-family: var(--font-mono);
+  font-size: var(--font-size-code);
+  color: var(--text-primary);
+  margin: 4px 0;
+}
+
+.trace-step-node {
+  color: var(--text-secondary);
+  font-size: var(--font-size-body);
+}
+
+.trace-step-boundary {
+  display: inline-block;
+  border: 1px solid var(--status-unprotected);
+  color: var(--status-unprotected);
+  border-radius: var(--radius-default);
+  padding: 1px 6px;
+  font-size: var(--font-size-code);
+  margin-top: 4px;
+}
+
+.trace-branch-group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  padding-left: var(--space-2);
+  border-left: 2px solid var(--accent-selection);
+}
+
+.trace-branch-label {
+  color: var(--text-secondary);
+  font-size: var(--font-size-code);
+  text-transform: uppercase;
+}
+
+.trace-alternates {
+  margin-top: var(--space-2);
+}
+
+.trace-alternate-item {
+  padding: var(--space-1) 0;
+  cursor: pointer;
+  color: var(--text-secondary);
+}
+
+.trace-alternate-item:hover {
+  color: var(--text-primary);
+}
+
+.trace-empty {
+  color: var(--text-secondary);
+  font-style: italic;
+  padding: var(--space-2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clear-capabilities/agentic-security-scanner",
-  "version": "0.147.0",
+  "version": "0.148.0",
   "description": "Scanner engine for the agentic-security Claude Code plugin — SAST, SCA (function-level reachability + CISA KEV), secrets, IaC, prompt-injection, MCP/agent-tool audit, auth/authZ deep analysis, attack chains, PoC generation, business logic, toxic-combinations scoring, SBOM, pipeline integrity, compliance attestation, and more.",
   "type": "module",
   "main": "src/index.js",
@@ -56,7 +56,7 @@
     "lodash-es": "^4.18.1"
   },
   "scripts": {
-    "build": "ncc build bin/agentic-security.js -o dist --minify -e web-tree-sitter -e tree-sitter-wasms && rm -rf dist/compliance-frameworks && mkdir -p dist/compliance-frameworks && cp src/posture/compliance-frameworks/*.json dist/compliance-frameworks/ && mv dist/index.js dist/agentic-security.mjs && rm -f dist/package.json && chmod +x dist/agentic-security.mjs && node -e \"const fs=require('fs');const p='dist/agentic-security.mjs';const c=fs.readFileSync(p,'utf8');if(!c.startsWith('#!'))fs.writeFileSync(p,'#!/usr/bin/env node\\n'+c);\" && node -e \"const fs=require('fs');const c=require('crypto');const h=c.createHash('sha256').update(fs.readFileSync('dist/agentic-security.mjs')).digest('hex');fs.writeFileSync('dist/agentic-security.mjs.sha256',h+'  agentic-security.mjs\\n');\"",
+    "build": "ncc build bin/agentic-security.js -o dist --minify -e web-tree-sitter -e tree-sitter-wasms && rm -rf dist/compliance-frameworks && mkdir -p dist/compliance-frameworks && cp src/posture/compliance-frameworks/*.json dist/compliance-frameworks/ && node scripts/copy-frontend.mjs && mv dist/index.js dist/agentic-security.mjs && rm -f dist/package.json && chmod +x dist/agentic-security.mjs && node -e \"const fs=require('fs');const p='dist/agentic-security.mjs';const c=fs.readFileSync(p,'utf8');if(!c.startsWith('#!'))fs.writeFileSync(p,'#!/usr/bin/env node\\n'+c);\" && node -e \"const fs=require('fs');const c=require('crypto');const h=c.createHash('sha256').update(fs.readFileSync('dist/agentic-security.mjs')).digest('hex');fs.writeFileSync('dist/agentic-security.mjs.sha256',h+'  agentic-security.mjs\\n');\"",
     "prepare": "node ../scripts/pre-push-gate.mjs --install-hook",
     "prepublishOnly": "npm run build && node ../scripts/sync-scanner-changelog.mjs && node ../scripts/release-check.mjs",
     "test": "node ../scripts/run-unit-tests.mjs && AGENTIC_SECURITY_CPP_DATAFLOW=1 node --test test/cpp-dataflow.test.js && node --experimental-test-module-mocks --test test/fault-injection.test.js && node --experimental-test-module-mocks --test test/detector-fault-injection.test.js && node --experimental-test-module-mocks --test test/detector-fault-injection-k8s-admission.test.js && node --experimental-test-module-mocks --test test/lineage-fault-injection.test.js && npm run test:python",

package/src/posture/auditor-walkthrough.js

@@ -10,6 +10,14 @@
 //   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)
+//   nist-800-171-r3     NIST SP 800-171 Rev. 3 — Protecting CUI in Nonfederal
+//                       Systems. FULL 97-requirement catalogue; 43 of those are
+//                       organisational/physical and carry no automated signal at
+//                       all, deliberately carried so the negative space is visible.
+//                       Control text is generated from the CSV export by
+//                       scripts/nist-800-171/build-catalog.py; the codeTestable
+//                       rating is OURS, not NIST's (that export rates nothing for
+//                       testability) and lives in nist-800-171/code-testability.json.
 //   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)
@@ -345,6 +353,60 @@ export function evaluateFramework(scanRoot, fw, scan) {
     families.get(k).push(f);
   }
 
+  // VACUOUS SATISFACTION GUARD (shared-evaluator half).
+  //
+  // The `family:` branch below clears a mapping when no findings of that family
+  // are open — which is ALSO true of a scan that examined nothing at all. So
+  // pointing `--report <framework>` at an empty directory, a wrong path, or a
+  // scan that failed to read anything reported mapped controls as fully
+  // evidenced, on the strength of having looked at zero files.
+  //
+  // privacy-framework.js's `bucketOf` has carried this guard for its own module
+  // since it was found by that module's test, and its comment already named
+  // `evaluateFramework` as the place the hazard originates — but the guard was
+  // never applied HERE, so every framework reached through `--report` /
+  // `--walkthrough` / `--gap` / `--format oscal` still had it. Found while
+  // adding NIST SP 800-171 Rev. 3, whose 50 mapped controls made a
+  // zero-file scan report 32 controls `present`.
+  //
+  // Reads THREE count fields, not the two privacy-framework.js reads. Measured,
+  // not assumed: a real scan of a clean one-file project persists
+  // `scanned.files: 1` and `_scanMeta.filesScanned: 1` but NO top-level
+  // `filesScanned` — that key exists only on the in-memory object engine.js
+  // returns. privacy-framework.js reads `filesScanned ?? _scanMeta.filesScanned`
+  // and gets away with it because engine.js hands it the live in-memory object;
+  // this evaluator is reached from the CLI with the PERSISTED artifact, where
+  // that first key is absent. Mirroring privacy's exact field list here would
+  // therefore have read 0 for every real scan and degraded a genuinely clean
+  // project to "not assessed" — the opposite failure, and worse, because it
+  // punishes the operator who did everything right.
+  //
+  // ABSENT IS UNKNOWN, NOT ZERO. Degrading requires POSITIVE evidence that
+  // nothing was examined: at least one count field actually present AND every
+  // present one reading 0. A scan object carrying no count fields at all
+  // (synthetic fixtures, older artifacts, third-party callers) is treated as
+  // assessable and behaves exactly as before. Same precedent as relevance.js —
+  // never assert the negative without evidence, and `unknown` is not `false`.
+  // The findings/components/... fallbacks then rescue the remaining case: an
+  // artifact that records 0 files but plainly holds real results.
+  //
+  // An unassessable scan does not remove or fail a control: the mapping is
+  // disclosed as unverifiable, which caps the control at 'partial' via the same
+  // path a `rule:` mapping already uses. Recall-preserving, same precedent as
+  // falsification.js / proof-gate.js.
+  const _counts = [
+    scan && scan.filesScanned,
+    scan && scan._scanMeta && scan._scanMeta.filesScanned,
+    scan && scan.scanned && scan.scanned.files,
+  ].filter((v) => typeof v === 'number' && Number.isFinite(v));
+  const _examinedNothing = _counts.length > 0 && _counts.every((v) => v === 0);
+  const assessable = !_examinedNothing
+    || findings.length > 0
+    || components.length > 0
+    || secrets.length > 0
+    || logicVulns.length > 0
+    || supplyChain.length > 0;
+
   const results = [];
   for (const c of fw.controls || []) {
     const obs = [];
@@ -447,6 +509,11 @@ export function evaluateFramework(scanRoot, fw, scan) {
           allCleared = false;
           contributingFindings.push(...open);
           obs.push(`${open.length} open ${fam} finding(s) at ${minSeverity}+.`);
+        } else if (!assessable) {
+          // Empty bucket, but the scan examined nothing — see the guard above.
+          // Not evidence, and deliberately not a failure either.
+          obs.push(`⚠ ${fam}: the scan examined no files, so an empty finding bucket is not evidence (not assessed).`);
+          hasUnverifiableMapping = true;
         } else {
           obs.push(`✓ ${fam}: no open ${minSeverity}+ findings.`);
           anyCleared = true;
@@ -465,7 +532,15 @@ export function evaluateFramework(scanRoot, fw, scan) {
           'aibom':                'aibom.json',
           'attack-taxonomy':      'last-scan.json',
           'why-fired':            'last-scan.json',
-          'scan-history':         'scan-history/',
+          // Two real spellings, both live in this codebase: security-trend.js and
+          // router.js read `scan-history.json` (a FILE), findings-memory.js uses
+          // `scan-history` (a DIRECTORY). Only the directory was listed here, so
+          // on a normal scan — which writes the .json — every control mapped to
+          // module:scan-history reported the artifact missing and could never
+          // clear. Five bundled frameworks were affected. An array means "any of
+          // these satisfies it", which is the honest reading: the control asks
+          // whether a scan history exists, not which shape it took.
+          'scan-history':         ['scan-history.json', 'scan-history/'],
           'integrity':            'last-scan.json.sig',
           'watch-mode':           'watch-status.json',
           'cve-alert-daemon':     'cve-alerts/',
@@ -480,17 +555,25 @@ export function evaluateFramework(scanRoot, fw, scan) {
           'security-fixer':       '.../agents/security-fixer.md',
           'mcp-tools':            '.../scanner/src/mcp/tools.js',
         };
+        // A table entry is either one path or an array of acceptable ones. An
+        // array means the artifact has more than one real spelling in this
+        // codebase and any of them evidences the control; the FIRST is the
+        // canonical name used in the observation text when none is found, so
+        // the message still names something a reader can go create.
         const target = ARTIFACT[mod];
+        const candidates = target == null ? [] : (Array.isArray(target) ? target : [target]);
         // 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, `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))
-          : statePath(scanRoot, target);
-        const label = target ? target.replace(/^\.\.\.\//, '') : '(unmapped)';
-        if (resolved && fs.existsSync(resolved)) {
+        const _resolve = (t) => t.startsWith('.../')
+          ? path.join(scanRoot, t.slice(4))
+          : statePath(scanRoot, t);
+        const found = candidates.find((t) => { try { return fs.existsSync(_resolve(t)); } catch { return false; } });
+        const resolved = found ? _resolve(found) : null;
+        const label = (found || candidates[0] || '(unmapped)').replace(/^\.\.\.\//, '');
+        if (resolved) {
           obs.push(`✓ ${mod}: ${label} present.`);
           anySignal = true;
           anyCleared = true;