ship-safe 4.0.0 → 4.1.0

package/README.md

@@ -92,6 +92,7 @@ npx ship-safe audit .
 - `--html [file]` — custom HTML report path (default: `ship-safe-report.html`)
 - `--no-deps` — skip dependency audit
 - `--no-ai` — skip AI classification
+- `--no-cache` — force full rescan (ignore cached results)
 
 ---
 
@@ -181,6 +182,54 @@ npx ship-safe mcp
 
 ---
 
+## Claude Code Plugin
+
+Use Ship Safe directly inside Claude Code — no CLI needed:
+
+```bash
+claude plugin add github:asamassekou10/ship-safe
+```
+
+| Command | Description |
+|---------|-------------|
+| `/ship-safe` | Full security audit — 12 agents, remediation plan, auto-fix |
+| `/ship-safe-scan` | Quick scan for leaked secrets |
+| `/ship-safe-score` | Security health score (0-100) |
+
+Claude interprets the results, explains findings in plain language, and can fix issues directly in your codebase.
+
+---
+
+## Incremental Scanning
+
+Ship Safe caches file hashes and findings in `.ship-safe/context.json`. On subsequent runs, only changed files are re-scanned — unchanged files reuse cached results.
+
+```
+✔ [Phase 1/4] Secrets: 41 found (0 changed, 313 cached)
+```
+
+- **~40% faster** on repeated scans
+- **Auto-invalidation** — cache expires after 24 hours or when ship-safe updates
+- **`--no-cache`** — force a full rescan anytime
+
+The cache is stored in `.ship-safe/` which is automatically excluded from scans.
+
+---
+
+## Smart `.gitignore` Handling
+
+Ship Safe respects your `.gitignore` for build output, caches, and vendor directories — but **always scans security-sensitive files** even if gitignored:
+
+| Skipped (gitignore respected) | Always scanned (gitignore overridden) |
+|-------------------------------|---------------------------------------|
+| `node_modules/`, `dist/`, `build/` | `.env`, `.env.local`, `.env.production` |
+| `*.log`, `*.pkl`, vendor dirs | `*.pem`, `*.key`, `*.p12` |
+| Cache directories, IDE files | `credentials.json`, `*.secret` |
+
+Why? Files like `.env` are gitignored *because* they contain secrets — which is exactly what a security scanner should catch.
+
+---
+
 ## Multi-LLM Support
 
 Ship Safe supports multiple AI providers for classification:

package/cli/agents/base-agent.js

@@ -18,7 +18,7 @@
 import fs from 'fs';
 import path from 'path';
 import fg from 'fast-glob';
-import { SKIP_DIRS, SKIP_EXTENSIONS, MAX_FILE_SIZE } from '../utils/patterns.js';
+import { SKIP_DIRS, SKIP_EXTENSIONS, MAX_FILE_SIZE, loadGitignorePatterns } from '../utils/patterns.js';
 
 // =============================================================================
 // FINDING FACTORY
