ship-safe 7.0.0 → 8.0.0

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;
+}

package/cli/utils/scan-playbook.js

@@ -0,0 +1,312 @@
+/**
+ * Scan Playbook
+ * =============
+ *
+ * Hermes-inspired repo-specific intelligence that accumulates across scans
+ * and gets injected into the DeepAnalyzer system prompt as project context.
+ *
+ * After each scan, the playbook is updated with:
+ *   - Tech stack (frameworks, databases, runtimes)
+ *   - Auth patterns detected
+ *   - Known suppressed rules (from memory)
+ *   - Scan statistics (score trend, most common finding categories)
+ *   - Custom notes added by the user
+ *
+ * DeepAnalyzer reads the playbook and prepends it to every LLM call so the
+ * model has richer context than the generic system prompt alone — reducing
+ * both false positives and missed findings.
+ *
+ * PLAYBOOK FILE: .ship-safe/playbook.md
+ *
+ * USAGE:
+ *   import { ScanPlaybook } from '../utils/scan-playbook.js';
+ *
+ *   const playbook = new ScanPlaybook(rootPath);
+ *
+ *   // After each scan — update with latest recon + score
+ *   playbook.update(recon, scoreResult, suppressedRules);
+ *
+ *   // Get the context string to inject into LLM prompts
+ *   const context = playbook.getPromptContext();
+ *
+ *   // CLI
+ *   playbook.show()   — print current playbook
+ *   playbook.addNote(text) — add a custom note
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+const PLAYBOOK_DIR  = '.ship-safe';
+const PLAYBOOK_FILE = 'playbook.md';
+const HISTORY_FILE  = 'scan-history.json';
+
+/** Minimum number of scans before the playbook is considered reliable */
+const MIN_SCANS_FOR_PLAYBOOK = 2;
+
+export class ScanPlaybook {
+  constructor(rootPath) {
+    this.rootPath     = rootPath;
+    this.playbookDir  = path.join(rootPath, PLAYBOOK_DIR);
+    this.playbookPath = path.join(this.playbookDir, PLAYBOOK_FILE);
+    this.historyPath  = path.join(this.playbookDir, HISTORY_FILE);
+  }
+
+  // ===========================================================================
+  // UPDATE — called after every scan
+  // ===========================================================================
+
+  /**
+   * Update the playbook with the latest scan data.
+   *
+   * @param {object} recon        — from ReconAgent
+   * @param {object} scoreResult  — { score, grade, totalFindings, ... }
+   * @param {object[]} findings   — all findings (used for category frequency)
+   * @param {string[]} suppressedRules — rules currently in memory
+   */
+  update(recon, scoreResult, findings = [], suppressedRules = []) {
+    // Ensure dir exists
+    if (!fs.existsSync(this.playbookDir)) {
+      fs.mkdirSync(this.playbookDir, { recursive: true });
+    }
+
+    // Update scan history
+    const history = this._loadHistory();
+    history.push({
+      date:          new Date().toISOString(),
+      score:         scoreResult?.score ?? null,
+      grade:         scoreResult?.grade?.letter ?? scoreResult?.grade ?? null,
+      totalFindings: scoreResult?.totalFindings ?? findings.length,
+    });
+    // Keep last 50 entries
+    while (history.length > 50) history.shift();
+    this._saveHistory(history);
+
+    // Only update the playbook markdown after MIN_SCANS
+    if (history.length < MIN_SCANS_FOR_PLAYBOOK) return;
+
+    // Preserve user-written custom notes from existing playbook
+    const existingNotes = this._extractCustomNotes();
+
+    const content = this._buildPlaybook(recon, history, findings, suppressedRules, existingNotes);
+    fs.writeFileSync(this.playbookPath, content, 'utf-8');
+  }
+
+  // ===========================================================================
+  // READ — injected into LLM prompts
+  // ===========================================================================
+
+  /**
+   * Returns a compact context string to prepend to LLM system prompts.
+   * Empty string if the playbook doesn't exist yet.
+   */
+  getPromptContext() {
+    if (!fs.existsSync(this.playbookPath)) return '';
+
+    try {
+      const content = fs.readFileSync(this.playbookPath, 'utf-8');
+      // Extract the machine-readable section between <!-- context-start --> and <!-- context-end -->
+      const match = content.match(/<!-- context-start -->([\s\S]*?)<!-- context-end -->/);
+      if (match) return match[1].trim();
+
+      // Fallback: return first 1500 chars of playbook
+      return content.slice(0, 1500);
+    } catch {
+      return '';
+    }
+  }
+
+  /**
+   * Whether the playbook has enough data to be useful.
+   */
+  get isReady() {
+    return fs.existsSync(this.playbookPath);
+  }
+
+  // ===========================================================================
+  // CLI
+  // ===========================================================================
+
+  show() {
+    if (!fs.existsSync(this.playbookPath)) {
+      console.log('\n  No playbook yet. Run `ship-safe audit` at least twice to generate one.\n');
+      return;
+    }
+    const content = fs.readFileSync(this.playbookPath, 'utf-8');
+    console.log('\n' + content);
+  }
+
+  /**
+   * Append a custom user note to the playbook.
+   */
+  addNote(text) {
+    if (!fs.existsSync(this.playbookPath)) {
+      console.error('  No playbook yet — run ship-safe audit first.');
+      return;
+    }
+    const existing = fs.readFileSync(this.playbookPath, 'utf-8');
+    const timestamp = new Date().toISOString().slice(0, 10);
+    const noteSection = existing.includes('## Custom Notes')
+      ? existing.replace('## Custom Notes', `## Custom Notes\n\n- [${timestamp}] ${text}`)
+      : existing + `\n\n## Custom Notes\n\n- [${timestamp}] ${text}\n`;
+    fs.writeFileSync(this.playbookPath, noteSection, 'utf-8');
+    console.log('  Note added to playbook.');
+  }
+
+  // ===========================================================================
+  // INTERNALS
+  // ===========================================================================
+
+  _loadHistory() {
+    try {
+      if (fs.existsSync(this.historyPath)) {
+        return JSON.parse(fs.readFileSync(this.historyPath, 'utf-8'));
+      }
+    } catch { /* start fresh */ }
+    return [];
+  }
+
+  _saveHistory(history) {
+    try {
+      fs.writeFileSync(this.historyPath, JSON.stringify(history, null, 2), 'utf-8');
+    } catch { /* non-fatal */ }
+  }
+
+  _extractCustomNotes() {
+    if (!fs.existsSync(this.playbookPath)) return '';
+    try {
+      const content = fs.readFileSync(this.playbookPath, 'utf-8');
+      const match = content.match(/## Custom Notes([\s\S]*)$/);
+      return match ? match[0] : '';
+    } catch { return ''; }
+  }
+
+  _buildPlaybook(recon, history, findings, suppressedRules, customNotes) {
+    const repoName  = path.basename(this.rootPath);
+    const lastScore = history.at(-1)?.score ?? '?';
+    const lastGrade = history.at(-1)?.grade ?? '?';
+    const scanCount = history.length;
+    const avgScore  = history.length > 0
+      ? Math.round(history.reduce((s, h) => s + (h.score ?? 0), 0) / history.length)
+      : 0;
+
+    // Score trend
+    const trend = history.length >= 2
+      ? (history.at(-1).score ?? 0) - (history.at(-2).score ?? 0)
+      : 0;
+    const trendStr = trend > 0 ? `↑ +${trend}` : trend < 0 ? `↓ ${trend}` : '→ stable';
+
+    // Category frequency
+    const catCounts = {};
+    for (const f of findings) {
+      catCounts[f.category || 'other'] = (catCounts[f.category || 'other'] || 0) + 1;
+    }
+    const topCategories = Object.entries(catCounts)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 5)
+      .map(([cat, count]) => `${cat} (${count})`)
+      .join(', ') || 'none';
+
+    // Tech stack
+    const frameworks = recon?.frameworks?.length ? recon.frameworks.join(', ') : 'unknown';
+    const databases  = recon?.databases?.length  ? recon.databases.join(', ')  : 'none detected';
+    const authPat    = recon?.authPatterns?.length ? recon.authPatterns.join(', ') : 'none detected';
+    const runtime    = recon?.runtime || 'unknown';
+    const packageManager = recon?.packageManager || 'unknown';
+    const language   = recon?.language || recon?.primaryLanguage || 'unknown';
+
+    const suppressedSection = suppressedRules.length > 0
+      ? suppressedRules.map(r => `- ${r}`).join('\n')
+      : '- none';
+
+    const historyTable = history.slice(-10).map(h =>
+      `| ${h.date.slice(0, 10)} | ${h.score ?? '?'}/100 | ${h.grade ?? '?'} | ${h.totalFindings ?? '?'} |`
+    ).join('\n');
+
+    return `# Ship Safe Playbook — ${repoName}
+
+> Auto-generated after ${scanCount} scan(s). Do not edit the section between the
+> \`<!-- context-start -->\` and \`<!-- context-end -->\` markers — it is overwritten on each scan.
+> Add custom notes at the bottom under **Custom Notes**.
+
+<!-- context-start -->
+REPO: ${repoName}
+LANGUAGE: ${language}
+RUNTIME: ${runtime}
+PACKAGE_MANAGER: ${packageManager}
+FRAMEWORKS: ${frameworks}
+DATABASES: ${databases}
+AUTH_PATTERNS: ${authPat}
+LAST_SCORE: ${lastScore}/100 (${lastGrade})
+TREND: ${trendStr}
+AVG_SCORE: ${avgScore}/100 over ${scanCount} scans
+TOP_FINDING_CATEGORIES: ${topCategories}
+SUPPRESSED_RULES: ${suppressedRules.join(', ') || 'none'}
+SCANS_COMPLETED: ${scanCount}
+<!-- context-end -->
+
+## Security Profile
+
+| Property | Value |
+|----------|-------|
+| Language | ${language} |
+| Runtime  | ${runtime} |
+| Frameworks | ${frameworks} |
+| Databases | ${databases} |
+| Auth patterns | ${authPat} |
+
+## Score History (last 10 scans)
+
+| Date | Score | Grade | Findings |
+|------|-------|-------|----------|
+${historyTable}
+
+**Current:** ${lastScore}/100 ${lastGrade} (${trendStr})
+
+## Known Suppressions
+
+The following rules are currently suppressed in \`.ship-safe/memory.json\`:
+
+${suppressedSection}
+
+## Top Finding Categories
+
+${topCategories}
+
+${customNotes || '## Custom Notes\n\n_Add project-specific context here with: `ship-safe playbook add-note "..."`_\n'}
+`;
+  }
+}
+
+// =============================================================================
+// CLI COMMAND  (ship-safe playbook)
+// =============================================================================
+
+import chalk from 'chalk';
+
+export async function playbookCommand(subcommand, args = [], options = {}) {
+  const rootPath = path.resolve(options.path || '.');
+  const playbook = new ScanPlaybook(rootPath);
+
+  switch (subcommand) {
+    case 'show':
+    case undefined:
+      playbook.show();
+      break;
+
+    case 'add-note': {
+      const text = args.join(' ').trim();
+      if (!text) {
+        console.error('  Usage: ship-safe playbook add-note "your note here"');
+        process.exit(1);
+      }
+      playbook.addNote(text);
+      break;
+    }
+
+    default:
+      console.error(`  Unknown playbook subcommand: ${subcommand}`);
+      console.log('  Usage: ship-safe playbook [show|add-note "..."]');
+      process.exit(1);
+  }
+}