@clear-capabilities/agentic-security-scanner 0.74.0

package/src/mcp/validate.js

@@ -0,0 +1,49 @@
+// Minimal JSON Schema validator — just the subset our tool schemas use.
+// No deps. Throws on invalid input with a path-prefixed error message.
+//
+// Supported keywords: type (object/array/string/boolean/number),
+// required, properties, items, enum, minItems, maxItems, maxLength,
+// minLength, additionalProperties (only as `false` — strict).
+
+const TYPE_OF = (v) => {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  return typeof v;
+};
+
+export function validate(schema, value, path = 'arguments') {
+  if (!schema) return;
+  const t = schema.type;
+  if (t === 'object') {
+    if (TYPE_OF(value) !== 'object') throw new Error(`${path}: expected object, got ${TYPE_OF(value)}`);
+    for (const req of schema.required || []) {
+      if (!(req in value)) throw new Error(`${path}: missing required property "${req}"`);
+    }
+    if (schema.additionalProperties === false) {
+      const allowed = new Set(Object.keys(schema.properties || {}));
+      for (const k of Object.keys(value)) {
+        if (!allowed.has(k)) throw new Error(`${path}: unexpected property "${k}"`);
+      }
+    }
+    for (const [k, sub] of Object.entries(schema.properties || {})) {
+      if (k in value) validate(sub, value[k], `${path}.${k}`);
+    }
+  } else if (t === 'array') {
+    if (!Array.isArray(value)) throw new Error(`${path}: expected array, got ${TYPE_OF(value)}`);
+    if (schema.minItems != null && value.length < schema.minItems) throw new Error(`${path}: minItems=${schema.minItems}, got length=${value.length}`);
+    if (schema.maxItems != null && value.length > schema.maxItems) throw new Error(`${path}: maxItems=${schema.maxItems}, got length=${value.length}`);
+    if (schema.items) for (let i = 0; i < value.length; i++) validate(schema.items, value[i], `${path}[${i}]`);
+  } else if (t === 'string') {
+    if (typeof value !== 'string') throw new Error(`${path}: expected string, got ${TYPE_OF(value)}`);
+    if (schema.enum && !schema.enum.includes(value)) throw new Error(`${path}: must be one of [${schema.enum.join(', ')}]`);
+    if (schema.maxLength != null && value.length > schema.maxLength) throw new Error(`${path}: maxLength=${schema.maxLength}, got length=${value.length}`);
+    if (schema.minLength != null && value.length < schema.minLength) throw new Error(`${path}: minLength=${schema.minLength}, got length=${value.length}`);
+  } else if (t === 'boolean') {
+    if (typeof value !== 'boolean') throw new Error(`${path}: expected boolean, got ${TYPE_OF(value)}`);
+  } else if (t === 'number' || t === 'integer') {
+    if (typeof value !== 'number') throw new Error(`${path}: expected number, got ${TYPE_OF(value)}`);
+    if (t === 'integer' && !Number.isInteger(value)) throw new Error(`${path}: expected integer`);
+    if (schema.minimum != null && value < schema.minimum) throw new Error(`${path}: < minimum (${schema.minimum})`);
+    if (schema.maximum != null && value > schema.maximum) throw new Error(`${path}: > maximum (${schema.maximum})`);
+  }
+}

package/src/personality.js

