@clear-capabilities/agentic-security-scanner 0.123.0 → 0.124.1

package/dist/agentic-security.mjs.sha256

@@ -1 +1 @@
-c8cf8da77f8cf7ba57141e8280ea3642843125b66c871e2051e5a99c1894cbbd  agentic-security.mjs
+c162f0538727ff2cce518e33cd577b95521e9a1926abe63d7ed89afc3d21c21c  agentic-security.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clear-capabilities/agentic-security-scanner",
-  "version": "0.123.0",
+  "version": "0.124.1",
   "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, SARIF ingest, pipeline integrity, compliance attestation, and more.",
   "type": "module",
   "main": "src/index.js",

package/src/posture/flow-narration.js

@@ -15,9 +15,9 @@
 
 const TEMPLATES = {
   'sql-injection': (f) =>
-    `An unauthenticated attacker sends a crafted request to ${_routeOf(f)} containing UNION-style SQL syntax in the ${f.source?.variable || 'tainted'} field. The server's database driver executes the injected query verbatim, returning rows from any table the connection has read access to. Typical impact: full table dump of users (emails, password hashes), bypass of authentication via boolean-blind exfiltration. If the DB role has write privileges, the attacker can also INSERT/UPDATE arbitrary rows. Recovery cost: incident response, customer notification, password reset, regulatory reporting if PII leaked.`,
+    `An unauthenticated attacker sends a crafted request containing UNION-style SQL syntax in the ${f.source?.variable || 'tainted'} field. The server's database driver executes the injected query verbatim, returning rows from any table the connection has read access to. Typical impact: full table dump of users (emails, password hashes), bypass of authentication via boolean-blind exfiltration. If the DB role has write privileges, the attacker can also INSERT/UPDATE arbitrary rows. Recovery cost: incident response, customer notification, password reset, regulatory reporting if PII leaked.`,
   'command-injection': (f) =>
-    `The handler at ${f.file}:${f.line} passes user-controlled input to a shell-spawning function. An attacker can append shell metacharacters (";", "$(...)", backticks) to execute arbitrary commands as the application's UID. Typical impact: read of /etc/passwd, /proc/self/environ (env vars including secrets), outbound connections to attacker-controlled hosts (data exfil). On unprivileged containers the blast radius is limited to that container; on privileged or root-owned processes, the attacker can pivot to the host.`,
+    `The handler passes user-controlled input to a shell-spawning function. An attacker can append shell metacharacters (";", "$(...)", backticks) to execute arbitrary commands as the application's UID. Typical impact: read of /etc/passwd, /proc/self/environ (env vars including secrets), outbound connections to attacker-controlled hosts (data exfil). On unprivileged containers the blast radius is limited to that container; on privileged or root-owned processes, the attacker can pivot to the host.`,
   'xss': (f) =>
     `An attacker injects HTML/JS markup into user-controllable input. The server reflects (or stores) it without encoding, so when a victim browser renders the page, the attacker's script executes in the victim's session origin. Typical impact: session cookie theft, CSRF-bypass on internal endpoints, account takeover via API calls executed under the victim's auth. Cost: incident response, customer notification, potential data egress depending on what the victim's session can access.`,
   'ssrf': (f) =>
@@ -27,18 +27,23 @@ const TEMPLATES = {
   'code-injection': (f) =>
     `User input is fed into a code-evaluation function (eval, new Function, exec). An attacker supplies arbitrary code that executes in the application's runtime context, with full access to the application's data, env, and outbound network. Typical impact: equivalent to remote code execution; same recovery cost as command-injection.`,
   'csrf': (f) =>
-    `The state-changing endpoint at ${f.file}:${f.line} doesn't validate that the request originated from your own application. An attacker hosts a page that issues a same-shape request from a logged-in victim's browser. Typical impact: state changes performed under the victim's identity — password change, money movement, role escalation. Cost: depends on what state can change; for billing endpoints, this is fraud-level.`,
+    `The state-changing endpoint doesn't validate that the request originated from your own application. An attacker hosts a page that issues a same-shape request from a logged-in victim's browser. Typical impact: state changes performed under the victim's identity — password change, money movement, role escalation. Cost: depends on what state can change; for billing endpoints, this is fraud-level.`,
   'open-redirect': (f) =>
     `The endpoint redirects to a URL the attacker controls. Used as part of phishing chains: victim clicks a legitimate-looking link to your domain, gets redirected to attacker.example, enters credentials thinking they're still on your site. Typical impact: phishing-amplified credential theft; reputational damage if your domain ends up on a phish-tracking list.`,
   'insecure-deserialization': (f) =>
     `The handler deserializes attacker-controlled bytes via pickle/yaml-load/Marshal. The deserialization callback invokes arbitrary code from class constructors / __reduce__ / __wakeup__. Typical impact: equivalent to remote code execution. Cost: full incident response, including investigating whether the attacker established persistence.`,
   'xxe': (f) =>
-    `The XML parser at ${f.file}:${f.line} resolves external entities. An attacker submits XML referencing file:///etc/passwd or http://internal/. Typical impact: file disclosure, SSRF, blind out-of-band exfiltration of secrets. Cost: similar to SSRF + path-traversal combined.`,
+    `The XML parser resolves external entities. An attacker submits XML referencing file:///etc/passwd or http://internal/. Typical impact: file disclosure, SSRF, blind out-of-band exfiltration of secrets. Cost: similar to SSRF + path-traversal combined.`,
 };
 
 function _routeOf(f) {
-  if (!f) return '<endpoint>';
-  return `${f.file || '?'}:${f.line || '?'}`;
+  if (!f) return 'this endpoint';
+  // Narration may run before the line is finalised; fall back to the file alone
+  // (or a generic phrase) rather than emitting "file:undefined" / "file:?".
+  const line = Number(f.line) || Number(f.source?.line) || 0;
+  if (f.file && line) return `${f.file}:${line}`;
+  if (f.file) return f.file;
+  return 'this endpoint';
 }
 
 function _templateFor(f) {
@@ -65,7 +70,7 @@ async function _renderLlm(f) {
 Vuln: ${f.vuln}
 CWE: ${f.cwe}
 Severity: ${f.severity}
-Location: ${f.file}:${f.line}
+Location: ${_routeOf(f)}
 Snippet: ${(f.snippet || '').slice(0, 200)}
 
 Write ONE paragraph (5-7 sentences) covering: (1) how an attacker reaches this code, (2) what they get if exploited, (3) typical recovery cost. Plain English, no marketing language, no emoji.`;

package/src/report/index.js

@@ -29,6 +29,54 @@ function riskNote(f) {
   return null;
 }
 
+function _firstSentences(text, n) {
+  if (!text) return '';
+  const t = String(text).replace(/\s+/g, ' ').trim();
+  return t.split(/(?<=[.!?])\s+/).slice(0, n).join(' ');
+}
+
+// "How it fires" summary from the whyFired provenance already on the finding:
+// the source→sink flow (or the sink line), plus rejected sanitizers / observed
+// guards / reachability demotion. Returns null when no provenance exists.
+function _flowSummary(f) {
+  const w = f.whyFired;
+  if (!w || !w.evidence) return null;
+  const ev = w.evidence;
+  const steps = Array.isArray(ev.pathSteps) ? ev.pathSteps.filter(s => s && s.label) : [];
+  let flow = null;
+  if (steps.length) flow = steps.map(s => s.label).join(' → ');
+  else if (ev.sourceSnippet && ev.sinkSnippet && ev.sourceSnippet !== ev.sinkSnippet) flow = `${ev.sourceSnippet.trim()} → ${ev.sinkSnippet.trim()}`;
+  else if (ev.sinkSnippet) flow = String(ev.sinkSnippet).trim();
+  const tags = [];
+  if (Array.isArray(ev.sanitizers) && ev.sanitizers.length) tags.push(`${ev.sanitizers.length} sanitizer(s) rejected`);
+  if (Array.isArray(ev.guards) && ev.guards.length) tags.push(`${ev.guards.length} guard(s) seen`);
+  if (w.considered && w.considered.reachabilityFilter === 'demoted') tags.push('reachability-demoted');
+  return { detector: w.detector || null, parser: w.parser || null, flow, tags };
+}
+
+// The inline "explain" depth — assembled entirely from fields already on the
+// finding (narration + whyFired + fix), so the default finding view carries the
+// same depth as `/triage --explain` without a second command. verbose=false
+// trims the narration to 2 sentences and omits the evidence tags + fix code.
+function explainParts(f, { verbose = false } = {}) {
+  const why = f.narration
+    ? (verbose ? String(f.narration).replace(/\s+/g, ' ').trim() : _firstSentences(f.narration, 2))
+    : '';
+  const fs = _flowSummary(f);
+  let how = '';
+  if (fs && (fs.flow || fs.detector)) {
+    const head = fs.detector ? fs.detector + (fs.parser ? ` (${fs.parser})` : '') : '';
+    how = [head, fs.flow].filter(Boolean).join('  ·  ');
+    if (verbose && fs.tags.length) how += `  ·  ${fs.tags.join(' · ')}`;
+  }
+  let fix = '';
+  if (f.fix && typeof f.fix === 'object' && typeof f.fix.description === 'string') fix = f.fix.description;
+  else if (typeof f.fix === 'string') fix = f.fix;
+  else if (typeof f.remediation === 'string') fix = f.remediation;
+  const fixCode = verbose && f.fix && typeof f.fix === 'object' && typeof f.fix.code === 'string' ? f.fix.code : '';
+  return { why, how, fix: fix.replace(/\s+/g, ' ').trim(), fixCode };
+}
+
 function fingerprint(f){
   const s = `${f.file}:${f.line||f.source?.line||0}:${f.vuln||f.type||''}`;
   return crypto.createHash('sha256').update(s).digest('hex').slice(0, 16);
@@ -703,9 +751,12 @@ export function toVex(scan, meta = {}) {
 }
 
 export function toHTML(scan, meta = {}) {
-  // Attach the "likely lower risk" note (computed server-side) so the browser
-  // render can badge over-stated high/critical findings.
-  const findings = normalizeFindings(scan).map(f => ({ ...f, _riskNote: riskNote(f) }));
+  // Attach the "likely lower risk" note + inline explain depth (computed
+  // server-side) so the browser render shows them without a second command.
+  const findings = normalizeFindings(scan).map(f => {
+    const ex = explainParts(f, { verbose: true });
+    return { ...f, _riskNote: riskNote(f), _explainWhy: ex.why, _explainHow: ex.how };
+  });
   const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
   for (const f of findings) counts[f.severity] = (counts[f.severity] || 0) + 1;
   const stride = {};
@@ -773,6 +824,9 @@ export function toHTML(scan, meta = {}) {
   .f-body{display:none;margin-top:12px;padding-top:12px;border-top:1px solid #1e293b;font-size:12px}
   .f.expanded .f-body{display:block}
   .f-body pre{background:#020617;padding:10px;border-radius:4px;overflow-x:auto;font-size:11px;line-height:1.5}
+  .f-why{margin-top:8px;color:#cbd5e1}
+  .f-how{margin-top:6px;color:#94a3b8;font-size:13px}
+  .f-how code{font-family:ui-monospace,monospace;color:#e2e8f4}
   .f-fix{background:#0d1f3d;border-left:3px solid #38bdf8;padding:8px 12px;margin-top:8px;border-radius:0 4px 4px 0}
   .hidden{display:none!important}
 </style></head>
@@ -824,6 +878,8 @@ function makeCard(f) {
       (f._riskNote ? '<span class="f-note" title="The reachability / confidence pipeline marked this down from its rule-default severity">↓ ' + esc(f._riskNote) + '</span>' : '') +
     '</div>' +
     '<div class="f-body">' +
+      (f._explainWhy ? '<div class="f-why"><b>Why it matters:</b> ' + esc(f._explainWhy) + '</div>' : '') +
+      (f._explainHow ? '<div class="f-how"><b>How it fires:</b> <code>' + esc(f._explainHow) + '</code></div>' : '') +
       (f.snippet ? '<pre>' + esc(f.snippet) + '</pre>' : '') +
       (f.masked ? '<pre style="color:#f97316">' + esc(f.masked) + ' (masked)</pre>' : '') +
       (f.fix && f.fix.description ? '<div class="f-fix"><b>Fix:</b> ' + esc(f.fix.description) + (f.fix.code ? '<pre>' + esc(f.fix.code) + '</pre>' : '') + '</div>' : '') +
@@ -926,10 +982,12 @@ export function toCLI(scan, { verbose=false, color=true }={}){
     const rn = riskNote(f);
     if (rn) lines.push(`        ${c('↓ ' + rn, '\x1b[2;33m')}`);
     if (f.masked) lines.push(`        ${c('value:', DIM)} ${f.masked}`);
-    if (verbose && f.fix?.description) {
-      lines.push(`        ${c('fix:', DIM)} ${f.fix.description}`);
-      if (f.fix.code) for (const ln of f.fix.code.split('\n').slice(0, 6)) lines.push(`           ${c(ln, DIM)}`);
-    }
+    // Inline explain depth — why it matters / how it fires / the fix (#explain).
+    const ex = explainParts(f, { verbose });
+    if (ex.why) lines.push(`        ${c('why:', DIM)} ${ex.why}`);
+    if (ex.how) lines.push(`        ${c('how:', DIM)} ${ex.how}`);
+    if (ex.fix) lines.push(`        ${c('fix:', DIM)} ${ex.fix}`);
+    if (ex.fixCode) for (const ln of ex.fixCode.split('\n').slice(0, 6)) lines.push(`           ${c(ln, DIM)}`);
   }
   lines.push('');
   const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
@@ -1155,6 +1213,9 @@ export function toProTable(scan, options = {}) {
     else lines.push(`${sev}  ${where}  ${cwe}  ${cvss}  ${owasp}  ${vuln}  ${conf}`);
     const rn = riskNote(f);
     if (rn) lines.push(c('     ↓ ' + rn, '\x1b[2;33m'));
+    // One compact "why it matters" line keeps the table scannable but not bare.
+    const why1 = f.narration ? _firstSentences(f.narration, 1) : '';
+    if (why1) lines.push(c('     ↳ ' + why1, DIM));
   }
 
   // Footer counts.