agent-security-scanner-mcp 4.1.1 → 4.3.0

package/src/lib/compliance-controls.js

@@ -1,6 +1,6 @@
-// src/lib/compliance-controls.js — AIUC-1 controls registry loader + schema validator.
+// src/lib/compliance-controls.js — Multi-framework controls registry loader + schema validator.
 
-import { readFileSync } from 'fs';
+import { readFileSync, readdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 
@@ -11,14 +11,15 @@ try {
   __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',
+  'sbom_generate', 'sbom_scan_vulnerabilities', 'sbom_check_hallucinations', 'sbom_diff',
 ]);
 const OWASP_TAG_RE = /^LLM\d{2}$/;
+const VALID_CHECK_OPS = new Set(['exists', 'eq', 'lte', 'gte']);
 
-let _cache = null;
+const _cache = new Map();
 
 /**
  * Validate the controls registry schema. Returns array of error strings (empty = valid).
@@ -36,6 +37,13 @@ export function validateRegistry(data) {
     return errors;
   }
 
+  // Validate registry-level domains array
+  if (!Array.isArray(data.domains) || data.domains.length === 0) {
+    errors.push('Registry must have a non-empty "domains" array');
+    return errors;
+  }
+  const registryDomains = new Set(data.domains);
+
   const ids = new Set();
   for (const ctrl of data.controls) {
     // Required fields
@@ -50,9 +58,9 @@ export function validateRegistry(data) {
     }
     ids.add(ctrl.id);
 
-    // Domain validation
-    if (ctrl.domain && !KNOWN_DOMAINS.has(ctrl.domain)) {
-      errors.push(`Control ${ctrl.id}: unknown domain "${ctrl.domain}"`);
+    // Domain validation — check against this registry's own domains
+    if (ctrl.domain && !registryDomains.has(ctrl.domain)) {
+      errors.push(`Control ${ctrl.id}: unknown domain "${ctrl.domain}" (registry allows: ${data.domains.join(', ')})`);
     }
 
     // Scanner tools validation
@@ -64,7 +72,7 @@ export function validateRegistry(data) {
       }
     }
 
-    // OWASP tags validation
+    // OWASP tags validation (optional — only validated when present)
     if (Array.isArray(ctrl.owasp_llm)) {
       for (const tag of ctrl.owasp_llm) {
         if (!OWASP_TAG_RE.test(tag)) {
@@ -73,6 +81,19 @@ export function validateRegistry(data) {
       }
     }
 
+    // References validation (optional — array of strings)
+    if (ctrl.references !== undefined) {
+      if (!Array.isArray(ctrl.references)) {
+        errors.push(`Control ${ctrl.id}: references must be an array`);
+      } else {
+        for (const ref of ctrl.references) {
+          if (typeof ref !== 'string') {
+            errors.push(`Control ${ctrl.id}: each reference must be a string`);
+          }
+        }
+      }
+    }
+
     // Evaluation field types
     if (ctrl.evaluation) {
       const ev = ctrl.evaluation;
@@ -102,6 +123,39 @@ export function validateRegistry(data) {
       if (ev.min_grade !== undefined && typeof ev.min_grade !== 'string') {
         errors.push(`Control ${ctrl.id}: evaluation.min_grade must be a string`);
       }
+
+      // evidence_checks validation (generic path-based checks for SOC2/GDPR controls)
+      if (ev.evidence_checks !== undefined) {
+        if (!Array.isArray(ev.evidence_checks)) {
+          errors.push(`Control ${ctrl.id}: evaluation.evidence_checks must be an array`);
+        } else {
+          for (let i = 0; i < ev.evidence_checks.length; i++) {
+            const check = ev.evidence_checks[i];
+            const prefix = `Control ${ctrl.id}: evidence_checks[${i}]`;
+            if (!check.path || typeof check.path !== 'string') {
+              errors.push(`${prefix}: must have a string "path"`);
+            }
+            if (!check.operator || !VALID_CHECK_OPS.has(check.operator)) {
+              errors.push(`${prefix}: operator must be one of: ${[...VALID_CHECK_OPS].join(', ')}`);
+            }
+            if (check.operator !== 'exists' && check.value === undefined) {
+              errors.push(`${prefix}: non-exists operators require a "value"`);
+            }
+            if (!check.on_fail || !['fail', 'partial', 'not_evaluated'].includes(check.on_fail)) {
+              errors.push(`${prefix}: on_fail must be "fail", "partial", or "not_evaluated"`);
+            }
+            if (check.not_evaluated_reason !== undefined && typeof check.not_evaluated_reason !== 'string') {
+              errors.push(`${prefix}: not_evaluated_reason must be a string`);
+            }
+            if (check.reason !== undefined && typeof check.reason !== 'string') {
+              errors.push(`${prefix}: reason must be a string`);
+            }
+            if (check.default !== undefined && typeof check.default !== 'number' && typeof check.default !== 'boolean') {
+              errors.push(`${prefix}: default must be a number or boolean`);
+            }
+          }
+        }
+      }
     }
   }
 
@@ -109,34 +163,42 @@ export function validateRegistry(data) {
 }
 
 /**
- * Load the AIUC-1 controls registry. Validates on first load.
+ * Load a controls registry by framework name. Validates on first load per framework.
+ * @param {string} [framework='aiuc-1'] - Framework identifier (maps to compliance/<framework>-controls.json)
  * @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'));
+export function loadControls(framework = 'aiuc-1') {
+  if (_cache.has(framework)) return _cache.get(framework);
+
+  const controlsPath = join(__dirname, '..', '..', 'compliance', `${framework}-controls.json`);
+  let raw;
+  try {
+    raw = readFileSync(controlsPath, 'utf-8');
+  } catch (err) {
+    throw new Error(`Cannot load controls registry for framework "${framework}": ${err.message}`);
+  }
+  const data = JSON.parse(raw);
 
   const errors = validateRegistry(data);
   if (errors.length > 0) {
-    throw new Error(`AIUC-1 controls registry validation failed:\n${errors.join('\n')}`);
+    throw new Error(`${framework} controls registry validation failed:\n${errors.join('\n')}`);
   }
 
-  _cache = data;
+  _cache.set(framework, data);
   return data;
 }
 
 /**
- * Filter controls by domain, control IDs, or OWASP tags.
+ * Filter controls by framework, domain, control IDs, or OWASP tags.
  * @param {object} [filters]
- * @param {string} [filters.domain] - 'security', 'safety', or 'all'
+ * @param {string} [filters.framework] - Framework to load (default: 'aiuc-1')
+ * @param {string} [filters.domain] - Domain name 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();
+export function filterControls({ framework = 'aiuc-1', domain, controlIds, owaspFilter } = {}) {
+  const registry = loadControls(framework);
   let controls = registry.controls;
 
   if (domain && domain !== 'all') {
@@ -158,7 +220,24 @@ export function filterControls({ domain, controlIds, owaspFilter } = {}) {
   return controls;
 }
 
+/**
+ * List available framework names by scanning the compliance directory.
+ * @returns {string[]} Available framework identifiers
+ */
+export function listFrameworks() {
+  const dir = join(__dirname, '..', '..', 'compliance');
+  try {
+    return readdirSync(dir)
+      .filter(f => f.endsWith('-controls.json'))
+      .map(f => f.replace('-controls.json', ''));
+  } catch {
+    return [];
+  }
+}
+
+export { KNOWN_TOOLS };
+
 // Reset cache (for testing)
 export function _resetCache() {
-  _cache = null;
+  _cache.clear();
 }

