ship-safe 6.4.0 → 8.0.0

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

package/cli/utils/security-memory.js

@@ -0,0 +1,296 @@
+/**
+ * Security Memory
+ * ================
+ *
+ * Hermes-inspired persistent memory for false-positive learning.
+ *
+ * After deep analysis confirms a finding is a false-positive, the verdict is
+ * written to `.ship-safe/memory.json`. On the next scan, the SecurityMemory
+ * filter runs before scoring and suppresses any finding whose (rule + file +
+ * matched-snippet hash) appears in memory — avoiding the same LLM call twice.
+ *
+ * Memory entries are per-repo (stored in `.ship-safe/` inside the project
+ * root), so suppressions don't bleed across unrelated projects.
+ *
+ * USAGE:
+ *   import { SecurityMemory } from '../utils/security-memory.js';
+ *
+ *   const memory = new SecurityMemory(rootPath);
+ *
+ *   // After deep analysis — auto-learn false positives
+ *   memory.learnFromAnalysis(findings);
+ *
+ *   // Filter findings against memory before scoring
+ *   const { kept, suppressed } = memory.filter(findings);
+ *
+ *   // Manual suppression (from `ship-safe memory add`)
+ *   memory.suppress(finding, 'Not reachable from user input');
+ *
+ *   // CLI commands
+ *   memory.list()   → all suppressed entries
+ *   memory.forget(id) → remove one entry
+ *   memory.clear()  → wipe all entries
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { createHash } from 'crypto';
+
+const MEMORY_DIR  = '.ship-safe';
+const MEMORY_FILE = 'memory.json';
+
+/** How many chars of the matched snippet to hash (stable across reformatting) */
+const SNIPPET_HASH_LEN = 120;
+
+export class SecurityMemory {
+  constructor(rootPath) {
+    this.rootPath   = rootPath;
+    this.memoryDir  = path.join(rootPath, MEMORY_DIR);
+    this.memoryPath = path.join(this.memoryDir, MEMORY_FILE);
+    this._data      = null; // lazy-loaded
+  }
+
+  // ===========================================================================
+  // PERSISTENCE
+  // ===========================================================================
+
+  _load() {
+    if (this._data) return this._data;
+
+    try {
+      if (fs.existsSync(this.memoryPath)) {
+        this._data = JSON.parse(fs.readFileSync(this.memoryPath, 'utf-8'));
+      }
+    } catch { /* corrupt file — start fresh */ }
+
+    if (!this._data || typeof this._data !== 'object') {
+      this._data = { version: 1, entries: [] };
+    }
+    if (!Array.isArray(this._data.entries)) {
+      this._data.entries = [];
+    }
+
+    return this._data;
+  }
+
+  _save() {
+    try {
+      if (!fs.existsSync(this.memoryDir)) {
+        fs.mkdirSync(this.memoryDir, { recursive: true });
+      }
+      fs.writeFileSync(this.memoryPath, JSON.stringify(this._data, null, 2), 'utf-8');
+    } catch { /* non-fatal */ }
+  }
+
+  // ===========================================================================
+  // KEY GENERATION
+  // ===========================================================================
+
+  /**
+   * Generate a stable key for a finding.
+   * Key = SHA-256(rule + file-basename + first N chars of matched).
+   * Deliberately excludes line number so the suppression survives minor refactors.
+   */
+  static keyOf(finding) {
+    const rule     = finding.rule    || '';
+    const file     = finding.file    ? path.basename(finding.file) : '';
+    const snippet  = (finding.matched || finding.title || '').slice(0, SNIPPET_HASH_LEN);
+    return createHash('sha256').update(`${rule}::${file}::${snippet}`).digest('hex').slice(0, 16);
+  }
+
+  // ===========================================================================
+  // CORE API
+  // ===========================================================================
+
+  /**
+   * Learn from deep analysis results.
+   * Any finding with exploitability === 'false_positive' is auto-added to memory.
+   *
+   * @param {object[]} findings — findings array (with deepAnalysis attached)
+   * @returns {number} — count of new entries added
+   */
+  learnFromAnalysis(findings) {
+    const data = this._load();
+    const existingKeys = new Set(data.entries.map(e => e.key));
+    let added = 0;
+
+    for (const f of findings) {
+      if (f.deepAnalysis?.exploitability !== 'false_positive') continue;
+
+      const key = SecurityMemory.keyOf(f);
+      if (existingKeys.has(key)) continue;
+
+      data.entries.push({
+        key,
+        rule:          f.rule,
+        file:          f.file ? path.basename(f.file) : '',
+        title:         f.title,
+        severity:      f.severity,
+        reason:        f.deepAnalysis.reasoning || 'Auto-detected false positive by deep analysis',
+        source:        'deep-analysis',
+        suppressedAt:  new Date().toISOString(),
+      });
+
+      existingKeys.add(key);
+      added++;
+    }
+
+    if (added > 0) this._save();
+    return added;
+  }
+
+  /**
+   * Manually suppress a finding with a reason.
+   *
+   * @param {object} finding
+   * @param {string} reason
+   * @returns {string} — the key added
+   */
+  suppress(finding, reason = '') {
+    const data = this._load();
+    const key  = SecurityMemory.keyOf(finding);
+
+    if (data.entries.some(e => e.key === key)) {
+      return key; // already suppressed
+    }
+
+    data.entries.push({
+      key,
+      rule:         finding.rule,
+      file:         finding.file ? path.basename(finding.file) : '',
+      title:        finding.title,
+      severity:     finding.severity,
+      reason:       reason || 'Manually suppressed',
+      source:       'manual',
+      suppressedAt: new Date().toISOString(),
+    });
+
+    this._save();
+    return key;
+  }
+
+  /**
+   * Filter findings against memory.
+   * Returns { kept, suppressed } — suppressed findings get a .memorySuppressed flag.
+   *
+   * @param {object[]} findings
+   * @returns {{ kept: object[], suppressed: object[], suppressedCount: number }}
+   */
+  filter(findings) {
+    const data  = this._load();
+    if (data.entries.length === 0) {
+      return { kept: findings, suppressed: [], suppressedCount: 0 };
+    }
+
+    const keySet = new Set(data.entries.map(e => e.key));
+    const kept       = [];
+    const suppressed = [];
+
+    for (const f of findings) {
+      const key    = SecurityMemory.keyOf(f);
+      const entry  = data.entries.find(e => e.key === key);
+      if (entry) {
+        suppressed.push({ ...f, memorySuppressed: true, suppressionReason: entry.reason });
+      } else {
+        kept.push(f);
+      }
+    }
+
+    return { kept, suppressed, suppressedCount: suppressed.length };
+  }
+
+  /**
+   * Remove a single entry by key.
+   */
+  forget(key) {
+    const data = this._load();
+    const before = data.entries.length;
+    data.entries = data.entries.filter(e => e.key !== key);
+    const removed = before - data.entries.length;
+    if (removed > 0) this._save();
+    return removed;
+  }
+
+  /**
+   * Wipe all memory entries.
+   */
+  clear() {
+    this._data = { version: 1, entries: [] };
+    this._save();
+  }
+
+  /**
+   * Return all entries.
+   */
+  list() {
+    return this._load().entries;
+  }
+
+  /**
+   * Count of suppressed entries.
+   */
+  get size() {
+    return this._load().entries.length;
+  }
+}
+
+// =============================================================================
+// CLI COMMAND  (ship-safe memory)
+// =============================================================================
+
+import chalk from 'chalk';
+import * as output from './output.js';
+
+export async function memoryCommand(subcommand, args = [], options = {}) {
+  const rootPath = path.resolve(options.path || '.');
+  const memory   = new SecurityMemory(rootPath);
+
+  switch (subcommand) {
+    case 'list':
+    case undefined: {
+      const entries = memory.list();
+      if (entries.length === 0) {
+        console.log('\n  No suppressed findings in memory.\n');
+        return;
+      }
+      console.log(`\n  ${chalk.cyan.bold('Security Memory')} — ${entries.length} suppressed finding(s)\n`);
+      for (const e of entries) {
+        const sev = e.severity === 'critical' ? chalk.red.bold(e.severity)
+          : e.severity === 'high'     ? chalk.yellow(e.severity)
+          : chalk.gray(e.severity);
+        console.log(`  ${chalk.gray(e.key)}  ${sev}  ${chalk.white(e.rule)}`);
+        console.log(`    ${chalk.gray('File:')} ${e.file}  ${chalk.gray('Source:')} ${e.source}  ${chalk.gray('Date:')} ${e.suppressedAt.slice(0, 10)}`);
+        console.log(`    ${chalk.gray('Reason:')} ${e.reason}`);
+        console.log();
+      }
+      break;
+    }
+
+    case 'forget': {
+      const key = args[0];
+      if (!key) {
+        output.error('Usage: ship-safe memory forget <key>');
+        process.exit(1);
+      }
+      const removed = memory.forget(key);
+      if (removed) {
+        console.log(chalk.green(`  Removed memory entry: ${key}`));
+      } else {
+        console.log(chalk.yellow(`  Key not found in memory: ${key}`));
+      }
+      break;
+    }
+
+    case 'clear': {
+      const before = memory.size;
+      memory.clear();
+      console.log(chalk.green(`  Cleared ${before} memory entry/entries.`));
+      break;
+    }
+
+    default:
+      output.error(`Unknown memory subcommand: ${subcommand}`);
+      console.log('  Usage: ship-safe memory [list|forget <key>|clear]');
+      process.exit(1);
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ship-safe",
-  "version": "6.4.0",
-  "description": "AI-powered multi-agent security platform. 18 agents scan 80+ attack classes with LLM-powered deep analysis. Red team your code before attackers do.",
+  "version": "8.0.0",
+  "description": "AI-powered multi-agent security platform. 22 agents scan 80+ attack classes including Hermes Agent deployments (ASI-01–ASI-10), tool registry poisoning, function-call injection, skill permission drift, and agent attestation. Ship Safe × Hermes Agent.",
   "main": "cli/index.js",
   "bin": {
     "ship-safe": "cli/bin/ship-safe.js"