@weave_protocol/mund 0.2.3 → 0.3.1

package/src/osv.ts

@@ -0,0 +1,310 @@
+/**
+ * Mund - The Guardian Protocol
+ * OSV.dev dependency vulnerability lookups with an offline fallback
+ *
+ * Live path: POST /v1/querybatch for every name@version in a lockfile,
+ * then GET /v1/vulns/{id} once per unique advisory for details.
+ *
+ * Offline path: every successful live lookup is written to an on-disk
+ * cache. When the network is unavailable (or MUND_OFFLINE=1 / --offline),
+ * results come from that cache and are reported with source "cache", so
+ * callers can tell a clean result from an unchecked one. Packages that
+ * were never looked up are reported as unchecked, never as clean.
+ */
+
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import type { SecurityIssue, Severity } from './types.js';
+
+const OSV_API = 'https://api.osv.dev/v1';
+const BATCH_SIZE = 1000;
+const DETAIL_CONCURRENCY = 8;
+
+export interface LockedPackage {
+  name: string;
+  version: string;
+  /** Lockfile key, e.g. "node_modules/qs", used to locate the finding. */
+  path?: string;
+}
+
+export interface OsvAdvisory {
+  id: string;
+  summary: string;
+  severity: Severity;
+  aliases: string[];
+  fixed?: string;
+  url: string;
+}
+
+export type OsvSource = 'live' | 'cache' | 'unavailable';
+
+export interface OsvLookupResult {
+  source: OsvSource;
+  /** Keyed by "name@version". */
+  advisories: Map<string, OsvAdvisory[]>;
+  /** name@version keys with no live or cached answer. */
+  unchecked: string[];
+  /** Why the live lookup did not run or failed, if it didn't. */
+  error?: string;
+}
+
+export interface OsvClientOptions {
+  offline?: boolean;
+  cachePath?: string;
+  timeoutMs?: number;
+  fetch?: typeof fetch;
+}
+
+interface CacheFile {
+  version: 1;
+  packages: Record<string, { checkedAt: string; advisories: OsvAdvisory[] }>;
+}
+
+interface OsvVuln {
+  id: string;
+  summary?: string;
+  details?: string;
+  aliases?: string[];
+  severity?: Array<{ type: string; score: string }>;
+  database_specific?: { severity?: string };
+  affected?: Array<{
+    package?: { name: string; ecosystem: string };
+    ranges?: Array<{ events: Array<{ introduced?: string; fixed?: string }> }>;
+  }>;
+}
+
+export function defaultCachePath(): string {
+  if (process.env.MUND_OSV_CACHE) return process.env.MUND_OSV_CACHE;
+  const base = process.env.XDG_CACHE_HOME || join(homedir(), '.cache');
+  return join(base, 'mund', 'osv-cache.json');
+}
+
+// ============================================================================
+// Lockfile parsing
+// ============================================================================
+
+/** Parse an npm package-lock.json (lockfileVersion 1, 2 or 3). */
+export function parseNpmLockfile(content: string): LockedPackage[] {
+  const lock = JSON.parse(content) as {
+    packages?: Record<string, { version?: string; name?: string; link?: boolean }>;
+    dependencies?: Record<string, V1Dep>;
+  };
+  const seen = new Map<string, LockedPackage>();
+  const add = (pkg: LockedPackage) => {
+    const key = `${pkg.name}@${pkg.version}`;
+    if (!seen.has(key)) seen.set(key, pkg);
+  };
+
+  if (lock.packages) {
+    for (const [path, entry] of Object.entries(lock.packages)) {
+      if (!path || entry.link || !entry.version) continue;
+      const idx = path.lastIndexOf('node_modules/');
+      if (idx === -1) continue; // workspace package, not a dependency
+      add({ name: entry.name ?? path.slice(idx + 'node_modules/'.length), version: entry.version, path });
+    }
+  } else if (lock.dependencies) {
+    const walk = (deps: Record<string, V1Dep>) => {
+      for (const [name, dep] of Object.entries(deps)) {
+        if (dep.version && !dep.version.startsWith('file:')) add({ name, version: dep.version });
+        if (dep.dependencies) walk(dep.dependencies);
+      }
+    };
+    walk(lock.dependencies);
+  }
+
+  return [...seen.values()];
+}
+
+interface V1Dep {
+  version?: string;
+  dependencies?: Record<string, V1Dep>;
+}
+
+// ============================================================================
+// Client
+// ============================================================================
+
+export class OsvClient {
+  private readonly offline: boolean;
+  private readonly cachePath: string;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(options: OsvClientOptions = {}) {
+    this.offline = options.offline ?? process.env.MUND_OFFLINE === '1';
+    this.cachePath = options.cachePath ?? defaultCachePath();
+    this.timeoutMs = options.timeoutMs ?? 15000;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+
+  async lookup(packages: LockedPackage[], ecosystem = 'npm'): Promise<OsvLookupResult> {
+    const keys = packages.map(p => `${p.name}@${p.version}`);
+    if (packages.length === 0) return { source: 'live', advisories: new Map(), unchecked: [] };
+
+    if (!this.offline) {
+      try {
+        const advisories = await this.lookupLive(packages, ecosystem);
+        await this.writeCache(advisories);
+        return { source: 'live', advisories, unchecked: [] };
+      } catch (error) {
+        return this.lookupCached(keys, `OSV.dev unreachable: ${(error as Error).message}`);
+      }
+    }
+    return this.lookupCached(keys, 'offline mode');
+  }
+
+  private async lookupLive(packages: LockedPackage[], ecosystem: string): Promise<Map<string, OsvAdvisory[]>> {
+    const idsByKey = new Map<string, string[]>();
+
+    for (let i = 0; i < packages.length; i += BATCH_SIZE) {
+      const chunk = packages.slice(i, i + BATCH_SIZE);
+      const body = { queries: chunk.map(p => ({ package: { name: p.name, ecosystem }, version: p.version })) };
+      const data = await this.request<{ results: Array<{ vulns?: Array<{ id: string }> }> }>(
+        `${OSV_API}/querybatch`, { method: 'POST', body: JSON.stringify(body) },
+      );
+      chunk.forEach((p, j) => {
+        idsByKey.set(`${p.name}@${p.version}`, (data.results[j]?.vulns ?? []).map(v => v.id));
+      });
+    }
+
+    const uniqueIds = [...new Set([...idsByKey.values()].flat())];
+    const details = new Map<string, OsvVuln>();
+    for (let i = 0; i < uniqueIds.length; i += DETAIL_CONCURRENCY) {
+      const batch = uniqueIds.slice(i, i + DETAIL_CONCURRENCY);
+      const fetched = await Promise.all(batch.map(id => this.request<OsvVuln>(`${OSV_API}/vulns/${encodeURIComponent(id)}`)));
+      fetched.forEach(v => details.set(v.id, v));
+    }
+
+    const advisories = new Map<string, OsvAdvisory[]>();
+    for (const [key, ids] of idsByKey) {
+      const name = key.slice(0, key.lastIndexOf('@'));
+      advisories.set(key, ids.map(id => toAdvisory(details.get(id) ?? { id }, name)));
+    }
+    return advisories;
+  }
+
+  private async lookupCached(keys: string[], reason: string): Promise<OsvLookupResult> {
+    const cache = await this.readCache();
+    const advisories = new Map<string, OsvAdvisory[]>();
+    const unchecked: string[] = [];
+
+    for (const key of keys) {
+      const hit = cache?.packages[key];
+      if (hit) advisories.set(key, hit.advisories);
+      else unchecked.push(key);
+    }
+
+    const source: OsvSource = advisories.size > 0 ? 'cache' : 'unavailable';
+    return { source, advisories, unchecked, error: reason };
+  }
+
+  private async request<T>(url: string, init: RequestInit = {}): Promise<T> {
+    const res = await this.fetchImpl(url, {
+      ...init,
+      headers: { 'Content-Type': 'application/json' },
+      signal: AbortSignal.timeout(this.timeoutMs),
+    });
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText} from ${url}`);
+    return (await res.json()) as T;
+  }
+
+  private async readCache(): Promise<CacheFile | null> {
+    try {
+      const cache = JSON.parse(await readFile(this.cachePath, 'utf8')) as CacheFile;
+      return cache.version === 1 && cache.packages ? cache : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async writeCache(advisories: Map<string, OsvAdvisory[]>): Promise<void> {
+    const cache: CacheFile = (await this.readCache()) ?? { version: 1, packages: {} };
+    const checkedAt = new Date().toISOString();
+    for (const [key, list] of advisories) cache.packages[key] = { checkedAt, advisories: list };
+    try {
+      await mkdir(dirname(this.cachePath), { recursive: true });
+      await writeFile(this.cachePath, JSON.stringify(cache));
+    } catch {
+      // A read-only cache dir shouldn't fail the scan; we just lose the fallback.
+    }
+  }
+}
+
+function toAdvisory(vuln: OsvVuln, packageName: string): OsvAdvisory {
+  let fixed: string | undefined;
+  for (const affected of vuln.affected ?? []) {
+    if (affected.package && affected.package.name !== packageName) continue;
+    for (const range of affected.ranges ?? []) {
+      for (const event of range.events) if (event.fixed) fixed = event.fixed;
+    }
+  }
+
+  return {
+    id: vuln.id,
+    summary: vuln.summary || vuln.details?.split('\n')[0]?.slice(0, 200) || 'No summary available',
+    severity: parseSeverity(vuln),
+    aliases: vuln.aliases ?? [],
+    fixed,
+    url: `https://osv.dev/vulnerability/${encodeURIComponent(vuln.id)}`,
+  };
+}
+
+/**
+ * OSV `severity[].score` is usually a CVSS *vector* string, not a number,
+ * so prefer the database's own label (GHSA sets it for npm advisories).
+ */
+export function parseSeverity(vuln: Pick<OsvVuln, 'severity' | 'database_specific'>): Severity {
+  const label = vuln.database_specific?.severity?.toLowerCase();
+  if (label === 'critical') return 'critical';
+  if (label === 'high') return 'high';
+  if (label === 'moderate' || label === 'medium') return 'medium';
+  if (label === 'low') return 'low';
+
+  for (const s of vuln.severity ?? []) {
+    const score = Number(s.score);
+    if (!Number.isNaN(score)) {
+      if (score >= 9) return 'critical';
+      if (score >= 7) return 'high';
+      if (score >= 4) return 'medium';
+      if (score > 0) return 'low';
+    }
+  }
+  return 'medium';
+}
+
+// ============================================================================
+// Findings
+// ============================================================================
+
+/** Turn lookup results into SecurityIssues located in the lockfile. */
+export function advisoriesToIssues(
+  packages: LockedPackage[],
+  result: OsvLookupResult,
+  lockfileContent: string,
+): SecurityIssue[] {
+  const issues: SecurityIssue[] = [];
+
+  for (const pkg of packages) {
+    const key = `${pkg.name}@${pkg.version}`;
+    for (const adv of result.advisories.get(key) ?? []) {
+      const needle = pkg.path ? `"${pkg.path}"` : `"${pkg.name}"`;
+      const start = Math.max(0, lockfileContent.indexOf(needle));
+      const before = lockfileContent.slice(0, start).split('\n');
+
+      issues.push({
+        rule_id: adv.id,
+        rule_name: `${key}: ${adv.summary}`,
+        type: 'dependency',
+        severity: adv.severity,
+        action: 'alert',
+        match: key,
+        location: { start, end: start + needle.length, line: before.length, column: before[before.length - 1].length + 1 },
+        suggestion: adv.fixed
+          ? `Upgrade ${pkg.name} to ${adv.fixed} or later. ${adv.url}`
+          : `No fixed version published yet. ${adv.url}`,
+      });
+    }
+  }
+  return issues;
+}