package/src/lib/compliance-evaluator.js

@@ -4,6 +4,131 @@ import { scoreBatch } from './aivss.js';
 
 const GRADE_ORDER = { A: 4, B: 3, C: 2, D: 1, F: 0 };
 
+/**
+ * Resolve a dot-path like "supply_chain.vulnerabilities.by_severity.critical" against an object.
+ * Returns undefined for any missing intermediate key (never throws).
+ */
+export function resolvePath(obj, path) {
+  if (obj == null || typeof path !== 'string') return undefined;
+  const segments = path.split('.');
+  let current = obj;
+  for (const seg of segments) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[seg];
+  }
+  return current;
+}
+
+/**
+ * Run a single evidence_check against the evidence bundle.
+ * Returns { passed: boolean, status: string|null, reason: string } where:
+ * - passed=true means check succeeded (no status change needed)
+ * - passed=false means on_fail status should be applied, with reason
+ */
+function runEvidenceCheck(check, evidenceBundle) {
+  const value = resolvePath(evidenceBundle, check.path);
+
+  // Missing evidence handling — three tiers:
+  //
+  // 1. Any node along the path is explicitly `null` → source failure → not_evaluated.
+  //    The evidence collector sets sections to null when a data source fails (e.g., OSV down).
+  //
+  // 2. A top-level section key is missing entirely (e.g., bundle has no "supply_chain") →
+  //    evidence was never collected → not_evaluated. Defaults must not mask this.
+  //
+  // 3. A deeper leaf is missing but its parent exists (e.g., scan.by_category_severity.crypto
+  //    is absent because no crypto findings) → safe to apply check.default.
+  //
+  if (value === undefined || value === null) {
+    const segments = check.path.split('.');
+
+    // Walk the path to find where it breaks
+    let current = evidenceBundle;
+    let depth = 0;
+    for (depth = 0; depth < segments.length; depth++) {
+      if (current === null) {
+        // Explicit null — source failure
+        const failedAt = segments.slice(0, depth).join('.') || segments[0];
+        return {
+          passed: false,
+          status: 'not_evaluated',
+          reason: `Evidence source unavailable: ${failedAt} is null (full path: ${check.path})`,
+        };
+      }
+      if (current === undefined || typeof current !== 'object') break;
+      const next = current[segments[depth]];
+      if (next === null) {
+        // Explicit null at this level
+        const failedAt = segments.slice(0, depth + 1).join('.');
+        return {
+          passed: false,
+          status: 'not_evaluated',
+          reason: `Evidence source unavailable: ${failedAt} is null (full path: ${check.path})`,
+        };
+      }
+      if (next === undefined) break; // missing key — check depth below
+      current = next;
+    }
+
+    // If the break happened at depth 0 or 1, the top-level section is missing.
+    // This means evidence was never collected — not_evaluated, no defaults.
+    if (depth <= 1) {
+      return {
+        passed: false,
+        status: 'not_evaluated',
+        reason: `Evidence source unavailable: ${segments[0]} is missing (full path: ${check.path})`,
+      };
+    }
+
+    // Break happened deeper — parent section exists, leaf key absent.
+    // Safe to apply default (e.g., scan ran but no "crypto" category).
+    if (check.default !== undefined) {
+      return evaluateOp(check.operator, check.default, check.value, check);
+    }
+
+    return {
+      passed: false,
+      status: 'not_evaluated',
+      reason: `Missing evidence at path: ${check.path}`,
+    };
+  }
+
+  return evaluateOp(check.operator, value, check.value, check);
+}
+
+function evaluateOp(operator, actual, expected, check) {
+  let passed;
+  switch (operator) {
+    case 'exists':
+      passed = actual !== undefined && actual !== null;
+      break;
+    case 'eq':
+      passed = actual === expected;
+      break;
+    case 'lte':
+      passed = typeof actual === 'number' && actual <= expected;
+      break;
+    case 'gte':
+      passed = typeof actual === 'number' && actual >= expected;
+      break;
+    default:
+      return { passed: false, status: 'not_evaluated', reason: `Unknown operator: ${operator}` };
+  }
+
+  if (passed) {
+    return { passed: true, status: null, reason: '' };
+  }
+
+  const status = check.on_fail || 'fail';
+  // Use distinct reason for not_evaluated vs failure to avoid confusing audit consumers.
+  // "reason" is the failure message; "not_evaluated_reason" explains why evidence was insufficient.
+  const reason = status === 'not_evaluated'
+    ? (check.not_evaluated_reason || `Evidence insufficient: ${check.path} ${operator} ${expected} (actual: ${actual})`)
+    : (check.reason || `Check failed: ${check.path} ${operator} ${expected} (actual: ${actual})`);
+
+  return { passed: false, status, reason };
+}
+
 /**
  * Check if actual grade is worse than threshold.
  * Missing/null grade → treated as F (worst case).
@@ -18,14 +143,11 @@ function gradeIsWorse(actual, threshold) {
  * 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
+ * @param {object} evidence - Legacy evidence shape (aivssPosture, findings, grades, toolsRun)
+ * @param {object} [evidenceBundle] - Full evidence bundle for evidence_checks evaluation
  * @returns {{ control_id: string, status: string, reasons: string[] }}
  */
