ship-safe 6.4.0 → 8.0.0

package/cli/utils/compliance-map.js

@@ -50,6 +50,72 @@ const AGENTIC_MAP = {
   'ASI10': { soc2: ['CC7.2', 'CC7.4'], iso27001: ['A.8.9', 'A.5.30'], nistAiRmf: ['MANAGE 2.2', 'MANAGE 4.1'] },
 };
 
+// =============================================================================
+// OWASP AGENTIC AI TOP 10 (December 2025)
+// =============================================================================
+
+const OWASP_AGENTIC_TOP_10 = {
+  ASI01: { id: 'ASI01', title: 'Agent Goal Hijacking',          description: 'Manipulation of agent objectives through prompt injection, memory poisoning, or instruction override.' },
+  ASI02: { id: 'ASI02', title: 'Tool Misuse',                   description: 'Agent uses tools in unintended or dangerous ways — shell execution, file deletion, network access beyond scope.' },
+  ASI03: { id: 'ASI03', title: 'Privilege Abuse',               description: 'Agent operates with excessive permissions — writes outside project, accesses secrets, escalates access.' },
+  ASI04: { id: 'ASI04', title: 'Agentic Supply Chain',          description: 'Compromised skills, MCP servers, or tool packages that the agent depends on.' },
+  ASI05: { id: 'ASI05', title: 'Memory & Context Poisoning',    description: 'Malicious data persisted in agent memory, rules files, or context that survives sessions.' },
+  ASI06: { id: 'ASI06', title: 'Uncontrolled Data Exposure',    description: 'Agent leaks code, secrets, or PII through tool outputs, logs, or external API calls.' },
+  ASI07: { id: 'ASI07', title: 'Insecure Communication',        description: 'Unencrypted MCP transport, HTTP model endpoints, or plaintext inter-agent messaging.' },
+  ASI08: { id: 'ASI08', title: 'Missing Human Oversight',       description: 'Agent takes destructive or irreversible actions without user confirmation — proactive mode risks.' },
+  ASI09: { id: 'ASI09', title: 'Weak Identity & Auth',          description: 'Agent sessions without authentication, shared API keys, or no audit trail of actions.' },
+  ASI10: { id: 'ASI10', title: 'Rogue Agent Behavior',          description: 'Agent deviates from intended behavior — self-modification, stealth mode, output suppression.' },
+};
+
+/**
+ * Enrich a finding with OWASP Agentic Top 10 metadata.
+ * Attaches `agenticRisk` object if the finding maps to ASI01–ASI10.
+ * @param {object} finding
+ * @returns {object} — finding with agenticRisk attached (or unchanged)
+ */
+export function enrichAgenticRisk(finding) {
+  const owasp = finding.owasp;
+  if (!owasp || !OWASP_AGENTIC_TOP_10[owasp]) return finding;
+
+  const risk = OWASP_AGENTIC_TOP_10[owasp];
+  finding.agenticRisk = {
+    id: risk.id,
+    title: risk.title,
+    description: risk.description,
+  };
+  return finding;
+}
+
+/**
+ * Get OWASP Agentic Top 10 summary across all findings.
+ * @param {object[]} findings
+ * @returns {{ risks: object[], coverage: number }}
+ */
+export function getAgenticSummary(findings) {
+  const counts = {};
+  for (const f of findings) {
+    const owasp = f.owasp;
+    if (owasp && OWASP_AGENTIC_TOP_10[owasp]) {
+      counts[owasp] = (counts[owasp] || 0) + 1;
+    }
+  }
+
+  const risks = Object.entries(OWASP_AGENTIC_TOP_10).map(([id, info]) => ({
+    ...info,
+    findingCount: counts[id] || 0,
+    status: counts[id] ? 'flagged' : 'clear',
+  }));
+
+  const flagged = risks.filter(r => r.findingCount > 0).length;
+
+  return {
+    risks,
+    flagged,
+    total: 10,
+    coverage: `${flagged}/10`,
+  };
+}
+
 // =============================================================================
 // PUBLIC API
 // =============================================================================

package/cli/utils/hermes-tool-registry.js

