@complior/engine 0.9.0

package/src/domain/scanner/evidence-store.ts

@@ -0,0 +1,195 @@
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import type { Evidence } from './evidence.js';
+import type { EvidenceEntry, EvidenceChain } from '../../types/common.types.js';
+import { parseEvidenceChain } from '../../types/common.schemas.js';
+
+export interface EvidenceChainSummary {
+  readonly totalEntries: number;
+  readonly scanCount: number;
+  readonly firstEntry: string;
+  readonly lastEntry: string;
+  readonly chainValid: boolean;
+  readonly uniqueFindings: number;
+}
+
+export interface EvidenceStore {
+  readonly append: (evidence: readonly Evidence[], scanId: string) => Promise<void>;
+  readonly getChain: () => Promise<EvidenceChain>;
+  readonly verify: () => Promise<{ valid: boolean; brokenAt?: number }>;
+  readonly getSummary: () => Promise<EvidenceChainSummary>;
+}
+
+// --- Helpers ---
+
+const computeHash = (evidence: Evidence, scanId: string, chainPrev: string | null): string => {
+  const payload = JSON.stringify({ evidence, scanId, chainPrev });
+  return createHash('sha256').update(payload).digest('hex');
+};
+
+const EMPTY_CHAIN = (projectPath: string): EvidenceChain => ({
+  version: '1.0.0',
+  projectPath,
+  entries: [],
+  lastHash: '',
+});
+
+// --- Constants ---
+
+/** Maximum entries before oldest are rotated out */
+const MAX_ENTRIES = 1000;
+
+/** Maximum file size in bytes before chain is reset (50 MB) */
+const MAX_FILE_SIZE = 50 * 1024 * 1024;
+
+// --- Factory ---
+
+export const createEvidenceStore = (
+  storePath: string,
+  signHash: (hash: string) => string,
+  verifyHash: (hash: string, signature: string) => boolean,
+): EvidenceStore => {
+  // In-memory cache of chain (lazy-loaded from disk)
+  let cachedChain: EvidenceChain | null = null;
+
+  const loadChain = async (): Promise<EvidenceChain> => {
+    if (cachedChain) return cachedChain;
+
+    const projectPath = dirname(dirname(dirname(storePath)));
+
+    try {
+      // Check file size before reading to avoid loading oversized chains
+      const fileStat = await stat(storePath);
+      if (fileStat.size > MAX_FILE_SIZE) {
+        // Chain is oversized — reset with warning
+        cachedChain = EMPTY_CHAIN(projectPath);
+        return cachedChain;
+      }
+
+      const raw = await readFile(storePath, 'utf-8');
+      const parsed = parseEvidenceChain(raw);
+
+      if (!parsed) {
+        cachedChain = EMPTY_CHAIN(projectPath);
+        return cachedChain;
+      }
+
+      cachedChain = parsed;
+      return cachedChain;
+    } catch {
+      cachedChain = EMPTY_CHAIN(projectPath);
+      return cachedChain;
+    }
+  };
+
+  const saveChain = async (chain: EvidenceChain): Promise<void> => {
+    await mkdir(dirname(storePath), { recursive: true });
+    await writeFile(storePath, JSON.stringify(chain, null, 2));
+    cachedChain = chain;
+  };
+
+  const append = async (evidence: readonly Evidence[], scanId: string): Promise<void> => {
+    const chain = await loadChain();
+    const newEntries = [...chain.entries];
+    let lastHash = chain.lastHash;
+
+    for (const ev of evidence) {
+      const chainPrev = lastHash || null;
+      const hash = computeHash(ev, scanId, chainPrev);
+      const signature = signHash(hash);
+
+      newEntries.push(Object.freeze({
+        evidence: ev,
+        scanId,
+        chainPrev,
+        hash,
+        signature,
+      }));
+
+      lastHash = hash;
+    }
+
+    // Rotate: keep only the newest MAX_ENTRIES entries
+    const trimmedEntries = newEntries.length > MAX_ENTRIES
+      ? newEntries.slice(newEntries.length - MAX_ENTRIES)
+      : newEntries;
+
+    const updated: EvidenceChain = {
+      ...chain,
+      entries: Object.freeze(trimmedEntries),
+      lastHash,
+    };
+
+    await saveChain(updated);
+  };
+
+  const getChain = async (): Promise<EvidenceChain> => {
+    return loadChain();
+  };
+
+  const verify = async (): Promise<{ valid: boolean; brokenAt?: number }> => {
+    const chain = await loadChain();
+
+    if (chain.entries.length === 0) {
+      return { valid: true };
+    }
+
+    let expectedPrev: string | null = null;
+
+    for (let i = 0; i < chain.entries.length; i++) {
+      const entry = chain.entries[i]!;
+
+      // Verify chain link
+      if (entry.chainPrev !== (expectedPrev || null)) {
+        return { valid: false, brokenAt: i };
+      }
+
+      // Verify hash
+      const recomputedHash = computeHash(entry.evidence, entry.scanId, entry.chainPrev);
+      if (entry.hash !== recomputedHash) {
+        return { valid: false, brokenAt: i };
+      }
+
+      // Verify signature
+      if (!verifyHash(entry.hash, entry.signature)) {
+        return { valid: false, brokenAt: i };
+      }
+
+      expectedPrev = entry.hash;
+    }
+
+    return { valid: true };
+  };
+
+  const getSummary = async (): Promise<EvidenceChainSummary> => {
+    const chain = await loadChain();
+    const verification = await verify();
+
+    if (chain.entries.length === 0) {
+      return {
+        totalEntries: 0,
+        scanCount: 0,
+        firstEntry: '',
+        lastEntry: '',
+        chainValid: verification.valid,
+        uniqueFindings: 0,
+      };
+    }
+
+    const scanIds = new Set(chain.entries.map(e => e.scanId));
+    const findingIds = new Set(chain.entries.map(e => e.evidence.findingId));
+    const timestamps = chain.entries.map(e => e.evidence.timestamp).sort();
+
+    return {
+      totalEntries: chain.entries.length,
+      scanCount: scanIds.size,
+      firstEntry: timestamps[0]!,
+      lastEntry: timestamps[timestamps.length - 1]!,
+      chainValid: verification.valid,
+      uniqueFindings: findingIds.size,
+    };
+  };
+
+  return Object.freeze({ append, getChain, verify, getSummary });
+};

