adithyan-ak/AgentHound

AgentHound 映射现代 AI agent 技术栈内部的信任关系，将其转化为 Neo4j 图，并揭示那些至关重要的路径：一个 agent 能够到达、执行、冒充或通过其进行数据渗漏的路径。 它以两个二进制文件的形式发布： - **`agenthound`**：一个精简的收集器，用于枚举本地配置、MCP、A2A 和 AI 服务面，然后输出 JSON。 - **`agenthound-server`**：一个 localhost 分析服务器，集成了 Neo4j、PostgreSQL、REST API、后处理器以及 React 图形 UI。 ## 为什么选择 AgentHound？ 静态配置扫描器一次只能读取一个文件。但攻击路径并非如此。 一个 agent 可能信任某个 MCP 服务器。该服务器可能暴露了一个凭据。另一个独立的服务可能使用了相同的凭据进行授权。没有任何单个配置文件会声明完整的路径，但组合起来的图可以。 AgentHound 将这些事实连接成一个有向信任图，这样你就可以查询： ``` Which agents can reach shell-capable tools? Which credentials create cross-service paths? Which poisoned tools sit on high-risk routes? Which agents can read sensitive data and send it outbound? ``` 这就是将 BloodHound 的理念应用于 AI agent 基础设施——跨越整个技术栈，而不仅仅局限于单一协议： - 🔌 **协议** — MCP · A2A - 🧠 **服务** — LiteLLM · Ollama · vLLM · LangServe · MLflow · Qdrant · Jupyter · Open WebUI - 💻 **Agent 客户端** — Claude Desktop · Claude Code · Cursor · VS Code · Windsurf · Continue · Cline · Zed · JetBrains · Amazon Q · Kiro · Augment ## 工作原理 ``` flowchart LR subgraph Field["Field / scanned environment"] Config["Local configs"] MCP["MCP servers"] A2A["A2A agents"] Services["AI services"] Collector["agenthound collector"] end subgraph Operator["Operator workstation"] JSON["Scan JSON"] Ingest["Ingest"] Neo4j[("Neo4j")] Postgres[("PostgreSQL")] Analyze["Post-processors
Risk scoring"] API["REST API"] UI["Graph UI"] end Config --> Collector MCP --> Collector A2A --> Collector Services --> Collector Collector --> JSON JSON --> Ingest Ingest --> Neo4j Ingest --> Postgres Neo4j --> Analyze Analyze --> API Analyze --> UI ``` 收集器保持小巧且便携：没有 Neo4j 驱动，没有 PostgreSQL 客户端，没有 UI，也没有服务器依赖。它写入 JSON 然后退出。服务器负责摄取、去重、图写入、后处理、查询 API 以及可视化。 AgentHound 的图模型包含 agent、MCP 服务器、工具、资源、prompt、凭据、主机、配置文件、指令文件、A2A agent、AI 服务节点和模型节点。诸如 `CAN_REACH`、`CAN_EXECUTE`、`CAN_EXFILTRATE_VIA`、`CAN_IMPERSONATE`、`SHADOWS`、`POISONED_DESCRIPTION` 和 `POISONED_INSTRUCTIONS` 等复合边是在数据摄取后计算得出的。 请在[图模型参考](https://docs.agenthound.io/reference/graph-model/)中阅读完整的 schema。

## 快速开始 前置条件：Docker + Compose v2。无需 Go，无需 Node.js，无需 `git clone`——服务器从预构建的镜像运行，而收集器是一个单一的静态二进制文件。 **1. 启动分析服务器**（Neo4j + Postgres + UI，绑定 `127.0.0.1:8080`）。`--wait` 会阻塞直到健康检查变为绿色，这样第 3 步就不会与之发生竞态： ``` curl -sSfL https://raw.githubusercontent.com/adithyan-ak/agenthound/main/docker/docker-compose.public.yml | docker compose -f - -p agenthound up -d --wait ``` **2. 安装收集器**（单一静态二进制文件，约 9 MiB → `~/.local/bin`）： ``` curl -sSfL https://raw.githubusercontent.com/adithyan-ak/agenthound/main/install.sh | sh ``` 将其添加到当前会话的 `PATH` 中（可通过追加到 `~/.zshrc` 或 `~/.bashrc` 来持久化；fish 用户请运行 `fish_add_path ~/.local/bin`）： ``` export PATH="$HOME/.local/bin:$PATH" ``` **3. 扫描并直接流式传输到运行中的服务器：** ``` agenthound scan --config --output - | curl --data-binary @- -H "Content-Type: application/json" http://127.0.0.1:8080/api/v1/ingest ``` **4. 打开 UI**，访问 `http://127.0.0.1:8080`（macOS 上使用 `open`，Linux 上使用 `xdg-open`）： ``` open http://127.0.0.1:8080 ``` 无需 token，无需登录，无需拖拽。服务器允许非浏览器调用者（curl、agenthound CLI、cron）访问，并拒绝来自你浏览器的跨域 POST 请求。单用户，仅限 localhost——请参阅[安全模型](docs/operator/security.md)。

