mhdebaky/darktrace-threat-hunting

# Darktrace 威胁狩猎 Skill 一个用于在 Darktrace 网络遥测数据中狩猎威胁的 **Agent Skill** —— 这是一个只读的 API 客户端，外加一份 Advanced Search 查询手册。 Darktrace 的 Threat Visualizer 擅长对模型已经标记的事件进行分类。而狩猎——也就是让你自己对原始网络遥测数据提出问题——在终端（terminal）中执行起来要快得多，你可以在几秒钟内完成聚合、关联和迭代。这就是它的用途。 ``` SKILL.md # the skill: setup, commands, hunting loop, visibility checks references/advanced-search.md # query reference — syntax, field map, ~60 hunting queries scripts/dark-trace-hunting.py # the API client (read-only, single file, requests only) ``` ## 作为 Skill 使用 Agent Skill 是包含带有 YAML frontmatter 的 `SKILL.md` 文件的文件夹。该 frontmatter 中的 `description` 是供 Agent 阅读以决定何时调用此 Skill 的；正文会在需要时加载，而 `references/advanced-search.md` 则只会在需要查询时叠加加载。 **Claude Code** —— 将其克隆到你的 skills 目录中，它就会被自动发现： ``` git clone https://github.com//darktrace-threat-hunting.git \ ~/.claude/skills/darktrace-threat-hunting ``` 然后你只需提问：*"hunt for DNS tunnelling in the last 24 hours"*，或者直接使用 `/darktrace-threat-hunting` 调用它。如果希望其针对特定项目而非全局生效：可以使用仓库中的 `.claude/skills/` 目录。 **在任何其他环境中** —— 其内容是纯 Markdown，没有 Claude 特定的语法，因此它可以用作任何模型的上下文：将 `SKILL.md` 和 `references/advanced-search.md` 粘贴到对话中，将它们作为系统提示词（system prompt）加载，或者将它们保存为你所使用的助手的规则文件。只有自动发现功能是 Claude 特有的；而这套技术方法并不是。 ## 作为普通 CLI 使用 无需 Agent —— 该客户端可独立运行。 ``` git clone https://github.com//darktrace-threat-hunting.git cd darktrace-threat-hunting pip install -r requirements.txt ``` 生成一对 **只读** 的 API token（Darktrace UI → **Admin → System Config → API Tokens**），然后通过以下三种方式之一提供它 —— CLI 参数会覆盖环境变量，而环境变量会覆盖配置文件： ``` # config 文件 — 复制到 repo 根目录或脚本旁边；两者均被 gitignore cp .dt_config.json.example .dt_config.json # environment export DT_HOST=https://darktrace.example.local export DT_PUBLIC_TOKEN=xxxxxxxx export DT_PRIVATE_TOKEN=xxxxxxxx # flags python3 scripts/dark-trace-hunting.py --host ... --public ... --private ... ping ``` 通过一个签名请求进行验证： ``` python3 scripts/dark-trace-hunting.py ping # [+] tokens 有效。appliance 时间: ... ``` 然后开始狩猎： ``` # Alerts python3 scripts/dark-trace-hunting.py breaches --hours 24 --minscore 0.5 python3 scripts/dark-trace-hunting.py aia --hours 24 # AI Analyst incidents # Advanced Search — 原始 hits python3 scripts/dark-trace-hunting.py search '@type:conn AND @fields.dest_port:4444' --hours 24 # Terms aggregation — 异常值查找器 python3 scripts/dark-trace-hunting.py agg @fields.dest_port \ '@type:conn AND @fields.source_ip:"10.0.0.5"' --hours 24 # 你喜欢的任何 endpoint python3 scripts/dark-trace-hunting.py get /summarystatistics ``` 所有内容都会以 JSON 格式打印到 stdout，因此你可以通过管道将其传递给 `jq`： ``` python3 scripts/dark-trace-hunting.py breaches --hours 24 | jq -r '.[] | "\(.score) \(.model.name)"' | sort -rn ``` 完整的命令表和狩猎方法论位于 [SKILL.md](SKILL.md) 中；查询手册位于 [references/advanced-search.md](references/advanced-search.md) 中。 ## 为什么会有这个项目 单凭文档很难搞清楚以下三件事，每件事都曾耗费了我一下午的时间： 1. **HMAC-SHA1 请求签名。** 每个 Darktrace API 调用都是基于*精确的*网络传输路径 + 查询字符串进行签名的。如果你的查询字符串构建方式与 HTTP 库的序列化方式不同，你就会收到一个 400 错误，并且没有任何有用的提示。该客户端会对准备好的请求进行签名，因此签名始终与实际发送的字节相匹配。 2. **Advanced Search 要求时间格式为 `YYYY-MM-DD HH:MM:SS` UTC 字符串，而不是 epoch** —— 并且整个搜索的有效载荷（payload）都会被 base64 编码到 URL 路径中。只要弄错其中一点，你得到的就会是空结果，而不是一个错误提示。 3. **`analyze/terms` 聚合 endpoint** 是该产品中最实用的单一狩猎原语，但几乎没有文档。它可以通过一次调用回答“查询 Y 中字段 X 的前 N 个值”——这正是你寻找异常值而非滚动浏览日志的方法。 ## 只有在检查了可见性之后，才能相信你的“无结果” 空结果集意味着两种截然不同的情况之一：*什么都没发生*，或者*传感器根本没有看到它*。传感器的覆盖范围是按路径划分的——一台主机在通往内部子网的的东西向流量（east-west）中可能完全可见，而在其通往互联网的出口的南北向流量（north-south）上却完全不可见，因为这些路径会经过不同的 SPAN/TAP 点。网络上的两台主机可能仅仅因为 tap 所在的位置不同，而在相同的测试中产生相反的结果。 如果一台主机的 DNS 查询记录出现了，但与之匹配的 `conn`/`ssl` 记录却从未出现，这就是典型的出口盲点：你可以看到它*询问*服务在哪里，但看不到它与服务*通信*。 **“未检测到”和“无法观察”是具有不同责任人的不同发现。** 一个是安全团队的调优问题；另一个是网络工程问题。将它们作为同一件事进行报告正是导致覆盖盲区在评估中得以存续的原因。Canary（金丝雀）验证程序位于 [SKILL.md](SKILL.md) 和 [references/advanced-search.md](references/advanced-search.md) 的第 8 节中。 ## 注意事项与说明 - **已在 Darktrace v7.x 版本上测试。** Endpoint 的可用性因版本和许可证而异；出现 400/403 错误通常意味着该 token 对对该 endpoint 缺乏作用域权限。 - **TLS 验证默认是关闭的**（`verify=False`），因为设备通常使用内部签名证书。如果你有 CA 证书，请改为设置 `verify="/path/to/ca.pem"`。 - **聚合操作开销很小，而原始搜索则不然。** 始终使用 `@type:` 和时间窗口来限制 `search`。 - 该客户端在**设计上是只读的** —— 它只发出 GET 请求。这里的任何操作都不会修改你的设备。 ## 法律声明 仅对你拥有或被明确授权测试的基础设施使用此工具。这些查询属于防御性的威胁狩猎技术；运行它们仍然意味着你正在读取你所在组织的网络遥测数据，这可能受你工作所在地的隐私和监控政策的约束。 本项目不隶属于 Darktrace，也未获得其认可。"Darktrace" 是其各自所有者的商标。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

标签：API客户端, IP 地址批量处理, LLM代理技能, 网络流量分析, 逆向工具