ship-safe 2.0.0 → 3.0.0

package/README.md

@@ -1,22 +1,36 @@
-# Ship Safe
+<p align="center">
+  <img src=".github/assets/logo%20ship%20safe.png" alt="Ship Safe Logo" width="180" />
+</p>
 
-**Don't let vibe coding leak your API keys.**
+<h1 align="center">Ship Safe</h1>
+
+<p align="center"><strong>Don't let vibe coding leak your API keys.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ship-safe"><img src="https://badge.fury.io/js/ship-safe.svg" alt="npm version" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a>
+</p>
+
+---
 
 You're shipping fast. You're using AI to write code. You're one `git push` away from exposing your database credentials to the world.
 
 **Ship Safe** is a security toolkit for indie hackers and vibe coders who want to secure their MVP in 5 minutes, not 5 days.
 
-[![npm version](https://badge.fury.io/js/ship-safe.svg)](https://www.npmjs.com/package/ship-safe)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
 ---
 
 ## Quick Start
 
 ```bash
-# Scan your project for leaked secrets (no install required!)
+# Scan for leaked secrets (no install required!)
 npx ship-safe scan .
 
+# Auto-generate .env.example from found secrets
+npx ship-safe fix
+
+# Block git push if secrets are found
+npx ship-safe guard
+
 # Run the launch-day security checklist
 npx ship-safe checklist
 
@@ -24,7 +38,9 @@ npx ship-safe checklist
 npx ship-safe init
 ```
 
-That's it. Three commands to secure your MVP.
+That's it. Five commands to secure your MVP.
+
+![ship-safe terminal demo](.github/assets/ship%20safe%20terminal.jpg)
 
 ### Let AI Do It For You
 
@@ -74,6 +90,32 @@ npx ship-safe scan . -v
 
 **Exit codes:** Returns `1` if secrets found (useful for CI), `0` if clean.
 
+**Flags:**
+- `--json` — structured JSON output for CI pipelines
+- `--sarif` — SARIF format for GitHub Code Scanning
+- `--include-tests` — also scan test/spec/fixture files (excluded by default)
+- `-v` — verbose mode
+
+**Suppress false positives:**
+```bash
+const apiKey = 'example-key'; // ship-safe-ignore
+```
+Or exclude paths with `.ship-safeignore` (gitignore syntax).
+
+**Custom patterns** — create `.ship-safe.json` in your project root:
+```json
+{
+  "patterns": [
+    {
+      "name": "My Internal API Key",
+      "pattern": "MYAPP_[A-Z0-9]{32}",
+      "severity": "high",
+      "description": "Internal key for myapp services."
+    }
+  ]
+}
+```
+
 **Detects 50+ secret patterns:**
 - **AI/ML:** OpenAI, Anthropic, Google AI, Cohere, Replicate, Hugging Face
 - **Auth:** Clerk, Auth0, Supabase Auth
@@ -125,6 +167,66 @@ npx ship-safe init -f
 
 ---
 
+### `npx ship-safe fix`
+
+Scan for secrets and auto-generate a `.env.example` file.
+
+```bash
+# Scan and generate .env.example
+npx ship-safe fix
+
+# Preview what would be generated without writing it
+npx ship-safe fix --dry-run
+```
+
+---
+
+### `npx ship-safe guard`
+
+Install a git hook that blocks pushes if secrets are found. Works with or without Husky.
+
+```bash
+# Install pre-push hook (runs scan before every git push)
+npx ship-safe guard
+
+# Install pre-commit hook instead
+npx ship-safe guard --pre-commit
+
+# Remove installed hooks
+npx ship-safe guard remove
+```
+
+**Suppress false positives:**
+- Add `# ship-safe-ignore` as a comment on a line to skip it
+- Create `.ship-safeignore` (gitignore syntax) to exclude paths
+
+---
+
+### `npx ship-safe mcp`
+
+Start ship-safe as an MCP server so AI editors can call it directly.
+
+**Setup (Claude Desktop)** — add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "ship-safe": {
+      "command": "npx",
+      "args": ["ship-safe", "mcp"]
+    }
+  }
+}
+```
+
+Works with Claude Desktop, Cursor, Windsurf, Zed, and any MCP-compatible editor.
+
+**Available tools:**
+- `scan_secrets` — scan a directory for leaked secrets
+- `get_checklist` — return the security checklist as structured data
+- `analyze_file` — analyze a single file for issues
+
+---
+
 ## What's Inside
 
 ### [`/checklists`](./checklists)

package/cli/bin/ship-safe.js

@@ -10,6 +10,8 @@
  *   npx ship-safe scan [path]      Scan for secrets in your codebase
  *   npx ship-safe checklist        Run the launch-day security checklist
  *   npx ship-safe init             Initialize security configs in your project
+ *   npx ship-safe fix              Generate .env.example from found secrets
+ *   npx ship-safe guard            Install pre-push git hook
  *   npx ship-safe --help           Show all commands
  */
 
@@ -21,6 +23,9 @@ import { dirname, join } from 'path';
 import { scanCommand } from '../commands/scan.js';
 import { checklistCommand } from '../commands/checklist.js';
 import { initCommand } from '../commands/init.js';
+import { fixCommand } from '../commands/fix.js';
+import { guardCommand } from '../commands/guard.js';
+import { mcpCommand } from '../commands/mcp.js';
 
 // =============================================================================
 // CLI CONFIGURATION
@@ -63,6 +68,8 @@ program
   .option('-v, --verbose', 'Show all files being scanned')
   .option('--no-color', 'Disable colored output')
   .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)')
   .action(scanCommand);
 
 // -----------------------------------------------------------------------------
@@ -85,6 +92,32 @@ program
   .option('--headers', 'Only copy security headers config')
   .action(initCommand);
 
+// -----------------------------------------------------------------------------
+// FIX COMMAND
+// -----------------------------------------------------------------------------
+program
+  .command('fix')
+  .description('Scan for secrets and generate a .env.example with placeholder values')
+  .option('--dry-run', 'Preview generated .env.example without writing it')
+  .action(fixCommand);
+
+// -----------------------------------------------------------------------------
+// GUARD COMMAND
+// -----------------------------------------------------------------------------
+program
+  .command('guard [action]')
+  .description('Install a git hook to block pushes if secrets are found')
+  .option('--pre-commit', 'Install as pre-commit hook instead of pre-push')
+  .action(guardCommand);
+
+// -----------------------------------------------------------------------------
+// MCP SERVER COMMAND
+// -----------------------------------------------------------------------------
+program
+  .command('mcp')
+  .description('Start ship-safe as an MCP server (for Claude Desktop, Cursor, Windsurf, etc.)')
+  .action(mcpCommand);
+
 // -----------------------------------------------------------------------------
 // PARSE AND RUN
 // -----------------------------------------------------------------------------
@@ -93,7 +126,9 @@ program
 if (process.argv.length === 2) {
   console.log(banner);
   console.log(chalk.yellow('\nQuick start:\n'));
-  console.log(chalk.white('  npx ship-safe scan .        ') + chalk.gray('# Scan current directory for secrets'));
+  console.log(chalk.white('  npx ship-safe scan .        ') + chalk.gray('# Scan for secrets'));
+  console.log(chalk.white('  npx ship-safe fix           ') + chalk.gray('# Generate .env.example from secrets'));
+  console.log(chalk.white('  npx ship-safe guard         ') + chalk.gray('# Block git push if secrets found'));
   console.log(chalk.white('  npx ship-safe checklist     ') + chalk.gray('# Run security checklist'));
   console.log(chalk.white('  npx ship-safe init          ') + chalk.gray('# Add security configs to your project'));
   console.log(chalk.white('\n  npx ship-safe --help        ') + chalk.gray('# Show all options'));

package/cli/commands/fix.js

@@ -0,0 +1,216 @@
+/**
+ * Fix Command
+ * ===========
+ *
+ * Scans for secrets and generates a .env.example file with placeholder values.
+ * Also shows a summary of what to move to environment variables.
+ *
+ * USAGE:
+ *   ship-safe fix             Scan and generate .env.example
+ *   ship-safe fix --dry-run   Preview what would be generated (don't write file)
+ */
+
+import fs from 'fs';
+import path from 'path';
+import ora from 'ora';
+import chalk from 'chalk';
+import {
+  SECRET_PATTERNS,
+  SKIP_DIRS,
+  SKIP_EXTENSIONS,
+  TEST_FILE_PATTERNS,
+  MAX_FILE_SIZE
+} from '../utils/patterns.js';
+import { isHighEntropyMatch } from '../utils/entropy.js';
+import { glob } from 'glob';
+import * as output from '../utils/output.js';
+
+// =============================================================================
+// MAIN COMMAND
+// =============================================================================
+
+export async function fixCommand(options = {}) {
+  const cwd = process.cwd();
+
+  const spinner = ora({ text: 'Scanning for secrets...', color: 'cyan' }).start();
+
+  try {
+    const files = await findFiles(cwd);
+    const results = [];
+
+    for (const file of files) {
+      const findings = await scanFile(file);
+      if (findings.length > 0) {
+        results.push({ file, findings });
+      }
+    }
+
+    spinner.stop();
+
+    if (results.length === 0) {
+      output.success('No secrets found — nothing to fix!');
+      console.log(chalk.gray('\nYour codebase looks clean. Keep it that way with:'));
+      console.log(chalk.gray('  npx ship-safe guard   # Block pushes if secrets are found'));
+      return;
+    }
+
+    // Build env var suggestions from findings
+    const envVars = buildEnvVarSuggestions(results);
+
+    output.header('Fix Report');
+    printFindings(results, cwd);
+    printEnvExample(envVars, options.dryRun);
+
+  } catch (err) {
+    spinner.fail('Fix scan failed');
+    output.error(err.message);
+    process.exit(1);
+  }
+}
+
+// =============================================================================
+// SCAN (same logic as scan command, reused here)
+// =============================================================================
+
+async function findFiles(rootPath) {
+  const globIgnore = Array.from(SKIP_DIRS).map(dir => `**/${dir}/**`);
+  const files = await glob('**/*', {
+    cwd: rootPath, absolute: true, nodir: true, ignore: globIgnore, dot: true
+  });
+
+  const filtered = [];
+  for (const file of files) {
+    const ext = path.extname(file).toLowerCase();
+    if (SKIP_EXTENSIONS.has(ext)) continue;
+    const basename = path.basename(file);
+    if (basename.endsWith('.min.js') || basename.endsWith('.min.css')) continue;
+    if (TEST_FILE_PATTERNS.some(p => p.test(file))) continue;
+    if (basename === '.env.example') continue; // Don't scan example files
+    try {
+      const stats = fs.statSync(file);
+      if (stats.size > MAX_FILE_SIZE) continue;
+    } catch { continue; }
+    filtered.push(file);
+  }
+  return filtered;
+}
+
+async function scanFile(filePath) {
+  const findings = [];
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const lines = content.split('\n');
+
+    for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+      const line = lines[lineNum];
+      if (/ship-safe-ignore/i.test(line)) continue;
+
+      for (const pattern of SECRET_PATTERNS) {
+        pattern.pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.pattern.exec(line)) !== null) {
+          if (pattern.requiresEntropyCheck && !isHighEntropyMatch(match[0])) continue;
+          findings.push({
+            line: lineNum + 1,
+            matched: match[0],
+            patternName: pattern.name,
+            severity: pattern.severity,
+          });
+        }
+      }
+    }
+  } catch {}
+  return findings;
+}
+
+// =============================================================================
+// ENV VAR GENERATION
+// =============================================================================
+
+function buildEnvVarSuggestions(results) {
+  const seen = new Set();
+  const vars = [];
+
+  for (const { findings } of results) {
+    for (const f of findings) {
+      const varName = patternToEnvVar(f.patternName);
+      if (!seen.has(varName)) {
+        seen.add(varName);
+        vars.push({ name: varName, comment: f.patternName });
+      }
+    }
+  }
+
+  return vars;
+}
+
+/**
+ * Convert a pattern name to a sensible env var name.
+ * e.g. "OpenAI API Key" → "OPENAI_API_KEY"
+ */
+function patternToEnvVar(patternName) {
+  return patternName
+    .toUpperCase()
+    .replace(/[^A-Z0-9\s]/g, '')
+    .trim()
+    .replace(/\s+/g, '_');
+}
+
+// =============================================================================
+// OUTPUT
+// =============================================================================
+
+function printFindings(results, rootPath) {
+  const total = results.reduce((sum, r) => sum + r.findings.length, 0);
+  console.log(chalk.red.bold(`\n  Found ${total} secret(s) across ${results.length} file(s)\n`));
+
+  for (const { file, findings } of results) {
+    const relPath = path.relative(rootPath, file);
+    console.log(chalk.white.bold(`  ${relPath}`));
+    for (const f of findings) {
+      console.log(chalk.gray(`    Line ${f.line}: `) + chalk.yellow(f.patternName));
+    }
+  }
+}
+
+function printEnvExample(envVars, dryRun) {
+  const lines = [
+    '# .env.example',
+    '# Generated by ship-safe — replace placeholder values with your actual secrets.',
+    '# Copy this file to .env and fill in the values.',
+    '# NEVER commit .env — only commit .env.example',
+    '',
+  ];
+
+  for (const { name, comment } of envVars) {
+    lines.push(`# ${comment}`);
+    lines.push(`${name}=your_${name.toLowerCase()}_here`);
+    lines.push('');
+  }
+
+  const content = lines.join('\n');
+
+  output.header(dryRun ? '.env.example Preview (dry run)' : 'Generated .env.example');
+  console.log();
+  console.log(chalk.gray(content));
+
+  if (!dryRun) {
+    const envExamplePath = path.join(process.cwd(), '.env.example');
+
+    if (fs.existsSync(envExamplePath)) {
+      output.warning('.env.example already exists — skipping. Use --force to overwrite.');
+    } else {
+      fs.writeFileSync(envExamplePath, content);
+      output.success('Created .env.example');
+    }
+
+    console.log();
+    console.log(chalk.cyan.bold('Next steps:'));
+    console.log(chalk.white('1.') + chalk.gray(' Copy .env.example to .env'));
+    console.log(chalk.white('2.') + chalk.gray(' Replace placeholder values with your real secrets'));
+    console.log(chalk.white('3.') + chalk.gray(' Remove the hardcoded values from your source code'));
+    console.log(chalk.white('4.') + chalk.gray(' Verify .env is in your .gitignore'));
+    console.log(chalk.white('5.') + chalk.gray(' Run npx ship-safe scan . to confirm clean'));
+    console.log();
+  }
+}