@@ -95,6 +95,10 @@ export class BaseAgent {
   async discoverFiles(rootPath, extraGlobs = ['**/*']) {
     const globIgnore = Array.from(SKIP_DIRS).map(dir => `**/${dir}/**`);
 
+    // Respect .gitignore patterns
+    const gitignoreGlobs = loadGitignorePatterns(rootPath);
+    globIgnore.push(...gitignoreGlobs);
+
     // Load .ship-safeignore patterns
     const ignorePatterns = this._loadIgnorePatterns(rootPath);
     for (const p of ignorePatterns) {
@@ -145,6 +149,15 @@ export class BaseAgent {
     }
   }
 
+  /**
+   * Get the files this agent should scan.
+   * If incremental scanning is active (changedFiles in context), returns only changed files.
+   * Otherwise returns all files. Agents that need the full file list can use context.files directly.
+   */
+  getFilesToScan(context) {
+    return context.changedFiles || context.files;
+  }
+
   /**
    * Read a file safely, returning null on failure.
    */

package/cli/agents/orchestrator.js

@@ -81,6 +81,11 @@ export class Orchestrator {
 
     // ── 4. Run each agent ─────────────────────────────────────────────────────
     const context = { rootPath: absolutePath, files, recon, options };
+
+    // Pass changedFiles for incremental scanning (agents can use this to scope analysis)
+    if (options.changedFiles) {
+      context.changedFiles = options.changedFiles;
+    }
     const agentResults = [];
     let allFindings = [];
 

package/cli/bin/ship-safe.js

@@ -82,6 +82,7 @@ program
   .option('--json', 'Output results as JSON (useful for CI)')
   .option('--sarif', 'Output results in SARIF format (for GitHub Code Scanning)')
   .option('--include-tests', 'Also scan test files (excluded by default to reduce false positives)')
+  .option('--no-cache', 'Force full rescan (ignore cached results)')
   .action(scanCommand);
 
 // -----------------------------------------------------------------------------
@@ -190,6 +191,7 @@ program
   .option('--html [file]', 'HTML report path (default: ship-safe-report.html)')
   .option('--no-deps', 'Skip dependency audit')
   .option('--no-ai', 'Skip AI classification')
+  .option('--no-cache', 'Force full rescan (ignore cached results)')
   .option('-v, --verbose', 'Verbose output')
   .action(auditCommand);
 

package/cli/commands/audit.js

@@ -29,9 +29,11 @@ import {
   SECURITY_PATTERNS,
   SKIP_DIRS,
   SKIP_EXTENSIONS,
-  MAX_FILE_SIZE
+  MAX_FILE_SIZE,
+  loadGitignorePatterns
 } from '../utils/patterns.js';
 import { isHighEntropyMatch, getConfidence } from '../utils/entropy.js';
+import { CacheManager } from '../utils/cache-manager.js';
 
 // =============================================================================
 // CONSTANTS
@@ -84,16 +86,36 @@ export async function auditCommand(targetPath = '.', options = {}) {
     console.log();
   }
 
+  // ── Cache Layer ──────────────────────────────────────────────────────────
+  const useCache = options.cache !== false;
+  const cache = new CacheManager(absolutePath);
+  let cacheData = useCache ? cache.load() : null;
+  let cacheDiff = null;
+  let allFiles = [];
+
   // ── Phase 1: Secret Scan ──────────────────────────────────────────────────
   const secretSpinner = machineOutput ? null : ora({ text: chalk.white('[Phase 1/4] Scanning for secrets...'), color: 'cyan' }).start();
   let secretFindings = [];
   let filesScanned = 0;
 
   try {
-    const files = await findFiles(absolutePath);
-    filesScanned = files.length;
+    allFiles = await findFiles(absolutePath);
+    filesScanned = allFiles.length;
+
+    // Determine which files need scanning (incremental if cache exists)
+    let filesToScan = allFiles;
+    let cachedSecretFindings = [];
+
+    if (cacheData) {
+      cacheDiff = cache.diff(allFiles);
+      filesToScan = cacheDiff.changedFiles;
+      // Reuse cached findings for unchanged files (secrets only)
+      cachedSecretFindings = cacheDiff.cachedFindings.filter(
+        f => f.category === 'secrets' || f.category === 'secret'
+      );
+    }
 
-    for (const file of files) {
+    for (const file of filesToScan) {
       const fileResults = scanFileForSecrets(file);
       for (const f of fileResults) {
         secretFindings.push({
@@ -112,10 +134,17 @@ export async function auditCommand(targetPath = '.', options = {}) {
       }
     }
 
+    // Merge with cached findings for unchanged files
+    secretFindings = [...secretFindings, ...cachedSecretFindings];
+
+    const cacheNote = cacheDiff && cacheDiff.changedFiles.length < allFiles.length
+      ? ` (${cacheDiff.changedFiles.length} changed, ${cacheDiff.unchangedCount} cached)`
+      : '';
+
     if (secretSpinner) secretSpinner.succeed(
       secretFindings.length === 0
-        ? chalk.green('[Phase 1/4] Secrets: clean')
-        : chalk.red(`[Phase 1/4] Secrets: ${secretFindings.length} found`)
+        ? chalk.green(`[Phase 1/4] Secrets: clean${cacheNote}`)
+        : chalk.red(`[Phase 1/4] Secrets: ${secretFindings.length} found${cacheNote}`)
     );
   } catch (err) {
     if (secretSpinner) secretSpinner.fail(chalk.red(`[Phase 1/4] Secret scan failed: ${err.message}`));
@@ -130,7 +159,12 @@ export async function auditCommand(targetPath = '.', options = {}) {
   try {
     const orchestrator = buildOrchestrator();
     // Suppress individual agent spinners by using quiet mode
-    const results = await orchestrator.runAll(absolutePath, { quiet: true });
+    // Pass changedFiles for incremental scanning if cache is valid
+    const orchestratorOpts = { quiet: true };
+    if (cacheDiff && cacheDiff.changedFiles.length < allFiles.length) {
+      orchestratorOpts.changedFiles = cacheDiff.changedFiles;
+    }
+    const results = await orchestrator.runAll(absolutePath, orchestratorOpts);
     recon = results.recon;
     agentFindings = results.findings;
     agentResults = results.agentResults;
@@ -207,6 +241,21 @@ export async function auditCommand(targetPath = '.', options = {}) {
     }
   }
 
+  // ── Save Cache ──────────────────────────────────────────────────────────
+  if (useCache) {
+    try {
+      // Merge agent findings back for cache (secret + agent findings from changed files)
+      // plus cached findings from unchanged files
+      const cachedAgentFindings = cacheData && cacheDiff
+        ? cacheDiff.cachedFindings.filter(f => f.category !== 'secrets' && f.category !== 'secret')
+        : [];
+      const allFindingsForCache = [...secretFindings, ...agentFindings, ...cachedAgentFindings];
+      cache.save(allFiles, deduplicateFindings(allFindingsForCache), recon, scoreResult);
+    } catch {
+      // Silent — caching should never break a scan
+    }
+  }
+
   // ── Build Remediation Plan ────────────────────────────────────────────────
   const remediationPlan = buildRemediationPlan(filteredFindings, depVulns, absolutePath);
 
@@ -230,26 +279,28 @@ export async function auditCommand(targetPath = '.', options = {}) {
     console.log(chalk.cyan(`  Full report: ${chalk.white.bold(htmlPath)}`));
   }
 
-  // ── Policy Violations ────────────────────────────────────────────────────
-  const violations = policy.evaluate(scoreResult, filteredFindings);
-  if (violations.length > 0) {
-    console.log();
-    console.log(chalk.red.bold('  Policy Violations:'));
-    for (const v of violations.slice(0, 5)) {
-      console.log(chalk.red(`    ✗ ${v.message}`));
+  if (!machineOutput) {
+    // ── Policy Violations ──────────────────────────────────────────────────
+    const violations = policy.evaluate(scoreResult, filteredFindings);
+    if (violations.length > 0) {
+      console.log();
+      console.log(chalk.red.bold('  Policy Violations:'));
+      for (const v of violations.slice(0, 5)) {
+        console.log(chalk.red(`    ✗ ${v.message}`));
+      }
     }
-  }
 
-  // ── Trend ─────────────────────────────────────────────────────────────────
-  const trend = scoringEngine.getTrend(absolutePath, scoreResult.score);
-  if (trend) {
-    const arrow = trend.diff > 0 ? chalk.green('↑') : trend.diff < 0 ? chalk.red('↓') : chalk.gray('→');
-    console.log(chalk.gray(`  Trend: ${trend.previousScore} → ${trend.currentScore} ${arrow} (${trend.diff > 0 ? '+' : ''}${trend.diff})`));
-  }
+    // ── Trend ───────────────────────────────────────────────────────────────
+    const trend = scoringEngine.getTrend(absolutePath, scoreResult.score);
+    if (trend) {
+      const arrow = trend.diff > 0 ? chalk.green('↑') : trend.diff < 0 ? chalk.red('↓') : chalk.gray('→');
+      console.log(chalk.gray(`  Trend: ${trend.previousScore} → ${trend.currentScore} ${arrow} (${trend.diff > 0 ? '+' : ''}${trend.diff})`));
+    }
 
-  console.log();
-  console.log(chalk.cyan('═'.repeat(60)));
-  console.log();
+    console.log();
+    console.log(chalk.cyan('═'.repeat(60)));
+    console.log();
+  }
 
   process.exit(scoreResult.score >= 75 ? 0 : 1);
 }
@@ -495,6 +546,10 @@ function outputSARIF(findings, rootPath) {
 async function findFiles(rootPath) {
   const globIgnore = Array.from(SKIP_DIRS).map(dir => `**/${dir}/**`);
 
+  // Respect .gitignore patterns
+  const gitignoreGlobs = loadGitignorePatterns(rootPath);
+  globIgnore.push(...gitignoreGlobs);
+
   // Load .ship-safeignore
   const ignorePath = path.join(rootPath, '.ship-safeignore');
   if (fs.existsSync(ignorePath)) {

package/cli/commands/scan.js

@@ -30,10 +30,12 @@ import {
   SKIP_DIRS,
   SKIP_EXTENSIONS,
   TEST_FILE_PATTERNS,
-  MAX_FILE_SIZE
+  MAX_FILE_SIZE,
+  loadGitignorePatterns
 } from '../utils/patterns.js';
 import { isHighEntropyMatch, getConfidence } from '../utils/entropy.js';
 import * as output from '../utils/output.js';
+import { CacheManager } from '../utils/cache-manager.js';
 
 // =============================================================================
 // CUSTOM PATTERNS (.ship-safe.json)
@@ -110,13 +112,49 @@ export async function scanCommand(targetPath = '.', options = {}) {
   try {
     // Find all files
     const files = await findFiles(absolutePath, ignorePatterns, options);
-    spinner.text = `Scanning ${files.length} files...`;
+
+    // Cache: determine which files changed
+    const useCache = options.cache !== false;
+    const cache = new CacheManager(absolutePath);
+    const cacheData = useCache ? cache.load() : null;
+    let filesToScan = files;
+    let cacheDiff = null;
+    const cachedResults = [];
+
+    if (cacheData) {
+      cacheDiff = cache.diff(files);
+      filesToScan = cacheDiff.changedFiles;
+
+      // Group cached findings by file
+      const cachedByFile = {};
+      for (const f of cacheDiff.cachedFindings) {
+        if (!cachedByFile[f.file]) cachedByFile[f.file] = [];
+        cachedByFile[f.file].push({
+          line: f.line,
+          column: f.column,
+          matched: f.matched,
+          patternName: f.rule || f.title,
+          severity: f.severity,
+          confidence: f.confidence,
+          description: f.description,
+          category: f.category,
+        });
+      }
+      for (const [file, findings] of Object.entries(cachedByFile)) {
+        cachedResults.push({ file, findings });
+      }
+    }
+
+    const cacheNote = cacheDiff && filesToScan.length < files.length
+      ? ` (${filesToScan.length} changed, ${cacheDiff.unchangedCount} cached)`
+      : '';
+    spinner.text = `Scanning ${filesToScan.length} files${cacheNote}...`;
 
     // Scan each file
     const results = [];
     let scannedCount = 0;
 
-    for (const file of files) {
+    for (const file of filesToScan) {
       const findings = await scanFile(file, allPatterns);
       if (findings.length > 0) {
         results.push({ file, findings });
@@ -124,7 +162,36 @@ export async function scanCommand(targetPath = '.', options = {}) {
 
       scannedCount++;
       if (options.verbose) {
-        spinner.text = `Scanned ${scannedCount}/${files.length}: ${path.relative(absolutePath, file)}`;
+        spinner.text = `Scanned ${scannedCount}/${filesToScan.length}: ${path.relative(absolutePath, file)}`;
+      }
+    }
+
+    // Merge with cached results
+    const allResults = [...results, ...cachedResults];
+
+    // Save cache
+    if (useCache) {
+      try {
+        const allFindings = [];
+        for (const { file, findings } of allResults) {
+          for (const f of findings) {
+            allFindings.push({
+              file,
+              line: f.line,
+              column: f.column,
+              severity: f.severity,
+              category: f.category || 'secrets',
+              rule: f.patternName,
+              title: f.patternName,
+              description: f.description,
+              matched: f.matched,
+              confidence: f.confidence,
+            });
+          }
+        }
+        cache.save(files, allFindings, null, null);
+      } catch {
+        // Silent
       }
     }
 
@@ -132,15 +199,15 @@ export async function scanCommand(targetPath = '.', options = {}) {
 
     // Output results
     if (options.sarif) {
-      outputSARIF(results, absolutePath);
+      outputSARIF(allResults, absolutePath);
     } else if (options.json) {
-      outputJSON(results, files.length);
+      outputJSON(allResults, files.length);
     } else {
-      outputPretty(results, files.length, absolutePath);
+      outputPretty(allResults, files.length, absolutePath);
     }
 
     // Exit with appropriate code
-    const hasFindings = results.length > 0;
+    const hasFindings = allResults.length > 0;
     process.exit(hasFindings ? 1 : 0);
 
   } catch (err) {
@@ -204,6 +271,10 @@ async function findFiles(rootPath, ignorePatterns, options = {}) {
   // Build ignore patterns from SKIP_DIRS
   const globIgnore = Array.from(SKIP_DIRS).map(dir => `**/${dir}/**`);
 
+  // Respect .gitignore patterns
+  const gitignoreGlobs = loadGitignorePatterns(rootPath);
+  globIgnore.push(...gitignoreGlobs);
+
   // Find all files
   const files = await fg('**/*', {
     cwd: rootPath,

package/cli/index.js

@@ -46,5 +46,8 @@ export { SBOMGenerator } from './agents/sbom-generator.js';
 export { PolicyEngine } from './agents/policy-engine.js';
 export { HTMLReporter } from './agents/html-reporter.js';
 
+// ── Caching ──────────────────────────────────────────────────────────────────
+export { CacheManager } from './utils/cache-manager.js';
+
 // ── LLM Providers ─────────────────────────────────────────────────────────────
 export { createProvider, autoDetectProvider } from './providers/llm-provider.js';

package/cli/utils/cache-manager.js

@@ -0,0 +1,258 @@
+/**
+ * Cache Manager
+ * =============
+ *
+ * Provides incremental scanning by caching file hashes and findings.
+ * On subsequent runs, only changed files are re-scanned.
+ *
+ * Cache location: .ship-safe/context.json
+ *
+ * USAGE:
+ *   import { CacheManager } from './cache-manager.js';
+ *   const cache = new CacheManager(rootPath);
+ *   const { changedFiles, cachedFindings } = await cache.getChangedFiles(currentFiles);
+ *   // ... scan only changedFiles ...
+ *   cache.save(allFiles, allFindings, recon, scoreResult);
+ */
+
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+// Read version from package.json
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_VERSION = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf8')).version;
+
+// Cache TTL: 24 hours
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+export class CacheManager {
+  /**
+   * @param {string} rootPath — Absolute path to project root
+   */
+  constructor(rootPath) {
+    this.rootPath = rootPath;
+    this.cacheDir = path.join(rootPath, '.ship-safe');
+    this.cachePath = path.join(this.cacheDir, 'context.json');
+    this.cache = null;
+  }
+
+  /**
+   * Load the cache from disk. Returns null if cache is missing, expired, or invalid.
+   */
+  load() {
+    try {
+      if (!fs.existsSync(this.cachePath)) return null;
+
+      const raw = fs.readFileSync(this.cachePath, 'utf-8');
+      const cache = JSON.parse(raw);
+
+      // Version mismatch — patterns may have changed
+      if (cache.version !== PACKAGE_VERSION) return null;
+
+      // TTL expired
+      const age = Date.now() - new Date(cache.generatedAt).getTime();
+      if (age > CACHE_TTL_MS) return null;
+
+      this.cache = cache;
+      return cache;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Compute SHA-256 hash of a file's contents.
+   */
+  hashFile(filePath) {
+    try {
+      const content = fs.readFileSync(filePath);
+      return crypto.createHash('sha256').update(content).digest('hex');
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Compare current files against cached file index to find what changed.
+   *
+   * @param {string[]} currentFiles — Array of absolute file paths
+   * @returns {{ changedFiles: string[], cachedFindings: object[], unchangedCount: number, newCount: number, modifiedCount: number, deletedCount: number }}
+   */
+  diff(currentFiles) {
+    if (!this.cache || !this.cache.fileIndex) {
+      return {
+        changedFiles: currentFiles,
+        cachedFindings: [],
+        unchangedCount: 0,
+        newCount: currentFiles.length,
+        modifiedCount: 0,
+        deletedCount: 0,
+      };
+    }
+
+    const cachedIndex = this.cache.fileIndex;
+    const cachedFindings = this.cache.lastFindings || {};
+    const changedFiles = [];
+    const reusedFindings = [];
+    let unchangedCount = 0;
+    let newCount = 0;
+    let modifiedCount = 0;
+
+    const currentSet = new Set(currentFiles);
+
+    for (const file of currentFiles) {
+      const relPath = path.relative(this.rootPath, file).replace(/\\/g, '/');
+      const cached = cachedIndex[relPath];
+
+      if (!cached) {
+        // New file — needs scanning
+        changedFiles.push(file);
+        newCount++;
+        continue;
+      }
+
+      // Quick size check before expensive hash
+      try {
+        const stats = fs.statSync(file);
+        if (stats.size !== cached.size) {
+          changedFiles.push(file);
+          modifiedCount++;
+          continue;
+        }
+      } catch {
+        changedFiles.push(file);
+        modifiedCount++;
+        continue;
+      }
+
+      // Hash check
+      const currentHash = this.hashFile(file);
+      if (currentHash !== cached.hash) {
+        changedFiles.push(file);
+        modifiedCount++;
+        continue;
+      }
+
+      // File unchanged — reuse cached findings
+      unchangedCount++;
+      if (cachedFindings[relPath]) {
+        // Restore absolute paths for cached findings
+        for (const finding of cachedFindings[relPath]) {
+          reusedFindings.push({ ...finding, file });
+        }
+      }
+    }
+
+    // Count deleted files (in cache but not in current)
+    const currentRelPaths = new Set(
+      currentFiles.map(f => path.relative(this.rootPath, f).replace(/\\/g, '/'))
+    );
+    const deletedCount = Object.keys(cachedIndex).filter(p => !currentRelPaths.has(p)).length;
+
+    return {
+      changedFiles,
+      cachedFindings: reusedFindings,
+      unchangedCount,
+      newCount,
+      modifiedCount,
+      deletedCount,
+    };
+  }
+
+  /**
+   * Save the cache to disk.
+   *
+   * @param {string[]} allFiles — All scanned file paths
+   * @param {object[]} allFindings — All findings from the scan
+   * @param {object} recon — ReconAgent output
+   * @param {object} [scoreResult] — Optional score result
+   */
+  save(allFiles, allFindings, recon, scoreResult) {
+    try {
+      // Ensure .ship-safe directory exists
+      if (!fs.existsSync(this.cacheDir)) {
+        fs.mkdirSync(this.cacheDir, { recursive: true });
+      }
+
+      // Build file index with hashes
+      const fileIndex = {};
+      for (const file of allFiles) {
+        const relPath = path.relative(this.rootPath, file).replace(/\\/g, '/');
+        const hash = this.hashFile(file);
+        if (hash) {
+          try {
+            const stats = fs.statSync(file);
+            fileIndex[relPath] = {
+              hash,
+              size: stats.size,
+              lastScanned: new Date().toISOString(),
+            };
+          } catch {
+            // Skip files we can't stat
+          }
+        }
+      }
+
+      // Group findings by file (relative paths)
+      const lastFindings = {};
+      for (const f of allFindings) {
+        const relPath = path.relative(this.rootPath, f.file).replace(/\\/g, '/');
+        if (!lastFindings[relPath]) lastFindings[relPath] = [];
+        // Store a lightweight copy (no absolute paths)
+        lastFindings[relPath].push({
+          line: f.line,
+          column: f.column,
+          severity: f.severity,
+          category: f.category,
+          rule: f.rule,
+          title: f.title,
+          description: f.description,
+          matched: f.matched,
+          confidence: f.confidence,
+          cwe: f.cwe,
+          owasp: f.owasp,
+          fix: f.fix,
+        });
+      }
+
+      const cache = {
+        version: PACKAGE_VERSION,
+        generatedAt: new Date().toISOString(),
+        rootPath: this.rootPath,
+        recon: recon || null,
+        fileIndex,
+        lastFindings,
+        stats: {
+          totalFiles: allFiles.length,
+          totalFindings: allFindings.length,
+          lastScore: scoreResult?.score ?? null,
+          lastGrade: scoreResult?.grade?.letter ?? null,
+        },
+      };
+
+      fs.writeFileSync(this.cachePath, JSON.stringify(cache, null, 2));
+    } catch {
+      // Silent failure — caching should never break a scan
+    }
+  }
+
+  /**
+   * Delete the cache file.
+   */
+  invalidate() {
+    try {
+      if (fs.existsSync(this.cachePath)) {
+        fs.unlinkSync(this.cachePath);
+      }
+    } catch {
+      // Silent
+    }
+  }
+}
+
+export default CacheManager;

package/cli/utils/patterns.js

@@ -1,3 +1,6 @@
+import fs from 'fs';
+import path from 'path';
+
 /**
  * Secret Detection Patterns
  * =========================
@@ -783,6 +786,7 @@ export const SKIP_DIRS = new Set([
   '.expo',
   '.docusaurus',
   '.storybook',
+  '.ship-safe',
 ]);
 
 export const SKIP_EXTENSIONS = new Set([
@@ -809,6 +813,97 @@ export const SKIP_EXTENSIONS = new Set([
 // Maximum file size to scan (1MB)
 export const MAX_FILE_SIZE = 1_000_000;
 
+// =============================================================================
+// .GITIGNORE LOADING
+// =============================================================================
+
+// Gitignore patterns that should NEVER be skipped by a security scanner.
+// These files are gitignored precisely because they contain secrets or
+// sensitive config — which is exactly what we want to detect.
+const SECURITY_SENSITIVE_PATTERNS = new Set([
+  '.env',
+  '.env.local',
+  '.env.development',
+  '.env.development.local',
+  '.env.test',
+  '.env.test.local',
+  '.env.production',
+  '.env.production.local',
+  '.env.staging',
+  '*.pem',
+  '*.key',
+  '*.p12',
+  '*.pfx',
+  '*.jks',
+  '*.keystore',
+  '*.crt',
+  '*.cer',
+  'credentials.json',
+  'service-account.json',
+  'serviceAccountKey.json',
+  '*.secret',
+  'htpasswd',
+  '.htpasswd',
+  'id_rsa',
+  'id_ed25519',
+  '*.sqlite',
+  '*.db',
+]);
+
+/**
+ * Load patterns from .gitignore file in the project root.
+ * Returns an array of glob-compatible ignore patterns.
+ *
+ * Smart filtering: skips gitignored build output, caches, and vendor dirs,
+ * but ALWAYS scans security-sensitive files (.env, *.key, *.pem, etc.)
+ * even if they appear in .gitignore.
+ */
+export function loadGitignorePatterns(rootPath) {
+  const gitignorePath = path.join(rootPath, '.gitignore');
+  try {
+    if (!fs.existsSync(gitignorePath)) return [];
+    return fs.readFileSync(gitignorePath, 'utf-8')
+      .split('\n')
+      .map(l => l.trim())
+      .filter(l => l && !l.startsWith('#') && !l.startsWith('!'))
+      .filter(p => !isSecuritySensitive(p))
+      .map(p => {
+        // Convert .gitignore patterns to fast-glob ignore patterns
+        if (p.startsWith('/')) {
+          // Rooted pattern: /build → build/**
+          return p.slice(1) + (p.endsWith('/') ? '**' : '');
+        }
+        if (p.endsWith('/')) {
+          // Directory pattern: logs/ → **/logs/**
+          return `**/${p}**`;
+        }
+        // General pattern: *.log → **/*.log, dist → **/dist, **/dist/**
+        if (!p.includes('/') && !p.includes('*')) {
+          return [`**/${p}`, `**/${p}/**`];
+        }
+        return `**/${p}`;
+      })
+      .flat();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Check if a .gitignore pattern targets security-sensitive files.
+ * These should always be scanned regardless of .gitignore.
+ */
+function isSecuritySensitive(pattern) {
+  const cleaned = pattern.replace(/^\//, '').replace(/\/$/, '');
+  if (SECURITY_SENSITIVE_PATTERNS.has(cleaned)) return true;
+  // Check wildcard patterns like *.pem, *.key
+  for (const sensitive of SECURITY_SENSITIVE_PATTERNS) {
+    if (sensitive.startsWith('*') && cleaned.endsWith(sensitive.slice(1))) return true;
+    if (cleaned === sensitive || cleaned.endsWith('/' + sensitive)) return true;
+  }
+  return false;
+}
+
 // =============================================================================
 // SECURITY VULNERABILITY PATTERNS
 // =============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ship-safe",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "AI-powered multi-agent security platform. 12 agents scan 50+ attack classes. Red team your code before attackers do.",
   "main": "cli/index.js",
   "bin": {