@clear-capabilities/agentic-security-scanner 0.74.0

package/bin/agentic-security-consistency.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// CLI front-end for the LLM-validator consistency harness.
+//
+// Reads .agentic-security/last-scan.json from the project root, picks the
+// top-N findings with precise file:line locations (validator preflight
+// requires them), and runs N trials of the validator on the same finding
+// set. Reports pass^N (unanimous-verdict rate) and per-finding flap detail.
+//
+// The validator endpoint is configured via the usual env vars:
+//   AGENTIC_SECURITY_LLM_VALIDATE=1
+//   AGENTIC_SECURITY_LLM_ENDPOINT=https://...
+//   AGENTIC_SECURITY_LLM_API_KEY=...
+//   AGENTIC_SECURITY_LLM_MODEL=...
+//
+// When the validator is off (env unset), every verdict will be 'unvalidated'
+// and pass^N is trivially 100%. That's an honest signal; deploy with the
+// validator on if you care about its behavior.
+//
+// Usage:
+//   agentic-security-consistency               # uses last-scan, 5 trials, 5 findings
+//   agentic-security-consistency --trials 10
+//   agentic-security-consistency --top 3
+//   agentic-security-consistency --json
+'use strict';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { measureConsistency, summarize } from '../src/llm-validator/consistency.js';
+
+function args() {
+  const a = process.argv.slice(2);
+  const out = { trials: 5, top: 5, json: false, root: process.cwd() };
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] === '--trials') out.trials = parseInt(a[++i], 10);
+    else if (a[i] === '--top') out.top = parseInt(a[++i], 10);
+    else if (a[i] === '--json') out.json = true;
+    else if (a[i] === '--root') out.root = a[++i];
+  }
+  return out;
+}
+
+async function main() {
+  const opts = args();
+  const scanFile = path.join(opts.root, '.agentic-security', 'last-scan.json');
+  if (!fs.existsSync(scanFile)) {
+    console.error(`no last-scan.json at ${scanFile} — run a scan first`);
+    process.exit(2);
+  }
+  let scan;
+  try { scan = JSON.parse(fs.readFileSync(scanFile, 'utf8')); }
+  catch (e) { console.error(`failed to parse last-scan.json: ${e.message}`); process.exit(2); }
+  // Pick findings the validator can actually grade: must have precise file+line.
+  const candidates = (scan.findings || [])
+    .filter(f => f && typeof f.file === 'string' && f.file.length > 0 &&
+                 typeof f.line === 'number' && f.line > 0)
+    .slice(0, opts.top);
+  if (!candidates.length) {
+    console.error('no findings with precise locations in last-scan.json');
+    process.exit(2);
+  }
+  // Build fileContents map from scan.fc if present, otherwise read from disk.
+  const fileContents = (scan.fc && typeof scan.fc === 'object') ? scan.fc : {};
+  for (const f of candidates) {
+    if (fileContents[f.file]) continue;
+    try {
+      const fp = path.join(opts.root, f.file);
+      if (fs.existsSync(fp)) fileContents[f.file] = fs.readFileSync(fp, 'utf8');
+    } catch { /* skip */ }
+  }
+  const r = await measureConsistency({
+    findings: candidates, fileContents,
+    scanRoot: opts.root, trials: opts.trials,
+  });
+  if (opts.json) {
+    console.log(JSON.stringify(r, null, 2));
+    return;
+  }
+  console.log(summarize(r));
+}
+
+main().catch(e => { console.error(e); process.exit(1); });