@@ -0,0 +1,164 @@
+// Security personality voices (v0.74).
+//
+// Same findings, dramatically different shareability. Three modes:
+//
+//   - sage      (default): calm explainer. "Consider that..." Reasonable
+//                tone for compliance audiences + general engineering.
+//   - cassandra: alarmist. "This WILL ship as a CVE." Sells urgency to
+//                management; useful for getting buy-in on remediation
+//                budget.
+//   - vince:    drill-sergeant. "Ship this and you're paged at 3am."
+//                Sells discipline; popular with vets / staff engineers
+//                who want zero ceremony.
+//
+// Selection: AGENTIC_SECURITY_PERSONALITY env var, or `personality:`
+// field on the renderer call. Defaults to 'sage'.
+//
+// What's actually different per voice:
+//   1. The OPENING line of any rendered report
+//   2. The PHRASING of severity descriptors
+//   3. The CLOSING line / call-to-action
+//   4. Specific lexical choices (emoji density, hedging vs. assertive,
+//      ALL CAPS for emphasis)
+//
+// What's THE SAME across voices:
+//   - The technical content (CWEs, finding IDs, file:line, remediation)
+//   - Severity assignments (a critical is a critical regardless of voice)
+//   - Counts + summary statistics
+//   - The decision (blocking-merge or non-blocking)
+//
+// Operators changing voice does NOT change WHAT findings fire — only
+// how they read.
+
+const VOICES = {
+  sage: {
+    glyph: '🛡',
+    openingClean: (n) => n === 0
+      ? `No security delta. Safe to merge.`
+      : `Clean scan — ${n} pre-existing findings unchanged.`,
+    openingNeedsWork: (n, files) =>
+      `I looked at the ${files} file${files === 1 ? '' : 's'} you changed and noticed ${n} new finding${n === 1 ? '' : 's'} worth your attention.`,
+    severityWord: (s) => ({
+      critical: 'critical',
+      high: 'high-severity',
+      medium: 'medium-severity',
+      low: 'low-impact',
+      info: 'informational',
+    }[s] || s),
+    closingBlocking: (counts) =>
+      `**Blocking merge:** ${counts.critical} critical + ${counts.high} high. Address these before merging — happy to walk through any of them.`,
+    closingNonblocking: () =>
+      `Non-blocking, but worth fixing while context is fresh.`,
+    fixCue: 'Suggested fix',
+  },
+  cassandra: {
+    glyph: '🚨',
+    openingClean: (n) => n === 0
+      ? `No new vulnerabilities introduced. The existing surface is still attackable, but you didn't make it worse.`
+      : `Scan is "clean" — but you're sitting on ${n} pre-existing findings. Today is the day they get exploited.`,
+    openingNeedsWork: (n, files) =>
+      `**${n} new attack surface${n === 1 ? '' : 's'}** opened in ${files} file${files === 1 ? '' : 's'}. This is how breaches start.`,
+    severityWord: (s) => ({
+      critical: 'CRITICAL — RCE-class',
+      high: 'high — exploitable today',
+      medium: 'medium — exploitable with chaining',
+      low: 'low — exploitable in 18 months when the toolchain catches up',
+      info: 'informational — write it down anyway',
+    }[s] || s),
+    closingBlocking: (counts) =>
+      `🚨 **DO NOT MERGE.** ${counts.critical} CRITICAL + ${counts.high} HIGH severity. Each one is a CVE waiting for a researcher. Fix or revert.`,
+    closingNonblocking: () =>
+      `No criticals — yet. Fix the rest before they chain into something that matters.`,
+    fixCue: 'Mitigation (apply now)',
+  },
+  vince: {
+    glyph: '🪖',
+    openingClean: (n) => n === 0
+      ? `Clean. Move out.`
+      : `Nothing new added. ${n} legacy findings still on the board — that's tomorrow's problem.`,
+    openingNeedsWork: (n, files) =>
+      `${n} new finding${n === 1 ? '' : 's'} in ${files} file${files === 1 ? '' : 's'}. Drop and give me twenty fixes.`,
+    severityWord: (s) => ({
+      critical: 'CRITICAL',
+      high: 'HIGH',
+      medium: 'MEDIUM',
+      low: 'LOW',
+      info: 'INFO',
+    }[s] || s.toUpperCase()),
+    closingBlocking: (counts) =>
+      `**HALT.** ${counts.critical} critical, ${counts.high} high. Ship this and you're paged at 3am. Fix it before the standup.`,
+    closingNonblocking: () =>
+      `No critical or high. You're cleared to merge — but address the rest this sprint. No exceptions, no carryover.`,
+    fixCue: 'Fix',
+  },
+};
+
+export function getPersonality(name) {
+  const key = String(name || process.env.AGENTIC_SECURITY_PERSONALITY || 'sage').toLowerCase();
+  return VOICES[key] || VOICES.sage;
+}
+
+export function listPersonalities() { return Object.keys(VOICES); }
+
+/**
+ * Wrap a renderer output's opening / closing lines with the active
+ * personality. Caller passes the raw delta + the personality name (or
+ * uses env default).
+ *
+ * This is intentionally additive — the renderer's middle body (CWE
+ * 'why' paragraphs, per-finding lines) is identical across voices.
+ * Only the framing changes.
+ */
+export function applyPersonality(rendered, delta, personality) {
+  const voice = getPersonality(personality);
+  if (!rendered || !delta) return rendered;
+  const intro = (delta.introduced || []).length;
+  const resolved = (delta.resolved || []).length;
+  const shifted = (delta.shifted || []).length;
+  const filesN = (delta.changedFiles || []).length;
+  // Replace the existing first-paragraph greeting with the voice-specific one.
+  let opening;
+  if (intro === 0 && resolved === 0 && shifted === 0) {
+    opening = voice.openingClean(delta.head?.summary?.total || 0);
+  } else if (intro === 0) {
+    opening = voice.openingClean(delta.head?.summary?.total || 0);
+  } else {
+    opening = voice.openingNeedsWork(intro, filesN);
+  }
+  // Replace closing/footer based on blocking status.
+  const i = delta.summary?.introduced || {};
+  const blocking = (i.critical || 0) + (i.high || 0) > 0;
+  const closing = blocking
+    ? voice.closingBlocking({ critical: i.critical || 0, high: i.high || 0 })
+    : voice.closingNonblocking();
+  // The rendered output has a structure: heading line, blank, opening,
+  // ..., separator line ('---'), blocking-or-nonblocking footer.
+  const lines = rendered.split('\n');
+  // Find the first non-empty content line after the heading.
+  let openingLineIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (i > 0 && lines[i].trim() && !lines[i].startsWith('###')) {
+      openingLineIdx = i;
+      break;
+    }
+  }
+  if (openingLineIdx > 0) lines[openingLineIdx] = opening;
+  // Replace the heading glyph.
+  if (lines[0]) {
+    lines[0] = lines[0].replace(/^###\s+🛡/, `### ${voice.glyph}`);
+  }
+  // Replace the closing line (last non-empty line after the '---' separator).
+  let separatorIdx = -1;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (lines[i].trim() === '---') { separatorIdx = i; break; }
+  }
+  if (separatorIdx > 0) {
+    // Find the first non-empty line after the separator and replace it.
+    for (let i = separatorIdx + 1; i < lines.length; i++) {
+      if (lines[i].trim()) { lines[i] = closing; break; }
+    }
+  }
+  return lines.join('\n');
+}
+
+export const _internal = { VOICES };

