ship-safe 3.2.0 → 4.1.0

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <img src=".github/assets/logo%20ship%20safe.png" alt="Ship Safe Logo" width="180" />
 </p>
-<p align="center"><strong>Don't let vibe coding leak your API keys.</strong></p>
+<p align="center"><strong>AI-powered application security platform for developers.</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>
@@ -13,523 +13,287 @@
 
 ---
 
-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.
+12 security agents. 50+ attack classes. One command.
 
-**Ship Safe** is a security toolkit for indie hackers and vibe coders who want to secure their MVP in 5 minutes, not 5 days.
+**Ship Safe v4.0** is an AI-powered security platform that runs 12 specialized agents against your codebase — scanning for secrets, injection vulnerabilities, auth bypass, SSRF, supply chain attacks, Docker/Terraform misconfigs, CI/CD pipeline poisoning, LLM security issues, and more. It produces a prioritized remediation plan so you know exactly what to fix first.
 
 ---
 
 ## Quick Start
 
 ```bash
-# AI-powered audit: scan, classify with Claude, auto-fix confirmed secrets
-npx ship-safe agent .
+# Full security audit — secrets + 12 agents + deps + remediation plan
+npx ship-safe audit .
+
+# Red team scan only (12 agents, 50+ attack classes)
+npx ship-safe red-team .
 
-# Scan for secrets AND code vulnerabilities (SQL injection, XSS, etc.)
+# Quick secret scan
 npx ship-safe scan .
 
-# Security health score (0-100, A–F grade)
+# Security health score (0-100)
 npx ship-safe score .
-
-# Audit dependencies for known CVEs
-npx ship-safe deps .
-
-# Auto-fix hardcoded secrets: rewrite code + write .env
-npx ship-safe remediate .
-
-# Revoke exposed keys — opens provider dashboards with step-by-step guide
-npx ship-safe rotate .
-```
-
-Or if you prefer the manual toolkit:
-
-```bash
-npx ship-safe fix           # Generate .env.example from secrets
-npx ship-safe guard         # Block git push if secrets found
-npx ship-safe checklist     # Run launch-day security checklist
-npx ship-safe init          # Add security configs to your project
 ```
 
 ![ship-safe terminal demo](.github/assets/ship%20safe%20terminal.jpg)
 
-### Let AI Do It For You
-
-Copy this prompt to your AI coding assistant:
-
-```
-Run "npx ship-safe scan ." on my project and fix any secrets you find.
-Then run "npx ship-safe init" to add security configs.
-Explain what you're doing as you go.
-```
-
-[More AI prompts for specific frameworks](./AI_SECURITY_PROMPT.md)
-
----
-
-## Why This Exists
-
-Vibe coding is powerful. You can build a SaaS in a weekend. But speed creates blind spots:
-
-- AI-generated code often hardcodes secrets
-- Default configs ship with debug mode enabled
-- "I'll fix it later" becomes "I got hacked"
-
-This repo is your co-pilot for security. Copy, paste, ship safely.
-
 ---
 
-## CLI Commands
+## The `audit` Command
 
-### `npx ship-safe agent [path]`
-
-AI-powered security audit. Scans for both secrets and code vulnerabilities, sends findings to Claude for classification, auto-fixes confirmed secrets, and provides specific fix suggestions for code issues.
+One command that runs everything and generates a full report:
 
 ```bash
-# Full AI audit (requires ANTHROPIC_API_KEY)
-npx ship-safe agent .
-
-# Preview classification without writing any files
-npx ship-safe agent . --dry-run
-
-# Use a specific Claude model
-npx ship-safe agent . --model claude-opus-4-6
+npx ship-safe audit .
 ```
 
