RepoShield 🔐

AI-assisted pre-commit security scanner for Git repositories.

RepoShield catches secrets, vulnerable dependencies, and hygiene issues before they reach your repository — with optional AI-powered false-positive reduction via Claude.

---

The Problem

Developers accidentally commit API keys, passwords, private certificates, and cloud credentials every day. One leaked secret can mean a compromised AWS account, a data breach, or worse. RepoShield sits at the last line of defense — the pre-commit hook — and stops secrets before they ever touch your Git history.

---

Features

• 🔑 Secret Detection — AWS keys, GitHub tokens, OpenAI keys, database URLs, private keys, JWT secrets, Stripe keys, and 15+ other patterns
• 🧠 AI Context Analysis — Claude distinguishes real secrets from test fixtures and placeholders, eliminating false positives
• 📦 Dependency Scanning — CVE detection via pip-audit and npm audit
• 🧹 Git Hygiene — detects tracked .env files, missing .gitignore entries, credentials in remote URLs
• 📊 Security Health Score — category scores across Secrets, Dependencies, Git Hygiene, and Configuration
• ⚡ Fast — non-AI path completes in under 2 seconds for typical repos
• 🪟 Cross-platform — works on Windows, macOS, and Linux

---

Installation

pip install reposhield

Or with pipx for an isolated global install:

pipx install reposhield

---

Quick Start

# Install the pre-commit hook in your repo
cd your-project
reposhield init

# That's it — every git commit is now scanned automatically
git commit -m "update config"   # RepoShield runs before the commit is created

---

Usage

reposhield scan                 # scan all tracked files
reposhield scan --staged        # scan only staged files
reposhield scan --ai            # enable AI false-positive filtering
reposhield scan --json          # machine-readable output for CI
reposhield init                 # install pre-commit hook
reposhield init --ai            # install AI-enabled hook
reposhield uninstall            # remove the hook
reposhield version              # show version

---

Example Output

╭─────────────────────────────────────────────────╮
│ RepoShield Security Scan  ·  BLOCKED            │
│ Scanned 2 files · 9 issues found · 0.06s        │
╰─────────────────────────────────────────────────╯

  Security Health Scores
╭────────────────────┬───────┬────────────╮
│ Secrets Management │     0 │ Critical   │
│ Dependency Safety  │   100 │ Excellent  │
│ Git Hygiene        │    70 │ Good       │
│ Overall            │    68 │ Needs Work │
╰────────────────────┴───────┴────────────╯

 CRITICAL  Potential AWS Access Key ID — config.py:1
 CRITICAL  Potential Database URL — config.py:3
 HIGH      Sensitive file tracked by Git: .env

Commit blocked. Resolve critical/high findings above.
To skip (not recommended): git commit --no-verify

---

AI Mode

Set your Anthropic API key to enable AI-powered context analysis:

export ANTHROPIC_API_KEY=sk-ant-...
reposhield scan --ai

The AI analyzes each finding in context and determines whether it's a real secret or a harmless placeholder — for example, distinguishing api_key = "your_key_here" (fake) from api_key = "sk-proj-xK9m..." (real). Verdicts are cached locally at ~/.reposhield/ai_cache/ to avoid redundant API calls.

---

Configuration

Create .reposhield.toml in your repository root to customize behaviour:

[general]
block_on_critical = true
block_on_high = true
exclude_patterns = ["docs/**", "*.md"]

[ai]
enabled = false   # override with --ai flag or ANTHROPIC_API_KEY

[ignore]
files = ["tests/fixtures/sample_secrets.py"]
rules = ["HIGH_ENTROPY"]

---

How It Works

git commit
    ↓
pre-commit hook
    ↓
┌──────────────────────────────────────┐
│  Pattern scanner (regex + entropy)   │
│  Dependency auditor (pip/npm)        │
│  Git hygiene checker                 │
│  AI context analyzer (optional)      │
└──────────────────────────────────────┘
    ↓
Risk scorer → Terminal report
    ↓
Block or pass

---

Exit Codes

Code	Meaning
0	Clean — no blocking issues found
1	Blocked — critical/high findings require attention

---

Contributing

Contributions are welcome. Please open an issue first to discuss major changes.

git clone https://github.com/Rishiprasad17/reposhield.git
cd reposhield
pip install -e ".[dev]"
pytest -v

---

License

MIT — see LICENSE for details.