adithyan-ak/AgentHound

AgentHound – Offensive security framework for AI‑agent infrastructure

What it is – AgentHound is an open‑source tool that lets a red‑team operator enumerate, validate, and attack the whole “agentic stack” that powers modern LLM‑backed assistants (Claude, Cursor, VS Code extensions, Ollama, LiteLLM, Qdrant, MLflow, Jupyter, etc.). It works from a foothold on a compromised host, collects configuration files, secrets and reachable AI services, re‑uses any discovered credentials, proves real access, and stores everything in a single, checkpointed JSON artifact. An optional server can ingest that artifact and present a graph‑based attack surface view with credential‑chains, execution and exfiltration paths, and risk scores.

---

Core workflow

1. Deploy the static collector on the compromised machine (single binary, no DB or runtime dependencies).
2. Run agenthound scan – the collector gathers local agent configs, environment secrets, loopback services, and (optionally) a network range. It fingerprints AI services, re‑uses any captured API keys or tokens, and performs verified reads (anonymous first, then credentialed) to prove access.
3. Produce a JSON artifact that contains every credential, service fingerprint, proof of access, and a checkpoint after each step.
4. (Optional) Start the analysis server on a separate machine, ingest the artifact, and explore a Neo4j‑backed attack graph via a web UI. The graph shows reachable resources, execution capabilities, exfiltration routes, cross‑protocol pivots, and poisoned instruction files.

---

Key capabilities

Capability	What it does
Foothold‑first autonomous collection	Pulls local agent configuration files, instruction files, environment variables, loopback services, and any explicitly‑provided network scope without needing a remote database.
Raw credential capture & reuse	Stores concrete secrets (API keys, bearer tokens, Jupyter tokens, master keys) as deduplicated values and immediately tries them against any compatible service discovered during the same scan.
Proof‑based access validation	Performs an anonymous read first; if that fails, it retries with a credential. A successful credentialed read is recorded as Verified During Scan evidence.
Reversible active validation	For ContextForge‑managed tools, writes a temporary marker, reads it back through the MCP, then restores the original state, confirming the rollback before proceeding.
Full‑spectrum agentic surface mapping	Detects and inventories MCP, A2A, twelve agent‑client config formats, model gateways, inference servers, vector stores, model registries, notebooks, and web interfaces as a single connected target set.
Deep service & model intelligence	Lists Ollama models, modelfiles, prompts; extracts LiteLLM credential references; enumerates MLflow experiments; discovers Qdrant collections; inspects Jupyter sessions. In deep mode it can invoke a bounded Ollama embedding request to prove compute access.
Graph‑native attack‑path analysis	The server builds a Neo4j graph linking trust, authentication, credential reuse, tool capabilities, and observed proofs. Operators can query reachability, execution, exfiltration, impersonation, poisoning, and more.
Loss‑of‑access resilience	The collector checkpoints the artifact after every meaningful action; if a mutation fails, it rolls back and can resume from the last checkpoint.

---

Modes of operation

Mode	Behaviour
agenthound scan (default)	Active collection: credential reuse, MCP proof, reversible ContextForge validation, and (if applicable) model invocation.
agenthound scan --deep	Adds recursive instruction discovery, bounded Qdrant point reads, and expensive service probes such as Ollama embedding verification.
agenthound scan --stealth	Read‑only collection: no cross‑target credential reuse, no model/tool invocation, no mutation. Only anonymous and exact configured reads are performed.
agenthound scan --stealth --deep	Same as stealth but still performs deep filesystem reads while keeping the collection non‑interactive.

---

Quick start (from the README)

# Install the static binary (macOS/Linux, amd64/arm64)
curl -sSfL https://raw.githubusercontent.com/adithyan-ak/agenthound/1.1.1/install.sh \
  | AGENTHOUND_VERSION=1.1.1 sh
export PATH="$HOME/.local/bin:$PATH"

# Run a basic scan from the foothold
agenthound scan --output scan.json

# Optional: start the analysis server with Docker Compose
curl -sSfL https://raw.githubusercontent.com/adithyan-ak/agenthound/1.1.1/docker/docker-compose.public.yml \
  -o agenthound-compose.yml
docker compose -f agenthound-compose.yml -p agenthound up -d --wait
docker compose -f agenthound-compose.yml -p agenthound exec -T agenthound \
  agenthound-server ingest - < scan.json

# Open the UI
open http://127.0.0.1:8080

---

What you get from a scan

Finding type	Example question it answers
Verified credential access	Which exact secret proved access to which MCP resource?
Credential‑chain paths	How does a captured API key connect an agent config to a model gateway?
Reachability	What services can be reached following current trust and authentication links?
Execution paths	Which agents can invoke a shell or database tool?
Exfiltration paths	Where can sensitive data be sent out of the environment?
Cross‑protocol pivots	Can an A2A delegation be used to reach a vector store?
Instruction poisoning	Which instruction files contain evidence of prompt injection or poisoned context?
Tool shadowing / rug pulls	Are there look‑alike tools that could hijack expected capabilities?
Unauthenticated surfaces	Which services expose data without any credential?
Risk hotspots	Which nodes or paths have the highest impact score?

---

Safety & OPSEC notes (from the README)

• Authorized use only – run against systems you own or have explicit permission to test.
• Active mode performs credential reuse and reversible mutations; use --stealth for read‑only collection when you need to stay hidden.
• Hard exclusions (--exclude) prevent accidental interaction with hosts or URLs you do not wish to touch.
• Immediate recovery – any mutation is undone before the next step; if cleanup fails, the artifact records the state so you can retry safely.
• Plain‑text evidence – the JSON artifact contains raw secrets and responses; the web UI masks them by default but they can be revealed with a click.

---

Documentation & contribution

• Full docs: https://docs.agenthound.io
• Quick‑start, scanner, CLI, attack‑paths, deployment, and security guides are all in the docs/ folder.
• Modules can be added to support new services; see CONTRIBUTING.md and docs/contributing/modules.md.
• Licensed under Apache‑2.0; vulnerability reports go to SECURITY.md.

---

Bottom line – AgentHound is a purpose‑built offensive framework that treats modern LLM‑powered assistants as a networked attack surface. It automates credential harvesting, proof‑based validation, and graph‑level analysis, giving red‑teamers a single artifact and visual UI to understand and exploit the entire agentic stack.