@@ -0,0 +1,252 @@
+/**
+ * Hermes Tool Registry — Ship Safe × Hermes Agent
+ * =================================================
+ *
+ * Declares Ship Safe's five security tools in the Hermes Agent tool-registry
+ * format. Import this module in your Hermes agent bootstrap to register
+ * Ship Safe as a first-class citizen in the tool registry.
+ *
+ * USAGE:
+ *   import { HERMES_TOOLS, registerWithHermes } from './hermes-tool-registry.js';
+ *
+ *   // Option A — register all tools at once
+ *   await registerWithHermes(agent.toolRegistry);
+ *
+ *   // Option B — use the raw definitions
+ *   for (const tool of HERMES_TOOLS) agent.toolRegistry.register(tool);
+ *
+ * SECURITY NOTE:
+ *   These definitions are pinned, hardcoded, and integrity-verified at load
+ *   time. They are never fetched from a remote URL. Do not replace the
+ *   INTEGRITY_HASH values without auditing the updated definitions.
+ */
+
+import { createHash } from 'crypto';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// =============================================================================
+// TOOL DEFINITIONS (Hermes function-call schema format)
+// =============================================================================
+
+export const HERMES_TOOLS = [
+  {
+    name: 'ship_safe_audit',
+    description:
+      'Run a Ship Safe security audit on a local codebase directory. ' +
+      'Returns a findings report with severity-graded issues, CWE/OWASP mappings, ' +
+      'and remediation guidance. Use before deploying any code or merging PRs.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute path to the project root directory to scan.',
+        },
+        severity: {
+          type: 'string',
+          enum: ['critical', 'high', 'medium', 'low'],
+          description: 'Minimum severity threshold for reported findings.',
+          default: 'medium',
+        },
+        deep: {
+          type: 'boolean',
+          description: 'Enable deep LLM-powered taint analysis (Haiku→Sonnet→Opus pipeline). Slower but more accurate.',
+          default: false,
+        },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    handler: async ({ path: scanPath, severity = 'medium', deep = false }) => {
+      const { auditCommand } = await import('../commands/audit.js');
+      return auditCommand(scanPath, { severity, deep, json: true, quiet: true });
+    },
+  },
+
+  {
+    name: 'ship_safe_scan_mcp',
+    description:
+      'Analyze an MCP server manifest (URL or local file path) for security issues ' +
+      'before connecting. Checks for prompt injection in tool descriptions, credential ' +
+      'harvesting patterns, Hermes function-call poisoning, schema bypass (additionalProperties: true), ' +
+      'and known-malicious server hashes. Returns per-tool findings.',
+    parameters: {
+      type: 'object',
+      properties: {
+        target: {
+          type: 'string',
+          description: 'URL (https://...) or absolute local file path to the MCP manifest JSON.',
+        },
+      },
+      required: ['target'],
+      additionalProperties: false,
+    },
+    handler: async ({ target }) => {
+      const { scanMcpCommand } = await import('../commands/scan-mcp.js');
+      return scanMcpCommand(target, { json: true });
+    },
+  },
+
+  {
+    name: 'ship_safe_get_findings',
+    description:
+      'Retrieve findings from the last saved Ship Safe scan report for a project. ' +
+      'Optionally filter by minimum severity. Returns an array of findings with rule, ' +
+      'title, severity, file, line, and remediation guidance.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute path to the project root (used to locate the saved report).',
+        },
+        severity: {
+          type: 'string',
+          enum: ['critical', 'high', 'medium', 'low'],
+          description: 'Minimum severity to include in results.',
+          default: 'medium',
+        },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    handler: async ({ path: projectPath, severity = 'medium' }) => {
+      const { mcpGetFindings } = await import('../commands/mcp.js');
+      return mcpGetFindings({ projectPath, severity });
+    },
+  },
+
+  {
+    name: 'ship_safe_suppress_finding',
+    description:
+      'Suppress a known-safe finding by inserting an inline ship-safe-ignore comment ' +
+      'in the source file before the flagged line. Use only when the finding is a ' +
+      'confirmed false positive and you can document why it is safe.',
+    parameters: {
+      type: 'object',
+      properties: {
+        file: {
+          type: 'string',
+          description: 'Absolute path to the source file containing the finding.',
+        },
+        line: {
+          type: 'number',
+          description: 'Line number of the finding (1-based).',
+        },
+        reason: {
+          type: 'string',
+          description: 'Human-readable explanation of why this finding is safe to suppress.',
+        },
+      },
+      required: ['file', 'line', 'reason'],
+      additionalProperties: false,
+    },
+    handler: async ({ file, line, reason }) => {
+      const { mcpSuppressFinding } = await import('../commands/mcp.js');
+      return mcpSuppressFinding({ file, line, reason });
+    },
+  },
+
+  {
+    name: 'ship_safe_memory_list',
+    description:
+      'List all entries in the Ship Safe security memory for a project. ' +
+      'The memory stores learned false positives that are automatically filtered ' +
+      'from future scans. Returns each entry with its rule, file pattern, and ' +
+      'the snippet that was suppressed.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: {
+          type: 'string',
+          description: 'Absolute path to the project root.',
+        },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    handler: async ({ path: projectPath }) => {
+      const { SecurityMemory } = await import('./security-memory.js');
+      const mem = new SecurityMemory(projectPath);
+      return mem.list();
+    },
+  },
+];
+
+// =============================================================================
+// INTEGRITY VERIFICATION
+// Each tool definition is hashed at module load time. If the registry is
+// tampered with (e.g. supply-chain attack), the hash check will fail.
+// Run `node -e "import('./hermes-tool-registry.js').then(m => m.printHashes())"` to regenerate.
+// =============================================================================
+
+const KNOWN_HASHES = {
+  ship_safe_audit:             '4d282d29e44fcc01',
+  ship_safe_scan_mcp:          'f967aea9626ca840',
+  ship_safe_get_findings:      'c09c9447efd574b3',
+  ship_safe_suppress_finding:  '3b7339419fe52ac7',
+  ship_safe_memory_list:       'c71c996716d1805b',
+};
+
+function toolHash(tool) {
+  // Hash name + description + parameter schema only (not handler function)
+  const canonical = JSON.stringify({ name: tool.name, description: tool.description, parameters: tool.parameters });
+  return createHash('sha256').update(canonical).digest('hex').slice(0, 16);
+}
+
+export function verifyIntegrity() {
+  const mismatches = [];
+  for (const tool of HERMES_TOOLS) {
+    const actual = toolHash(tool);
+    const expected = KNOWN_HASHES[tool.name];
+    if (expected && actual !== expected) {
+      mismatches.push({ tool: tool.name, expected, actual });
+    }
+  }
+  return mismatches;
+}
+
+export function printHashes() {
+  console.log('// Current tool definition hashes — paste into KNOWN_HASHES:');
+  for (const tool of HERMES_TOOLS) {
+    console.log(`  ${tool.name}: '${toolHash(tool)}',`);
+  }
+}
+
+// =============================================================================
+// REGISTRATION HELPER
+// =============================================================================
+
+/**
+ * Register all Ship Safe tools with a Hermes tool registry instance.
+ *
+ * @param {object} toolRegistry — Hermes ToolRegistry instance with a .register() method
+ * @param {object} options
+ * @param {boolean} [options.skipVerification=false] — bypass hash verification (not recommended)
+ * @param {boolean} [options.quiet=false] — suppress registration log lines
+ */
+export async function registerWithHermes(toolRegistry, options = {}) {
+  if (!options.skipVerification) { // ship-safe-ignore — this is the integrity-check implementation, not a bypass
+    const mismatches = verifyIntegrity();
+    if (mismatches.length > 0) {
+      const msg = mismatches.map(m => `  ${m.tool}: expected ${m.expected}, got ${m.actual}`).join('\n');
+      throw new Error(`Ship Safe tool registry integrity check failed:\n${msg}\n\nThis may indicate a supply-chain attack. Run ship-safe --version to verify your installation.`);
+    }
+  }
+
+  for (const tool of HERMES_TOOLS) {
+    if (typeof toolRegistry.register === 'function') {
+      toolRegistry.register(tool);
+    } else if (typeof toolRegistry.registerTool === 'function') {
+      toolRegistry.registerTool(tool);
+    } else {
+      throw new Error('toolRegistry must have a .register() or .registerTool() method');
+    }
+    if (!options.quiet) {
+      console.log(`  [ship-safe] Registered tool: ${tool.name}`);
+    }
+  }
+}

