🔐 Point it at any GitHub repository. Watch it hunt.

An autonomous AI agent that crawls code, commit history, and config files to find exposed passwords, API keys, and tokens — before the bad guys do.

📖 Documentation · 🛡️ Security

---

The Problem: Accidental Password Posting

Imagine accidentally leaving your house keys under the doormat and posting a photo of it online. That's essentially what happens when a developer commits a password, API key, or database credential to a public GitHub repository. It happens more often than you'd think — and hackers have automated tools that scan millions of repos every day looking for exactly this mistake.

How VaultHound Solves It

VaultHound is an autonomous AI agent that acts like a security expert reviewing your codebase. You give it a GitHub URL, and it systematically hunts through every file, every past commit, and every configuration to find secrets that shouldn't be there. Unlike simple keyword scanners, VaultHound uses GPT-4o to understand context — it can tell the difference between a real production password and a test password in example code.

Why This Matters for Your Business

Every data breach costs money — not just in fines (GDPR can fine up to 4% of annual revenue), but in lost customer trust and reputation damage. A single exposed AWS key has led to ransomware attacks costing hundreds of thousands of dollars. VaultHound catches these leaks before attackers find them, saving your business from costly incidents.

Here's what happens when you point VaultHound at a repository:

flowchart TD
    A[👤 User enters GitHub URL] --> B[🔒 Input Validator\nChecks for attacks & sanitizes input]
    B --> C[🕷️ Repo Crawler\nFetches files, configs, CI/CD]
    C --> D[📜 Commit History Scanner\nLooks through past commits & deleted files]
    D --> E[⚡ Entropy Analyzer\nFlags suspicious high-randomness strings]
    E --> F{🚨 High Risk\nFindings?}
    F -- Yes --> G[🧠 GPT-4o Semantic Analyzer\nReads context like a human expert]
    F -- No --> G
    G --> H{🔴 Critical\nFindings?}
    H -- Yes --> I[🙋 Human Approval Gate\nYOU decide if deep scan proceeds]
    H -- No --> J[📊 Risk Scorer\nCVSS-style 0-10 score per finding]
    I -- Approved --> J
    J --> K[📋 Report Generator\nMarkdown + JSON output]
    K --> L[🛡️ Security Monitor\nRuns at every step checking for AI attacks]
    L --> M[✅ Dashboard + Export]

    style A fill:#e07b39,color:#1a1008
    style G fill:#8b2e0f,color:#f5e6d0
    style I fill:#c4922a,color:#1a1008
    style L fill:#5a8a3c,color:#f5e6d0
    style M fill:#2d1f0e,color:#f5e6d0

The 9 Pipeline Steps Explained:

1. Input Validator — Before anything else, VaultHound sanitizes your input to prevent attacks (like someone trying to inject malicious code into the URL field).

2. Repo Crawler — Downloads all files from the target repository, including configuration files and CI/CD pipelines.

3. Commit History Scanner — Dives into Git history to find secrets that were committed in the past but later deleted. These are still in the repository's history and are still dangerous.

4. Entropy Analyzer — Uses mathematical formulas (Shannon entropy) to find strings that look like random passwords or API keys, even if they're not obvious keywords.

5. GPT-4o Semantic Analysis — This is the brain. GPT-4o reads the code around each suspicious finding and decides: "Is this actually a secret, or is it a test/example?"

6. Human Approval Gate — If the AI finds something critical, it pauses and asks for your permission before running deeper analysis. You're always in control.

7. Risk Scorer — Every finding gets a score from 0 to 10 based on how dangerous it is, similar to how hospitals triage patients.

8. Report Generator — Creates a clean, readable report in both JSON (for machines) and Markdown (for humans).

9. Security Monitor — Runs invisibly at every step, watching for attempts to hack or manipulate the AI itself.

Modern AI agents can be attacked, tricked, or manipulated — just like regular software. A hacker might hide fake instructions inside a repository's code, hoping the AI will follow them instead of doing its job. VaultHound is built to resist all 10 known categories of attacks against AI agents.

🔍 Scan Tab — Watch the Agent Work in Real Time

Enter any GitHub URL and watch each AI agent step execute live. Every finding appears instantly in the results table.

📊 Dashboard — Your Risk At a Glance

Interactive Plotly charts show finding distribution, risk scores by file, and an overall danger gauge from 0–10.

Follow these steps to run VaultHound on your own machine:

• Python 3.11 or higher — Download from python.org
• Git — Usually pre-installed on Mac/Linux; download from git-scm.com for Windows
• OpenAI API Key — Get one at platform.openai.com (costs about $0.01 per scan)
• GitHub Personal Access Token — See the next section for how to create one

git clone https://github.com/AnandSundar/vaulthound.git
cd vaulthound

# On Windows
python -m venv venv
venv\Scripts\activate

# On Mac/Linux
python3 -m venv venv
source venv/bin/activate

pip install -r requirements.txt