package/bin/agentic-security-diff.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// FR-SDLC-10 — Differential scanner CLI.
+//
+// Run two versions of the scanner against the same target and emit the
+// delta. Use cases:
+//   1. PR-time regression detection — catch when an upgrade of the scanner
+//      itself loses or adds findings on a stable codebase.
+//   2. Migration confidence — let a customer dry-run a scanner upgrade
+//      before bumping their pinned version.
+//
+// Usage:
+//   agentic-security-diff --baseline ./dist/agentic-security.mjs \
+//                         --candidate ./dist/agentic-security.mjs.next \
+//                         [--root .]
+//
+// Both `--baseline` and `--candidate` paths must point to runnable scanner
+// bundles. The CLI invokes each via child_process with `--format json` and
+// computes the diff on the resulting findings list (keyed by `stableId`
+// when present, else by `(file, line, family)`).
+
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+
+function parseArgs(argv) {
+  const opts = { root: '.', baseline: null, candidate: null, format: 'cli' };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--baseline') opts.baseline = argv[++i];
+    else if (a === '--candidate') opts.candidate = argv[++i];
+    else if (a === '--root') opts.root = argv[++i];
+    else if (a === '--format') opts.format = argv[++i];
+    else if (a === '--help' || a === '-h') opts.help = true;
+  }
+  return opts;
+}
+
+function runScan(binPath, root) {
+  if (!fs.existsSync(binPath)) {
+    return { error: `binary not found: ${binPath}`, findings: [] };
+  }
+  const res = spawnSync(process.execPath, [binPath, 'scan', root, '--format', 'json'], {
+    encoding: 'utf8',
+    maxBuffer: 256 * 1024 * 1024,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (res.status !== 0 && !res.stdout) {
+    return { error: `scanner exited ${res.status}: ${(res.stderr || '').slice(0, 200)}`, findings: [] };
+  }
+  try {
+    const data = JSON.parse(res.stdout);
+    const findings = Array.isArray(data) ? data : (data.findings || []);
+    return { findings };
+  } catch (e) {
+    return { error: `failed to parse JSON: ${e.message}`, findings: [] };
+  }
+}
+
+function keyOf(f) {
+  if (f.stableId) return `sid:${f.stableId}`;
+  return `pos:${f.file}:${f.line}:${f.family || f.vuln || '?'}`;
+}
+
+function diff(baseline, candidate) {
+  const byKey = (arr) => {
+    const m = new Map();
+    for (const f of arr) m.set(keyOf(f), f);
+    return m;
+  };
+  const a = byKey(baseline);
+  const b = byKey(candidate);
+  const added = [], removed = [], changed = [];
+  for (const [k, f] of b) {
+    if (!a.has(k)) added.push(f);
+    else {
+      const prev = a.get(k);
+      if (prev.severity !== f.severity || prev.vuln !== f.vuln) changed.push({ before: prev, after: f });
+    }
+  }
+  for (const [k, f] of a) if (!b.has(k)) removed.push(f);
+  return { added, removed, changed };
+}
+
+function summarize(d) {
+  const lines = [];
+  lines.push('# Differential scan report');
+  lines.push('');
+  lines.push(`Added:    ${d.added.length}`);
+  lines.push(`Removed:  ${d.removed.length}`);
+  lines.push(`Changed:  ${d.changed.length}`);
+  lines.push('');
+  if (d.added.length) {
+    lines.push('## Added (candidate found, baseline did not)');
+    for (const f of d.added.slice(0, 25)) lines.push(`  + [${f.severity}] ${f.vuln || ''} at ${f.file}:${f.line}`);
+    if (d.added.length > 25) lines.push(`  + ... ${d.added.length - 25} more`);
+    lines.push('');
+  }
+  if (d.removed.length) {
+    lines.push('## Removed (baseline found, candidate did not)');
+    for (const f of d.removed.slice(0, 25)) lines.push(`  - [${f.severity}] ${f.vuln || ''} at ${f.file}:${f.line}`);
+    if (d.removed.length > 25) lines.push(`  - ... ${d.removed.length - 25} more`);
+    lines.push('');
+  }
+  if (d.changed.length) {
+    lines.push('## Changed (same finding, different severity or wording)');
+    for (const c of d.changed.slice(0, 15)) {
+      lines.push(`  ~ [${c.before.severity}→${c.after.severity}] ${c.after.file}:${c.after.line}`);
+    }
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+  if (opts.help || !opts.baseline || !opts.candidate) {
+    console.log('Usage: agentic-security-diff --baseline <bin> --candidate <bin> [--root .] [--format cli|json]');
+    process.exit(opts.help ? 0 : 1);
+  }
+  const root = path.resolve(opts.root);
+  const baseline = runScan(opts.baseline, root);
+  const candidate = runScan(opts.candidate, root);
+  if (baseline.error) { console.error('baseline:', baseline.error); process.exit(2); }
+  if (candidate.error) { console.error('candidate:', candidate.error); process.exit(2); }
+  const d = diff(baseline.findings, candidate.findings);
+  if (opts.format === 'json') {
+    process.stdout.write(JSON.stringify(d, null, 2));
+  } else {
+    process.stdout.write(summarize(d));
+  }
+  // Exit 0 if no delta, 1 if delta, 2 if errors (already exited above).
+  const hasDelta = d.added.length || d.removed.length || d.changed.length;
+  process.exit(hasDelta ? 1 : 0);
+}
+
+main();

package/bin/agentic-security-lsp.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// agentic-security LSP server — stdio entry point.
+//
+// Speaks the Language Server Protocol (vscode-jsonrpc framing) on stdin/stdout.
+// Used by the JetBrains plugin (via LSP4IJ) and the Neovim plugin (via
+// built-in LSP). Diagnostics emitted to publishDiagnostics on save/open.
+//
+// Usage (typically invoked by an editor, not directly):
+//   node bin/agentic-security-lsp.js
+//
+import { startLspServer } from '../src/lsp/server.js';
+startLspServer();

package/bin/agentic-security-mcp.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// agentic-security MCP server — stdio entry point.
+//
+// Speaks JSON-RPC 2.0 over NDJSON on stdin/stdout. stderr is for logging.
+//
+// Usage:
+//   node bin/agentic-security-mcp.js [--root <path>]
+//
+// Session root resolution (highest precedence first):
+//   1. --root <path> CLI arg
+//   2. AGENTIC_SECURITY_MCP_ROOT env var
+//   3. process.cwd()
+//
+// The session root confines every tool: paths in tool arguments must resolve
+// inside it, and apply_fix refuses any finding whose file field escapes it.
+
+import * as path from 'node:path';
+import { runStdio } from '../src/mcp/stdio.js';
+
+function _parseRoot() {
+  const argv = process.argv.slice(2);
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--root' && argv[i + 1]) return argv[i + 1];
+    if (argv[i].startsWith('--root=')) return argv[i].slice('--root='.length);
+  }
+  return process.env.AGENTIC_SECURITY_MCP_ROOT || process.cwd();
+}
+
+// Operator kill-switch (OWASP MCP09 Shadow MCP Servers): bin exits
+// immediately if disabled. Tool calls would also be refused server-side,
+// but exiting early prevents the process from staying resident as an
+// invisible attack surface on machines where the env var is set.
+if (process.env.AGENTIC_SECURITY_MCP_DISABLED === '1') {
+  process.stderr.write('mcp: disabled via AGENTIC_SECURITY_MCP_DISABLED=1 — exiting.\n');
+  process.exit(0);
+}
+
+const sessionRoot = path.resolve(_parseRoot());
+process.stderr.write(`mcp: session root = ${sessionRoot}\n`);
+runStdio({ sessionRoot });

package/bin/agentic-security-rule.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+// agentic-security-rule — CLI for signing / verifying custom rule packs.
+//
+// Subcommands:
+//   keygen                Generate an Ed25519 key pair (PRIVATE KEY printed
+//                         to stdout; handle with care).
+//   sign <rule-yml>       Sign the rule file. Writes <rule-yml>.sig.
+//                         Reads the private key from $AGENTIC_SECURITY_PRIVATE_KEY
+//                         or --key <base64>.
+//   verify <rule-yml>     Verify against the project's trusted-keys.json
+//                         (or bundled official keys). Honors revocation.
+//
+// First-time setup walkthrough:
+//
+//   1) Generate a key pair OUTSIDE the project tree:
+//        mkdir -p ~/.config/agentic-security/keys
+//        agentic-security-rule keygen --out ~/.config/agentic-security/keys/MY_KEY.json
+//      (the file is written 0600. KEEP the private key SECRET — do not commit it,
+//       do not put it in a cloud-synced directory.)
+//
+//   2) Add the public key to .agentic-security/trusted-keys.json:
+//        {
+//          "keys": [
+//            { "id": "my-team-2026", "alg": "ed25519",
+//              "publicKey": "<paste publicKey from step 1>" }
+//          ]
+//        }
+//
+//   3) Tell the scanner to trust project-local keys (audit-logged):
+//        export AGENTIC_SECURITY_ALLOW_PROJECT_KEYS=1
+//
+//   4) Author a custom rule at .agentic-security/rules/my-rule.yml.
+//
+//   5) Sign it:
+//        export AGENTIC_SECURITY_PRIVATE_KEY="<paste privateKey from step 1>"
+//        agentic-security-rule sign .agentic-security/rules/my-rule.yml
+//
+//   6) Verify before commit:
+//        agentic-security-rule verify .agentic-security/rules/my-rule.yml
+//
+// CAUTION: the private key in step 1 is a SECRET. Anyone with it can sign
+// rules that will execute in your CI. Store in a password manager / KMS,
+// never in source control or shell history. Use --rotate to retire keys.
+
+import { keygen, signRulePack, verifyRulePack, loadTrustedKeys } from '../src/posture/rule-pack-signing.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const cmd = process.argv[2];
+const args = process.argv.slice(3);
+
+function die(msg, code = 1) {
+  process.stderr.write(msg + '\n');
+  process.exit(code);
+}
+
+function pickArg(flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : null;
+}
+
+if (cmd === 'keygen') {
+  // Premortem 3R3.2 / 3R-5: keygen output contains a PRIVATE KEY. Three
+  // safety rails:
+  //   1. If --out <path> is supplied AND the path resolves under the project's
+  //      .agentic-security/ directory, REFUSE. That directory tends to be
+  //      cloud-synced / git-checked / editor-recent. The right place for
+  //      private keys is outside source control.
+  //   2. If stdout is not a TTY (redirected to a file or pipe) AND no --out
+  //      was specified, WARN that the operator is about to write a private
+  //      key somewhere we can't see; suggest --out so we can validate.
+  //   3. Operators who really mean it can pass --i-understand-private-keys
+  //      to silence the warnings.
+  const outArg = pickArg('--out');
+  const understandFlag = args.includes('--i-understand-private-keys');
+  if (outArg) {
+    const projectAgenticDir = path.resolve(process.cwd(), '.agentic-security') + path.sep;
+    const absOut = path.resolve(outArg);
+    if (absOut.startsWith(projectAgenticDir)) {
+      die(
+        `Refusing to write a private key into ${absOut}.\n` +
+        `  .agentic-security/ is typically git-tracked, cloud-synced, or editor-indexed.\n` +
+        `  Choose a location OUTSIDE the project tree (e.g. ~/.config/agentic-security/keys/).\n` +
+        `  Override with --i-understand-private-keys if you really mean it.`,
+        2);
+    }
+  } else if (!process.stdout.isTTY && !understandFlag) {
+    process.stderr.write(
+      'agentic-security-rule: WARNING — stdout is being redirected, but no --out was specified.\n' +
+      '  This command emits a PRIVATE KEY. We cannot validate where it ends up.\n' +
+      '  Re-run with --out <path-outside-project> so we can check the destination,\n' +
+      '  or with --i-understand-private-keys to silence this warning.\n');
+    process.exit(3);
+  }
+  const kp = keygen();
+  const out = {
+    note: 'STORE THE privateKey SECURELY. Do not commit it to source control. Anyone with this key can sign rules that execute in your CI.',
+    id: `key-${new Date().toISOString().slice(0, 10)}-${Math.random().toString(36).slice(2, 6)}`,
+    alg: 'ed25519',
+    issuedAt: new Date().toISOString(),
+    publicKey:  kp.publicKey,
+    privateKey: kp.privateKey,
+  };
+  const payload = JSON.stringify(out, null, 2) + '\n';
+  if (outArg) {
+    fs.writeFileSync(outArg, payload, { mode: 0o600 });
+    process.stderr.write(`\nagentic-security-rule: keypair written to ${outArg} (mode 0600).\n`);
+  } else {
+    process.stdout.write(payload);
+  }
+  process.stderr.write('  · Add publicKey to .agentic-security/trusted-keys.json (this IS git-trackable)\n');
+  process.stderr.write('  · Store privateKey in a password manager / KMS\n');
+  process.stderr.write('  · Set AGENTIC_SECURITY_ALLOW_PROJECT_KEYS=1 so the scanner trusts project-local keys\n');
+  process.exit(0);
+}
+
+if (cmd === 'sign') {
+  const target = args.find(a => !a.startsWith('--'));
+  if (!target) die('Usage: agentic-security-rule sign <rule-yml> [--key <base64>]');
+  if (!fs.existsSync(target)) die(`File not found: ${target}`);
+  const key = pickArg('--key') || process.env.AGENTIC_SECURITY_PRIVATE_KEY;
+  if (!key) die('No private key. Set AGENTIC_SECURITY_PRIVATE_KEY or pass --key <base64>.');
+  try {
+    signRulePack(target, key);
+    process.stdout.write(`Signed: ${target}.sig\n`);
+    process.exit(0);
+  } catch (e) {
+    die(`Sign failed: ${e.message}`);
+  }
+}
+
+if (cmd === 'verify') {
+  const target = args.find(a => !a.startsWith('--'));
+  if (!target) die('Usage: agentic-security-rule verify <rule-yml>');
+  if (!fs.existsSync(target)) die(`File not found: ${target}`);
+  const scanRoot = path.resolve('.');
+  const keys = loadTrustedKeys(scanRoot);
+  if (keys.length === 0) {
+    process.stderr.write('agentic-security-rule: no trusted keys configured.\n');
+    process.stderr.write('  Add keys to .agentic-security/trusted-keys.json and set AGENTIC_SECURITY_ALLOW_PROJECT_KEYS=1.\n');
+    process.exit(2);
+  }
+  const r = verifyRulePack(target, keys);
+  if (r.ok) {
+    process.stdout.write(`OK — signed by ${r.keyId}\n`);
+    process.exit(0);
+  } else {
+    process.stderr.write(`FAILED: ${r.reason}${r.keyId ? ` (key ${r.keyId})` : ''}\n`);
+    process.exit(1);
+  }
+}
+
+die(`Usage: agentic-security-rule <keygen | sign <rule.yml> | verify <rule.yml>>`);