package/src/domain/scanner/evidence.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from 'vitest';
+import { createEvidence, createEvidenceCollector } from './evidence.js';
+import type { Evidence, EvidenceSource } from './evidence.js';
+
+describe('createEvidence', () => {
+  it('creates evidence with required fields', () => {
+    const evidence = createEvidence('ai-disclosure', 'L1', 'file-presence');
+
+    expect(evidence.findingId).toBe('ai-disclosure');
+    expect(evidence.layer).toBe('L1');
+    expect(evidence.source).toBe('file-presence');
+    expect(evidence.timestamp).toBeTruthy();
+  });
+
+  it('creates evidence with optional fields', () => {
+    const evidence = createEvidence('l4-bare-llm', 'L4', 'pattern-match', {
+      snippet: 'openai.chat.completions.create()',
+      file: 'src/api.ts',
+      line: 42,
+    });
+
+    expect(evidence.snippet).toBe('openai.chat.completions.create()');
+    expect(evidence.file).toBe('src/api.ts');
+    expect(evidence.line).toBe(42);
+  });
+
+  it('has valid ISO timestamp', () => {
+    const evidence = createEvidence('test', 'L1', 'file-presence');
+    const date = new Date(evidence.timestamp);
+    expect(date.getTime()).not.toBeNaN();
+  });
+
+  it('supports all evidence sources', () => {
+    const sources: EvidenceSource[] = [
+      'file-presence', 'heading-match', 'content-analysis',
+      'dependency', 'pattern-match', 'llm-analysis', 'cross-layer',
+    ];
+
+    for (const source of sources) {
+      const evidence = createEvidence('test', 'L1', source);
+      expect(evidence.source).toBe(source);
+    }
+  });
+});
+
+describe('createEvidenceCollector', () => {
+  it('starts empty', () => {
+    const collector = createEvidenceCollector();
+    expect(collector.getAll()).toHaveLength(0);
+  });
+
+  it('collects evidence items', () => {
+    const collector = createEvidenceCollector();
+    collector.add(createEvidence('finding-1', 'L1', 'file-presence'));
+    collector.add(createEvidence('finding-2', 'L3', 'dependency'));
+
+    expect(collector.getAll()).toHaveLength(2);
+  });
+
+  it('filters by finding ID', () => {
+    const collector = createEvidenceCollector();
+    collector.add(createEvidence('ai-disclosure', 'L1', 'file-presence'));
+    collector.add(createEvidence('ai-disclosure', 'L4', 'pattern-match'));
+    collector.add(createEvidence('logging', 'L4', 'pattern-match'));
+
+    const disclosureEvidence = collector.getByFinding('ai-disclosure');
+    expect(disclosureEvidence).toHaveLength(2);
+    expect(disclosureEvidence.every((e) => e.findingId === 'ai-disclosure')).toBe(true);
+  });
+
+  it('returns empty for unknown finding', () => {
+    const collector = createEvidenceCollector();
+    collector.add(createEvidence('finding-1', 'L1', 'file-presence'));
+
+    expect(collector.getByFinding('nonexistent')).toHaveLength(0);
+  });
+
+  it('getAll returns a copy (immutable)', () => {
+    const collector = createEvidenceCollector();
+    collector.add(createEvidence('finding-1', 'L1', 'file-presence'));
+
+    const all1 = collector.getAll();
+    collector.add(createEvidence('finding-2', 'L2', 'heading-match'));
+    const all2 = collector.getAll();
+
+    expect(all1).toHaveLength(1);
+    expect(all2).toHaveLength(2);
+  });
+
+  it('handles multiple evidence for same finding from different layers', () => {
+    const collector = createEvidenceCollector();
+    collector.add(createEvidence('check-1', 'L1', 'file-presence', { file: 'COMPLIANCE.md' }));
+    collector.add(createEvidence('check-1', 'L2', 'heading-match', { snippet: 'All sections present' }));
+    collector.add(createEvidence('check-1', 'L4', 'pattern-match', { file: 'src/app.ts', line: 10 }));
+
+    const evidence = collector.getByFinding('check-1');
+    expect(evidence).toHaveLength(3);
+
+    const layers = evidence.map((e) => e.layer);
+    expect(layers).toContain('L1');
+    expect(layers).toContain('L2');
+    expect(layers).toContain('L4');
+  });
+});