-**Flow:**
-1. Scan for secrets + code vulnerabilities (XSS, SQLi, command injection, etc.)
-2. Send findings to Claude — classify each as `REAL` or `FALSE_POSITIVE`
-3. For secrets: auto-remediate confirmed findings (rewrite code + write `.env`)
-4. For code vulns: print Claude's verdict + specific 1-line fix suggestion
-5. Re-scan to verify secrets are gone
-
-No `ANTHROPIC_API_KEY`? Falls back to `remediate` for secrets automatically.
-
----
+```
+════════════════════════════════════════════════════════════
+  Ship Safe v4.0 — Full Security Audit
+════════════════════════════════════════════════════════════
 
-### `npx ship-safe scan [path]`
+  [Phase 1/4] Scanning for secrets...         ✔ 49 found
+  [Phase 2/4] Running 12 security agents...   ✔ 103 findings
+  [Phase 3/4] Auditing dependencies...        ✔ 44 CVEs
+  [Phase 4/4] Computing security score...     ✔ 25/100 F
 
-Scans your codebase for leaked secrets **and** code vulnerabilities.
+  Remediation Plan
+  ════════════════════════════════════════════════════════
 
-```bash
-# Scan current directory
-npx ship-safe scan .
+  🔴 CRITICAL — fix immediately
+  ────────────────────────────────────────────────────────
+   1. [SECRETS] Rotate Stripe Live Secret Key
+      .env:67 → Move to environment variable or secrets manager
 
-# Scan a specific folder
-npx ship-safe scan ./src
+   2. [INJECTION] Unsafe pickle.loads()
+      backend/ai_processor.py:64 → Use JSON for untrusted data
 
-# Get JSON output (for CI pipelines)
-npx ship-safe scan . --json
+  🟠 HIGH — fix before deploy
+  ────────────────────────────────────────────────────────
+   3. [XSS] dangerouslySetInnerHTML without sanitization
+      frontend/src/utils/blogContentRenderer.jsx:50 → Add DOMPurify
 
-# SARIF output for GitHub Code Scanning
-npx ship-safe scan . --sarif
+  ... 149 more items in the full report
 
-# Verbose mode (show files being scanned)
-npx ship-safe scan . -v
+  📊 Full report: ship-safe-report.html
 ```
 
-**Exit codes:** Returns `1` if issues found (useful for CI), `0` if clean.
+**What it runs:**
+1. **Secret scan** — 50+ patterns with entropy scoring (API keys, passwords, tokens)
+2. **12 security agents** — injection, auth, SSRF, supply chain, config, LLM, mobile, git history, CI/CD, API
+3. **Dependency audit** — npm/pip/bundler CVE scanning
+4. **Score computation** — 8-category weighted scoring (0-100, A-F)
+5. **Remediation plan** — prioritized fix list grouped by severity
+6. **HTML report** — standalone dark-themed report with table of contents
 
 **Flags:**
-- `--json` — structured JSON output for CI pipelines
+- `--json` — structured JSON output (clean for piping)
 - `--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
-- **Cloud:** AWS, Google Cloud, Azure
-- **Database:** Supabase, PlanetScale, Neon, MongoDB, PostgreSQL, MySQL
-- **Payment:** Stripe, PayPal
-- **Messaging:** Twilio, SendGrid, Resend
-- **And more:** GitHub tokens, private keys, JWTs, generic secrets
-
-**Detects 18 code vulnerability patterns (OWASP Top 10):**
-- **Injection:** SQL injection (template literals), command injection, code injection (`eval`)
-- **XSS:** `dangerouslySetInnerHTML`, `innerHTML` assignment, `document.write`
-- **Crypto:** MD5 / SHA-1 for passwords, weak random number generation
-- **TLS:** `NODE_TLS_REJECT_UNAUTHORIZED=0`, `rejectUnauthorized: false`, Python `verify=False`
-- **Deserialization:** `pickle.loads`, `yaml.load` without `Loader`
-- **Misconfiguration:** CORS wildcard (`*`), deprecated `new Buffer()`
+- `--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)
 
 ---
 
-### `npx ship-safe remediate [path]`
-
-Auto-fix hardcoded secrets: rewrites source files to use `process.env` variables, writes a `.env` file with the actual values, and updates `.gitignore`.
-
-```bash
-# Auto-fix secrets
-npx ship-safe remediate .
-
-# Preview changes without writing any files
-npx ship-safe remediate . --dry-run
-
-# Apply all fixes without prompting (for CI)
-npx ship-safe remediate . --yes
-
-# Also run git add on modified files
-npx ship-safe remediate . --stage
-```
+## 12 Security Agents
+
+| Agent | Category | What It Detects |
+|-------|----------|-----------------|
+| **InjectionTester** | Code Vulns | SQL/NoSQL injection, command injection, code injection (eval), XSS, path traversal, XXE, ReDoS, prototype pollution |
+| **AuthBypassAgent** | Auth | JWT vulnerabilities (alg:none, weak secrets), cookie security, CSRF, OAuth misconfig, BOLA/IDOR, weak crypto, timing attacks, TLS bypass |
+| **SSRFProber** | SSRF | User input in fetch/axios, cloud metadata endpoints, internal IPs, redirect following |
+| **SupplyChainAudit** | Supply Chain | Typosquatting (Levenshtein distance), git/URL dependencies, wildcard versions, suspicious install scripts |
+| **ConfigAuditor** | Config | Dockerfile (running as root, :latest tags), Terraform (public S3, open SG), Kubernetes (privileged containers), CORS, CSP, Firebase, Nginx |
+| **LLMRedTeam** | AI/LLM | OWASP LLM Top 10 — prompt injection, excessive agency, system prompt leakage, unbounded consumption, RAG poisoning |
+| **MobileScanner** | Mobile | OWASP Mobile Top 10 2024 — insecure storage, WebView JS injection, HTTP endpoints, excessive permissions, debug mode |
+| **GitHistoryScanner** | Secrets | Leaked secrets in git commit history (checks if still active in working tree) |
+| **CICDScanner** | CI/CD | OWASP CI/CD Top 10 — pipeline poisoning, unpinned actions, secret logging, self-hosted runners, script injection |
+| **APIFuzzer** | API | Routes without auth, missing input validation, mass assignment, unrestricted file upload, GraphQL introspection, debug endpoints |
+| **ReconAgent** | Recon | Attack surface discovery — frameworks, languages, auth patterns, databases, cloud providers, IaC, CI/CD pipelines |
+| **ScoringEngine** | Scoring | 8-category weighted scoring with trend tracking |
 
 ---
 
-### `npx ship-safe rotate [path]`
+## All Commands
 
-Revoke and rotate exposed secrets. Detects which providers your secrets belong to and opens the right dashboard with step-by-step revocation instructions.
+### Core Audit Commands
 
 ```bash
