agent-security-scanner-mcp 4.1.0 → 4.2.0

package/src/lib/osv-client.js

@@ -0,0 +1,254 @@
+// OSV.dev API client for vulnerability enrichment.
+// M1 scope: OSV only. NVD/GHSA as future providers.
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { buildPurl } from './purl.js';
+
+const OSV_BATCH_URL = 'https://api.osv.dev/v1/querybatch';
+const BATCH_SIZE = 1000;
+const FETCH_TIMEOUT = 30000;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+/**
+ * Query OSV.dev for vulnerabilities affecting a list of packages.
+ * Accepts normalized components (with purl, namespace) to avoid lossy flattening.
+ * Uses local cache to avoid redundant network calls.
+ * @param {Array<{ name: string, version: string, ecosystem: string, purl?: string, namespace?: string }>} packages
+ * @param {{ cacheDir?: string }} [options={}]
+ * @returns {Promise<Map<string, object[]>>} Map of cacheKey → vulnerability list
+ */
+export async function queryBatch(packages, options = {}) {
+  const { cacheDir } = options;
+  const results = new Map();
+  const uncached = [];
+
+  // Check cache first
+  for (const pkg of packages) {
+    const cacheKey = getPackageIdentity(pkg);
+    const cached = readCache(cacheDir, cacheKey);
+    if (cached !== null) {
+      if (cached.length > 0) results.set(cacheKey, cached);
+      continue;
+    }
+    uncached.push(pkg);
+  }
+
+  if (uncached.length === 0) return results;
+
+  // Map ecosystem names to OSV ecosystem names
+  const ecosystemMap = {
+    npm: 'npm',
+    pypi: 'PyPI',
+    rubygems: 'RubyGems',
+    crates: 'crates.io',
+    go: 'Go',
+    java: 'Maven',
+    dart: 'Pub',
+  };
+
+  // Batch into chunks of BATCH_SIZE
+  for (let i = 0; i < uncached.length; i += BATCH_SIZE) {
+    const chunk = uncached.slice(i, i + BATCH_SIZE);
+    const queries = chunk.map(pkg => ({
+      package: {
+        name: pkg.ecosystem === 'java' && pkg.namespace
+          ? `${pkg.namespace}:${pkg.name}` : pkg.name,
+        ecosystem: ecosystemMap[pkg.ecosystem] || pkg.ecosystem,
+      },
+      version: pkg.version,
+    }));
+
+    try {
+      const response = await fetchWithRetry(OSV_BATCH_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ queries }),
+      });
+
+      if (!response.ok) continue;
+
+      const data = await response.json();
+      const batchResults = data.results || [];
+
+      for (let j = 0; j < chunk.length; j++) {
+        const pkg = chunk[j];
+        const cacheKey = getPackageIdentity(pkg);
+        const vulns = (batchResults[j] && batchResults[j].vulns) || [];
+        const mapped = vulns.map(v => mapOsvVulnerability(v, pkg));
+
+        writeCache(cacheDir, cacheKey, mapped);
+        if (mapped.length > 0) results.set(cacheKey, mapped);
+      }
+    } catch {
+      // Network error — skip this batch, don't cache
+    }
+  }
+
+  return results;
+}
+
+async function fetchWithRetry(url, options, retries = 1) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+
+  try {
+    const response = await fetch(url, { ...options, signal: controller.signal });
+    clearTimeout(timeout);
+    if (response.status === 429 && retries > 0) {
+      await new Promise(r => setTimeout(r, 2000));
+      return fetchWithRetry(url, options, retries - 1);
+    }
+    return response;
+  } catch (err) {
+    clearTimeout(timeout);
+    if (retries > 0) {
+      await new Promise(r => setTimeout(r, 1000));
+      return fetchWithRetry(url, options, retries - 1);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Map an OSV vulnerability to CycloneDX vulnerability format.
+ */
+function mapOsvVulnerability(osvEntry, pkg) {
+  const cveId = (osvEntry.aliases || []).find(a => a.startsWith('CVE-')) || osvEntry.id;
+  const severity = extractSeverity(osvEntry);
+  const fixedVersion = extractFixedVersion(osvEntry, pkg);
+
+  return {
+    id: cveId,
+    source: { name: 'OSV', url: `https://osv.dev/vulnerability/${osvEntry.id}` },
+    ratings: [{
+      score: severity.score,
+      severity: severity.level,
+      method: severity.method || 'other',
+    }],
+    description: osvEntry.summary || osvEntry.details || '',
+    affects: [{
+      ref: getPackageIdentity(pkg),
+    }],
+    ...(fixedVersion && {
+      recommendation: `Upgrade to ${fixedVersion}`,
+    }),
+    properties: [
+      { name: 'osv:id', value: osvEntry.id },
+      ...(osvEntry.aliases || []).filter(a => a !== cveId).map(a => ({ name: 'alias', value: a })),
+    ],
+  };
+}
+
+function getPackageIdentity(pkg) {
+  if (pkg.purl) return pkg.purl;
+
+  const purl = buildPurl(pkg.ecosystem, pkg.name, pkg.version, pkg.namespace);
+  if (purl) return purl;
+
+  if (pkg.namespace) {
+    return `${pkg.ecosystem}:${pkg.namespace}:${pkg.name}@${pkg.version}`;
+  }
+  return `${pkg.ecosystem}:${pkg.name}@${pkg.version}`;
+}
+
+function extractSeverity(osvEntry) {
+  // Try CVSS from severity array
+  if (osvEntry.severity && osvEntry.severity.length > 0) {
+    for (const sev of osvEntry.severity) {
+      if (sev.type === 'CVSS_V3') {
+        const score = parseCvssScore(sev.score);
+        if (score !== null) {
+          return { score, level: scoreToLevel(score), method: 'CVSSv3' };
+        }
+      }
+    }
+  }
+  // Try database_specific
+  if (osvEntry.database_specific && osvEntry.database_specific.severity) {
+    const level = osvEntry.database_specific.severity.toLowerCase();
+    return { score: levelToScore(level), level, method: 'other' };
+  }
+  return { score: 0, level: 'unknown', method: 'other' };
+}
+
+function parseCvssScore(cvssString) {
+  if (typeof cvssString === 'number') return cvssString;
+  // CVSS vector strings don't contain the score directly; try to extract from a numeric prefix
+  const num = parseFloat(cvssString);
+  return isNaN(num) ? null : num;
+}
+
+/**
+ * Map CVSS score to severity level.
+ * @param {number} score
+ * @returns {string}
+ */
+export function scoreToLevel(score) {
+  if (score >= 9.0) return 'critical';
+  if (score >= 7.0) return 'high';
+  if (score >= 4.0) return 'medium';
+  if (score > 0) return 'low';
+  return 'unknown';
+}
+
+function levelToScore(level) {
+  switch (level) {
+    case 'critical': return 9.5;
+    case 'high': return 7.5;
+    case 'medium': return 5.0;
+    case 'moderate': return 5.0;
+    case 'low': return 2.5;
+    default: return 0;
+  }
+}
+
+function extractFixedVersion(osvEntry, pkg) {
+  if (!osvEntry.affected) return null;
+  for (const affected of osvEntry.affected) {
+    if (affected.package && affected.package.name === pkg.name) {
+      for (const range of affected.ranges || []) {
+        for (const event of range.events || []) {
+          if (event.fixed) return event.fixed;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// ─── Local cache ─────────────────────────────────────────────────────
+
+function getCachePath(cacheDir, key) {
+  if (!cacheDir) return null;
+  // Sanitize key for filesystem
+  const safe = key.replace(/[^a-zA-Z0-9@._-]/g, '_');
+  return join(cacheDir, `${safe}.json`);
+}
+
+function readCache(cacheDir, key) {
+  const path = getCachePath(cacheDir, key);
+  if (!path || !existsSync(path)) return null;
+
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf-8'));
+    if (Date.now() - data.timestamp > CACHE_TTL_MS) return null; // expired
+    return data.vulns;
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(cacheDir, key, vulns) {
+  const path = getCachePath(cacheDir, key);
+  if (!path) return;
+
+  try {
+    if (!existsSync(cacheDir)) {
+      mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+    }
+    writeFileSync(path, JSON.stringify({ timestamp: Date.now(), vulns }, null, 2), { mode: 0o600 });
+  } catch {
+    // Cache write failure is non-fatal
+  }
+}

package/src/lib/purl.js

@@ -0,0 +1,90 @@
+// Package URL (PURL) builder — https://github.com/package-url/purl-spec
+
+const ECOSYSTEM_TO_PURL_TYPE = {
+  npm: 'npm',
+  pypi: 'pypi',
+  rubygems: 'gem',
+  crates: 'cargo',
+  go: 'golang',
+  java: 'maven',
+  dart: 'pub',
+  perl: 'cpan',
+  raku: 'cpan',
+};
+
+const PURL_TYPE_TO_ECOSYSTEM = {
+  npm: 'npm',
+  pypi: 'pypi',
+  gem: 'rubygems',
+  cargo: 'crates',
+  golang: 'go',
+  maven: 'java',
+  pub: 'dart',
+  cpan: 'perl',
+};
+
+/**
+ * Build a Package URL string.
+ * @param {string} ecosystem - Internal ecosystem name (npm, pypi, etc.)
+ * @param {string} name - Package name
+ * @param {string} [version] - Package version
+ * @param {string} [namespace] - Optional namespace (e.g. Maven groupId)
+ * @returns {string} PURL string like pkg:npm/express@4.18.2
+ */
+export function buildPurl(ecosystem, name, version, namespace) {
+  const type = ECOSYSTEM_TO_PURL_TYPE[ecosystem] || ecosystem;
+  if (!name) return '';
+
+  let qualifiedName;
+
+  if (type === 'npm' && name.startsWith('@')) {
+    // Scoped npm: @scope/name → namespace=scope, name=name
+    const [scope, pkg] = name.split('/');
+    qualifiedName = `${encodeURIComponent(scope)}/${pkg}`;
+  } else if (type === 'maven' && namespace) {
+    qualifiedName = `${namespace}/${name}`;
+  } else if (type === 'golang') {
+    // Go modules use the full module path as-is
+    qualifiedName = name;
+  } else {
+    qualifiedName = name;
+  }
+
+  return version
+    ? `pkg:${type}/${qualifiedName}@${version}`
+    : `pkg:${type}/${qualifiedName}`;
+}
+
+/**
+ * Parse a PURL string back into components.
+ * @param {string} purl
+ * @returns {{ type: string, namespace?: string, name: string, version?: string } | null}
+ */
+export function parsePurl(purl) {
+  const match = purl.match(/^pkg:([^/]+)\/(.+?)(?:@(.+))?$/);
+  if (!match) return null;
+
+  const [, type, qualifiedName, version] = match;
+  const slashIdx = qualifiedName.lastIndexOf('/');
+
+  if (slashIdx !== -1) {
+    return {
+      type,
+      namespace: decodeURIComponent(qualifiedName.slice(0, slashIdx)),
+      name: qualifiedName.slice(slashIdx + 1),
+      ...(version && { version }),
+    };
+  }
+
+  return {
+    type,
+    name: qualifiedName,
+    ...(version && { version }),
+  };
+}
+
+export function ecosystemFromPurlType(type) {
+  return PURL_TYPE_TO_ECOSYSTEM[type] || type;
+}
+
+export { ECOSYSTEM_TO_PURL_TYPE, PURL_TYPE_TO_ECOSYSTEM };

package/src/lib/sbom-component.js

@@ -0,0 +1,88 @@
+// Normalized SBOM component model — decoupled from any output format.
+// CycloneDX, SPDX, and all tools operate on this model.
+
+import { buildPurl, parsePurl, ecosystemFromPurlType } from './purl.js';
+
+/**
+ * Create a normalized component.
+ * @param {{ name: string, version?: string, ecosystem: string, isDev?: boolean, isDirect?: boolean, scope?: string, namespace?: string }} opts
+ * @returns {{ name: string, version: string, ecosystem: string, isDev: boolean, isDirect: boolean, scope: string, purl: string, namespace?: string }}
+ */
+export function createComponent({ name, version, ecosystem, isDev = false, isDirect = false, scope, namespace }) {
+  return {
+    name,
+    version: version || 'unknown',
+    ecosystem,
+    isDev,
+    isDirect,
+    scope: scope || (isDev ? 'optional' : 'required'),
+    purl: buildPurl(ecosystem, name, version, namespace),
+    ...(namespace && { namespace }),
+  };
+}
+
+/**
+ * Create a dependency edge between two components.
+ * @param {string} fromPurl - PURL of the dependent
+ * @param {string} toPurl - PURL of the dependency
+ * @returns {{ from: string, to: string }}
+ */
+export function createEdge(fromPurl, toPurl) {
+  return { from: fromPurl, to: toPurl };
+}
+
+/**
+ * Create a component list with metadata and dependency graph.
+ * @param {object[]} components - Array of normalized components
+ * @param {object[]} [edges=[]] - Array of dependency edges
+ * @param {{ name?: string, version?: string, ecosystems?: string[] }} [metadata={}]
+ * @returns {{ components: object[], edges: object[], metadata: object }}
+ */
+export function createComponentList(components = [], edges = [], metadata = {}) {
+  const ecosystems = [...new Set(components.map(c => c.ecosystem))];
+  return {
+    components,
+    edges,
+    metadata: {
+      name: metadata.name || 'unknown',
+      version: metadata.version || '0.0.0',
+      ecosystems,
+      total: components.length,
+      direct: components.filter(c => c.isDirect).length,
+      dev: components.filter(c => c.isDev).length,
+      ...metadata,
+    },
+  };
+}
+
+function getPropertyValue(component, name) {
+  return component.properties?.find(p => p.name === name)?.value;
+}
+
+/**
+ * Reconstruct a normalized component from a CycloneDX component entry.
+ * Preserves canonical PURL identity and Maven group when present.
+ * @param {object} component
+ * @returns {{ name: string, version: string, ecosystem: string, isDev: boolean, isDirect: boolean, scope: string, purl: string, namespace?: string }}
+ */
+export function componentFromBomComponent(component) {
+  const parsed = component.purl ? parsePurl(component.purl) : null;
+  const ecosystem = getPropertyValue(component, 'cdx:ecosystem')
+    || (parsed ? ecosystemFromPurlType(parsed.type) : 'unknown');
+  const namespace = component.group || parsed?.namespace;
+  const name = parsed?.name || component.name;
+  const version = parsed?.version || component.version || 'unknown';
+  const isDev = getPropertyValue(component, 'cdx:development') === 'true';
+  const purl = component.purl || buildPurl(ecosystem, name, version, namespace);
+
+  return {
+    name,
+    version,
+    ecosystem,
+    isDev,
+    isDirect: false,
+    scope: component.scope || (isDev ? 'optional' : 'required'),
+    purl,
+    ...(namespace && { namespace }),
+  };
+}

package/src/tools/compliance-controls.js

@@ -1,31 +1,35 @@
 // src/tools/compliance-controls.js — get_compliance_controls MCP tool (thin wrapper)
 
 import { z } from 'zod';
-import { loadControls, filterControls } from '../lib/compliance-controls.js';
+import { loadControls, filterControls, listFrameworks } from '../lib/compliance-controls.js';
 
 export const complianceControlsSchema = {
-  domain: z.enum(['security', 'safety', 'all']).optional().describe("Filter by domain"),
+  framework: z.string().optional().describe("Framework to query (default: aiuc-1). Use 'soc2-technical', 'gdpr-technical', etc."),
+  domain: z.string().optional().describe("Filter by domain (e.g. 'security', 'safety', 'all'). Accepted values depend on the framework."),
   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 }) {
+export async function getComplianceControls({ framework, domain, control_ids, owasp_filter, verbosity }) {
+  const fw = framework || 'aiuc-1';
   const level = verbosity || 'compact';
 
   const controls = filterControls({
+    framework: fw,
     domain: domain || 'all',
     controlIds: control_ids,
     owaspFilter: owasp_filter,
   });
 
-  const registry = loadControls();
+  const registry = loadControls(fw);
 
   let output;
   switch (level) {
     case 'minimal':
       output = {
         framework: registry.framework,
+        domains: registry.domains,
         controls_count: controls.length,
         controls: controls.map(c => ({ id: c.id, title: c.title, domain: c.domain })),
       };
@@ -37,6 +41,8 @@ export async function getComplianceControls({ domain, control_ids, owasp_filter,
         schema_version: registry.schema_version,
         source: registry.source,
         source_snapshot: registry.source_snapshot,
+        domains: registry.domains,
+        available_frameworks: listFrameworks(),
         controls_count: controls.length,
         controls,
       };
@@ -47,14 +53,18 @@ export async function getComplianceControls({ domain, control_ids, owasp_filter,
       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,
-        })),
+        controls: controls.map(c => {
+          const out = {
+            id: c.id,
+            title: c.title,
+            domain: c.domain,
+            scanner_tools: c.scanner_tools,
+            evaluation: c.evaluation,
+          };
+          if (c.owasp_llm) out.owasp_llm = c.owasp_llm;
+          if (c.references) out.references = c.references;
+          return out;
+        }),
       };
   }
 

package/src/tools/evaluate-compliance.js

@@ -0,0 +1,161 @@
+// src/tools/evaluate-compliance.js — evaluate_compliance MCP tool.
+// Collects evidence from scan + SBOM, evaluates controls per framework, persists optionally.
+
+import { z } from 'zod';
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { collectEvidence, buildEvaluatorEvidence } from '../lib/compliance-evidence.js';
+import { loadControls } from '../lib/compliance-controls.js';
+import { evaluateAll } from '../lib/compliance-evaluator.js';
+function formatTimestamp(date) {
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}-${pad(date.getMinutes())}-${pad(date.getSeconds())}`;
+}
+
+export const evaluateComplianceSchema = {
+  directory_path: z.string().describe('Path to project root directory to evaluate'),
+  frameworks: z.array(z.string()).optional()
+    .describe('Compliance frameworks to evaluate (default: ["aiuc-1"]). Options: aiuc-1, soc2-technical, gdpr-technical'),
+  sbom_path: z.string().optional().describe('Path to existing SBOM file (skips SBOM generation)'),
+  baseline_path: z.string().optional().describe('Path to SBOM baseline file for drift comparison'),
+  save_evidence: z.boolean().optional().describe('Save evidence bundle to .scanner/evidence/ (default: false)'),
+  verbosity: z.enum(['minimal', 'compact', 'full']).optional().describe('Response detail level (default: compact)'),
+};
+
+export async function evaluateCompliance({ directory_path, frameworks, sbom_path, baseline_path, save_evidence, verbosity }) {
+  if (!existsSync(directory_path)) {
+    return error(`Directory not found: ${directory_path}`);
+  }
+
+  const fws = (frameworks && frameworks.length > 0) ? frameworks : ['aiuc-1'];
+  const level = verbosity || 'compact';
+
+  // Collect evidence once, evaluate against all requested frameworks
+  let bundle;
+  try {
+    bundle = await collectEvidence({
+      directory: directory_path,
+      sbomPath: sbom_path,
+      baselinePath: baseline_path,
+      toolVersion: process.env.npm_package_version || 'unknown',
+      verbosity: level,
+    });
+  } catch (err) {
+    return error(`Evidence collection failed: ${err.message}`);
+  }
+
+  // Add requested frameworks to metadata
+  bundle.metadata.frameworks = fws;
+
+  // Build legacy evaluator evidence (for AIUC-1 backward compat)
+  const legacyEvidence = buildEvaluatorEvidence(bundle);
+
+  // Evaluate each framework
+  const frameworkResults = [];
+  for (const fw of fws) {
+    try {
+      const registry = loadControls(fw);
+      const result = evaluateAll(registry.controls, legacyEvidence, bundle);
+      frameworkResults.push({
+        framework: registry.framework,
+        controls_evaluated: result.controls_evaluated,
+        summary: {
+          pass: result.pass,
+          partial: result.partial,
+          fail: result.fail,
+          not_evaluated: result.not_evaluated,
+        },
+        results: result.results,
+      });
+    } catch (err) {
+      frameworkResults.push({
+        framework: fw,
+        error: err.message,
+      });
+    }
+  }
+
+  // Persist evidence if requested
+  let savedPath = null;
+  if (save_evidence) {
+    try {
+      const evidenceDir = join(directory_path, '.scanner', 'evidence');
+      if (!existsSync(evidenceDir)) {
+        mkdirSync(evidenceDir, { recursive: true, mode: 0o700 });
+      }
+      const filename = `${formatTimestamp(new Date())}.json`;
+      savedPath = join(evidenceDir, filename);
+      const persistBundle = {
+        ...bundle,
+        compliance: frameworkResults,
+      };
+      writeFileSync(savedPath, JSON.stringify(persistBundle, null, 2), { encoding: 'utf-8', mode: 0o600 });
+    } catch (err) {
+      // Non-fatal — report but don't fail
+      if (!bundle.errors) bundle.errors = [];
+      bundle.errors.push({ source: 'evidence_persist', message: err.message });
+    }
+  }
+
+  // Build response based on verbosity
+  let response;
+  switch (level) {
+    case 'minimal':
+      response = {
+        directory: directory_path,
+        tools_run: bundle.tools_run,
+        compliance: frameworkResults.map(r => ({
+          framework: r.framework,
+          summary: r.summary || null,
+          error: r.error || undefined,
+        })),
+        ...(savedPath && { evidence_saved: savedPath }),
+      };
+      break;
+
+    case 'full':
+      response = {
+        evidence: bundle,
+        compliance: frameworkResults,
+        ...(savedPath && { evidence_saved: savedPath }),
+      };
+      break;
+
+    case 'compact':
+    default:
+      response = {
+        directory: directory_path,
+        tools_run: bundle.tools_run,
+        errors: bundle.errors || undefined,
+        scan_summary: bundle.scan ? {
+          grade: bundle.scan.grade,
+          by_severity: bundle.scan.by_severity,
+        } : null,
+        sbom_summary: bundle.sbom ? {
+          component_count: bundle.sbom.component_count,
+          ecosystems: bundle.sbom.ecosystems,
+        } : null,
+        supply_chain: bundle.supply_chain.vulnerabilities || bundle.supply_chain.hallucinations ? {
+          vulnerabilities: bundle.supply_chain.vulnerabilities ? {
+            total: bundle.supply_chain.vulnerabilities.total,
+            by_severity: bundle.supply_chain.vulnerabilities.by_severity,
+          } : null,
+          hallucinations: bundle.supply_chain.hallucinations ? {
+            hallucinated_count: bundle.supply_chain.hallucinations.hallucinated_count,
+          } : null,
+          drift: bundle.supply_chain.drift,
+        } : null,
+        compliance: frameworkResults,
+        ...(savedPath && { evidence_saved: savedPath }),
+      };
+      break;
+  }
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+  };
+}
+
+function error(msg) {
+  return { content: [{ type: 'text', text: JSON.stringify({ error: msg }) }] };
+}