package/src/domain/scanner/evidence.ts

@@ -0,0 +1,71 @@
+export type EvidenceSource =
+  | 'file-presence'
+  | 'heading-match'
+  | 'content-analysis'
+  | 'dependency'
+  | 'pattern-match'
+  | 'llm-analysis'
+  | 'cross-layer'
+  | 'fix'
+  | 'passport'
+  | 'passport-import'
+  | 'export'
+  | 'fria'
+  | 'worker-notification'
+  | 'policy'
+  | 'document'
+  | 'adversarial-test'
+  | 'supply-chain'
+  | 'nhi-scan'
+  | 'security-import'
+  | 'redteam';
+
+export interface Evidence {
+  readonly findingId: string;
+  readonly layer: string;
+  readonly timestamp: string;
+  readonly source: EvidenceSource;
+  readonly snippet?: string;
+  readonly file?: string;
+  readonly line?: number;
+}
+
+export const createEvidence = (
+  findingId: string,
+  layer: string,
+  source: EvidenceSource,
+  opts?: {
+    readonly snippet?: string;
+    readonly file?: string;
+    readonly line?: number;
+  },
+): Evidence => ({
+  findingId,
+  layer,
+  timestamp: new Date().toISOString(),
+  source,
+  snippet: opts?.snippet,
+  file: opts?.file,
+  line: opts?.line,
+});
+
+export interface EvidenceCollector {
+  readonly add: (evidence: Evidence) => void;
+  readonly getAll: () => readonly Evidence[];
+  readonly getByFinding: (findingId: string) => readonly Evidence[];
+}
+
+export const createEvidenceCollector = (): EvidenceCollector => {
+  const items: Evidence[] = [];
+
+  const add = (evidence: Evidence): void => {
+    items.push(evidence);
+  };
+
+  const getAll = (): readonly Evidence[] => [...items];
+
+  const getByFinding = (findingId: string): readonly Evidence[] =>
+    items.filter((e) => e.findingId === findingId);
+
+  return { add, getAll, getByFinding };
+};