-export function evaluateControl(control, evidence) {
+export function evaluateControl(control, evidence, evidenceBundle) {
   if (!control || !control.id || !control.evaluation) {
     return {
       control_id: control?.id || 'unknown',
@@ -123,6 +245,24 @@ export function evaluateControl(control, evidence) {
     }
   }
 
+  // 7. Run evidence_checks (generic path-based checks, used by SOC2/GDPR controls)
+  if (Array.isArray(ev.evidence_checks) && evidenceBundle) {
+    for (const check of ev.evidence_checks) {
+      const result = runEvidenceCheck(check, evidenceBundle);
+      if (!result.passed) {
+        if (result.status === 'not_evaluated') {
+          // If we haven't already failed/passed via legacy checks, mark not_evaluated
+          if (status === 'pass') status = 'not_evaluated';
+        } else if (result.status === 'fail') {
+          status = 'fail';
+        } else if (result.status === 'partial' && status !== 'fail') {
+          status = 'partial';
+        }
+        if (result.reason) reasons.push(result.reason);
+      }
+    }
+  }
+
   return { control_id: control.id, status, reasons };
 }
 
@@ -130,11 +270,12 @@ export function evaluateControl(control, evidence) {
  * Evaluate all controls against evidence.
  *
  * @param {object[]} controls - Array of controls from registry
- * @param {object} evidence - Same shape as evaluateControl
+ * @param {object} evidence - Legacy evidence shape
+ * @param {object} [evidenceBundle] - Full evidence bundle for evidence_checks
  * @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));
+export function evaluateAll(controls, evidence, evidenceBundle) {
+  const results = controls.map(c => evaluateControl(c, evidence, evidenceBundle));
 
   const summary = { pass: 0, partial: 0, fail: 0, not_evaluated: 0 };
   for (const r of results) {