ShipShield

Pre-commit guardrail that scans staged diffs for AI-code risks before you commit.

Zero dependencies. Works with any git repo. Catches the stuff AI assistants leave behind — leaked secrets, ghost imports, forgotten TODOs, stub functions.

Quick Start

# Install globally
npm install -g ship-shield

# Or use npx (no install)
npx ship-shield

# Run in any git repo
cd your-project
ship-shield

What It Checks

| Check | Description | Severity | |-------|-------------|----------| | Secrets | API keys, tokens, private keys, database URLs | ERROR or WARN | | Ghost Files | Relative imports/file references that do not resolve on disk or in the Git index | WARN | | TODO/FIXME | Incomplete markers left in added lines | WARN or ERROR | | Stub Functions | Placeholder implementations such as pass, empty functions, Not implemented | WARN | | External Imports | Newly added non-relative imports that should be verified against project manifests | WARN |

* --fail-on-todo upgrades TODO/FIXME-style warnings to blocking errors.

Usage

# Basic scan of staged changes
ship-shield

# Short alias
oguard

# JSON output for CI/CD
ship-shield --json

# Only show output if issues found
ship-shield --quiet

# Treat TODO/FIXME as errors
ship-shield --fail-on-todo

# Print version
ship-shield --version

# Combined options
ship-shield --json --fail-on-todo > scan-results.json

Options

| Option | Description | |--------|-------------| | --json | Emit machine-readable JSON results | | --quiet | Suppress output unless findings are present; scanner errors still return exit code 2 | | --fail-on-todo | Upgrade TODO/FIXME-style warnings to blocking errors | | --version | Print the current CLI version | | -h, --help | Show usage |

Exit Codes

| Code | Meaning | |------|---------| | 0 | No blocking issues found (warnings alone do not fail) | | 1 | One or more blocking issues found | | 2 | Scanner error or not a git repo |

Git Hook Setup

Husky (recommended)

npm install --save-dev husky
npx husky init

echo 'npx ship-shield' > .husky/pre-commit

Manual pre-commit

# Create hook
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/sh
npx ship-shield --quiet
EOF

# Make executable
chmod +x .git/hooks/pre-commit

Example Output

╔══════════════════════════════════════════════════════════════╗
║            SHIPSHIELD - AI-Code Risk Report                 ║
╚══════════════════════════════════════════════════════════════╝

┌────────────────────────────────────────────────────────────┐
│  ✗ BLOCKING ISSUES FOUND                                   │
│     ● Errors: 1                                            │
│     ● Warnings: 2                                          │
│     ○ Total: 3                                             │
└────────────────────────────────────────────────────────────┘

▶ SECRETS
────────────────────────────────────────────────────────────
  [ERR] AWS Access Key ID
  File: src/config.js:12
  Code: const key = "AKIA..."
  Match: AKIA***IOSF

  [ERR] OpenAI API Key
  File: src/ai.js:5
  Code: apiKey: "sk-..."
  Match: sk-***test

▶ TODO-FIXME
────────────────────────────────────────────────────────────
  [WARN] Stub Function
  File: src/utils.js:42
  Code: function calculate() { return null; // TODO }
  Note: Function appears to be an incomplete stub

┌────────────────────────────────────────────────────────────┐
│  Commit blocked: Fix errors before committing              │
└────────────────────────────────────────────────────────────┘

Behavior Notes

• ShipShield scans git diff --staged; unstaged changes are ignored.
• Findings are reported against added lines in staged hunks.
• Relative file checks use the working tree plus the Git index, so newly staged files count as existing.
• Non-relative imports are not resolved against node_modules or Python environments; they are reported as warnings to review.
• Binary content and generated artifacts are only visible if Git includes text diff output for them.

Secret Detection Patterns

ShipShield detects:

• AWS: Access keys, secret keys
• GitHub: Personal access tokens (ghp_, gho_, ghs_, etc.)
• Slack: Bot/user tokens (xoxb-, xoxp-)
• Stripe: Live secret keys (sk_live_)
• OpenAI: API keys (sk-...)
• Generic: High-entropy secrets, database URLs with passwords
• Private Keys: PEM-encoded RSA/DSA/EC keys

CI/CD Integration

GitHub Actions

name: Guard Checks

on: [push, pull_request]

jobs:
  guard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Run ShipShield
        run: npx ship-shield --fail-on-todo

Why ShipShield?

AI coding assistants are powerful, but they still:

• Hallucinate file paths that don't exist
• Leave TODOs as "temporary" fixes that become permanent
• Hardcode credentials for "testing"
• Generate stub functions you forget to implement

ShipShield catches the obvious stuff before it hits your repo.

License

MIT. Do whatever you want with these.

About

Made by @BChopLXXXII

Pre-commit armor for vibe coders. Stop shipping AI mistakes.

Ship it. 🚀

If this helped, ⭐ — it helps others find it.