praxis-sec 1.0.0

package/cli/agents/model-file-scanner.js

@@ -0,0 +1,259 @@
+/**
+ * Model File Scanner
+ * ===================
+ *
+ * Finds machine-learning model artifacts in the repository and flags risky
+ * formats. Pickle-based formats (.pkl/.pt/.pth/.ckpt/pytorch_model.bin)
+ * execute arbitrary code on load — adversaries embed `os.system` payloads
+ * via `__reduce__` to gain RCE. SafeTensors and GGUF are safer but still
+ * benefit from a model-card / origin check.
+ *
+ * Risk classes:
+ *   - pickle-based (.pkl, .pt, .pth, .ckpt, pytorch_model.bin)  → critical/high
+ *   - safetensors (.safetensors)                                → low/informational
+ *   - gguf, onnx, h5, pb                                        → low
+ *   - missing MODEL_CARD.md / README.md alongside weights       → low
+ *
+ * References: ProtectAI ModelScan, Trail of Bits "PyTorch Pickle Risks".
+ *
+ * Maps to: OWASP LLM03 / LLM04, MITRE ATLAS AML.T0010 / AML.T0018,
+ *          OWASP ML Top 10 ML06 / ML10.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import fg from 'fast-glob';
+import { BaseAgent, createFinding } from './base-agent.js';
+
+const MODEL_GLOBS = [
+  '**/*.pkl', '**/*.pickle',
+  '**/*.pt', '**/*.pth',
+  '**/*.ckpt',
+  '**/*.safetensors',
+  '**/*.gguf',
+  '**/*.onnx',
+  '**/*.h5', '**/*.hdf5',
+  '**/*.pb',
+  '**/pytorch_model.bin',
+  '**/model.bin',
+  '**/consolidated.*.bin',
+];
+
+const PICKLE_EXTS = new Set(['.pkl', '.pickle', '.pt', '.pth', '.ckpt']);
+const SAFE_EXTS = new Set(['.safetensors']);
+const NEUTRAL_EXTS = new Set(['.gguf', '.onnx', '.h5', '.hdf5', '.pb']);
+
+// Strings that, when present in a pickle byte stream, indicate the file
+// imports a dangerous module during deserialization. These are not
+// definitive RCE proofs (Python's pickle stores module names as ASCII), but
+// in practice their presence in a model artifact is anomalous.
+const PICKLE_DANGEROUS_MODULES = [
+  'posix', 'nt', 'os.system', 'os.popen', 'os.exec',
+  'subprocess', 'subprocess.Popen', 'subprocess.call', 'subprocess.run',
+  'commands.getoutput',
+  'builtins.eval', 'builtins.exec', 'builtins.compile',
+  '__builtin__.eval', '__builtin__.exec',
+  'shutil.rmtree',
+  'pty.spawn',
+  'socket.socket',
+  'requests.get', 'urllib.request',
+  '__reduce__', '__reduce_ex__',
+];
+
+const PICKLE_OPCODE_GLOBAL = 0x63;   // 'c' — GLOBAL (push module.attr onto stack)
+const PICKLE_OPCODE_REDUCE = 0x52;   // 'R' — call callable with args (the dangerous one)
+const PICKLE_OPCODE_INST = 0x69;     // 'i' — INST (also reduce-like)
+const PICKLE_OPCODE_STACK_GLOBAL = 0x93; // STACK_GLOBAL (proto 4)
+
+const MAX_BYTES_TO_SCAN = 5 * 1024 * 1024; // 5MB head — more than enough to see opcodes
+
+export class ModelFileScanner extends BaseAgent {
+  constructor() {
+    super(
+      'ModelFileScanner',
+      'Detects risky ML model artifacts (pickle, safetensors, gguf) and missing model cards',
+      'llm'
+    );
+  }
+
+  shouldRun(recon) {
+    if (recon?.hasModelFiles) return true;
+    const langs = recon?.languages;
+    if (langs && (langs instanceof Set ? langs.has('python') : langs.includes?.('python'))) {
+      return true;
+    }
+    return false;
+  }
+
+  async analyze(context) {
+    const { rootPath } = context;
+    const findings = [];
+
+    let modelFiles = [];
+    try {
+      modelFiles = await fg(MODEL_GLOBS, {
+        cwd: rootPath,
+        absolute: true,
+        onlyFiles: true,
+        dot: false,
+        ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
+      });
+    } catch {
+      return findings;
+    }
+
+    if (modelFiles.length === 0) return findings;
+
+    const directoriesWithModels = new Set();
+
+    for (const file of modelFiles) {
+      directoriesWithModels.add(path.dirname(file));
+      const ext = path.extname(file).toLowerCase();
+      const relPath = path.relative(rootPath, file).replace(/\\/g, '/');
+
+      if (PICKLE_EXTS.has(ext) || /pytorch_model\.bin$|consolidated\..*\.bin$|^model\.bin$/.test(path.basename(file))) {
+        findings.push(...this._inspectPickle(file, relPath));
+      } else if (SAFE_EXTS.has(ext)) {
+        findings.push(this._informational(file, relPath, 'safetensors',
+          'SafeTensors is the recommended safe format. Verify the file came from a trusted source and matches a published checksum.'));
+      } else if (NEUTRAL_EXTS.has(ext)) {
+        findings.push(this._informational(file, relPath, ext.replace('.', ''),
+          'Non-pickle model artifact. Verify origin and checksums; some loaders (e.g. ONNX custom ops) can still execute attacker-controlled code.'));
+      }
+    }
+
+    for (const dir of directoriesWithModels) {
+      const sample = modelFiles.find(f => path.dirname(f) === dir);
+      if (!sample) continue;
+      if (!this._hasModelCard(dir)) {
+        findings.push(createFinding({
+          file: sample,
+          line: 0,
+          severity: 'low',
+          category: 'llm',
+          rule: 'MODEL_FILE_NO_CARD',
+          title: 'Model artifact without a model card',
+          description: 'No MODEL_CARD.md / README.md / model_card.* alongside the model artifact. Model cards document training data, intended use, and limitations.',
+          matched: path.relative(rootPath, dir).replace(/\\/g, '/'),
+          confidence: 'medium',
+          owasp: 'ASI04',
+          fix: 'Add a MODEL_CARD.md describing source, training data, intended use, license, and known limitations.',
+        }));
+      }
+    }
+
+    return findings;
+  }
+
+  _inspectPickle(filePath, relPath) {
+    const findings = [];
+    let buf;
+    try {
+      const fd = fs.openSync(filePath, 'r');
+      const stat = fs.fstatSync(fd);
+      const size = Math.min(stat.size, MAX_BYTES_TO_SCAN);
+      buf = Buffer.alloc(size);
+      fs.readSync(fd, buf, 0, size, 0);
+      fs.closeSync(fd);
+    } catch {
+      return findings;
+    }
+
+    const isZip = buf.length >= 2 && buf[0] === 0x50 && buf[1] === 0x4B;
+
+    findings.push(createFinding({
+      file: filePath,
+      line: 0,
+      severity: 'high',
+      category: 'llm',
+      rule: 'MODEL_FILE_PICKLE_FORMAT',
+      title: 'Pickle-based model format detected',
+      description: 'Pickle-based model artifacts execute arbitrary Python on load via `__reduce__`. Loading a malicious file is equivalent to running its code. Treat any unverified pickle as untrusted.',
+      matched: relPath,
+      confidence: 'high',
+      cwe: 'CWE-502',
+      owasp: 'ASI04',
+      fix: 'Convert to SafeTensors (`safetensors.torch.save_file`). If pickle is unavoidable, verify a SHA-256 you control before loading and load only inside a sandbox.',
+    }));
+
+    const text = buf.toString('binary');
+    const hits = [];
+    for (const mod of PICKLE_DANGEROUS_MODULES) {
+      const idx = text.indexOf(mod);
+      if (idx !== -1) hits.push({ mod, idx });
+    }
+
+    let hasReduce = false;
+    let hasGlobal = false;
+    if (!isZip) {
+      for (let i = 0; i < buf.length; i++) {
+        const b = buf[i];
+        if (b === PICKLE_OPCODE_REDUCE) hasReduce = true;
+        else if (b === PICKLE_OPCODE_GLOBAL || b === PICKLE_OPCODE_STACK_GLOBAL || b === PICKLE_OPCODE_INST) hasGlobal = true;
+        if (hasReduce && hasGlobal) break;
+      }
+    }
+
+    if (hits.length > 0) {
+      findings.push(createFinding({
+        file: filePath,
+        line: 0,
+        severity: 'critical',
+        category: 'llm',
+        rule: 'MODEL_FILE_PICKLE_DANGEROUS_IMPORT',
+        title: 'Pickle artifact imports a dangerous module',
+        description: `Pickle stream references known-dangerous symbols: ${hits.slice(0, 5).map(h => h.mod).join(', ')}. Loading this file with torch.load / pickle.load may execute code.`,
+        matched: hits.slice(0, 5).map(h => h.mod).join(', '),
+        confidence: 'high',
+        cwe: 'CWE-502',
+        owasp: 'ASI04',
+        fix: 'Do not load this file. Re-source the model from a trusted publisher and verify checksums. Convert to SafeTensors before reuse.',
+      }));
+    } else if (hasReduce && hasGlobal) {
+      findings.push(createFinding({
+        file: filePath,
+        line: 0,
+        severity: 'medium',
+        category: 'llm',
+        rule: 'MODEL_FILE_PICKLE_REDUCE',
+        title: 'Pickle artifact contains REDUCE opcodes',
+        description: 'Pickle stream contains GLOBAL + REDUCE opcodes — typical for callable invocations during unpickling. Without a known-good source, this is the same shape malicious pickles use.',
+        matched: 'pickle GLOBAL + REDUCE opcodes present',
+        confidence: 'medium',
+        cwe: 'CWE-502',
+        owasp: 'ASI04',
+        fix: 'Verify the artifact origin and checksum, or scan with a dedicated pickle scanner (picklescan / modelscan) before loading.',
+      }));
+    }
+
+    return findings;
+  }
+
+  _informational(filePath, relPath, label, description) {
+    return createFinding({
+      file: filePath,
+      line: 0,
+      severity: 'low',
+      category: 'llm',
+      rule: `MODEL_FILE_${label.toUpperCase()}`,
+      title: `Model artifact detected (${label})`,
+      description,
+      matched: relPath,
+      confidence: 'high',
+      owasp: 'ASI04',
+      fix: 'Document the model origin and license. Pin a checksum in your repo so future loads can be verified.',
+    });
+  }
+
+  _hasModelCard(dir) {
+    const candidates = ['MODEL_CARD.md', 'model_card.md', 'modelcard.md', 'MODELCARD.md', 'README.md', 'README'];
+    for (const name of candidates) {
+      try {
+        if (fs.existsSync(path.join(dir, name))) return true;
+      } catch { /* ignore */ }
+    }
+    return false;
+  }
+}
+
+export default ModelFileScanner;

