AgentHound

The offensive security framework for agentic infrastructure

MCP · A2A · agent clients · model gateways · inference servers · vector stores · MLOps · notebooks

Quickstart · Capabilities · Attack surface · Attack paths · Docs · Safety

Authorized use only. AgentHound performs active credential validation, model invocation, and reversible mutation when their prerequisites are present. Run it only against systems you own or are authorized to assess.

AgentHound is an open-source offensive security framework for agentic infrastructure. Drop one static collector onto a compromised host and run one scan. AgentHound captures local credentials and agent configuration, discovers reachable AI services, fingerprints and inventories them, reuses compatible credentials, verifies concrete access, and preserves everything in one continuously checkpointed JSON artifact.

The default scan is active because foothold access may disappear at any moment. --stealth switches the same workflow to read-only collection when OPSEC requires it.

The optional analysis server turns the artifact into a queryable attack graph with credential chains, execution and exfiltration paths, cross-protocol pivots, evidence-backed findings, risk scoring, history, and triage.

one foothold → one scan → secrets + services + proof → one artifact → full attack graph

⚡ Offensive capabilities

🎯 Foothold-first autonomous collection Local agent configs, instruction files, environment-backed secrets, loopback services, active interfaces, configured endpoints, and optional network scope all feed the same scan. No database or server connection is required on the compromised host.

🔑 Raw credential capture and reuse Concrete secrets are saved as usable material, deduplicated by value hash, and associated with every observed source. Newly discovered bearer tokens, API keys, master keys, and Jupyter tokens immediately unlock compatible same-scan collection and validation candidates.

🧪 Proof instead of reachability guesses For an eligible MCP resource, AgentHound first performs an anonymous control read. If that exact read succeeds, it records public access without presenting a credential. Otherwise, it follows with an authenticated read; a denied control plus an allowed credentialed read becomes Verified During Scan evidence tied to that credential and resource.

☠️ Reversible active validation Against eligible ContextForge-managed tools, the planner writes a scan-specific description marker, observes it through MCP, restores the original immediately, and independently confirms restoration before any other work continues.

🌐 Full-spectrum agentic attack surface AgentHound maps MCP, A2A, twelve agent-client configuration formats, model gateways, inference servers, vector stores, model registries, notebooks, and web interfaces as one connected target set.

🧬 Deep service and model intelligence Inventory Ollama served models, modelfiles, templates, and system prompts; LiteLLM credential references and virtual-key context; MLflow experiments and model registries; Jupyter sessions and files; and Qdrant collections. Deep mode adds recursive instruction discovery, bounded vector point references, and Ollama compute verification.

🕸️ Graph-native attack-path analysis The server joins trust, authentication, credential reuse, tool capabilities, sensitive resources, protocol boundaries, and observed proof into paths a red-team operator can query: reachability, execution, exfiltration, impersonation, shadowing, poisoning, and tainted data flow.

💾 Built for loss of access The collector writes an ingest-valid artifact before collection and checkpoints every meaningful result and action transition. Recovery state is persisted before mutation, cleanup runs even after cancellation, and unresolved restoration can be retried from the same artifact.

🎯 Every plane of the agentic stack

🚀 Quick start

1. Install the collector

Install the 1.1.1 static binary to ~/.local/bin:

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"

Or install with Homebrew:

brew install adithyan-ak/agenthound/agenthound

The collector has no Neo4j, PostgreSQL, Node.js, or server dependency. The shell installer supports macOS and Linux on amd64 or arm64. Windows builds are available from GitHub Releases.

2. Run one scan

Start with the compromised host and everything it can immediately reveal:

agenthound scan --output scan.json

Add a host, CIDR, or targets file without disabling local collection:

agenthound scan 10.20.0.0/24 --output scan.json
agenthound scan @targets.txt --deep --exclude 10.20.0.15 --output scan.json

Choose the mode that matches the operation:

These commands are alternatives and write scan.json. Without --output, the result is scan-<scan_id>.json. An explicit output path replaces an existing file, so use a new name for each scan. Concrete credentials and collected content are stored directly in the artifact; treat it as operationally sensitive.

If the final summary reports unresolved cleanup, preserve the artifact and retry safely:

agenthound revert scan.json

3. Analyze the attack graph

The server is optional during collection. Start it on the analysis system when you are ready to ingest:

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 http://127.0.0.1:8080 to inspect findings, attack paths, credentials, risk, queries, scan history, and triage.

Use the collector and server from the same release. Releases after 1.1.1 pin the exact server image in Compose; older Compose files retain their historical latest reference. A current server accepts supported older V1 artifacts. If ingest reports an unsupported contract, upgrade the server instead of editing the artifact.

🔪 One autonomous offensive workflow

agenthound scan drives the operational loop without requiring the operator to choose a module for every discovered service:

1. Map the foothold — parse supported agent configs and instruction sources; capture concrete credentials and configured endpoints.
2. Discover the reachable estate — seed local interfaces and explicit targets, scan standard AI-service ports, and fingerprint responding services.
3. Collect useful data — enumerate MCP and A2A, then inventory applicable gateways, inference servers, vector stores, MLOps services, notebooks, and web interfaces.
4. Expand with credentials — present newly observed material only to compatible service adapters and generate new candidates as access grows.
5. Prove access — perform differential MCP resource reads, eligible reversible ContextForge round trips, and deep Ollama compute verification.
6. Preserve evidence — merge every observation, action outcome, proof, and recovery transition into the continuously checkpointed artifact.
7. Pathfind — ingest later to build full-graph reachability, execution, exfiltration, credential-chain, and cross-protocol findings.

Independent collection failures do not block unrelated work. A checkpoint failure or unresolved mutation cleanup stops new forward work so the artifact remains the source of truth.

🔎 What AgentHound finds

Core graph primitives include CAN_REACH, CAN_EXECUTE, CAN_EXFILTRATE_VIA, CAN_IMPERSONATE, SHADOWS, POISONED_DESCRIPTION, INSTRUCTION_SIGNAL, POISONED_INSTRUCTIONS, TAINTS, and IFC_VIOLATION. Instruction findings retain bounded matched excerpts with paths and line numbers; the hash remains secondary integrity metadata. See the Attack Paths guide and Graph Model for their evidence semantics.

🛡️ Safety & OPSEC

AgentHound is designed for authorized operation from a compromised host:

• Active by default: compatible credential reuse, differential access reads, deep model invocation, and eligible reversible mutation happen in the initial scan.
• Read-only switch: --stealth disables cross-target credential presentation, compute and tool invocation, and mutation while preserving anonymous and exact configured collection.
• Hard exclusions: repeatable --exclude rules are enforced against hostnames, IPs, CIDRs, DNS results, redirects, derived URLs, cleanup requests, and final socket dials.
• Immediate recovery: reversible actions persist original state before mutation, restore immediately under a separate cleanup context, and confirm the original before planning continues.
• Plaintext evidence: concrete secrets, returned content, action outcomes, and recovery data remain available in the JSON artifact. The dashboard masks credential values by default and keeps Reveal and Copy one click away.

Read Security and OPSEC before using active mode in a constrained environment.

📚 Documentation and development

Install · Quickstart · Scanner · CLI · Attack Paths · Deployment · Security

The collector remains a static binary with no database or server dependency. New service intelligence and autonomous actions are registered as modules and participate in the same artifact, planner, contact-policy, and evidence contracts. See CONTRIBUTING.md and Writing Modules.

AgentHound is licensed under the Apache License 2.0. To report a vulnerability in AgentHound itself, see SECURITY.md.