package/src/rugpull.ts

@@ -0,0 +1,233 @@
+/**
+ * Mund - The Guardian Protocol
+ * MCP Rug-Pull Detection (OWASP ASI04)
+ *
+ * A rug pull is an MCP server that passes review at install time and
+ * then changes what its tools say or do. Static scanning can't see that,
+ * so Mund records a fingerprint of every tool when a server is first
+ * approved (the baseline) and diffs later manifests against it.
+ *
+ *   tool description changed  -> high   (the classic rug pull)
+ *   tool input schema changed -> medium
+ *   tool added                -> medium
+ *   tool removed              -> low
+ *   server name changed       -> high
+ *
+ * Any changed or added tool is re-scanned with the MCP analyzer; if it
+ * now trips a high/critical finding, or newly gains execution
+ * capability, the change is escalated to critical.
+ */
+
+import { createHash } from 'crypto';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { homedir } from 'os';
+import { dirname, join } from 'path';
+import type { IAnalyzer, SecurityIssue, Severity } from './types.js';
+import { McpServerAnalyzer, type McpServerManifest, type McpToolDefinition } from './analyzers/mcp-server-analyzer.js';
+
+export type ToolChangeKind = 'description_changed' | 'schema_changed' | 'tool_added' | 'tool_removed' | 'server_renamed';
+
+export interface ToolFingerprint {
+  descriptionHash: string;
+  schemaHash: string;
+  /** Kept so a diff can show what the description used to say. */
+  description: string;
+}
+
+export interface ManifestBaseline {
+  serverId: string;
+  serverName: string;
+  recordedAt: string;
+  tools: Record<string, ToolFingerprint>;
+}
+
+export interface ToolChange {
+  kind: ToolChangeKind;
+  tool: string;
+  severity: Severity;
+  detail: string;
+  /** Set when the changed tool now trips the MCP analyzer or gains execution capability. */
+  escalated?: string;
+}
+
+export interface RugPullResult {
+  serverId: string;
+  status: 'baseline_created' | 'unchanged' | 'changed';
+  changes: ToolChange[];
+  baselineRecordedAt?: string;
+}
+
+const SEVERITY_RANK: Record<Severity, number> = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+
+export function defaultBaselinePath(): string {
+  if (process.env.MUND_BASELINE_PATH) return process.env.MUND_BASELINE_PATH;
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'mund', 'mcp-baselines.json');
+}
+
+/** Stable JSON: object keys sorted so equivalent schemas hash the same. */
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(',')}}`;
+  }
+  return JSON.stringify(value ?? null);
+}
+
+const sha256 = (s: string) => createHash('sha256').update(s).digest('hex');
+
+export function fingerprintManifest(serverId: string, manifest: McpServerManifest): ManifestBaseline {
+  const tools: Record<string, ToolFingerprint> = {};
+  for (const tool of manifest.tools ?? []) {
+    tools[tool.name] = {
+      descriptionHash: sha256(tool.description ?? ''),
+      schemaHash: sha256(canonical(tool.inputSchema ?? {})),
+      description: (tool.description ?? '').slice(0, 2000),
+    };
+  }
+  return { serverId, serverName: manifest.name ?? serverId, recordedAt: new Date().toISOString(), tools };
+}
+
+/** Compare a manifest against its baseline. Pure: no I/O. */
+export async function diffManifest(
+  baseline: ManifestBaseline,
+  manifest: McpServerManifest,
+  analyzer: IAnalyzer = new McpServerAnalyzer(),
+): Promise<ToolChange[]> {
+  const current = fingerprintManifest(baseline.serverId, manifest);
+  const byName = new Map((manifest.tools ?? []).map(t => [t.name, t]));
+  const changes: ToolChange[] = [];
+
+  if (current.serverName !== baseline.serverName) {
+    changes.push({
+      kind: 'server_renamed', tool: '*', severity: 'high',
+      detail: `Server name changed from "${baseline.serverName}" to "${current.serverName}"`,
+    });
+  }
+
+  for (const [name, now] of Object.entries(current.tools)) {
+    const before = baseline.tools[name];
+    if (!before) {
+      changes.push({ kind: 'tool_added', tool: name, severity: 'medium', detail: `New tool "${name}" not present at baseline` });
+      continue;
+    }
+    if (now.descriptionHash !== before.descriptionHash) {
+      changes.push({
+        kind: 'description_changed', tool: name, severity: 'high',
+        detail: `Description of "${name}" changed after approval`,
+      });
+    }
+    if (now.schemaHash !== before.schemaHash) {
+      changes.push({ kind: 'schema_changed', tool: name, severity: 'medium', detail: `Input schema of "${name}" changed after approval` });
+    }
+  }
+
+  for (const name of Object.keys(baseline.tools)) {
+    if (!current.tools[name]) {
+      changes.push({ kind: 'tool_removed', tool: name, severity: 'low', detail: `Tool "${name}" removed since baseline` });
+    }
+  }
+
+  // Escalate changed/added tools that now look dangerous.
+  for (const change of changes) {
+    if (change.kind === 'tool_removed' || change.kind === 'server_renamed') continue;
+    const tool = byName.get(change.tool);
+    if (!tool) continue;
+    const reason = await escalationReason(tool, baseline.tools[change.tool], analyzer);
+    if (reason) {
+      change.severity = 'critical';
+      change.escalated = reason;
+    }
+  }
+
+  return changes.sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity]);
+}
+
+async function escalationReason(
+  tool: McpToolDefinition,
+  before: ToolFingerprint | undefined,
+  analyzer: IAnalyzer,
+): Promise<string | undefined> {
+  const single = JSON.stringify({ name: 'rugpull-check', tools: [tool] });
+  const findings = await analyzer.analyze(single, []);
+  const serious = findings.find(f => f.severity === 'critical' || f.severity === 'high');
+  if (serious) return `Changed tool now triggers "${serious.rule_name}"`;
+
+  const nowExec = McpServerAnalyzer.analyzeCapabilities({ name: 'x', version: '0', tools: [tool] }).execution;
+  const wasExec = before
+    ? McpServerAnalyzer.analyzeCapabilities({ name: 'x', version: '0', tools: [{ name: tool.name, description: before.description }] }).execution
+    : false;
+  if (nowExec && !wasExec) return 'Tool newly requests command-execution capability';
+  return undefined;
+}
+
+/** Persisted baselines, keyed by server id. */
+export class BaselineStore {
+  constructor(private path: string = defaultBaselinePath()) {}
+
+  async load(): Promise<Record<string, ManifestBaseline>> {
+    try {
+      const data = JSON.parse(await readFile(this.path, 'utf8'));
+      return data && typeof data === 'object' && data.version === 1 ? data.baselines : {};
+    } catch {
+      return {};
+    }
+  }
+
+  async get(serverId: string): Promise<ManifestBaseline | undefined> {
+    return (await this.load())[serverId];
+  }
+
+  async put(baseline: ManifestBaseline): Promise<void> {
+    const all = await this.load();
+    all[baseline.serverId] = baseline;
+    await mkdir(dirname(this.path), { recursive: true });
+    await writeFile(this.path, JSON.stringify({ version: 1, baselines: all }, null, 2));
+  }
+}
+
+/**
+ * Check a manifest against its stored baseline. The first check for a
+ * server records the baseline. Pass acceptChanges to re-baseline after
+ * a human has reviewed the changes.
+ */
+export async function checkRugPull(
+  serverId: string,
+  manifest: McpServerManifest,
+  opts: { store?: BaselineStore; analyzer?: IAnalyzer; acceptChanges?: boolean } = {},
+): Promise<RugPullResult> {
+  const store = opts.store ?? new BaselineStore();
+  const baseline = await store.get(serverId);
+
+  if (!baseline) {
+    await store.put(fingerprintManifest(serverId, manifest));
+    return { serverId, status: 'baseline_created', changes: [] };
+  }
+
+  const changes = await diffManifest(baseline, manifest, opts.analyzer);
+  if (opts.acceptChanges && changes.length > 0) {
+    await store.put(fingerprintManifest(serverId, manifest));
+  }
+  return {
+    serverId,
+    status: changes.length > 0 ? 'changed' : 'unchanged',
+    changes,
+    baselineRecordedAt: baseline.recordedAt,
+  };
+}
+
+/** Express rug-pull changes as standard SecurityIssues (for scoring / SARIF). */
+export function changesToIssues(result: RugPullResult): SecurityIssue[] {
+  return result.changes.map(c => ({
+    rule_id: `mcp_rugpull_${c.kind}`,
+    rule_name: `MCP rug pull: ${c.detail}`,
+    type: 'mcp_rugpull',
+    severity: c.severity,
+    action: c.severity === 'critical' || c.severity === 'high' ? 'block' : 'alert',
+    match: `${result.serverId}:${c.tool}`,
+    suggestion: c.escalated
+      ? `${c.escalated}. Do not use this server until the change is reviewed.`
+      : 'Review the change before continuing to use this server; accept it to update the baseline.',
+  }));
+}

package/src/sarif.ts

@@ -0,0 +1,146 @@
+/**
+ * Mund - The Guardian Protocol
+ * SARIF 2.1.0 output - for GitHub code scanning and other SARIF consumers
+ *
+ * https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+ * GitHub-specific: rules carry `security-severity` (0.0-10.0) so code
+ * scanning ranks alerts as critical/high/medium/low.
+ */
+
+import { createHash } from 'crypto';
+import type { SecurityIssue, Severity } from './types.js';
+import { computeRiskScore } from './scoring.js';
+
+export interface SarifTarget {
+  /** Path relative to the repository root, using forward slashes. */
+  uri: string;
+  issues: SecurityIssue[];
+}
+
+export interface SarifOptions {
+  toolVersion: string;
+  informationUri?: string;
+}
+
+type SarifLevel = 'error' | 'warning' | 'note' | 'none';
+
+const LEVELS: Record<Severity, SarifLevel> = {
+  critical: 'error',
+  high: 'error',
+  medium: 'warning',
+  low: 'note',
+  info: 'note',
+};
+
+/** GitHub maps >=9.0 critical, >=7.0 high, >=4.0 medium, >0.1 low. */
+const SECURITY_SEVERITY: Record<Severity, string> = {
+  critical: '9.5',
+  high: '8.0',
+  medium: '5.5',
+  low: '3.0',
+  info: '0.0',
+};
+
+export function toSarif(targets: SarifTarget[], options: SarifOptions): object {
+  const rules = new Map<string, { issue: SecurityIssue; index: number }>();
+  const results: object[] = [];
+  const allIssues: SecurityIssue[] = [];
+
+  for (const target of targets) {
+    for (const issue of target.issues) {
+      allIssues.push(issue);
+
+      let rule = rules.get(issue.rule_id);
+      if (!rule) {
+        rule = { issue, index: rules.size };
+        rules.set(issue.rule_id, rule);
+      } else if (severityRank(issue.severity) < severityRank(rule.issue.severity)) {
+        // A rule's descriptor takes the worst severity seen for it.
+        rule.issue = issue;
+      }
+
+      results.push({
+        ruleId: issue.rule_id,
+        ruleIndex: rule.index,
+        level: LEVELS[issue.severity] ?? 'warning',
+        message: { text: issue.suggestion ? `${issue.rule_name}. ${issue.suggestion}` : issue.rule_name },
+        locations: [{
+          physicalLocation: {
+            artifactLocation: { uri: target.uri },
+            ...(issue.location?.line ? { region: toRegion(issue) } : {}),
+          },
+        }],
+        partialFingerprints: {
+          'mundFinding/v1': fingerprint(target.uri, issue),
+        },
+        properties: {
+          severity: issue.severity,
+          type: issue.type,
+        },
+      });
+    }
+  }
+
+  const risk = computeRiskScore(allIssues);
+
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [{
+      tool: {
+        driver: {
+          name: 'Mund',
+          fullName: 'Mund - The Guardian Protocol',
+          version: options.toolVersion,
+          semanticVersion: options.toolVersion,
+          informationUri: options.informationUri ?? 'https://github.com/Tyox-all/Weave_Protocol/tree/main/mund',
+          rules: [...rules.values()].map(({ issue }) => ({
+            id: issue.rule_id,
+            name: toPascalCase(issue.rule_name),
+            shortDescription: { text: issue.rule_name },
+            ...(issue.suggestion ? { help: { text: issue.suggestion } } : {}),
+            defaultConfiguration: { level: LEVELS[issue.severity] ?? 'warning' },
+            properties: {
+              'security-severity': SECURITY_SEVERITY[issue.severity] ?? '5.5',
+              tags: ['security', issue.type],
+            },
+          })),
+        },
+      },
+      results,
+      properties: {
+        riskScore: risk.score,
+        riskLabel: risk.label,
+      },
+    }],
+  };
+}
+
+function toRegion(issue: SecurityIssue): object {
+  const loc = issue.location!;
+  const region: Record<string, number> = { startLine: loc.line! };
+  if (loc.column) {
+    region.startColumn = loc.column;
+    const length = loc.end - loc.start;
+    // Only emit endColumn for single-line matches; multi-line spans would
+    // need the source text to compute endLine.
+    if (length > 0 && !issue.match.includes('\n')) region.endColumn = loc.column + length;
+  }
+  return region;
+}
+
+function fingerprint(uri: string, issue: SecurityIssue): string {
+  return createHash('sha256')
+    .update(`${uri}\0${issue.rule_id}\0${issue.location?.line ?? 0}\0${issue.match}`)
+    .digest('hex')
+    .slice(0, 32);
+}
+
+function severityRank(severity: Severity): number {
+  return ['critical', 'high', 'medium', 'low', 'info'].indexOf(severity);
+}
+
+function toPascalCase(text: string): string {
+  return text.replace(/[^A-Za-z0-9]+(.)?/g, (_, c: string | undefined) => (c ? c.toUpperCase() : ''))
+    .replace(/^./, c => c.toUpperCase());
+}