其他安装和摄取选项

``` # 将扫描文件拖拽到 UI 的 Scan Manager 中（零 CLI 摄取） agenthound scan --config open http://127.0.0.1:8080 # then drop scan-*.json into the Scan Manager # 从源码构建（需要 Go 1.25+ 和 Node.js 20+） git clone https://github.com/adithyan-ak/agenthound.git && cd agenthound docker compose -f docker/docker-compose.yml up -d --build # builds server image locally make build # bin/agenthound + bin/agenthound-server # 使用 Go 安装 collector go install github.com/adithyan-ak/agenthound/collector/cmd/agenthound@latest # 使用 Go 安装并启动 server（完全跳过 Docker；由您提供 Neo4j + Postgres） go install github.com/adithyan-ak/agenthound/server/cmd/agenthound-server@latest agenthound-server serve # 将 install.sh 固定到 release tag（校验 checksums；在可用时使用 cosign） curl -sSfL https://raw.githubusercontent.com/adithyan-ak/agenthound/v0.7.0/install.sh | sh ``` 请查看完整的[安装指南](https://docs.agenthound.io/getting-started/install/)以了解 Homebrew、发布二进制文件、签名验证和源码构建。

## 从侦察到报告 一个二进制文件运行整个攻击路径生命周期。每个阶段都输出相同的摄取封装，因此结果会汇入同一个图中。主动性动词（`loot`、`poison`、`implant`）需要交互式的 `AUTHORIZED` 确认；`poison` 和 `implant` 在使用 `--commit` 前处于试运行状态，并可通过 `agenthound revert` 撤销——请参阅[负责任的使用与安全姿态](#responsible-use--security-posture)。 **1. 侦察** — 发现攻击面： ``` agenthound scan 10.0.0.0/24 agenthound discover 10.0.0.0/24 --mcp ``` **2. 收集** — 提取潜伏凭据，只读（GET/HEAD）： ``` agenthound loot 172.30.0.20:4000 --type litellm --master-key sk-... --engagement-id RTV --output - ``` 收集器类型：`litellm`、`ollama`、`mlflow`、`qdrant`、`openwebui`、`jupyter`。 **3. 利用** — 授权的、可逆的攻击性操作： ``` agenthound poison 10.0.0.30:8080 --type mcp.tool.description --target-id support_lookup --inject "Ignore prior instructions." --engagement-id RTV --commit agenthound revert RTV ``` **4. 分析** — 路径发现与门控： ``` agenthound-server query --prebuilt credential-chain agenthound-server query --findings --fail-on critical ``` 请查看完整的 [CLI 参考](https://docs.agenthound.io/reference/cli/)以了解每个动词、标志和模块。 ## AgentHound 能发现什么 AgentHound 的检测功能围绕安全团队在需要了解可达性、影响范围和路径风险时提出的问题而构建。 | 发现 | 含义 | 安全问题 | |---|---|---| | **凭据链路径** | 同一 secret 出现在多个上下文中，让信任跨越了服务边界。 | 哪个被重复使用的凭据让 agent 获得了它从未明确拥有过的访问权限？ | | **可达性** | Agent、MCP 服务器、工具、资源、prompt、A2A 技能和 AI 服务被连接到一个图中。 | 如果沿着信任边追踪，这个 agent 实际上能到达哪里？ | | **执行路径** | Agent 能够到达类似 shell、数据库、网络或其他高影响力的工具。 | 哪些 agent 拥有通往命令执行、数据面控制或影响生产环境的路径？ | | **数据渗漏路径** | Agent 能够读取敏感数据，并且能够访问出站通道。 | 敏感数据可以从环境中的哪里外泄？ | | **跨协议枢轴** | MCP、A2A、主机上下文和 AI 服务基础设施结合形成一条可达路径。 | 一个 agent 协议能否成为通往另一个信任域的桥梁？ | | **工具投毒** | 工具描述、prompt 或指令文件包含可疑的模型引导内容。 | 哪些工具或指令可能会以不安全的方式影响模型行为？ | | **工具影子化** | 外观相似的工具模仿受信任的能力或名称。 | 哪个工具可能会拦截或劫持预期的操作？ | | **地毯式撤回** | 工具的描述在不同扫描之间发生了变化。 | 自上一个已知良好的图以来发生了什么变化，它是否创建了一个新的风险路径？ | | **未经身份验证的服务器或 agent** | 可以在没有预期身份验证的情况下访问 MCP 服务器或 A2A agent。 | 哪些暴露的 agent 面需要立即审查？ | | **风险热点** | 节点和路径根据风险评分和预置图查询进行优先排序。 | 首先应该从哪里开始调查或修复？ | 请参阅[检测规则](https://docs.agenthound.io/reference/detection-rules/)和[风险评分](https://docs.agenthound.io/reference/risk-scoring/)获取完整目录。 ## 路径原语 AgentHound 不仅列出发现结果。它还创建你可以链接、查询和报告的图边： - **`CAN_REACH`**：agent 可以遍历信任、凭据、主机或协议关系以到达目标。 - **`CAN_EXECUTE`**：agent 能够到达能够执行命令、数据库、网络或代码执行的工具。 - **`CAN_EXFILTRATE_VIA`**：agent 能够读取敏感数据并通过出站通道发送。 - **`CAN_IMPERSONATE`**：agent 或身份可以作为另一个信任主体行事。 - **`SHADOWS`**：一个工具足够逼真地模仿受信任的工具，从而劫持预期行为。 - **`POISONED_DESCRIPTION` / `POISONED_INSTRUCTIONS`**：工具或指令文本包含模型引导内容。 这些边将 AI agent 基础设施转变为你能够进行路径发现的东西，而无需手动推理。 ## 路径示例 ``` flowchart LR Agent["AgentInstance
claude-desktop"] Notes["MCPServer
internal-notes"] Cred["Credential
value_hash: a3f9..."] Gateway["LiteLLMGateway
prod"] Providers["LLM providers
OpenAI / Anthropic / Bedrock"] Agent -- TRUSTS_SERVER --> Notes Notes -- HAS_ENV_VAR --> Cred Gateway -- EXPOSES_CREDENTIAL --> Cred Agent -- CAN_REACH --> Gateway Gateway -- PROVIDES_MODEL --> Providers ``` 没有任何单个配置文件声明此路径。一旦收集器输出汇入同一个图，AgentHound 就会将其计算出来。 ## 适用场景 - **初始访问分诊**：识别在未经预期身份验证的情况下暴露的 agent 面。 - **权限提升**：发现 agent、工具、主机和服务之间重复使用的凭据和信任路径。 - **目标路径规划**：查询通往类 shell 工具、数据库、模型网关和敏感资源的路由。 - **证据打包**：报告基于图的路径，而不是模糊的配置观察结果。 - **重测验证**：比较扫描结果以证明关键路径已消失。 ## 负责任的使用与安全姿态 AgentHound 专为授权评估和内部可见性而构建。主动模块仅用于授权测试，并单独记录在案。操作者负责对每个目标进行授权。 - 收集器默认处于离线状态，并将 JSON 写入文件或标准输出。 - 服务器默认绑定到 `127.0.0.1:8080`。 - 服务器为单用户，没有应用层登录。请勿将其暴露在 localhost 之外；读取 endpoint 可能会暴露收集到的图内容。 - 更改 localhost API endpoint 受 Origin 允许列表（`OriginGuard`）限制；跨域浏览器 POST 请求会被拒绝，非浏览器调用者（curl、agenthound CLI）可直接通过。 - 对于支持的网络模块，默认严格进行 TLS 验证。 - 破坏性或变更性的评估工作流需要操作者的明确意图，应仅在书面授权范围内使用。 请阅读[安全姿态指南](https://docs.agenthound.io/operator/security/)和[攻击性操作指南](https://docs.agenthound.io/operator/offensive-actions/)。 ## 文档 完整文档位于 [docs.agenthound.io](https://docs.agenthound.io)。 从以下内容开始： - [快速开始](https://docs.agenthound.io/getting-started/quickstart/) - [安装指南](https://docs.agenthound.io/getting-started/install/) - [CLI 参考](https://docs.agenthound.io/reference/cli/) - [配置指南](https://docs.agenthound.io/reference/configuration/) - [图模型](https://docs.agenthound.io/reference/graph-model/) - [检测规则](https://docs.agenthound.io/reference/detection-rules/) - [部署指南](https://docs.agenthound.io/operator/deployment/) - [安全姿态](https://docs.agenthound.io/operator/security/) ## 贡献 AgentHound 围绕小型的、自注册的模块和稳定的摄取格式构建。收集器、检测器和后处理器设计为可扩展，而无需将服务器依赖项拉入收集器。 请从 [CONTRIBUTING.md](CONTRIBUTING.md) 和[模块编写指南](https://docs.agenthound.io/contributing/modules/)开始。发现 AgentHound 本身的漏洞？请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 AgentHound 采用 [Apache License 2.0](LICENSE) 授权。

标签：A2A, AI安全, Chat Copilot, EVTX分析, Go语言, MCP, StruQ, 攻击路径分析, 数据泄露, 日志审计, 测试用例, 程序破解, 请求拦截