-# Open dashboards for all detected secrets
-npx ship-safe rotate .
-
-# Rotate only a specific provider
-npx ship-safe rotate . --provider github
-npx ship-safe rotate . --provider stripe
-npx ship-safe rotate . --provider openai
-```
+# Full audit with remediation plan + HTML report
+npx ship-safe audit .
 
-**Supports:** OpenAI, Anthropic, GitHub, Stripe, AWS, Google Cloud, Supabase, and more.
+# Red team: 12 agents, 50+ attack classes
+npx ship-safe red-team .
+npx ship-safe red-team . --agents injection,auth    # Run specific agents
+npx ship-safe red-team . --html report.html         # HTML report
+npx ship-safe red-team . --json                     # JSON output
 
----
-
-### `npx ship-safe deps [path]`
+# Secret scanner (pattern matching + entropy)
+npx ship-safe scan .
+npx ship-safe scan . --json          # JSON for CI
+npx ship-safe scan . --sarif         # SARIF for GitHub
 
-Audit your dependencies for known CVEs using the project's native package manager.
+# Security health score (0-100, A-F)
+npx ship-safe score .
 
-```bash
-# Audit dependencies
+# Dependency CVE audit
 npx ship-safe deps .
-
-# Also run the package manager's auto-fix command
-npx ship-safe deps . --fix
+npx ship-safe deps . --fix           # Auto-fix vulnerabilities
 ```
 
-**Supported package managers:**
-- `npm` → `npm audit`
-- `yarn` → `yarn audit`
-- `pnpm` → `pnpm audit`
-- `pip` → `pip-audit` (install with `pip install pip-audit`)
-- `bundler` → `bundle-audit` (install with `gem install bundler-audit`)
-
-Auto-detected from your lock file. Gracefully skips if the tool isn't installed.
-
----
-
-### `npx ship-safe score [path]`
-
-Compute a 0–100 security health score for your project. Combines secret detection, code vulnerability detection, and dependency CVEs into a single grade. No API key needed — instant and free.
+### AI-Powered Commands
 
 ```bash
