Abdulla-AlBassam/url-triage-agent

# URL 分诊代理 一个自主的 AI 代理，用于调查网络链接是安全、可疑还是恶意，并逐步解释其推理过程。 ``` $ uv run triage https://carbon-dating-calibration.garden/.../google.ct → whois_lookup ... age: 1 day, registrar: PDR → dns_lookup ... Cloudflare A records, 300s TTL → virustotal_lookup ... submitted (not previously seen) → urlhaus_lookup ... found, threat: malware_download, tag: ClearFake ╭─────────────────────────── Verdict ────────────────────────────╮ │ MALICIOUS │ │ Confidence: 10/10 │ │ │ │ URLhaus positively identifies this URL as an active ClearFake │ │ malware-download site... │ ╰────────────────────────────────────────────────────────────────╯ ``` 向它提供任何 URL。它会选择合适的调查工具，读取证据，并返回判定（`BENIGN`（良性）、`SUSPICIOUS`（可疑）或 `MALICIOUS`（恶意）），附带置信度分数和经过证实的证据列表。 该项目在一次通宵会议中完成，作为对抗“构建用于威胁检测的 AI 代理”简报的展示作品。有关设计理念、威胁模型和详细的组件分解，请参阅 [`技术文档`](TECHNICAL.md)。 ## 通俗易懂的功能描述 你收到一个链接。你不信任它。它是钓鱼页面吗？是恶意软件下载吗？还是一个你没听说过的正规企业？ 一个人类安全分析师会手动调查。他们会查是谁注册了这个域名。他们会看它是否被报告到公开的威胁数据库。他们会在隔离的浏览器中打开页面，看看它到底显示什么。然后他们会写一个简短的笔记：“是的，这是恶意的，原因是这样。” 这每个链接需要几分钟，而待处理队列的增长速度超过了他们的处理能力。 这个工具能在几秒钟内自动完成这项工作，适用于你提供的任何 URL。 ## 工作原理 这个故事里有两个角色。 **大脑。** Claude（Anthropic 的 AI 模型）读取 URL 并决定要进行哪些检查。它自己无法执行，因此要求程序代表它去执行。 **双手。** 十个小型 Python 脚本，每个执行一项特定的调查：“查询此域名”、“询问 VirusTotal 对此 URL 的看法”、“在沙盒浏览器中打开此页面”。代理称它们为“工具”。 大脑选择一个工具，双手运行它，大脑读取结果，大脑选择下一个工具。最终，大脑调用一个特殊的工具 `write_report`，并说：“我完成了。这是我的判定和证据。” 这个来回的过程就是 *代理循环*，它位于 [`agent_loop.py`](src/triage_agent/agent_loop.py) 中。 ## 工具列表 | 工具名称 | 功能描述 | | --- | --- | | `dns_lookup` | 询问 DNS 谁来响应这个域名。包含 A/AAAA/MX/NS/TXT 记录和 TTL。 | | `whois_lookup` | 查询域名的注册时间和注册人。新注册的域名通常可疑。 | | `tls_certificate` | 拉取网站的 TLS 证书。自签名、全新的或 SAN 列表很短的证书是可疑的。 | | `urlhaus_lookup` | 检查 abuse.ch 的恶意 URL 社区反馈。命中这里就是强有力的证据。 | | `virustotal_lookup` | 询问 70 多个防病毒引擎对该 URL 的看法。 | | `urlscan_lookup` | 检查 urlscan.io 针对此域名的以往沙盒渲染存档。 | | `sandbox_fetch` | 在加固的 Docker 容器中渲染页面。参见下面的“沙盒”部分。 | | `ioc_extractor` | 从任意文本中提取 IOC（URL、IP、哈希、电子邮件、比特币地址）。 | | `favicon_hasher` | 计算网站 favicon 的 Shodan 兼容 MurmurHash3。这是它所来自的钓鱼工具包的指纹。 | | `brand_impersonation` | 使用渲染后的 DOM 对“这个页面是否在冒充已知品牌？”进行 0-10 分的评分。 | | `write_report` | 代理的“我完成”信号。以结构化的判定结束调查。 | ## 沙盒 `sandbox_fetch` 工具是项目中最复杂的工程部分。当廉价的信号无法解决问题且需要渲染页面本身时，代理才会使用它。该容器通过多个方面进行了加固： - **无主机挂载。** 容器无法访问主机文件系统。 - **`--cap-drop=ALL`** 仅加上 `NET_ADMIN`、`SETUID`、`SETGID`。其他所有权限都被拒绝。 - **`--security-opt=no-new-privileges`**。没有 setuid 提权路径。 - **`--read-only`** 根文件系统，加上一个小型的 `/tmp` tmpfs 用于临时存储。 - **内存和 CPU 限制**（768 MB，1 个 CPU）。失控的页面无法耗尽笔记本资源。 - **iptables 出口锁定。** 仅允许出站 TCP 连接到已解析的目标 IP 的 80 和 443 端口。页面无法悄无声息地联系 C2 服务器、跟踪像素或其他任何东西。 - **非 root 运行。** 入口点以 root 身份设置 iptables，然后在启动 Chromium 之前通过 `gosu` 切换到非 root 用户。 - **每次请求独立使用。** 每次请求使用一个全新的容器，退出后即移除。不保留任何状态。 完整的威胁模型请见 [`技术文档`](TECHNICAL.md#the-sandbox-threat-model)。 ## 快速开始 你需要三样东西： 1. **Python 3.12+**。使用 `python3 --version` 检查。 2. **uv**，一个快速的 Python 包管理器：`curl -LsSf https://astral.sh/uv/install.sh | sh` 3. **Docker Desktop**，正在运行。仅沙盒工具需要。 然后： ``` # 复制 env 模板并粘贴您的真实密钥。 cp .env.example .env # 在编辑器中打开 .env 文件并添加至少一个 ANTHROPIC_API_KEY。 # 安装依赖项。 uv sync # 对 URL 进行分类处理。 uv run triage https://example.com ``` 首次调用沙盒会构建 Docker 镜像（约 1.5 GB 下载，仅一次）。后续调用将重用该镜像。 ## API 密钥 | 密钥名称 | 是否必需？ | 获取方式 | | --- | --- | --- | | `ANTHROPIC_API_KEY` | **必需** | [console.anthropic.com](https://console.anthropic.com/) | | `URLHAUS_AUTH_KEY` | 用于 URLhaus | [auth.abuse.ch](https://auth.abuse.ch/) (免费) | | `VIRUSTOTAL_API_KEY` | 可选，推荐 | [virustotal.com](https://www.virustotal.com/gui/join-us) (免费) | | `URLSCAN_API_KEY` | 可选，推荐 | [urlscan.io](https://urlscan.io/user/signup) (免费) | 缺少密钥的工具会报告自身不可用，代理会绕过它们。严格来说，运行只需要 Anthropic 密钥。 ## 运行示例 真实运行的两个记录在 [`docs/sample_runs/`](docs/sample_runs/) 中： - [`01_benign_github.txt`](docs/sample_runs/01_benign_github.txt)。`https://github.com`。通过廉价信号轻松判定。 - [`02_malicious_tiktok_phish.txt`](docs/sample_runs/02_malicious_tiktok_phish.txt)。一个活跃的 TikTok Shop 凭证钓鱼。完整使用了流程：DNS、WHOIS、TLS、VirusTotal、URLhaus、沙盒渲染和品牌冒充分析。 ## 仓库结构 ``` url-triage-agent/ ├── README.md ← you are here ├── TECHNICAL.md ← design rationale and threat model ├── PLAN.md ← the original design notes ├── pyproject.toml ← dependencies and entry point ├── .env.example ← template for API keys ├── sandbox/ ← the Docker sandbox │ ├── Dockerfile ← Playwright + iptables + non-root │ ├── entrypoint.sh ← egress lockdown, then drop privs │ └── runner.py ← Playwright capture, JSON to stdout ├── src/triage_agent/ │ ├── agent_loop.py ← the brain-talks-to-hands loop │ ├── cli.py ← the command-line interface │ ├── tool_registry.py ← decorator-based tool registration │ ├── prompts/system_prompt.md ← the SOC-analyst system prompt │ └── tools/ ← one file per tool, all real ├── tests/ │ └── test_smoke.py ← scaffolding integrity tests ├── docs/sample_runs/ ← saved transcripts of real runs └── reports/ ← saved verdicts (JSON) ``` ## 局限性说明 - **不是** SIEM、完整威胁情报平台或 SOC 的替代品。它一次只对单个 URL 进行分诊。 - **不是** 恶意软件分析意义上的沙盒。Chromium 在其中运行，但我们不会引爆二进制文件；我们渲染网页。 - **不是** 确定性的。代理通过工具的确切路径可能变化。在明确的情况下判定是可靠的，在模棱两可的情况下也有充分的证据支持，但你应该阅读证据而不是只依赖标签。 - **未进行基准测试**。这个仓库中的少数真实运行案例是轶事，不是统计数据。对标记语料库进行测量精确率/召回率的研究是自然的下一步。 ## 测试 ``` uv run pytest ``` 冒烟测试覆盖了基础结构：每个工具都已注册，每个模式都是可序列化的 JSON，调度处理未知情况，系统提示加载正常。 ## 许可证 MIT。参见 `LICENSE`。

标签：AI 代理, AMSI绕过, Anthropic 工具, DAST, DNS 分析, Docker 沙箱, URLhaus 集成, URL 分流, VirusTotal 集成, WHOIS 查询, 公开威胁数据库, 在线安全检查, 威胁检测, 威胁置信度评估, 安全分析工具, 安全评分系统, 恶意软件分析, 恶意链接识别, 特征检测, 网络安全, 自动化威胁调查, 自定义DNS解析器, 证据驱动分析, 请求拦截, 逆向工具, 逐步推理, 钓鱼检测, 隐私保护