@clear-capabilities/agentic-security-scanner 0.74.0

package/src/posture/specification-mining.js

@@ -0,0 +1,170 @@
+// FR-LOGIC-8 — Specification mining.
+//
+// Extract the implicit specification of each function from five signal
+// sources: (1) function name, (2) docstring / inline comments, (3) co-located
+// tests, (4) call sites, (5) PR title + AI prompt (CLAUDE.md / system
+// prompts). Flag implementations that drift from the inferred spec — the
+// function named `validateOwnership` whose body never references the user
+// identity is the canonical example.
+//
+// This is the bug class no pattern matcher reaches. The intent-drift recall
+// target is F1 ≥ 0.70 (PRD G13). We expect noise on legacy code; the rule
+// emits at LOW confidence and lets the active-learning loop tune.
+//
+// What we mine in v1:
+//   • name → expected body content (regex set per name family)
+//   • body content present? → if NO, emit drift finding
+//
+// Name families and required body evidence (each family lists the *kind* of
+// thing the body must reference; missing means drift):
+//
+//   validate*Ownership / check*Owner   → references req.user / session / context user id
+//   validate*Access    / authorize*    → references roles / permissions / can / allowedTo
+//   sanitize*          / escape*       → references DOMPurify / escape / replace
+//   verify*Signature   / check*Sig     → references hmac / verify / crypto.createVerify / timingSafeEqual
+//   verify*Webhook                     → references webhook signature constant
+//   rateLimit*         / throttle*     → references express-rate-limit / Math.min / sliding window
+//   isAdmin / requireAdmin             → references admin role check
+//   requireAuth / mustBeLoggedIn       → references auth middleware / login flag
+
+const NAME_FAMILIES = [
+  {
+    label: 'ownership-check',
+    nameRe: /(?:validate|check|enforce|ensure|verify)\w*ownership|\bcheckOwner\b|\bisOwner\b|\bownerOnly\b/i,
+    bodyMustHave: /\b(?:req\.user|session\.user|ctx\.user|currentUser|userId|owner_?id)\b/,
+    severity: 'medium',
+    cwe: 'CWE-639',
+    rationale: 'function name claims an ownership check but body never references the requesting-user identity',
+  },
+  {
+    label: 'authorization-check',
+    nameRe: /(?:validate|check|require|enforce)\w*(?:access|authoriz|permission)|\bauthorize\b|\bcanAccess\b/i,
+    bodyMustHave: /\b(?:role|permission|scope|claim|isAllowed|can\(|allowedTo|hasPermission)\b/,
+    severity: 'medium',
+    cwe: 'CWE-863',
+    rationale: 'function name claims an authorization check but body has no role/permission/scope reference',
+  },
+  {
+    label: 'output-sanitizer',
+    nameRe: /\b(?:sanitize|escape|clean|safe(?:n|ify)?|purify)\w*(?:html|xml|sql|input|user|output)\b/i,
+    bodyMustHave: /\b(?:DOMPurify|escape|encodeURI|sanitizeHtml|replace\(|str\.replace|html_escape|escape_html|bleach)\b/,
+    severity: 'high',
+    cwe: 'CWE-79',
+    rationale: 'function name claims sanitization but body has no encoding/escaping/library call',
+  },
+  {
+    label: 'signature-verify',
+    nameRe: /(?:verify|check|validate)\w*(?:signature|sig|hmac)\b/i,
+    bodyMustHave: /\b(?:hmac|createVerify|verify\(|timingSafeEqual|crypto\.subtle\.verify|hashlib\.compare|hash_equals)\b/,
+    severity: 'high',
+    cwe: 'CWE-347',
+    rationale: 'function name claims signature verification but body has no HMAC / verify / constant-time-compare call',
+  },
+  {
+    label: 'webhook-verify',
+    nameRe: /(?:verify|validate|check)\w*webhook\b/i,
+    bodyMustHave: /\b(?:stripeSignature|webhook_secret|svix|x-hub-signature|hmac|timingSafeEqual)\b/i,
+    severity: 'high',
+    cwe: 'CWE-345',
+    rationale: 'function name claims webhook verification but body has no signature material or constant-time compare',
+  },
+  {
+    label: 'rate-limit-impl',
+    nameRe: /(?:rateLimit|throttle|limitRate|rateLimiter)\b/i,
+    bodyMustHave: /\b(?:expressRateLimit|rateLimiterFlexible|RateLimiterMemory|Math\.min|window|slidingWindow|tokenBucket|sleep|setTimeout)\b/,
+    severity: 'medium',
+    cwe: 'CWE-770',
+    rationale: 'function name claims rate-limiting but body has no rate-limit library or windowing logic',
+  },
+  {
+    label: 'admin-gate',
+    nameRe: /\b(?:isAdmin|requireAdmin|adminOnly|enforceAdmin)\b/i,
+    bodyMustHave: /\b(?:admin|role\s*===?\s*['"]admin['"]|isAdmin|hasRole\(['"]admin['"]\))\b/i,
+    severity: 'high',
+    cwe: 'CWE-862',
+    rationale: 'function name claims admin gating but body has no admin-role reference',
+  },
+  {
+    label: 'auth-required',
+    nameRe: /\b(?:requireAuth|mustBeLoggedIn|enforceLogin|authenticated)\b/i,
+    bodyMustHave: /\b(?:req\.user|session\.user|isAuthenticated|currentUser|jwt|bearer|authHeader|getServerSession)\b/i,
+    severity: 'medium',
+    cwe: 'CWE-306',
+    rationale: 'function name claims auth requirement but body has no session/user lookup',
+  },
+];
+
+const JS_FN_RE = /(?:function|const|let)\s+([A-Za-z_$][\w$]*)\s*(?:=\s*(?:async\s*)?\([^)]*\)\s*=>\s*\{|\([^)]*\)\s*\{)/g;
+const PY_FN_RE = /def\s+([A-Za-z_][\w]*)\s*\([^)]*\)\s*:/g;
+
+function extractFunctionBodies(text, lang) {
+  const bodies = [];
+  if (!text || typeof text !== 'string') return bodies;
+  if (lang === 'js' || lang === 'ts') {
+    JS_FN_RE.lastIndex = 0;
+    let m;
+    while ((m = JS_FN_RE.exec(text))) {
+      const startName = m.index;
+      // find the opening brace and then naive balanced-brace seek up to 1500 chars.
+      const braceIdx = text.indexOf('{', startName);
+      if (braceIdx === -1) continue;
+      let depth = 0, end = braceIdx;
+      for (let i = braceIdx; i < Math.min(braceIdx + 4000, text.length); i++) {
+        if (text[i] === '{') depth++;
+        else if (text[i] === '}') {
+          depth--;
+          if (depth === 0) { end = i; break; }
+        }
+      }
+      bodies.push({ name: m[1], body: text.slice(braceIdx, end + 1), startLine: text.slice(0, startName).split('\n').length });
+    }
+  } else if (lang === 'py') {
+    PY_FN_RE.lastIndex = 0;
+    let m;
+    while ((m = PY_FN_RE.exec(text))) {
+      const startName = m.index;
+      // simple python body harvest: take next 60 lines starting at the def
+      const startLine = text.slice(0, startName).split('\n').length;
+      const allLines = text.split('\n');
+      const body = allLines.slice(startLine - 1, Math.min(startLine + 60, allLines.length)).join('\n');
+      bodies.push({ name: m[1], body, startLine });
+    }
+  }
+  return bodies;
+}
+
+function inferLang(filePath) {
+  if (/\.(ts|tsx)$/i.test(filePath)) return 'ts';
+  if (/\.(js|jsx|mjs|cjs)$/i.test(filePath)) return 'js';
+  if (/\.py$/i.test(filePath)) return 'py';
+  return null;
+}
+
+export function scanSpecificationDrift(fileContents) {
+  const findings = [];
+  if (!fileContents || typeof fileContents !== 'object') return findings;
+  for (const [fp, text] of Object.entries(fileContents)) {
+    const lang = inferLang(fp);
+    if (!lang) continue;
+    for (const fn of extractFunctionBodies(text, lang)) {
+      for (const fam of NAME_FAMILIES) {
+        if (!fam.nameRe.test(fn.name)) continue;
+        if (fam.bodyMustHave.test(fn.body)) continue;       // body satisfies the implicit spec
+        findings.push({
+          id: `spec-drift:${fam.label}:${fp}:${fn.startLine}`,
+          file: fp,
+          line: fn.startLine,
+          vuln: `Spec drift — ${fn.name}() claims ${fam.label} but body lacks expected evidence`,
+          severity: fam.severity,
+          family: 'spec-drift',
+          cwe: fam.cwe,
+          confidence: 0.45,
+          description: fam.rationale,
+          remediation: `Verify that ${fn.name}() actually implements ${fam.label}; rename if not, or add the missing check.`,
+          specMined: { name: fn.name, family: fam.label, mustHaveRegex: fam.bodyMustHave.source },
+        });
+      }
+    }
+  }
+  return findings;
+}

package/src/posture/stable-id.js

@@ -0,0 +1,75 @@
+// Stable finding IDs (FR-PREC-5).
+//
+// The engine's default finding IDs include file path and line number, which
+// makes them brittle: any refactor that moves code rotates the IDs and breaks
+// triage/learning persistence. This module computes a refactor-stable hash
+// from (rule_id, normalized_sink_signature, normalized_path_shape) so the
+// same vulnerability keeps the same `stableId` across renames and reformats.
+//
+// The original `id` field is preserved for backwards compatibility — callers
+// that need stability use `stableId`.
+
+import * as crypto from 'node:crypto';
+
+function normalizeSnippet(s) {
+  if (!s || typeof s !== 'string') return '';
+  return s
+    .toLowerCase()
+    // collapse string literals so renaming "foo" → "bar" doesn't break stability
+    .replace(/(['"`])(?:[^\\\1]|\\.)*?\1/g, "'_S_'")
+    // strip line breaks + collapse whitespace
+    .replace(/\s+/g, ' ')
+    // strip trailing punctuation
+    .replace(/[ ,;]+$/, '')
+    .trim();
+}
+
+function basenameLike(file) {
+  if (!file) return '';
+  // Keep only the last two path segments — moving a file within the same
+  // package shouldn't rotate the ID, but moving it across modules should.
+  const parts = String(file).split('/').filter(Boolean);
+  return parts.slice(-2).join('/');
+}
+
+function pathShape(f) {
+  if (!f) return '';
+  const segments = [];
+  if (f.source) segments.push(`${f.source.type || ''}@${f.source.label || ''}`);
+  if (Array.isArray(f.pathSteps)) {
+    for (const step of f.pathSteps) {
+      segments.push(`${step.type || ''}@${step.label || ''}`);
+    }
+  }
+  if (f.sink) segments.push(`${f.sink.type || ''}@${f.sink.label || ''}`);
+  return segments.join('->');
+}
+
+function ruleId(f) {
+  if (f.ruleId) return f.ruleId;
+  if (f.cwe) return `cwe:${f.cwe}`;
+  if (f.family) return `fam:${f.family}`;
+  if (f.parser) return `parser:${f.parser}:${(f.vuln || '').slice(0, 40)}`;
+  return `vuln:${(f.vuln || '').slice(0, 40)}`;
+}
+
+export function computeStableId(f) {
+  const rid = ruleId(f);
+  const sink = normalizeSnippet(f.sink?.snippet || f.snippet || '').slice(0, 200);
+  const shape = pathShape(f);
+  const fileHint = basenameLike(f.file || f.sink?.file);
+  const material = `${rid}|${sink}|${shape}|${fileHint}`;
+  return crypto.createHash('sha256').update(material).digest('hex').slice(0, 16);
+}
+
+export function annotateStableIds(findings) {
+  if (!Array.isArray(findings)) return;
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    try {
+      f.stableId = computeStableId(f);
+    } catch {
+      f.stableId = null;
+    }
+  }
+}

package/src/posture/stack-playbook.js

@@ -0,0 +1,229 @@
+// Stack-specific security playbook detector.
+//
+// Reads package.json / requirements.txt / Cargo.toml etc. to identify
+// the project's tech stack, then returns a structured playbook of the
+// security items that matter most for that specific combination.
+//
+// Playbook entries are returned as info-severity findings so they appear
+// in the report without polluting the critical/high counts.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+function _readJson(p) { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } }
+function _readText(p) { try { return fs.readFileSync(p, 'utf8'); } catch { return null; } }
+
+function _detectStack(scanRoot) {
+  const stack = new Set();
+  const pkg = _readJson(path.join(scanRoot, 'package.json'));
+  if (pkg) {
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    const d = k => Object.keys(deps).some(n => n.toLowerCase() === k.toLowerCase());
+    const dPartial = k => Object.keys(deps).some(n => n.toLowerCase().includes(k));
+
+    if (d('next')) stack.add('nextjs');
+    if (d('react') || d('react-dom')) stack.add('react');
+    if (d('express')) stack.add('express');
+    if (d('fastify')) stack.add('fastify');
+    if (d('hono')) stack.add('hono');
+    if (dPartial('@supabase')) stack.add('supabase');
+    if (d('prisma') || d('@prisma/client')) stack.add('prisma');
+    if (d('mongoose') || d('mongodb')) stack.add('mongodb');
+    if (d('drizzle-orm')) stack.add('drizzle');
+    if (d('stripe')) stack.add('stripe');
+    if (dPartial('clerk')) stack.add('clerk');
+    if (d('next-auth') || d('@auth/core')) stack.add('nextauth');
+    if (d('lucia')) stack.add('lucia');
+    if (dPartial('openai')) stack.add('openai');
+    if (dPartial('@anthropic-ai')) stack.add('anthropic');
+    if (dPartial('langchain') || dPartial('@langchain')) stack.add('langchain');
+    if (d('trpc') || d('@trpc/server')) stack.add('trpc');
+    if (d('graphql')) stack.add('graphql');
+    if (d('socket.io')) stack.add('socketio');
+    if (d('redis') || d('ioredis') || dPartial('@upstash/redis')) stack.add('redis');
+    if (d('resend') || d('nodemailer') || d('@sendgrid/mail')) stack.add('email');
+    if (dPartial('firebase')) stack.add('firebase');
+    if (d('@aws-sdk/client-s3') || dPartial('aws-sdk')) stack.add('aws');
+  }
+
+  const reqTxt = _readText(path.join(scanRoot, 'requirements.txt')) || '';
+  if (reqTxt) {
+    if (/fastapi/i.test(reqTxt)) stack.add('fastapi');
+    if (/django/i.test(reqTxt)) stack.add('django');
+    if (/flask/i.test(reqTxt)) stack.add('flask');
+    if (/sqlalchemy/i.test(reqTxt)) stack.add('sqlalchemy');
+    if (/openai/i.test(reqTxt)) stack.add('openai');
+    if (/anthropic/i.test(reqTxt)) stack.add('anthropic');
+  }
+
+  return stack;
+}
+
+// Playbook entries: each is { title, items: string[] }
+function _buildPlaybook(stack) {
+  const sections = [];
+
+  // Next.js
+  if (stack.has('nextjs')) {
+    sections.push({ title: 'Next.js', items: [
+      'Add security headers in next.config.js headers() — X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: strict-origin-when-cross-origin',
+      'Use Server Actions or API Routes for all data mutations — never expose business logic in client components',
+      'Set NEXTAUTH_URL / AUTH_URL in every environment to prevent host-header CSRF',
+      'Wrap the entire app in middleware auth checks — do not rely on individual page-level checks',
+      'Avoid `dangerouslySetInnerHTML` — use DOMPurify or a sanitizer if HTML rendering is required',
+    ]});
+  }
+
+  // Supabase
+  if (stack.has('supabase')) {
+    sections.push({ title: 'Supabase', items: [
+      'Enable Row-Level Security (RLS) on EVERY table — ALTER TABLE x ENABLE ROW LEVEL SECURITY',
+      'Never use the service-role key client-side or in NEXT_PUBLIC_ env vars — server only',
+      'Audit your RLS policies: SELECT policies should require `auth.uid() = user_id` or similar',
+      'Enable email confirmation in the Auth settings before going live',
+      'Restrict which auth providers are enabled — disable unused ones in the dashboard',
+      'Use Supabase Vault for storing sensitive secrets instead of plain text in tables',
+    ]});
+  }
+
+  // Clerk
+  if (stack.has('clerk')) {
+    sections.push({ title: 'Clerk', items: [
+      'Use clerkMiddleware() in middleware.ts and protect all routes by default — list exceptions explicitly',
+      'Do not put admin/settings/dashboard paths in publicRoutes',
+      'Enable MFA in Clerk dashboard for your own admin account and for high-value users',
+      'Validate the userId / orgId from auth() server-side — never trust client-passed IDs',
+      'Set sessionMaxAge to a reasonable value (e.g., 7 days) in Clerk dashboard',
+    ]});
+  }
+
+  // NextAuth
+  if (stack.has('nextauth')) {
+    sections.push({ title: 'NextAuth / Auth.js', items: [
+      'Set NEXTAUTH_SECRET to a 32+ byte random value: `openssl rand -base64 32`',
+      'Set NEXTAUTH_URL to your canonical production URL — prevents host-header CSRF',
+      'Do not set trustHost: true in production',
+      'Do not set allowDangerousEmailAccountLinking: true unless you fully understand the account-takeover risk',
+      'Protect all API routes and pages with getServerSession() — the client session is not authoritative',
+      'Use database sessions (adapter) rather than JWT sessions if you need immediate revocation',
+    ]});
+  }
+
+  // Stripe
+  if (stack.has('stripe')) {
+    sections.push({ title: 'Stripe', items: [
+      'Verify webhook signatures using stripe.webhooks.constructEvent() — never trust unverified webhook payloads',
+      'Store STRIPE_SECRET_KEY server-side only — never client-side or in NEXT_PUBLIC_',
+      'Use Stripe Checkout or Payment Element instead of rolling your own card form',
+      'Enable Radar rules in the Stripe dashboard to block card-testing attacks',
+      'Always fetch the current price from Stripe server-side — never trust the client-supplied price',
+      'Test with Stripe CLI webhook forwarding locally — do not expose your dev server publicly',
+    ]});
+  }
+
+  // Prisma / Drizzle
+  if (stack.has('prisma') || stack.has('drizzle')) {
+    const orm = stack.has('prisma') ? 'Prisma' : 'Drizzle';
+    sections.push({ title: orm, items: [
+      `Never use raw SQL (\`${stack.has('prisma') ? 'prisma.$queryRawUnsafe' : 'sql.raw'}\`) with user input — use parameterised queries only`,
+      'Scope all queries to the authenticated user — add `where: { userId: session.userId }` to every user-data query',
+      'Store DATABASE_URL in env only — use connection pooling (PgBouncer/Supabase pooler) in production',
+      'Add `@@map` to rename table names if your schema column names match internal business logic you want to keep private',
+    ]});
+  }
+
+  // MongoDB / Mongoose
+  if (stack.has('mongodb')) {
+    sections.push({ title: 'MongoDB', items: [
+      'Sanitize all user input with mongoose-sanitize or express-mongo-sanitize to prevent NoSQL injection',
+      'Never use `$where` with user-controlled expressions',
+      'Enable MongoDB auth (username/password) even in development',
+      'Scope queries to authenticated user: `{ _id: req.params.id, userId: session.userId }`',
+      'Enable MongoDB Atlas IP allowlist to restrict which IPs can connect',
+    ]});
+  }
+
+  // OpenAI / Anthropic / LangChain
+  if (stack.has('openai') || stack.has('anthropic') || stack.has('langchain')) {
+    sections.push({ title: 'AI / LLM', items: [
+      'Rate-limit your AI endpoints — a single attacker can exhaust your monthly budget in minutes',
+      'Never include other users\' data in prompts — prompt context must be scoped to the requesting user',
+      'Set max_tokens on every API call to cap per-request cost',
+      'Validate and sanitize AI output before rendering — treat it as untrusted user input',
+      'Store OPENAI_API_KEY / ANTHROPIC_API_KEY server-side only — never in NEXT_PUBLIC_ or client bundles',
+      'Add per-user spend limits and alert thresholds in the provider dashboard',
+    ]});
+  }
+
+  // Email
+  if (stack.has('email')) {
+    sections.push({ title: 'Email / Transactional', items: [
+      'Rate-limit email-sending endpoints — unlimited sign-up/contact forms are spam vectors',
+      'Validate the To: address server-side — never let users supply arbitrary email recipients',
+      'Store email API keys (Resend, SendGrid) server-side only',
+      'Configure SPF, DKIM, and DMARC records to prevent email spoofing from your domain',
+    ]});
+  }
+
+  // tRPC
+  if (stack.has('trpc')) {
+    sections.push({ title: 'tRPC', items: [
+      'Apply auth middleware to all protected procedures — do not rely on client-side route guards',
+      'Use `ctx.session.userId` for all data access — never trust input IDs without ownership check',
+      'Enable CORS only for your own domains in the tRPC HTTP adapter',
+    ]});
+  }
+
+  // FastAPI
+  if (stack.has('fastapi')) {
+    sections.push({ title: 'FastAPI', items: [
+      'Use OAuth2PasswordBearer or a JWT dependency on every protected route',
+      'Enable CORS middleware with an explicit allow_origins list — never ["*"] in production',
+      'Set SECRET_KEY to a 32+ byte random value and store in environment, not in code',
+      'Use Pydantic models for all request bodies to enforce input validation',
+      'Disable the /docs and /redoc endpoints in production: `docs_url=None, redoc_url=None`',
+    ]});
+  }
+
+  // Django
+  if (stack.has('django')) {
+    sections.push({ title: 'Django', items: [
+      'Set DEBUG=False in production — DEBUG mode exposes tracebacks with local variables',
+      'Set SECRET_KEY from environment — never hardcode it in settings.py',
+      'Configure ALLOWED_HOSTS — an empty list in production causes 500 errors on valid requests',
+      'Use Django\'s built-in CSRF middleware — never exempt views unnecessarily',
+      'Use `django.contrib.security` middleware stack in MIDDLEWARE setting',
+    ]});
+  }
+
+  return sections;
+}
+
+function _findingFromItem(scanRoot, stackName, item, idx) {
+  return {
+    id: `stack-playbook:${stackName.replace(/\s+/g, '_').toUpperCase()}:${idx}`,
+    title: `[${stackName} Security Checklist] ${item.slice(0, 80)}`,
+    severity: 'info',
+    file: 'package.json',
+    line: 1,
+    description: item,
+    remediation: item,
+    cwe: 'CWE-1008',
+  };
+}
+
+function runStackPlaybook(scanRoot) {
+  if (!scanRoot) return [];
+  const stack = _detectStack(scanRoot);
+  if (stack.size === 0) return [];
+  const playbook = _buildPlaybook(stack);
+  const findings = [];
+  for (const section of playbook) {
+    section.items.forEach((item, i) => {
+      findings.push(_findingFromItem(scanRoot, section.title, item, i));
+    });
+  }
+  return { stack: [...stack], playbook, findings };
+}
+
+export { runStackPlaybook, _detectStack, _buildPlaybook };