-# Score the project
-npx ship-safe score .
-
-# Skip dependency audit (faster)
-npx ship-safe score . --no-deps
-```
-
-**Scoring (starts at 100):**
-
-| Category | Critical | High | Medium | Cap |
-|----------|----------|------|--------|-----|
-| Secrets | −25 | −15 | −5 | −40 |
-| Code Vulns | −20 | −10 | −3 | −30 |
-| Dependencies | −20 | −10 | −5 | −30 |
-
-**Grades:**
-
-| Score | Grade | Verdict |
-|-------|-------|---------|
-| 90–100 | A | Ship it! |
-| 75–89 | B | Minor issues to review |
-| 60–74 | C | Fix before shipping |
-| 40–59 | D | Significant security risks |
-| 0–39 | F | Not safe to ship |
-
-**Exit codes:** Returns `0` for A/B (≥ 75), `1` for C/D/F.
+# AI audit: scan + classify with Claude + auto-fix secrets
+npx ship-safe agent .
 
----
+# Auto-fix hardcoded secrets: rewrite code + write .env
+npx ship-safe remediate .
 
-### `npx ship-safe checklist`
+# Revoke exposed keys — opens provider dashboards
+npx ship-safe rotate .
+```
 
-Interactive 10-point security checklist for launch day.
+### Infrastructure Commands
 
 ```bash
-# Interactive mode (prompts for each item)
-npx ship-safe checklist
-
-# Print checklist without prompts
-npx ship-safe checklist --no-interactive
-```
-
-Covers: exposed .git folders, debug mode, RLS policies, hardcoded keys, HTTPS, security headers, rate limiting, and more.
+# Continuous monitoring (watch files for changes)
+npx ship-safe watch .
 
----
+# Generate CycloneDX SBOM
+npx ship-safe sbom .
 
-### `npx ship-safe init`
+# Policy-as-code (enforce minimum score, fail on severity)
+npx ship-safe policy init
 
-Initialize security configs in your project.
+# Block git push if secrets found
+npx ship-safe guard
 
-```bash
-# Add all security configs
+# Initialize security configs (.gitignore, headers)
 npx ship-safe init
 
-# Only add .gitignore patterns
-npx ship-safe init --gitignore
-
-# Only add security headers config
-npx ship-safe init --headers
+# Launch-day security checklist
+npx ship-safe checklist
 
-# Force overwrite existing files
-npx ship-safe init -f
+# MCP server for AI editors (Claude Desktop, Cursor, etc.)
+npx ship-safe mcp
 ```
 
-**What it copies:**
-- `.gitignore` - Patterns to prevent committing secrets
-- `security-headers.config.js` - Drop-in Next.js security headers
-
 ---
 
-### `npx ship-safe fix`
+## Claude Code Plugin
 
-Scan for secrets and auto-generate a `.env.example` file.
+Use Ship Safe directly inside Claude Code — no CLI needed:
 
 ```bash
-# Scan and generate .env.example
-npx ship-safe fix
-
-# Preview what would be generated without writing it
-npx ship-safe fix --dry-run
+claude plugin add github:asamassekou10/ship-safe
 ```
 
----
-
-### `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
-```
+| 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) |
 
-**Suppress false positives:**
-- Add `# ship-safe-ignore` as a comment on a line to skip it
-- Create `.ship-safeignore` (gitignore syntax) to exclude paths
+Claude interprets the results, explains findings in plain language, and can fix issues directly in your codebase.
 
 ---
 
-### `npx ship-safe mcp`
+## Incremental Scanning
 
-Start ship-safe as an MCP server so AI editors can call it directly.
+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.
 