package/cli/utils/patterns.js

@@ -865,6 +865,7 @@ const SECURITY_SENSITIVE_PATTERNS = new Set([
   'id_ed25519',
   '*.sqlite',
   '*.db',
+  '.projects',
 ]);
 
 /**

package/cli/utils/plugin-loader.js

@@ -0,0 +1,276 @@
+/**
+ * Plugin Loader — Custom Agent Plugin System
+ * ============================================
+ *
+ * Allows users to drop custom security agents into `.ship-safe/agents/` and
+ * have them automatically loaded and run alongside the built-in agents.
+ *
+ * HOW IT WORKS:
+ *   1. On startup, loadPlugins(rootPath) scans `.ship-safe/agents/*.js`
+ *   2. Each file must export a default class that extends BaseAgent
+ *   3. Validated plugins are instantiated and returned for registration
+ *   4. buildOrchestrator() calls loadPlugins() and registers the results
+ *
+ * PLUGIN CONTRACT:
+ *   A valid plugin must:
+ *   - Export a default class (ES module)
+ *   - Extend BaseAgent (from ship-safe's agent framework)
+ *   - Implement `async analyze(context)` returning an array of findings
+ *   - Set `this.name` and `this.category` in the constructor
+ *
+ * EXAMPLE PLUGIN:
+ *
+ *   // .ship-safe/agents/my-rule.js
+ *   import { BaseAgent, createFinding } from 'ship-safe';
+ *
+ *   export default class MyCustomRule extends BaseAgent {
+ *     constructor() {
+ *       super();
+ *       this.name     = 'MyCustomRule';
+ *       this.category = 'custom';
+ *     }
+ *
+ *     async analyze({ rootPath, files }) {
+ *       const findings = [];
+ *       for (const file of files) {
+ *         const content = fs.readFileSync(file, 'utf-8');
+ *         if (content.includes('eval(')) { // ship-safe-ignore — JSDoc example, not real eval
+ *           findings.push(createFinding({
+ *             rule:        'CUSTOM_EVAL',
+ *             severity:    'high',
+ *             title:       'Dangerous eval() usage', // ship-safe-ignore — JSDoc string literal
+ *             description: 'eval() can execute arbitrary code', // ship-safe-ignore — JSDoc string literal
+ *             file,
+ *             remediation: 'Replace eval() with safer alternatives', // ship-safe-ignore — JSDoc string literal
+ *           }));
+ *         }
+ *       }
+ *       return findings;
+ *     }
+ *   }
+ *
+ * PLUGIN ISOLATION:
+ *   Plugins run in the same process but each agent gets its own timeout (30s).
+ *   A crashing or hanging plugin does not affect other agents.
+ *
+ * SECURITY NOTE:
+ *   Plugins are arbitrary code executed from the local filesystem. Never install
+ *   plugins from untrusted sources. ship-safe will warn if plugins are detected.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+
+const PLUGIN_DIR = '.ship-safe/agents';
+
+/**
+ * Load custom agent plugins from .ship-safe/agents/*.js
+ *
+ * @param {string} rootPath — project root directory
+ * @param {object} options  — { verbose, quiet }
+ * @returns {Promise<object[]>} — array of instantiated agent objects
+ */
+export async function loadPlugins(rootPath, options = {}) {
+  const pluginDir = path.join(rootPath, PLUGIN_DIR);
+
+  if (!fs.existsSync(pluginDir)) return [];
+
+  let files;
+  try {
+    files = fs.readdirSync(pluginDir)
+      .filter(f => f.endsWith('.js') || f.endsWith('.mjs'))
+      .map(f => path.join(pluginDir, f));
+  } catch {
+    return [];
+  }
+
+  if (files.length === 0) return [];
+
+  if (!options.quiet) {
+    console.log(`  Loading ${files.length} plugin(s) from ${PLUGIN_DIR}...`);
+  }
+
+  const plugins = [];
+
+  for (const filePath of files) {
+    try {
+      const fileUrl = pathToFileURL(filePath).href;
+      const mod     = await import(fileUrl);
+      const PluginClass = mod.default;
+
+      if (typeof PluginClass !== 'function') {
+        if (options.verbose) console.warn(`  [plugin] ${path.basename(filePath)}: no default export class`);
+        continue;
+      }
+
+      // Validate the plugin before instantiation
+      const validation = validatePlugin(PluginClass, filePath);
+      if (!validation.valid) {
+        console.warn(`  [plugin] ${path.basename(filePath)} skipped: ${validation.reason}`);
+        continue;
+      }
+
+      const instance = new PluginClass();
+
+      // Ensure required fields are set after construction
+      if (!instance.name) {
+        instance.name = path.basename(filePath, '.js');
+      }
+      if (!instance.category) {
+        instance.category = 'custom';
+      }
+
+      plugins.push(instance);
+
+      if (!options.quiet) {
+        console.log(`  [plugin] Loaded: ${instance.name} (${instance.category})`);
+      }
+    } catch (err) {
+      console.warn(`  [plugin] Failed to load ${path.basename(filePath)}: ${err.message}`);
+    }
+  }
+
+  return plugins;
+}
+
+/**
+ * Validate a plugin class before instantiation.
+ * Does static checks only — does not instantiate.
+ */
+function validatePlugin(PluginClass, filePath) {
+  const name = path.basename(filePath);
+
+  if (typeof PluginClass !== 'function') {
+    return { valid: false, reason: 'default export is not a class/function' };
+  }
+
+  // Check prototype has analyze() — the required method
+  const proto = PluginClass.prototype;
+  if (typeof proto?.analyze !== 'function') {
+    return { valid: false, reason: 'class does not implement analyze()' };
+  }
+
+  return { valid: true };
+}
+
+/**
+ * List available plugins without loading them.
+ * Used by `ship-safe doctor` and `ship-safe plugins list`.
+ */
+export function listPluginFiles(rootPath) {
+  const pluginDir = path.join(rootPath, PLUGIN_DIR);
+  if (!fs.existsSync(pluginDir)) return [];
+
+  try {
+    return fs.readdirSync(pluginDir)
+      .filter(f => f.endsWith('.js') || f.endsWith('.mjs'))
+      .map(f => ({
+        name: path.basename(f, '.js'),
+        path: path.join(pluginDir, f),
+        size: fs.statSync(path.join(pluginDir, f)).size,
+      }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Scaffold a new plugin file in .ship-safe/agents/
+ */
+export function scaffoldPlugin(rootPath, pluginName) {
+  const pluginDir = path.join(rootPath, PLUGIN_DIR);
+  if (!fs.existsSync(pluginDir)) {
+    fs.mkdirSync(pluginDir, { recursive: true });
+  }
+
+  const safeName  = pluginName.replace(/[^a-zA-Z0-9_-]/g, '-');
+  const className = safeName.replace(/-([a-z])/g, (_, c) => c.toUpperCase()).replace(/^[a-z]/, c => c.toUpperCase());
+  const filePath  = path.join(pluginDir, `${safeName}.js`);
+
+  if (fs.existsSync(filePath)) {
+    throw new Error(`Plugin already exists: ${filePath}`);
+  }
+
+  const template = `/**
+ * Custom Ship Safe Agent: ${className}
+ *
+ * Drop this file in .ship-safe/agents/ to have it run automatically
+ * as part of every \`ship-safe audit\` or \`ship-safe watch --deep\`.
+ *
+ * The \`analyze(context)\` method receives:
+ *   context.rootPath   — absolute path to the project root
+ *   context.files      — array of absolute file paths to scan
+ *   context.recon      — recon data (frameworks, databases, auth patterns)
+ *   context.options    — CLI options passed to the scan
+ *
+ * Return an array of findings using \`createFinding()\`.
+ */
+
+import fs from 'fs';
+
+// BaseAgent and createFinding are available from ship-safe internals.
+// If ship-safe is installed globally, use:
+//   import { BaseAgent, createFinding } from 'ship-safe';
+// If running from source:
+//   import { BaseAgent, createFinding } from '../agents/base-agent.js';
+let BaseAgent, createFinding;
+try {
+  ({ BaseAgent, createFinding } = await import('ship-safe'));
+} catch {
+  // Running from source — adjust path if needed
+  ({ BaseAgent, createFinding } = await import('../agents/base-agent.js'));
+}
+
+export default class ${className} extends BaseAgent {
+  constructor() {
+    super();
+    this.name     = '${className}';
+    this.category = 'custom'; // or: secrets | injection | auth | config | api | llm
+  }
+
+  async analyze({ rootPath, files = [], recon, options }) {
+    const findings = [];
+
+    for (const file of files) {
+      // Skip files you don't care about
+      if (!/\\.(js|ts|jsx|tsx|py|rb|go|java)$/.test(file)) continue;
+
+      let content;
+      try {
+        content = fs.readFileSync(file, 'utf-8');
+      } catch {
+        continue;
+      }
+
+      const lines = content.split('\\n');
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (/ship-safe-ignore/i.test(line)) continue; // respect suppression comments
+
+        // Example: flag dangerous eval calls // ship-safe-ignore
+        if (/\\beval\\s*\\(/.test(line)) { // ship-safe-ignore — template example in plugin scaffold, not real eval
+          findings.push(createFinding({
+            rule:        '${safeName.toUpperCase().replace(/-/g, '_')}',
+            severity:    'high',          // critical | high | medium | low
+            title:       'Example finding from ${className}',
+            description: 'Describe the security risk here.',
+            file,
+            line:        i + 1,
+            matched:     line.trim().slice(0, 100),
+            category:    this.category,
+            remediation: 'Describe the fix here.',
+            confidence:  'medium',        // high | medium | low
+          }));
+        }
+      }
+    }
+
+    return findings;
+  }
+}
+`;
+
+  fs.writeFileSync(filePath, template, 'utf-8');
+  return filePath;
+}