package/src/domain/scanner/external/bandit-runner.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { parseBanditOutput } from './bandit-runner.js';
+
+describe('parseBanditOutput', () => {
+  it('parses valid Bandit JSON output', () => {
+    const output = JSON.stringify({
+      results: [
+        {
+          test_id: 'B603',
+          test_name: 'subprocess_without_shell_equals_true',
+          issue_text: 'subprocess call - check for execution of untrusted input',
+          issue_severity: 'HIGH',
+          issue_confidence: 'HIGH',
+          filename: '/project/scripts/run.py',
+          line_number: 15,
+        },
+        {
+          test_id: 'B101',
+          test_name: 'assert_used',
+          issue_text: 'Use of assert detected. The enclosed code will be removed when compiling to optimised byte code.',
+          issue_severity: 'LOW',
+          issue_confidence: 'HIGH',
+          filename: '/project/tests/test_app.py',
+          line_number: 3,
+        },
+      ],
+    });
+
+    const findings = parseBanditOutput(output, '/project');
+    expect(findings).toHaveLength(2);
+    expect(findings[0]!.ruleId).toBe('B603');
+    expect(findings[0]!.file).toBe('scripts/run.py');
+    expect(findings[0]!.severity).toBe('HIGH');
+    expect(findings[0]!.line).toBe(15);
+    expect(findings[1]!.severity).toBe('LOW');
+  });
+
+  it('returns empty array for empty output', () => {
+    expect(parseBanditOutput('', '/project')).toEqual([]);
+  });
+
+  it('returns empty array for invalid JSON', () => {
+    expect(parseBanditOutput('syntax error', '/project')).toEqual([]);
+  });
+});

package/src/domain/scanner/external/bandit-runner.ts

@@ -0,0 +1,90 @@
+import type { ExternalRunner, ExternalRunnerDeps, ExternalRunnerResult, RawExternalFinding } from './runner-port.js';
+import { normalizeFilePath } from './path-utils.js';
+
+interface BanditResult {
+  readonly results?: readonly BanditFinding[];
+  readonly errors?: readonly unknown[];
+}
+
+interface BanditFinding {
+  readonly test_id: string;
+  readonly test_name: string;
+  readonly issue_text: string;
+  readonly issue_severity: string;
+  readonly issue_confidence: string;
+  readonly filename: string;
+  readonly line_number: number;
+  readonly col_offset?: number;
+}
+
+export const createBanditRunner = (): ExternalRunner => Object.freeze({
+  name: 'bandit',
+  run: async (deps: ExternalRunnerDeps): Promise<ExternalRunnerResult> => {
+    // Only run if Python files exist
+    const hasPython = deps.files.some((f) =>
+      f.extension === '.py' || f.relativePath.endsWith('.py'),
+    );
+    if (!hasPython) {
+      return {
+        tool: 'bandit',
+        version: '',
+        rawFindings: [],
+        duration: 0,
+        exitCode: 0,
+      };
+    }
+
+    const startTime = Date.now();
+    const toolCmd = deps.toolPath ?? 'bandit';
+
+    const result = await deps.runProcess(toolCmd, [
+      '-r', deps.projectPath,
+      '-f', 'json',
+      '-q',
+      '--exclude', `${deps.projectPath}/.complior,${deps.projectPath}/node_modules,${deps.projectPath}/dist`,
+    ], { timeout: 120_000 });
+
+    const duration = Date.now() - startTime;
+
+    if (result.exitCode !== 0 && result.exitCode !== 1) {
+      return {
+        tool: 'bandit',
+        version: '',
+        rawFindings: [],
+        duration,
+        exitCode: result.exitCode,
+        error: result.stderr.slice(0, 500),
+      };
+    }
+
+    const rawFindings = parseBanditOutput(result.stdout, deps.projectPath);
+    return {
+      tool: 'bandit',
+      version: '',
+      rawFindings,
+      duration,
+      exitCode: result.exitCode,
+    };
+  },
+});
+
+export const parseBanditOutput = (stdout: string, projectPath: string): RawExternalFinding[] => {
+  if (!stdout.trim()) return [];
+
+  let parsed: BanditResult;
+  try {
+    parsed = JSON.parse(stdout) as BanditResult;
+  } catch {
+    return [];
+  }
+
+  if (!parsed.results) return [];
+
+  return parsed.results.map((r): RawExternalFinding => ({
+    ruleId: r.test_id,
+    message: `${r.test_name}: ${r.issue_text}`,
+    severity: r.issue_severity,
+    file: normalizeFilePath(r.filename, projectPath),
+    line: r.line_number,
+  }));
+};