-**Setup (Claude Desktop)** — add to `claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "ship-safe": {
-      "command": "npx",
-      "args": ["ship-safe", "mcp"]
-    }
-  }
-}
+```
+✔ [Phase 1/4] Secrets: 41 found (0 changed, 313 cached)
 ```
 
-Works with Claude Desktop, Cursor, Windsurf, Zed, and any MCP-compatible editor.
+- **~40% faster** on repeated scans
+- **Auto-invalidation** — cache expires after 24 hours or when ship-safe updates
+- **`--no-cache`** — force a full rescan anytime
 
-**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
+The cache is stored in `.ship-safe/` which is automatically excluded from scans.
 
 ---
 
-## What's Inside
-
-### [`/checklists`](./checklists)
-**Manual security audits you can do in 5 minutes.**
-- [Launch Day Checklist](./checklists/launch-day.md) - 10 things to check before you go live
-
-### [`/configs`](./configs)
-**Secure defaults for popular stacks. Drop-in ready.**
-
-| Stack | Files |
-|-------|-------|
-| **Next.js** | [Security Headers](./configs/nextjs-security-headers.js) - CSP, X-Frame-Options, HSTS |
-| **Supabase** | [RLS Templates](./configs/supabase/rls-templates.sql) \| [Security Checklist](./configs/supabase/security-checklist.md) \| [Secure Client](./configs/supabase/secure-client.ts) |
-| **Firebase** | [Firestore Rules](./configs/firebase/firestore-rules.txt) \| [Storage Rules](./configs/firebase/storage-rules.txt) \| [Security Checklist](./configs/firebase/security-checklist.md) |
-
-### [`/snippets`](./snippets)
-**Copy-paste code blocks for common security patterns.**
+## Smart `.gitignore` Handling
 
-| Category | Files |
-|----------|-------|
-| **Rate Limiting** | [Upstash Redis](./snippets/rate-limiting/upstash-ratelimit.ts) \| [Next.js Middleware](./snippets/rate-limiting/nextjs-middleware.ts) |
-| **Authentication** | [JWT Security Checklist](./snippets/auth/jwt-checklist.md) |
-| **API Security** | [CORS Config](./snippets/api-security/cors-config.ts) \| [Input Validation](./snippets/api-security/input-validation.ts) \| [API Checklist](./snippets/api-security/api-security-checklist.md) |
-
-### [`/ai-defense`](./ai-defense)
-**Protect your AI features from abuse and cost explosions.**
+Ship Safe respects your `.gitignore` for build output, caches, and vendor directories — but **always scans security-sensitive files** even if gitignored:
 
-| File | Description |
-|------|-------------|
-| [LLM Security Checklist](./ai-defense/llm-security-checklist.md) | Based on OWASP LLM Top 10 - prompt injection, data protection, scope control |
-| [Prompt Injection Patterns](./ai-defense/prompt-injection-patterns.js) | Regex patterns to detect 25+ injection attempts |
-| [Cost Protection Guide](./ai-defense/cost-protection.md) | Prevent $50k surprise bills - rate limits, budget caps, circuit breakers |
-| [System Prompt Armor](./ai-defense/system-prompt-armor.md) | Template for hardened system prompts |
+| 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` |
 
-### [`/scripts`](./scripts)
-**Automated scanning tools. Run them in CI or locally.**
-- [Secret Scanner](./scripts/scan_secrets.py) - Python version of the secret scanner
+Why? Files like `.env` are gitignored *because* they contain secrets — which is exactly what a security scanner should catch.
 
 ---
 
-## AI/LLM Security
+## Multi-LLM Support
 
-Building with AI? Don't let it bankrupt you or get hijacked.
+Ship Safe supports multiple AI providers for classification:
 
-### Quick Setup
+| Provider | Env Variable | Model |
+|----------|-------------|-------|
+| **Anthropic** | `ANTHROPIC_API_KEY` | claude-haiku-4-5 |
+| **OpenAI** | `OPENAI_API_KEY` | gpt-4o-mini |
+| **Google** | `GOOGLE_AI_API_KEY` | gemini-2.0-flash |
+| **Ollama** | `OLLAMA_HOST` | Local models |
 
-```typescript
-import { containsInjectionAttempt } from './ai-defense/prompt-injection-patterns';
-
-async function handleChat(userInput: string) {
-  // 1. Check for injection attempts
-  const { detected } = containsInjectionAttempt(userInput);
-  if (detected) {
-    return "I can't process that request.";
-  }
-
-  // 2. Rate limit per user
-  const { success } = await ratelimit.limit(userId);
-  if (!success) {
-    return "Too many requests. Please slow down.";
-  }
-
-  // 3. Check budget before calling
-  await checkUserBudget(userId, estimatedCost);
-
-  // 4. Make the API call with token limits
-  const response = await openai.chat.completions.create({
-    model: 'gpt-4',
-    messages,
-    max_tokens: 500, // Hard cap
-  });
-
-  return response;
-}
-```
-
-### Cost Protection Layers
-
-1. **Token limits** - Cap input/output per request
-2. **Rate limits** - Cap requests per user (10/min)
-3. **Budget caps** - Daily ($1) and monthly ($10) per user
-4. **Circuit breaker** - Disable AI when global budget hit
-5. **Provider limits** - Set hard limits in OpenAI/Anthropic dashboard
-
-[Full cost protection guide →](./ai-defense/cost-protection.md)
+Auto-detected from environment variables. No API key required for scanning — AI is optional.
 
 ---
 
-## Database Security
+## Scoring System
 
-### Supabase RLS Templates
+Starts at 100. Each finding deducts points by severity and category.
 