package/src/poc-video.js

@@ -0,0 +1,239 @@
+// Auto-recorded PoC video / exploit-runner generator (v0.74).
+//
+// For each finding with an `_exploitInput` (set by the v0.71 symbolic
+// exploit prover), generate a self-contained script the user can run
+// against their staging/dev environment to:
+//
+//   1. Drive the exploit live (HTTP request, browser interaction, etc.)
+//   2. Capture the response showing the vuln triggered
+//   3. Record the session as a video (Playwright) or transcript (curl)
+//
+// Three output formats:
+//   - 'playwright' — TypeScript test that launches Chromium, records
+//     video to a known path. Best for screenshareable evidence on
+//     UI-driven exploits (DOM XSS, open redirect, CSRF, prototype
+//     pollution).
+//   - 'curl'       — bash script using curl with verbose tracing.
+//     Best for backend exploits (SQLi, command injection, SSRF, path
+//     traversal, deserialization).
+//   - 'http'       — RFC 7230-style raw HTTP request + expected
+//     response shape. Format-agnostic; pastable into any HTTP client.
+//
+// The generator does NOT execute anything — it produces a script the
+// operator runs against their OWN environment. We never bundle a
+// browser, never make network calls during generation.
+
+const TEMPLATES = {
+  playwright: _playwrightTemplate,
+  curl:       _curlTemplate,
+  http:       _httpTemplate,
+};
+
+/**
+ * Pick the best default format for a given vuln family. UI-driven
+ * exploits get playwright; backend exploits get curl.
+ */
+function _defaultFormatFor(cwe) {
+  const ui = new Set(['CWE-79', 'CWE-601', 'CWE-352', 'CWE-1321']);
+  return ui.has(cwe) ? 'playwright' : 'curl';
+}
+
+/**
+ * Top-level entry. Returns a script string + a short filename hint.
+ *
+ *   finding: { cwe, vuln, file, line, _exploitInput, sink, ... }
+ *   opts: {
+ *     format: 'playwright' | 'curl' | 'http'   (default: by CWE)
+ *     baseUrl: 'https://staging.example.com'   (default: http://localhost:3000)
+ *     route:   '/api/admin/users'              (default: derived from finding)
+ *     method:  'POST'                          (default: derived from finding)
+ *   }
+ */
+export function generatePocScript(finding, opts = {}) {
+  if (!finding) return { script: '', filename: 'poc.txt', format: null };
+  const format = opts.format || _defaultFormatFor(finding.cwe);
+  const baseUrl = opts.baseUrl || 'http://localhost:3000';
+  const route = opts.route || _inferRoute(finding) || '/api/endpoint';
+  const method = opts.method || _inferMethod(finding) || 'POST';
+  const payload = finding._exploitInput || _fallbackPayload(finding.cwe);
+  const template = TEMPLATES[format];
+  if (!template) throw new Error(`Unknown format: ${format}`);
+  const script = template({ finding, baseUrl, route, method, payload });
+  const filename = _filenameFor(finding, format);
+  return { script, filename, format, payload };
+}
+
+function _filenameFor(finding, format) {
+  const ext = format === 'playwright' ? 'spec.ts'
+    : format === 'curl' ? 'sh'
+    : 'http';
+  const slug = (finding.cwe || 'vuln').toLowerCase().replace(/[^a-z0-9]/g, '-');
+  return `poc-${slug}-${finding.file?.replace(/[\/.]/g, '_') || 'finding'}.${ext}`;
+}
+
+function _inferRoute(f) {
+  if (f.route) return f.route;
+  if (typeof f.vuln === 'string') {
+    const m = f.vuln.match(/(?:GET|POST|PUT|DELETE)\s+([\/\w:-]+)/i);
+    if (m) return m[1];
+  }
+  return null;
+}
+
+function _inferMethod(f) {
+  if (f.method) return f.method;
+  if (typeof f.vuln === 'string') {
+    const m = f.vuln.match(/\b(GET|POST|PUT|DELETE|PATCH)\b/i);
+    if (m) return m[1].toUpperCase();
+  }
+  return null;
+}
+
+function _fallbackPayload(cwe) {
+  const fallback = {
+    'CWE-89':   "1' OR '1'='1",
+    'CWE-78':   "; rm -rf /tmp/x",
+    'CWE-79':   "<script>alert(1)</script>",
+    'CWE-22':   "../../etc/passwd",
+    'CWE-918':  "http://169.254.169.254/latest/meta-data/",
+    'CWE-94':   "{{7*7}}",
+    'CWE-601':  "//evil.example.com/phish",
+    'CWE-1321': '{"__proto__":{"polluted":true}}',
+  };
+  return fallback[cwe] || '<attacker-payload>';
+}
+
+// ─── Templates ───────────────────────────────────────────────────────────
+
+function _playwrightTemplate({ finding, baseUrl, route, method, payload }) {
+  const safePayload = JSON.stringify(payload);
+  return `// Auto-generated PoC by agentic-security ${new Date().toISOString().slice(0,10)}.
+//
+// Finding: ${finding.vuln} (${finding.cwe})
+// Location: ${finding.file}:${finding.line}
+//
+// Run: npx playwright test ${_filenameFor(finding, 'playwright')}
+//
+// Records video to test-results/. The test PASSES when the exploit
+// successfully triggers — flip the assertion if you're auditing the
+// scanner's accuracy.
+
+import { test, expect } from '@playwright/test';
+
+test('PoC: ${finding.vuln}', async ({ page, request }) => {
+  // Phase 1: take a clean baseline screenshot.
+  await page.goto('${baseUrl}');
+  await page.screenshot({ path: 'test-results/before.png', fullPage: true });
+
+  // Phase 2: trigger the exploit.
+  const PAYLOAD = ${safePayload};
+  const response = await request.${method.toLowerCase()}('${baseUrl}${route}', {
+    data: { input: PAYLOAD },
+    failOnStatusCode: false,
+  });
+
+  // Phase 3: confirm the exploit fired. The exact assertion depends on
+  // the vuln class — adjust before running.
+  console.log('Response status:', response.status());
+  const body = await response.text();
+  console.log('Response (first 500 chars):', body.slice(0, 500));
+
+  // Phase 4: capture the post-exploit state.
+  await page.goto('${baseUrl}${route}');
+  await page.screenshot({ path: 'test-results/after.png', fullPage: true });
+
+  // Default assertion: the response should NOT 4xx-reject the payload.
+  // If your sanitizer is in place, this assertion FAILS — which is the
+  // outcome you want after applying the fix.
+  expect(response.status()).toBeLessThan(400);
+});
+`;
+}
+
+function _curlTemplate({ finding, baseUrl, route, method, payload }) {
+  return `#!/usr/bin/env bash
+# Auto-generated PoC by agentic-security ${new Date().toISOString().slice(0,10)}.
+#
+# Finding: ${finding.vuln} (${finding.cwe})
+# Location: ${finding.file}:${finding.line}
+#
+# Run: bash ${_filenameFor(finding, 'curl')}
+#
+# Exits 0 if the exploit appears to trigger; non-zero otherwise.
+# Flip the assertion if you're auditing the scanner's accuracy.
+
+set -euo pipefail
+
+BASE_URL="\${BASE_URL:-${baseUrl}}"
+ROUTE="${route}"
+METHOD="${method}"
+PAYLOAD=${JSON.stringify(payload)}
+
+echo "→ Sending $METHOD $BASE_URL$ROUTE"
+echo "  Payload: $PAYLOAD"
+echo
+
+RESPONSE=$(curl -sS -X "$METHOD" \\
+  -H "Content-Type: application/json" \\
+  -d "{\\"input\\":$(printf %s "$PAYLOAD" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')}" \\
+  -w "\\nHTTP_STATUS:%{http_code}\\n" \\
+  "$BASE_URL$ROUTE" || true)
+
+STATUS=$(echo "$RESPONSE" | grep '^HTTP_STATUS:' | cut -d: -f2)
+BODY=$(echo "$RESPONSE" | sed '/^HTTP_STATUS:/d')
+
+echo "← HTTP $STATUS"
+echo "$BODY" | head -20
+echo
+
+# Default assertion: 2xx means the payload was accepted (i.e., the
+# vulnerable path was reached). After fixing the vuln, this should 4xx.
+if [ "$STATUS" -lt 400 ]; then
+  echo "❌ PAYLOAD ACCEPTED ($STATUS) — vuln likely still present"
+  exit 1
+else
+  echo "✓ Payload rejected ($STATUS) — sanitizer appears to be working"
+  exit 0
+fi
+`;
+}
+
+function _httpTemplate({ finding, baseUrl, route, method, payload }) {
+  const url = new URL(route, baseUrl);
+  return `# Auto-generated PoC by agentic-security ${new Date().toISOString().slice(0,10)}.
+# Finding: ${finding.vuln} (${finding.cwe})
+# Location: ${finding.file}:${finding.line}
+#
+# Paste this into any HTTP client (Postman, Insomnia, vscode-rest-client).
+
+${method} ${url.pathname}${url.search} HTTP/1.1
+Host: ${url.host}
+User-Agent: agentic-security-poc/1.0
+Content-Type: application/json
+Accept: application/json
+
+{"input": ${JSON.stringify(payload)}}
+
+###
+
+# Expected outcome (pre-fix): server returns 2xx + vulnerable payload
+# reaches the sink. After fix: server returns 4xx with a validation
+# error. The CWE-specific signature to look for in the response:
+#
+${_responseSignatureFor(finding.cwe)}
+`;
+}
+
+function _responseSignatureFor(cwe) {
+  const sigs = {
+    'CWE-89':   '# - SQL error containing "syntax" / "quote" / "OR"',
+    'CWE-78':   '# - shell output of the injected command in body',
+    'CWE-79':   '# - <script> tag echoed back into HTML response body',
+    'CWE-22':   '# - file contents from outside the intended directory',
+    'CWE-918':  '# - response body from the metadata IP',
+    'CWE-601':  '# - Location: header pointing to the attacker domain',
+  };
+  return sigs[cwe] || '# - unexpected response shape consistent with the vuln class';
+}
+
+export const _internal = { _defaultFormatFor, _inferRoute, _inferMethod, _fallbackPayload, _playwrightTemplate, _curlTemplate, _httpTemplate };