agent-security-scanner-mcp 3.18.0 → 3.20.0

package/src/lib/compliance-controls.js

@@ -0,0 +1,164 @@
+// src/lib/compliance-controls.js — AIUC-1 controls registry loader + schema validator.
+
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+let __dirname;
+try {
+  __dirname = dirname(fileURLToPath(import.meta.url));
+} catch {
+  __dirname = process.cwd();
+}
+
+const KNOWN_DOMAINS = new Set(['security', 'safety']);
+const KNOWN_TOOLS = new Set([
+  'scan_security', 'scan_agent_prompt', 'scan_project', 'scan_skill',
+  'scan_mcp_server', 'scan_agent_action', 'scan_git_diff',
+]);
+const OWASP_TAG_RE = /^LLM\d{2}$/;
+
+let _cache = null;
+
+/**
+ * Validate the controls registry schema. Returns array of error strings (empty = valid).
+ */
+export function validateRegistry(data) {
+  const errors = [];
+
+  if (!data || typeof data !== 'object') {
+    errors.push('Registry must be a non-null object');
+    return errors;
+  }
+
+  if (!Array.isArray(data.controls)) {
+    errors.push('Registry must have a "controls" array');
+    return errors;
+  }
+
+  const ids = new Set();
+  for (const ctrl of data.controls) {
+    // Required fields
+    if (!ctrl.id) errors.push(`Control missing "id"`);
+    if (!ctrl.title) errors.push(`Control ${ctrl.id || '?'} missing "title"`);
+    if (!ctrl.domain) errors.push(`Control ${ctrl.id || '?'} missing "domain"`);
+    if (!ctrl.evaluation) errors.push(`Control ${ctrl.id || '?'} missing "evaluation"`);
+
+    // Duplicate ID check
+    if (ctrl.id && ids.has(ctrl.id)) {
+      errors.push(`Duplicate control ID: ${ctrl.id}`);
+    }
+    ids.add(ctrl.id);
+
+    // Domain validation
+    if (ctrl.domain && !KNOWN_DOMAINS.has(ctrl.domain)) {
+      errors.push(`Control ${ctrl.id}: unknown domain "${ctrl.domain}"`);
+    }
+
+    // Scanner tools validation
+    if (Array.isArray(ctrl.scanner_tools)) {
+      for (const tool of ctrl.scanner_tools) {
+        if (!KNOWN_TOOLS.has(tool)) {
+          errors.push(`Control ${ctrl.id}: unknown scanner tool "${tool}"`);
+        }
+      }
+    }
+
+    // OWASP tags validation
+    if (Array.isArray(ctrl.owasp_llm)) {
+      for (const tag of ctrl.owasp_llm) {
+        if (!OWASP_TAG_RE.test(tag)) {
+          errors.push(`Control ${ctrl.id}: invalid OWASP tag "${tag}" (expected LLM\\d{2})`);
+        }
+      }
+    }
+
+    // Evaluation field types
+    if (ctrl.evaluation) {
+      const ev = ctrl.evaluation;
+      if (ev.max_aivss_posture !== undefined && typeof ev.max_aivss_posture !== 'number') {
+        errors.push(`Control ${ctrl.id}: evaluation.max_aivss_posture must be a number`);
+      }
+      if (ev.max_critical_findings !== undefined && typeof ev.max_critical_findings !== 'number') {
+        errors.push(`Control ${ctrl.id}: evaluation.max_critical_findings must be a number`);
+      }
+      if (ev.required_tools !== undefined) {
+        if (!Array.isArray(ev.required_tools)) {
+          errors.push(`Control ${ctrl.id}: evaluation.required_tools must be an array`);
+        } else {
+          for (const tool of ev.required_tools) {
+            if (!KNOWN_TOOLS.has(tool)) {
+              errors.push(`Control ${ctrl.id}: evaluation.required_tools references unknown tool "${tool}"`);
+            }
+          }
+        }
+      }
+      if (ev.fail_on_severities !== undefined && !Array.isArray(ev.fail_on_severities)) {
+        errors.push(`Control ${ctrl.id}: evaluation.fail_on_severities must be an array`);
+      }
+      if (ev.fail_on_actions !== undefined && !Array.isArray(ev.fail_on_actions)) {
+        errors.push(`Control ${ctrl.id}: evaluation.fail_on_actions must be an array`);
+      }
+      if (ev.min_grade !== undefined && typeof ev.min_grade !== 'string') {
+        errors.push(`Control ${ctrl.id}: evaluation.min_grade must be a string`);
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Load the AIUC-1 controls registry. Validates on first load.
+ * @returns {object} The full registry object
+ */
+export function loadControls() {
+  if (_cache) return _cache;
+
+  const controlsPath = join(__dirname, '..', '..', 'compliance', 'aiuc-1-controls.json');
+  const data = JSON.parse(readFileSync(controlsPath, 'utf-8'));
+
+  const errors = validateRegistry(data);
+  if (errors.length > 0) {
+    throw new Error(`AIUC-1 controls registry validation failed:\n${errors.join('\n')}`);
+  }
+
+  _cache = data;
+  return data;
+}
+
+/**
+ * Filter controls by domain, control IDs, or OWASP tags.
+ * @param {object} [filters]
+ * @param {string} [filters.domain] - 'security', 'safety', or 'all'
+ * @param {string[]} [filters.controlIds] - Specific control IDs
+ * @param {string[]} [filters.owaspFilter] - OWASP LLM tags to match
+ * @returns {object[]} Filtered controls
+ */
+export function filterControls({ domain, controlIds, owaspFilter } = {}) {
+  const registry = loadControls();
+  let controls = registry.controls;
+
+  if (domain && domain !== 'all') {
+    controls = controls.filter(c => c.domain === domain);
+  }
+
+  if (controlIds && controlIds.length > 0) {
+    const idSet = new Set(controlIds);
+    controls = controls.filter(c => idSet.has(c.id));
+  }
+
+  if (owaspFilter && owaspFilter.length > 0) {
+    const owaspSet = new Set(owaspFilter);
+    controls = controls.filter(c =>
+      Array.isArray(c.owasp_llm) && c.owasp_llm.some(tag => owaspSet.has(tag))
+    );
+  }
+
+  return controls;
+}
+
+// Reset cache (for testing)
+export function _resetCache() {
+  _cache = null;
+}

package/src/lib/compliance-evaluator.js

@@ -0,0 +1,149 @@
+// src/lib/compliance-evaluator.js — Deterministic pass/partial/fail evaluation logic.
+
+import { scoreBatch } from './aivss.js';
+
+const GRADE_ORDER = { A: 4, B: 3, C: 2, D: 1, F: 0 };
+
+/**
+ * Check if actual grade is worse than threshold.
+ * Missing/null grade → treated as F (worst case).
+ */
+function gradeIsWorse(actual, threshold) {
+  const actualVal = GRADE_ORDER[actual] ?? 0; // null/missing → F → 0
+  const thresholdVal = GRADE_ORDER[threshold] ?? 0;
+  return actualVal < thresholdVal;
+}
+
+/**
+ * Evaluate a single control against evidence.
+ *
+ * @param {object} control - A control from the registry
+ * @param {object} evidence
+ * @param {object|null} evidence.aivssPosture - Posture from scoreBatch, or null
+ * @param {object[]} evidence.findings - Normalized findings from all available tools
+ * @param {object} evidence.grades - Map of tool/scope → grade (e.g. { project: 'B' })
+ * @param {string[]} evidence.toolsRun - Array of tool names whose output is available
+ * @returns {{ control_id: string, status: string, reasons: string[] }}
+ */
+export function evaluateControl(control, evidence) {
+  if (!control || !control.id || !control.evaluation) {
+    return {
+      control_id: control?.id || 'unknown',
+      status: 'not_evaluated',
+      reasons: ['Malformed control: missing id or evaluation'],
+    };
+  }
+
+  const ev = control.evaluation;
+  const reasons = [];
+  const toolsRun = evidence.toolsRun || [];
+
+  // 1. Check required_tools
+  if (Array.isArray(ev.required_tools)) {
+    for (const tool of ev.required_tools) {
+      if (!toolsRun.includes(tool)) {
+        return {
+          control_id: control.id,
+          status: 'not_evaluated',
+          reasons: [`Missing required tool: ${tool}`],
+        };
+      }
+    }
+  }
+
+  let status = 'pass';
+
+  // Scope findings to this control's relevant tools
+  const relevantTools = Array.isArray(control.scanner_tools) ? new Set(control.scanner_tools) : null;
+  const relevantFindings = (evidence.findings || []).filter(f => {
+    if (!relevantTools) return true;
+    return relevantTools.has(f.source_tool);
+  });
+
+  // 2. Check fail_on_severities
+  if (Array.isArray(ev.fail_on_severities) && ev.fail_on_severities.length > 0) {
+    const sevSet = new Set(ev.fail_on_severities);
+    const matched = relevantFindings.filter(f => sevSet.has(f.severity));
+    if (matched.length > 0) {
+      status = 'fail';
+      reasons.push(`${matched.length} finding(s) with severity in [${ev.fail_on_severities.join(', ')}]`);
+    }
+  }
+
+  // 3. Check fail_on_actions
+  if (Array.isArray(ev.fail_on_actions) && ev.fail_on_actions.length > 0) {
+    const actSet = new Set(ev.fail_on_actions);
+    const matched = relevantFindings.filter(f => f.action && actSet.has(f.action));
+    if (matched.length > 0) {
+      status = 'fail';
+      reasons.push(`${matched.length} finding(s) with action in [${ev.fail_on_actions.join(', ')}]`);
+    }
+  }
+
+  // 4. Check max_aivss_posture (scoped to this control's relevant findings)
+  if (typeof ev.max_aivss_posture === 'number' && relevantFindings.length > 0) {
+    const scopedPosture = scoreBatch(relevantFindings).posture;
+    if (scopedPosture.posture_score > ev.max_aivss_posture) {
+      status = 'fail';
+      reasons.push(`AIVSS posture ${scopedPosture.posture_score} exceeds max ${ev.max_aivss_posture}`);
+    }
+  }
+
+  // 5. Check max_critical_findings (scoped to this control's tools)
+  if (typeof ev.max_critical_findings === 'number') {
+    const critCount = relevantFindings.filter(f => f.severity === 'CRITICAL').length;
+    if (critCount > ev.max_critical_findings) {
+      status = 'fail';
+      reasons.push(`${critCount} CRITICAL finding(s) exceeds max ${ev.max_critical_findings}`);
+    }
+  }
+
+  // 6. Check min_grade (scoped to control's relevant grade keys)
+  if (ev.min_grade) {
+    const grades = evidence.grades || {};
+    // Only consider grades for tools this control cares about
+    const relevantGradeKeys = relevantTools
+      ? Object.keys(grades).filter(k => relevantTools.has(k) || relevantTools.has(`scan_${k}`))
+      : Object.keys(grades);
+    const gradeValues = relevantGradeKeys.map(k => grades[k]);
+    if (gradeValues.length > 0) {
+      const worstGrade = gradeValues.reduce((worst, g) => {
+        return gradeIsWorse(g, worst) ? g : worst;
+      }, gradeValues[0]);
+      if (gradeIsWorse(worstGrade, ev.min_grade)) {
+        if (status !== 'fail') status = 'partial';
+        reasons.push(`Grade ${worstGrade || 'F'} below minimum ${ev.min_grade}`);
+      }
+    } else if (status !== 'fail') {
+      // No relevant grades available → treat as F
+      if (gradeIsWorse(null, ev.min_grade)) {
+        status = 'partial';
+        reasons.push(`No relevant grade available (treated as F), below minimum ${ev.min_grade}`);
+      }
+    }
+  }
+
+  return { control_id: control.id, status, reasons };
+}
+
+/**
+ * Evaluate all controls against evidence.
+ *
+ * @param {object[]} controls - Array of controls from registry
+ * @param {object} evidence - Same shape as evaluateControl
+ * @returns {{ controls_evaluated: number, pass: number, partial: number, fail: number, not_evaluated: number, results: object[] }}
+ */
+export function evaluateAll(controls, evidence) {
+  const results = controls.map(c => evaluateControl(c, evidence));
+
+  const summary = { pass: 0, partial: 0, fail: 0, not_evaluated: 0 };
+  for (const r of results) {
+    summary[r.status] = (summary[r.status] || 0) + 1;
+  }
+
+  return {
+    controls_evaluated: controls.length,
+    ...summary,
+    results,
+  };
+}

package/src/lib/normalize-finding.js

@@ -0,0 +1,146 @@
+// src/lib/normalize-finding.js — Normalize findings from 6 different tool shapes into one internal format.
+
+const SEVERITY_MAP = {
+  'error': { severity: 'HIGH', severity_rank: 3 },
+  'ERROR': { severity: 'HIGH', severity_rank: 3 },
+  'warning': { severity: 'MEDIUM', severity_rank: 2 },
+  'WARNING': { severity: 'MEDIUM', severity_rank: 2 },
+  'info': { severity: 'INFO', severity_rank: 0 },
+  'INFO': { severity: 'INFO', severity_rank: 0 },
+  'CRITICAL': { severity: 'CRITICAL', severity_rank: 4 },
+  'critical': { severity: 'CRITICAL', severity_rank: 4 },
+  'LOW': { severity: 'LOW', severity_rank: 1 },
+  'low': { severity: 'LOW', severity_rank: 1 },
+  'HIGH': { severity: 'HIGH', severity_rank: 3 },
+  'high': { severity: 'HIGH', severity_rank: 3 },
+  'MEDIUM': { severity: 'MEDIUM', severity_rank: 2 },
+  'medium': { severity: 'MEDIUM', severity_rank: 2 },
+};
+
+const DEFAULT_SEVERITY = { severity: 'MEDIUM', severity_rank: 2 };
+
+// Map ruleId segments to categories for tools that don't emit category directly.
+// Keyed by the second dotted segment of ruleId (e.g. "injection" from "python.injection.sql-injection").
+const RULE_CATEGORY_MAP = {
+  'injection': 'injection',
+  'crypto': 'crypto',
+  'auth': 'auth',
+  'xss': 'xss',
+  'ssrf': 'ssrf',
+  'path': 'path-traversal',
+  'deserialization': 'deserialization',
+  'info': 'info-exposure',
+  'permissions': 'permissions',
+  'logging': 'info-exposure',
+  'secrets': 'info-exposure',
+  'prompt': 'prompt-injection',
+  'exfiltration': 'exfiltration',
+  'supply': 'supply-chain',
+  'command': 'injection',
+  'sql': 'injection',
+};
+
+/**
+ * Extract a unified rule_id from any finding shape.
+ */
+function extractRuleId(finding) {
+  return finding.ruleId || finding.rule_id || finding.id || finding.rule || null;
+}
+
+/**
+ * Infer category from ruleId when no explicit category is set.
+ * Looks at dotted segments of the ruleId for known category keywords.
+ */
+function inferCategory(ruleId) {
+  if (!ruleId) return null;
+  const segments = ruleId.toLowerCase().split('.');
+  for (const seg of segments) {
+    if (RULE_CATEGORY_MAP[seg]) return RULE_CATEGORY_MAP[seg];
+  }
+  // Check if any segment contains a known keyword
+  for (const seg of segments) {
+    for (const [key, cat] of Object.entries(RULE_CATEGORY_MAP)) {
+      if (seg.includes(key)) return cat;
+    }
+  }
+  return null;
+}
+
+/**
+ * Normalize confidence to uppercase HIGH/MEDIUM/LOW.
+ */
+function normalizeConfidence(confidence) {
+  if (!confidence) return 'MEDIUM';
+  const upper = String(confidence).toUpperCase();
+  if (upper === 'HIGH' || upper === 'MEDIUM' || upper === 'LOW') return upper;
+  return 'MEDIUM';
+}
+
+/**
+ * Normalize action to uppercase BLOCK/WARN/ALLOW or null.
+ */
+function normalizeAction(action) {
+  if (!action) return null;
+  const upper = String(action).toUpperCase();
+  if (upper === 'BLOCK' || upper === 'WARN' || upper === 'ALLOW') return upper;
+  if (upper === 'LOG') return 'WARN';
+  return null;
+}
+
+/**
+ * Normalize a single finding into the internal format.
+ *
+ * @param {object} finding - Raw finding from any scanner tool
+ * @param {string} sourceTool - Tool that produced this finding (fallback if not on finding)
+ * @param {object} [options] - Options
+ * @param {boolean} [options.includeRaw] - Include original finding as `raw` field
+ * @returns {object} Normalized finding
+ */
+export function normalizeFinding(finding, sourceTool, options = {}) {
+  if (!finding || typeof finding !== 'object') {
+    return null;
+  }
+
+  const originalSeverity = finding.severity || null;
+  const mapped = SEVERITY_MAP[originalSeverity] || DEFAULT_SEVERITY;
+
+  const normalized = {
+    rule_id: extractRuleId(finding) || 'unknown',
+    original_severity: originalSeverity,
+    severity: mapped.severity,
+    severity_rank: mapped.severity_rank,
+    confidence: normalizeConfidence(finding.confidence),
+    message: finding.message || '',
+    category: finding.category || inferCategory(extractRuleId(finding)),
+    cwe: finding.cwe || (finding.metadata && finding.metadata.cwe) || null,
+    owasp: finding.owasp || (finding.metadata && finding.metadata.owasp) || null,
+    file: finding.file || null,
+    line: typeof finding.line === 'number' ? finding.line : null,
+    action: normalizeAction(finding.action),
+    risk_score: typeof finding.risk_score === 'number'
+      ? finding.risk_score
+      : (typeof finding.risk_score === 'string' ? parseFloat(finding.risk_score) || null : null),
+    source_tool: finding.source_tool || sourceTool || 'unknown',
+  };
+
+  if (options.includeRaw) {
+    normalized.raw = finding;
+  }
+
+  return normalized;
+}
+
+/**
+ * Normalize an array of findings.
+ *
+ * @param {object[]} findings - Array of raw findings
+ * @param {string} sourceTool - Default source tool (per-finding source_tool wins)
+ * @param {object} [options] - Options passed to normalizeFinding
+ * @returns {object[]} Array of normalized findings
+ */
+export function normalizeFindings(findings, sourceTool, options = {}) {
+  if (!Array.isArray(findings)) return [];
+  return findings
+    .map(f => normalizeFinding(f, sourceTool, options))
+    .filter(Boolean);
+}

package/src/tools/check-package.js

@@ -32,6 +32,17 @@ const BLOOM_FILTERS = {
   rubygems: null
 };
 
+// Flutter/Dart SDK packages are legitimate dependencies even though they do
+// not appear in the pub.dev package dump used for the text-based lookup.
+const DART_SDK_PACKAGES = new Set([
+  'flutter',
+  'flutter_test',
+  'flutter_driver',
+  'flutter_localizations',
+  'flutter_web_plugins',
+  'integration_test',
+]);
+
 // Load package lists on startup
 export function loadPackageLists() {
   const packagesDir = join(__dirname, '..', '..', 'packages');
@@ -67,6 +78,10 @@ export function loadPackageLists() {
 
 // Check if a package is hallucinated
 export function isHallucinated(packageName, ecosystem) {
+  if (ecosystem === 'dart' && DART_SDK_PACKAGES.has(packageName)) {
+    return { hallucinated: false, sdkPackage: true };
+  }
+
   const legitPackages = LEGITIMATE_PACKAGES[ecosystem];
 
   // First check Set-based lookup (exact match)

package/src/tools/compliance-controls.js

@@ -0,0 +1,67 @@
+// src/tools/compliance-controls.js — get_compliance_controls MCP tool (thin wrapper)
+
+import { z } from 'zod';
+import { loadControls, filterControls } from '../lib/compliance-controls.js';
+
+export const complianceControlsSchema = {
+  domain: z.enum(['security', 'safety', 'all']).optional().describe("Filter by domain"),
+  control_ids: z.array(z.string()).optional().describe("Specific control IDs to retrieve"),
+  owasp_filter: z.array(z.string()).optional().describe("Filter by OWASP LLM tags (e.g. LLM01)"),
+  verbosity: z.enum(['minimal', 'compact', 'full']).optional().describe("Response detail level"),
+};
+
+export async function getComplianceControls({ domain, control_ids, owasp_filter, verbosity }) {
+  const level = verbosity || 'compact';
+
+  const controls = filterControls({
+    domain: domain || 'all',
+    controlIds: control_ids,
+    owaspFilter: owasp_filter,
+  });
+
+  const registry = loadControls();
+
+  let output;
+  switch (level) {
+    case 'minimal':
+      output = {
+        framework: registry.framework,
+        controls_count: controls.length,
+        controls: controls.map(c => ({ id: c.id, title: c.title, domain: c.domain })),
+      };
+      break;
+
+    case 'full':
+      output = {
+        framework: registry.framework,
+        schema_version: registry.schema_version,
+        source: registry.source,
+        source_snapshot: registry.source_snapshot,
+        controls_count: controls.length,
+        controls,
+      };
+      break;
+
+    case 'compact':
+    default:
+      output = {
+        framework: registry.framework,
+        controls_count: controls.length,
+        controls: controls.map(c => ({
+          id: c.id,
+          title: c.title,
+          domain: c.domain,
+          owasp_llm: c.owasp_llm,
+          scanner_tools: c.scanner_tools,
+          evaluation: c.evaluation,
+        })),
+      };
+  }
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(output, null, 2),
+    }],
+  };
+}