-```sql
--- Users can only see their own data
-CREATE POLICY "Users own their data" ON items
-  FOR ALL USING (auth.uid() = user_id);
+**8 Categories** (with weight caps):
 
--- Read-only public data
-CREATE POLICY "Public read access" ON public_items
-  FOR SELECT USING (true);
-```
-
-[6 more RLS patterns →](./configs/supabase/rls-templates.sql)
-
-### Firebase Security Rules
+| Category | Weight | Critical | High | Medium | Cap |
+|----------|--------|----------|------|--------|-----|
+| Secrets | 15% | -25 | -15 | -5 | -15 |
+| Code Vulnerabilities | 15% | -20 | -10 | -3 | -15 |
+| Dependencies | 15% | -20 | -10 | -5 | -15 |
+| Auth & Access Control | 15% | -20 | -10 | -3 | -15 |
+| Configuration | 10% | -15 | -8 | -3 | -10 |
+| Supply Chain | 10% | -15 | -8 | -3 | -10 |
+| API Security | 10% | -15 | -8 | -3 | -10 |
+| AI/LLM Security | 10% | -15 | -8 | -3 | -10 |
 
-```javascript
-// Users can only access their own documents
-match /users/{userId} {
-  allow read, write: if request.auth != null
-    && request.auth.uid == userId;
-}
-```
+**Grades:** A (90-100), B (75-89), C (60-74), D (40-59), F (0-39)
 
-[Full Firestore rules template →](./configs/firebase/firestore-rules.txt)
+**Exit codes:** `0` for A/B (>= 75), `1` for C/D/F — use in CI to fail builds.
 
 ---
 
-## API Security
+## Policy-as-Code
 
-### CORS (Don't use `*` in production)
+Create `.ship-safe.policy.json` to enforce team-wide security standards:
 
