Hound
Language-agnostic AI auditor that autonomously builds and refines adaptive knowledge graphs for deep, iterative code reasoning.
Install / Use
/learn @scabench-org/HoundREADME
Overview
Hound is a Language-agnostic AI auditor that autonomously builds and refines adaptive knowledge graphs for deep, iterative code reasoning.
Key Features
- Graph-driven analysis – Flexible, agent-designed graphs that can model any aspect of a system (e.g. architecture, access control, value flows, math, etc.)
- Relational graph views – High-level graphs support cross-aspect reasoning and precise retrieval of the code snippets that back each subsystem investigated.
- Belief & hypothesis system – Observations, assumptions, and hypotheses evolve with confidence scores, enabling long-horizon reasoning and cumulative audits.
- Dynamic model switching – Lightweight "scout" models handle exploration; heavyweight "strategist" models provide deep reasoning, mirroring expert workflows while keeping costs efficient.
- Strategic audit planning - Balances broad code coverage with focused investigation of the most promising aspects, ensuring both depth and efficiency.
Codebase size considerations: While Hound can analyze any codebase, it's optimized for small-to-medium sized projects like typical smart contract applications. Large enterprise codebases may exceed context limits and require selective analysis of specific subsystems.
Links
Installation
pip install -r requirements.txt
Configuration
Set up your OpenAI API key and optional base URL:
export OPENAI_API_KEY=your_key_here
# Optional: override the base URL (defaults to https://api.openai.com)
export OPENAI_BASE_URL=https://api.openai.com
Using Gemini via Vertex AI (optional):
- Enable Vertex AI mode (instead of AI Studio) and set your GCP project and region.
- Credentials are taken from ADC (Application Default Credentials) or a service account; GOOGLE_API_KEY is not used in Vertex AI mode.
# Enable Vertex AI routing for Gemini
export GOOGLE_USE_VERTEX_AI=1
# Provide project and region (region examples: us-central1, europe-west1, asia-northeast1, etc.)
export VERTEX_PROJECT_ID=my-gcp-project
export VERTEX_LOCATION=us-central1
# Alternatively (fallbacks also supported):
# export GOOGLE_CLOUD_PROJECT=my-gcp-project
# export GOOGLE_CLOUD_REGION=us-central1
# Authenticate (one of the following)
# 1) Use gcloud ADC (recommended for local dev):
# gcloud auth application-default login
# 2) Or point to a service account key file:
# export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
When configured, the effective Vertex AI endpoint will be constructed as: https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{region} For example: https://us-central1-aiplatform.googleapis.com/v1/projects/my-gcp-project/locations/us-central1
Optional: configure via config.yaml instead of env vars:
gemini:
api_key_env: GOOGLE_API_KEY
vertex_ai:
enabled: true
project_id: "my-gcp-project"
region: "us-central1"
Copy the example configuration and edit as needed:
cp hound/config.yaml.example hound/config.yaml
# then edit hound/config.yaml to select providers/models and options
Notes:
- Defaults work out-of-the-box; you can override many options via CLI flags.
- Keep API keys out of the repo;
API_KEYS.txtis gitignored and can be sourced.
Note: Audit quality scales with time and model capability. Use longer runs and advanced models for more complete results.
Complete Audit Workflow
Step 1: Create a Project
Projects organize your audits and store all analysis data:
# Create a project from local code
./hound.py project create myaudit /path/to/code
# List all projects
./hound.py project ls
# View project details and coverage
./hound.py project info myaudit
Step 2: Build Knowledge Graphs
Hound analyzes your codebase and builds aspect‑oriented knowledge graphs that serve as the foundation for all subsequent analysis.
Recommended (one‑liner):
# Auto-generate a default set of graphs (up to 5) and refine
# Strongly recommended: pass a whitelist of files (comma-separated)
./hound.py graph build myaudit --auto \
--files "src/A.sol,src/B.sol,src/utils/Lib.sol"
# View generated graphs
./hound.py graph ls myaudit
Alternative (manual guidance):
# 1) Initialize the baseline SystemArchitecture graph
./hound.py graph build myaudit --init \
--files "src/A.sol,src/B.sol,src/utils/Lib.sol"
# 2) Add a specific graph with your own description (exactly one graph)
./hound.py graph custom myaudit \
"Call graph focusing on function call relationships across modules" \
--iterations 2 \
--files "src/A.sol,src/B.sol,src/utils/Lib.sol"
# (Repeat 'graph custom' for additional targeted graphs as needed)
Operational notes:
--autoalways includes the SystemArchitecture graph as the first graph. You do not need to run--initin addition to--auto.- If
--initis used and aSystemArchitecturegraph already exists, initialization is skipped. Use--autoto add more graphs, or remove existing graphs first if you want a clean re‑init. - When running
--autoand graphs already exist, Hound asks for confirmation before updating/overwriting graphs (including SystemArchitecture). To clear graphs:
./hound.py graph rm myaudit --all # remove all graphs
./hound.py graph rm myaudit --name SystemArchitecture # remove one graph
- For large repos, you can constrain scope with
--files(comma‑separated whitelist) alongside either approach.
Whitelists (strongly recommended):
- Always pass a whitelist of input files via
--files. For the best results, the selected files should fit in the model’s available context window; whitelisting keeps the graph builder focused and avoids token overflows. - If you do not pass
--files, Hound will consider all files in the repository. On large codebases this triggers sampling and may degrade coverage/quality. --filesexpects a comma‑separated list of paths relative to the repo root.
Examples:
# Manual (small projects)
./hound.py graph build myaudit --auto \
--files "src/A.sol,src/B.sol,src/utils/Lib.sol"
# Use the generated list (newline-separated) as a comma list for --files
./hound.py graph build myaudit --auto \
--files "$(tr '\n' ',' < whitelists/myaudit | sed 's/,$//')"
- Refine existing graphs (resume building):
You can resume/refine an existing graph without creating new ones using graph refine. This skips discovery and saves updates incrementally.
# Refine a single graph by name (internal or display)
./hound.py graph refine myaudit SystemArchitecture \
--iterations 2 \
--files "src/A.sol,src/B.sol,src/utils/Lib.sol"
# Refine all existing graphs
./hound.py graph refine myaudit --all --iterations 2 \
--files "src/A.sol,src/B.sol,src/utils/Lib.sol"
Step 3: Run the Audit
The audit phase uses the senior/junior pattern with planning and investigation:
# 1. Sweep all components for shallow bugs, build code understanding
./hound.py agent audit myaudit --mode sweep
# 2. Intuition-guided search to find complex bugs
./hound.py agent audit myaudit --mode intuition --time-limit 300
# Start with telemetry (connect the Chatbot UI to steer)
./hound.py agent audit myaudit --mode intuition --time-limit 30 --telemetry
# Attach to an existing session and continue where you left off
./hound.py agent audit myaudit --mode intuition --session <session_id>
Tip: When started with --telemetry, you can connect the Chatbot UI and steer the audit interactively (see Chatbot section above).
Audit Modes:
Hound supports two distinct audit modes:
-
Sweep Mode (
--mode sweep): Phase 1 - Systematic component analysis- Performs a broad, systematic analysis of every major component
- Examines each contract, module, and class for vulnerabilities
- Builds comprehensive graph annotations for later analysis
- Terminates when all accessible components have been analyzed
- Best for: Initial vulnerability discovery and building code understanding
-
Intuition Mode (
--mode intuition): Phase 2 - Deep, targeted exploration- Uses intuition-guided search to find high-impact vulnerabilities
- Prioritizes monetary flows, value transfers, and theft opportunities
- Investigates contradictions between assumptions and observations
- Focuses on authentication bypasses and state corruption
- B