Create a file named .env in the project root (copy from the example):

# VaultHound Environment Variables
# ⚠️ NEVER commit this file to Git — it's in .gitignore for a reason!

OPENAI_API_KEY=your_openai_api_key_here
GITHUB_TOKEN=your_github_personal_access_token_here  # Needs repo:read scope only

streamlit run vaulthound/app.py

Open your browser and go to: http://localhost:8501

# One-line Docker run (placeholder for future use)
docker run -p 8501:8501 --env-file .env vaulthound:latest

Follow these steps to create a GitHub Personal Access Token with minimum required permissions:

1. Go to GitHub Settings — Click your profile picture in the top-right, then select "Settings"

2. Navigate to Developer Settings — Scroll down and click "Developer settings" (near the bottom of the left sidebar)

3. Go to Personal Access Tokens — Click "Personal access tokens" → "Tokens (classic)"

4. Generate New Token — Click "Generate new token (classic)"

5. Give It a Name — Enter something like "VaultHound Scanner" in the "Note" field

6. Select the repo:read Scope — Check the box for repo (this automatically includes repo:read). This is the minimum permission VaultHound needs.

   ⚠️ Important: Do NOT select any write permissions. VaultHound only reads data — it never modifies anything.

7. Generate and Copy — Click "Generate token" at the bottom, then copy the token immediately (you won't be able to see it again)

8. Add to .env — Paste the token into your .env file as shown above

⚠️ Security Note: VaultHound only needs READ access to scan repositories. Never grant write permissions. Your token is stored only in your local session — it is never logged, transmitted, or stored in the database.

vaulthound/
├── vaulthound/
│   ├── app.py                      # 🚀 Main entry point — run this to start the app
│   ├── agents/
│   │   ├── graph.py                # 🕸️ LangGraph state machine — defines the AI pipeline
│   │   ├── nodes.py                # 🔧 Each AI agent step implemented here
│   │   ├── state.py                # 📐 Data models — defines what information flows between steps
│   │   └── security_monitor.py    # 🛡️ OWASP hardening — runs at every pipeline step
│   ├── tools/
│   │   ├── github_tools.py         # 🐙 GitHub API wrapper with rate limiting
│   │   ├── entropy_tools.py        # ⚡ Shannon entropy calculator + detect-secrets integration
│   │   └── validators.py           # ✅ Input sanitization and Pydantic schema validation
│   ├── ui/
│   │   ├── theme.py                # 🍂 Autumn color theme CSS injection
│   │   ├── components.py           # 🧩 Reusable Streamlit UI components
│   │   └── charts.py               # 📊 All Plotly visualization functions
│   └── db/
│       └── sqlite_store.py         # 💾 Scan history read/write with SQLite
├── .streamlit/
│   └── config.toml                 # ⚙️ Streamlit server and theme configuration
├── requirements.txt                # 📦 Pinned dependencies (exact versions for security)
├── .env.example                    # 🔑 Template for environment variables (safe to commit)
├── .gitignore                      # 🚫 Excludes .env, database files, secrets from Git
├── vaulthound.db                   # 💾 SQLite database (created automatically on first run)
└── README.md                       # 📖 You are here

VaultHound uses a dual-layer detection approach. First, it uses entropy analysis (mathematical formulas that detect how random a string looks — real passwords look very random) to find suspicious strings. Then, GPT-4o semantic analysis reads the surrounding code to determine if it's actually a secret or just a test/example.

You can deploy VaultHound to Streamlit Cloud for free — no credit card required:

1. Push Your Code to GitHub — Make sure your repository is public or you're comfortable making it public

2. Go to Streamlit Cloud — Visit share.streamlit.io and sign in with GitHub

3. Connect Your Repository — Click "New app" and select your GitHub repository

4. Set Your Secrets — In the Streamlit Cloud dashboard, go to "Secrets" and add your environment variables:

   OPENAI_API_KEY = "your-openai-api-key"
   GITHUB_TOKEN = "your-github-token"
   

5. Deploy — Click "Deploy". Within 2 minutes, your app will be live at a URL like https://vaulthound.streamlit.app

Note: On Streamlit Cloud, secrets are stored in their encrypted secrets manager — never in your code. They're automatically available as environment variables when your app runs.

We welcome contributions from the community! Here's how to help:

1. Fork the repository
2. Create a branch for your feature or bugfix (git checkout -b my-feature)
3. Make your changes and commit with clear messages
4. Push to your fork and submit a Pull Request

• We use Black for code formatting — run black . before committing
• Type hints are required for all new code
• All functions need docstrings

If you find a security vulnerability in VaultHound itself, please email your.email@example.com rather than opening a public issue. We'll respond within 24 hours and coordinate a responsible disclosure.

MIT License — feel free to use VaultHound in your projects, commercial or otherwise.

Built with 🍂 and ☕ by Anand Sundar

💼 LinkedIn · 🐙 GitHub