🐕 KeyHound

Sniff out leaked secrets, API keys, and credentials before they hit production.

KeyHound is a fast, lightweight, offline-first security scanner that analyzes your source code for accidentally exposed secrets (AWS keys, Stripe secrets, GitHub tokens, private keys, database passwords) and prevents leaks in your CI/CD pipeline or local development workflow.

⚡ Instant Quickstart (Zero Install)

Run KeyHound directly in any directory without installing anything:

npx keyhound .

📦 Installation Options

1. npm (Global CLI)

npm install -g keyhound

# Scan any folder
keyhound .

2. GitHub Action (CI/CD)

Add KeyHound to .github/workflows/security.yml to automatically scan PRs and post review alerts:

name: Security Scan
on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  keyhound:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 🐕 Run KeyHound Secret Scan
        uses: Krish121234/Keyhound@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          fail-on-findings: 'true'

3. Docker

docker run --rm -v $(pwd):/workspace keyhound /workspace

4. Git Pre-Commit Hook (Husky / Local Git)

Prevent secrets from ever leaving your machine:

# .husky/pre-commit or .git/hooks/pre-commit
npx keyhound .

🎯 What KeyHound Detects

| Secret Type | Examples | Confidence | | --- | --- | --- | | AWS Access Keys | AKIAIOSFODNN7EXAMPLE | 🔴 High | | AWS Secret Keys | aws_secret = "..." | 🟡 Medium | | GitHub Tokens | ghp_..., gho_..., ghu_... | 🔴 High | | Stripe Keys | sk_live_..., pk_live_... | 🔴 High | | Slack Tokens | xoxb-..., xoxp-... | 🔴 High | | Google API Keys | AIzaSy... | 🟡 Medium | | Private Keys | -----BEGIN PRIVATE KEY----- | 🔴 High | | Generic Credentials | API_KEY="xxx", PASSWORD="xxx" | 🟢 Low | | High Entropy Strings | Unknown base64 / hex random tokens (Shannon entropy) | 🟡 Medium |

💻 CLI Usage

# Basic scan
keyhound [path]

# Scan specific folder
keyhound src/

# Output machine-readable JSON (useful for custom scripts & pipelines)
keyhound . --json

# Ignore specific files or directories
keyhound . --ignore "docs/" --ignore "*.mock.js"

# Use a custom rules file
keyhound . --config ./my-rules.json

# Verbose output with full error traces
keyhound . --verbose

Exit Codes

• 0 — Codebase is clean, no secrets detected.
• 1 — Potential secrets detected (blocks CI builds).
• 2 — Error encountered (e.g. invalid arguments or non-existent path).

🚫 Ignoring Files (.scanignore)

Place a .scanignore file in the root of your project to exclude files and test fixtures (supports glob patterns):

# Dependencies & Build artifacts
node_modules/
dist/
coverage/

# Test mocks with fake credentials
test/fixtures/
**/*.mock.json

⚙️ Custom Rules Configuration

Create a custom rules.json file to add your company's custom token patterns:

{
  "rules": [
    {
      "id": "acme-corp-key",
      "name": "Acme Corp Production Token",
      "pattern": "acme_live_[0-9a-zA-Z]{32}",
      "confidence": "high"
    }
  ],
  "placeholders": [
    "your_key_here",
    "dummy_token"
  ],
  "entropy": {
    "enabled": true,
    "minLength": 32,
    "minEntropy": 4.5
  }
}

Then run:

keyhound . --config rules.json

🔒 Security & Privacy Guarantee

• Zero Telemetry / Offline First: KeyHound operates 100% locally on your machine. It does not send code or metadata to any external server.
• Always Redacted: Secret values are never logged or stored in plain text. Previews only show the first and last two characters (e.g., AK...LE).

🛠️ Contributing & Testing

# Clone the repository
git clone https://github.com/Krish121234/Keyhound.git
cd Keyhound

# Run unit tests
npm test

📄 License

MIT License. Free for personal and commercial use.