package/cli/agents/orchestrator.js

@@ -0,0 +1,355 @@
+/**
+ * Agent Orchestrator
+ * ==================
+ *
+ * Coordinates all security agents, deduplicates findings,
+ * and produces a unified report.
+ *
+ * Features:
+ * - Per-agent timeouts (default 30s, configurable via --timeout)
+ * - Parallel execution with configurable concurrency (default 6)
+ *
+ * USAGE:
+ *   const orchestrator = new Orchestrator();
+ *   orchestrator.register(new InjectionTester());
+ *   const results = await orchestrator.runAll(rootPath, options);
+ */
+
+import path from 'path';
+import ora from 'ora';
+import chalk from 'chalk';
+import { ReconAgent } from './recon-agent.js';
+import { VerifierAgent } from './verifier-agent.js';
+import { DeepAnalyzer } from './deep-analyzer.js';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const DEFAULT_TIMEOUT = 30_000; // 30s per agent
+const DEFAULT_CONCURRENCY = 6;
+
+// =============================================================================
+// ORCHESTRATOR
+// =============================================================================
+
+export class Orchestrator {
+  constructor() {
+    /** @type {import('./base-agent.js').BaseAgent[]} */
+    this.agents = [];
+    this.reconAgent = new ReconAgent();
+    this.verifierAgent = new VerifierAgent();
+  }
+
+  /**
+   * Register an agent for execution.
+   */
+  register(agent) {
+    this.agents.push(agent);
+    return this;
+  }
+
+  /**
+   * Register multiple agents at once.
+   */
+  registerAll(agents) {
+    for (const agent of agents) {
+      this.register(agent);
+    }
+    return this;
+  }
+
+  /**
+   * Run a single agent with a timeout.
+   */
+  async runAgent(agent, context, timeout) {
+    return Promise.race([
+      agent.analyze(context),
+      new Promise((_, reject) => {
+        setTimeout(() => reject(new Error(`timed out after ${timeout / 1000}s`)), timeout);
+      }),
+    ]);
+  }
+
+  /**
+   * Run all registered agents against the codebase.
+   *
+   * @param {string} rootPath — Absolute path to the project root
+   * @param {object} options  — { verbose, agents[], categories[], timeout, concurrency }
+   * @returns {Promise<object>} — { recon, findings[], agentResults[] }
+   */
+  async runAll(rootPath, options = {}) {
+    const absolutePath = path.resolve(rootPath);
+    const timeout = options.timeout || DEFAULT_TIMEOUT;
+    const concurrency = options.concurrency || DEFAULT_CONCURRENCY;
+
+    // ── 1. Recon — map the attack surface ─────────────────────────────────────
+    const quiet = options.quiet || false;
+    const reconSpinner = quiet ? null : ora({ text: 'Mapping attack surface...', color: 'cyan' }).start();
+    const recon = await this.reconAgent.analyze({ rootPath: absolutePath, options }); // praxis-ignore AGENT_ESCALATED_PERMISSIONS — calling ReconAgent.analyze(); no permission escalation
+    if (reconSpinner) reconSpinner.succeed(chalk.green('Attack surface mapped'));
+
+    // ── 2. Discover files once (shared across agents) ─────────────────────────
+    const files = await this.reconAgent.discoverFiles(absolutePath);
+
+    // ── 3. Filter agents if specific ones requested ───────────────────────────
+    let agentsToRun = this.agents;
+    if (options.agents && options.agents.length > 0) {
+      const requested = options.agents.map(a => a.toLowerCase());
+      agentsToRun = this.agents.filter(a => {
+        const name = a.name.toLowerCase();
+        const cat = a.category.toLowerCase();
+        return requested.some(r => name === r || name.includes(r) || cat === r);
+      });
+    }
+    if (options.categories && options.categories.length > 0) {
+      const requested = new Set(options.categories.map(c => c.toLowerCase()));
+      agentsToRun = agentsToRun.filter(a => requested.has(a.category.toLowerCase()));
+    }
+
+    // ── 4. Build shared context ─────────────────────────────────────────────
+    // sharedFindings allows cross-agent awareness: later agents can see
+    // what earlier agents found (e.g., secrets agent finds a key,
+    // supply-chain agent can check if it's committed to a public repo).
+    const sharedFindings = [];
+    const context = { rootPath: absolutePath, files, recon, options, sharedFindings };
+    if (options.changedFiles) {
+      context.changedFiles = options.changedFiles;
+    }
+
+    // ── 5. Run agents in parallel (chunked by concurrency) ──────────────────
+    const agentResults = [];
+    let allFindings = [];
+
+    const spinner = quiet ? null : ora({
+      text: `Running ${agentsToRun.length} agents in parallel...`,
+      color: 'cyan'
+    }).start();
+
+    // Filter agents by framework relevance (shouldRun check)
+    const relevantAgents = agentsToRun.filter(a => {
+      if (typeof a.shouldRun === 'function') {
+        return a.shouldRun(recon);
+      }
+      return true;
+    });
+    const skippedAgents = agentsToRun.length - relevantAgents.length;
+
+    for (let i = 0; i < relevantAgents.length; i += concurrency) {
+      const chunk = relevantAgents.slice(i, i + concurrency);
+      const settled = await Promise.allSettled(
+        chunk.map(agent => this.runAgent(agent, context, timeout)) // praxis-ignore AGENT_RECURSIVE_INVOCATION — one agent invoking another by design, not self-recursion
+      );
+
+      for (let j = 0; j < chunk.length; j++) {
+        const agent = chunk[j];
+        const result = settled[j];
+
+        if (result.status === 'fulfilled') {
+          const findings = result.value;
+          agentResults.push({
+            agent: agent.name,
+            category: agent.category,
+            findingCount: findings.length,
+            success: true,
+          });
+          allFindings = allFindings.concat(findings);
+          // Share findings with subsequent agents
+          sharedFindings.push(...findings);
+          // Optional progress hook: fires once per agent as it settles, so callers
+          // that stream progress (e.g. the web UI) report real work rather than a
+          // placeholder percentage. Optional so existing callers are unaffected.
+          if (typeof options.onProgress === 'function') {
+            try {
+              options.onProgress({
+                agent: agent.name,
+                category: agent.category,
+                done: agentResults.length,
+                total: relevantAgents.length,
+                findingCount: findings.length,
+              });
+            } catch { /* a progress listener must never break a scan */ }
+          }
+        } else {
+          agentResults.push({
+            agent: agent.name,
+            category: agent.category,
+            findingCount: 0,
+            success: false,
+            error: result.reason.message,
+          });
+        }
+      }
+    }
+
+    // Show results summary
+    if (spinner) {
+      const succeeded = agentResults.filter(a => a.success).length;
+      const failed = agentResults.filter(a => !a.success).length;
+      const totalFindings = allFindings.length;
+
+      const skipNote = skippedAgents > 0 ? `, ${skippedAgents} skipped (not relevant)` : '';
+      if (failed > 0) {
+        spinner.warn(chalk.yellow(
+          `${succeeded}/${relevantAgents.length} agents completed, ${failed} failed, ${totalFindings} finding(s)${skipNote}`
+        ));
+      } else {
+        spinner.succeed(
+          totalFindings === 0
+            ? chalk.green(`${succeeded} agents: clean${skipNote}`)
+            : chalk.yellow(`${succeeded} agents: ${totalFindings} finding(s)${skipNote}`)
+        );
+      }
+    }
+
+    // Show per-agent results when not in quiet mode
+    if (!quiet) {
+      for (const r of agentResults) {
+        if (r.success) {
+          const icon = r.findingCount === 0 ? chalk.green('  ✔') : chalk.yellow('  ⚠');
+          const msg = r.findingCount === 0
+            ? chalk.green(`${r.agent}: clean`)
+            : chalk.yellow(`${r.agent}: ${r.findingCount} finding(s)`);
+          console.log(`${icon} ${msg}`);
+        } else {
+          console.log(chalk.red(`  ✗ ${r.agent}: ${r.error}`));
+        }
+      }
+    }
+
+    // ── 6. Deduplicate ────────────────────────────────────────────────────────
+    allFindings = this.deduplicate(allFindings);
+
+    // ── 7. Second-pass verification (confirms or downgrades findings) ───────
+    if (!options.skipVerifier) {
+      const verifySpinner = quiet ? null : ora({ text: 'Verifying findings...', color: 'cyan' }).start();
+      allFindings = this.verifierAgent.verify(allFindings, options);
+      const verified = allFindings.filter(f => f.verified === true).length;
+      const downgraded = allFindings.filter(f => f.verified === false).length;
+      if (verifySpinner) {
+        verifySpinner.succeed(chalk.green(
+          `Verified: ${verified} confirmed, ${downgraded} downgraded`
+        ));
+      }
+    }
+
+    // ── 8. Deep LLM analysis (optional, --deep flag) ───────────────────────
+    if (options.deep) {
+      const analyzer = DeepAnalyzer.create(absolutePath, {
+        local: options.local,
+        model: options.model,
+        budgetCents: options.budget ?? 50,
+        verbose: options.verbose,
+      });
+
+      if (analyzer) {
+        const deepSpinner = quiet ? null : ora({ text: `Deep analysis with ${analyzer.provider.name}...`, color: 'cyan' }).start();
+        try {
+          allFindings = await analyzer.analyze(allFindings, { rootPath: absolutePath, recon });
+          const stats = analyzer.getStats();
+          if (deepSpinner) {
+            if (stats.multiTier) {
+              const providerName = analyzer.provider?.name || 'unknown';
+              const cascade = stats.isAnthropic !== false ? 'Haiku→Sonnet→Opus' : `${providerName} (3-tier)`;
+              const tierNote = stats.tier3Count > 0
+                ? `, ${stats.tier3Count} escalated to tier-3`
+                : stats.tier2Count > 0 ? `, ${stats.tier2Count} via tier-2` : '';
+              const skipNote = stats.skippedCount > 0 ? `, ${stats.skippedCount} triaged away` : '';
+              deepSpinner.succeed(chalk.green(
+                `Deep analysis (${cascade}): ${stats.analyzedCount} analyzed${tierNote}${skipNote} (${stats.spentCents}¢)`
+              ));
+            } else {
+              deepSpinner.succeed(chalk.green(
+                `Deep analysis: ${stats.analyzedCount} findings analyzed (${stats.spentCents}¢)`
+              ));
+            }
+          }
+        } catch (err) {
+          if (deepSpinner) deepSpinner.fail(chalk.yellow(`Deep analysis failed: ${err.message}`));
+        }
+      } else if (!quiet) {
+        console.log(chalk.gray('  Deep analysis: no LLM provider found (set ANTHROPIC_API_KEY, MOONSHOT_API_KEY, or use --local)'));
+      }
+    }
+
+    // ── 9. Context-aware confidence tuning ──────────────────────────────────
+    allFindings = this.tuneConfidence(allFindings);
+
+    // ── 9.5 Governance absence-audits (no-human-oversight, no-observability)
+    try {
+      const { runGovernanceAudits } = await import('./governance-audits.js');
+      const governance = runGovernanceAudits({ rootPath: absolutePath, files, findings: allFindings });
+      allFindings = allFindings.concat(governance);
+    } catch { /* governance audits are additive — never break a scan */ }
+
+    // ── 10. Sort by severity ──────────────────────────────────────────────────
+    const sevOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+    allFindings.sort((a, b) =>
+      (sevOrder[a.severity] ?? 4) - (sevOrder[b.severity] ?? 4)
+    );
+
+    return { recon, findings: allFindings, agentResults };
+  }
+
+  /**
+   * Run only agents matching a specific category.
+   */
+  async runCategory(category, rootPath, options = {}) {
+    return this.runAll(rootPath, { ...options, categories: [category] });
+  }
+
+  /**
+   * Downgrade confidence for findings in test files, comments, docs, or examples.
+   * Reduces false-positive noise since ScoringEngine applies confidence multipliers.
+   */
+  tuneConfidence(findings) {
+    const TEST_PATH = /(?:__tests__|\.test\.|\.spec\.|\/test\/|\/tests\/|\/fixtures?\/)/i;
+    const DOC_EXT = new Set(['.md', '.txt', '.rst', '.adoc', '.rdoc']);
+    const EXAMPLE_PATH = /(?:\/examples?\/|\/samples?\/|\/demos?\/|\/fixtures?\/|\/mocks?\/)/i;
+    const COMMENT_LINE = /^\s*(?:\/\/|#|\/?\*|<!--)/;
+
+    for (const f of findings) {
+      const ext = (f.file || '').match(/\.[^.]+$/)?.[0]?.toLowerCase() || '';
+
+      // Findings in documentation files
+      if (DOC_EXT.has(ext)) {
+        f.confidence = 'low';
+        continue;
+      }
+
+      // Findings in test files
+      if (TEST_PATH.test(f.file || '')) {
+        f.confidence = 'low';
+        continue;
+      }
+
+      // Findings in example/sample/demo paths: high → medium
+      if (EXAMPLE_PATH.test(f.file || '') && f.confidence === 'high') {
+        f.confidence = 'medium';
+        continue;
+      }
+
+      // Findings on comment lines
+      if (f.matched && COMMENT_LINE.test(f.matched)) {
+        f.confidence = 'low';
+      }
+    }
+
+    return findings;
+  }
+
+  /**
+   * Remove duplicate findings (same file + line + rule).
+   */
+  deduplicate(findings) {
+    const seen = new Set();
+    return findings.filter(f => {
+      const key = `${f.file}:${f.line}:${f.rule}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+}
+
+export default Orchestrator;