-```typescript
-const ALLOWED_ORIGINS = [
-  'https://yourapp.com',
-  'https://www.yourapp.com',
-];
-
-// Only allow specific origins
-if (origin && ALLOWED_ORIGINS.includes(origin)) {
-  headers['Access-Control-Allow-Origin'] = origin;
-}
+```bash
+npx ship-safe policy init
 ```
 
-[CORS configs for Next.js, Express, Fastify, Hono →](./snippets/api-security/cors-config.ts)
-
-### Input Validation (Zod)
-
-```typescript
-const createUserSchema = z.object({
-  email: z.string().email().max(255),
-  password: z.string().min(8).max(128),
-});
-
-const result = createUserSchema.safeParse(body);
-if (!result.success) {
-  return Response.json({ error: result.error.issues }, { status: 400 });
+```json
+{
+  "minimumScore": 70,
+  "failOn": "critical",
+  "requiredScans": ["secrets", "injection", "deps", "auth"],
+  "ignoreRules": [],
+  "customSeverityOverrides": {},
+  "maxAge": { "criticalCVE": "7d", "highCVE": "30d", "mediumCVE": "90d" }
 }
 ```
 
-[Full validation patterns →](./snippets/api-security/input-validation.ts)
-
 ---
 
 ## CI/CD Integration
 
-Add to your GitHub Actions workflow:
-
 ```yaml
 # .github/workflows/security.yml
-name: Security Scan
+name: Security Audit
 
 on: [push, pull_request]
 
@@ -539,60 +303,70 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Scan for secrets and code vulnerabilities
-        run: npx ship-safe scan . --json
+      - name: Full security audit
+        run: npx ship-safe audit . --no-ai --json
 
-      - name: Audit dependencies for CVEs
-        run: npx ship-safe deps .
+      - name: Upload SARIF to GitHub Security tab
+        run: npx ship-safe audit . --no-ai --sarif > results.sarif
 
-      - name: Security health score (fail if C or below)
-        run: npx ship-safe score . --no-deps
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: results.sarif
 ```
 
-Each command exits with code `1` on findings, failing your build. Use `--sarif` with `scan` to send results to GitHub's Security tab:
+---
 
-```yaml
-      - name: Scan (SARIF for GitHub Security tab)
-        run: npx ship-safe scan . --sarif > results.sarif
+## Suppress False Positives
 
-      - name: Upload to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@v3
-        with:
-          sarif_file: results.sarif
+**Inline:** Add `# ship-safe-ignore` comment on a line:
+```python
+password = get_password()  # ship-safe-ignore
+```
+
+**File-level:** Create `.ship-safeignore` (gitignore syntax):
+```gitignore
+# Exclude test fixtures
+tests/fixtures/
+*.test.js
+
+# Exclude documentation with code examples
+docs/
 ```
 
 ---
 
-## The 5-Minute Security Checklist
+## OWASP Coverage
 
-1. ✅ Run `npx ship-safe agent .` — AI audit: finds + classifies + fixes secrets and code vulns
-2. ✅ Run `npx ship-safe deps .` — audit your dependencies for known CVEs
-3. ✅ Run `npx ship-safe score .` — check your overall security health score
-4. ✅ Run `npx ship-safe init` — add security configs (.gitignore, security headers)
-5. ✅ Run `npx ship-safe guard` — install git hook to block pushes if secrets found
-6. ✅ Run `npx ship-safe checklist` — run the interactive launch-day security checklist
-7. ✅ If using AI features, implement [cost protection](./ai-defense/cost-protection.md)
-8. ✅ If using Supabase, check the [RLS checklist](./configs/supabase/security-checklist.md)
-9. ✅ If using Firebase, check the [Firebase checklist](./configs/firebase/security-checklist.md)
+| Standard | Coverage |
+|----------|----------|
+| **OWASP Top 10 Web 2025** | A01-A10: Broken Access Control, Cryptographic Failures, Injection, Insecure Design, Security Misconfiguration, Vulnerable Components, Auth Failures, Data Integrity, Logging Failures, SSRF |
+| **OWASP Top 10 Mobile 2024** | M1-M10: Improper Credential Usage, Inadequate Supply Chain, Insecure Auth, Insufficient Validation, Insecure Communication, Inadequate Privacy, Binary Protections, Security Misconfiguration, Insecure Data Storage, Insufficient Cryptography |
+| **OWASP LLM Top 10 2025** | LLM01-LLM10: Prompt Injection, Sensitive Info Disclosure, Supply Chain, Data Poisoning, Improper Output Handling, Excessive Agency, System Prompt Leakage, Vector/Embedding Weaknesses, Misinformation, Unbounded Consumption |
+| **OWASP CI/CD Top 10** | CICD-SEC-1 to 10: Insufficient Flow Control, Identity Management, Dependency Chain Abuse, Poisoned Pipeline Execution, Insufficient PBAC, Credential Hygiene, Insecure System Config, Ungoverned Usage, Improper Artifact Integrity, Insufficient Logging |
 
 ---
 
-## Philosophy
+## What's Inside
 
-- **Low friction** - If it takes more than 5 minutes, people won't do it
-- **Educational** - Every config has comments explaining *why*
-- **Modular** - Take what you need, ignore the rest
-- **Copy-paste friendly** - No complex setup, just grab and go
+### [`/configs`](./configs)
+Drop-in security configs for Next.js, Supabase, and Firebase.
+
+### [`/snippets`](./snippets)
+Copy-paste security patterns: rate limiting, JWT, CORS, input validation.
+
+### [`/ai-defense`](./ai-defense)
+LLM security: prompt injection detection, cost protection, system prompt hardening.
+
+### [`/checklists`](./checklists)
+Manual security audits: launch-day checklist, framework-specific guides.
 
 ---
 
 ## Contributing
 
-Found a security pattern that saved your app? Share it!
-
 1. Fork the repo
-2. Add your checklist, config, or script
-3. Include educational comments explaining *why* it matters
+2. Add your security pattern, agent, or config
+3. Include comments explaining *why* it matters
 4. Open a PR
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
@@ -601,11 +375,11 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
 
 ## Security Standards Reference
 
-This toolkit is based on:
 - [OWASP Top 10 Web 2025](https://owasp.org/Top10/)
 - [OWASP Top 10 Mobile 2024](https://owasp.org/www-project-mobile-top-10/)
 - [OWASP LLM Top 10 2025](https://genai.owasp.org/llm-top-10/)
 - [OWASP API Security Top 10 2023](https://owasp.org/API-Security/)
+- [OWASP CI/CD Top 10](https://owasp.org/www-project-top-10-ci-cd-security-risks/)
 
 ---
 
@@ -621,6 +395,4 @@ MIT - Use it, share it, secure your stuff.
 
 ---
 
-**Remember: Security isn't about being paranoid. It's about being prepared.**
-
-Ship fast. Ship safe.
+**Ship fast. Ship safe.**