pmatheus/mas-hunt

# MAS-Hunt **用于威胁狩猎的弹性 AI 多智能体系统** — Claude Code 可复现性插件 本项目为 Paulo Matheus Nicolau Silva（UnB / PPGEE, 2026）的硕士论文所作。 此插件使任何安装了 Claude Code 的研究人员都能复现 MAS-Hunt 的实验设置。它打包了完整的 3 层 Kagebushin 编排、六种论文实验变体、十一项领域技能、七个专家智能体，以及经过签名的 Hunt Dossier 证据链——涵盖了针对实时 Elasticsearch SIEM 或静态证据文件夹重放论文结果所需的一切。 ## 引用 如果您在学术工作中使用了 MAS-Hunt，请引用： ``` @mastersthesis{silva2026mashunt, author = {Silva, Paulo Matheus Nicolau}, title = {{MAS-HUNT}: A Resilient {AI} Multi-Agent System for Threat Hunting}, school = {Universidade de Bras{\'\i}lia (UnB), Programa de P{\'o}s-Gradua{\c{c}}{\~a}o em Engenharia El{\'e}trica (PPGEE)}, year = {2026}, address = {Bras{\'\i}lia, DF, Brazil}, type = {Professional Master's Thesis}, url = {https://github.com/pmatheus/mas-hunt} } ``` 论文源文件（LaTeX，ABNT 格式）位于此插件目录的父目录中：`../main.tex`（章节位于 `../partes/` 下）。 ## 架构概览 MAS-Hunt 是一个 3 层多智能体系统，在控制循环中编织了六项对抗性防御。董事会（Board） deliberates 策略，管理者（Managers）将其分解为清洁上下文的子智能体任务，工作者（Workers）执行单次检测，随后由拥有新鲜记忆的验证者（Validator）团队在任何档案签署前审查结论。 ``` [Chairman / Hunt Operator] │ ▼ ┌───────────────────────────────────────────────────────┐ │ LAYER 1 — BOARD (5 anonymous roles) │ │ Strategist · Skeptic · Adversary · Auditor · Chair │ │ → Strategic Briefing (.orchestration/board/*.json) │ └───────────────────────────────────────────────────────┘ │ briefing ▼ ┌───────────────────────────────────────────────────────┐ │ LAYER 2 — MANAGERS (plan + validate, fresh memory) │ │ Decompose tasks · Spawn workers · Audit verdicts │ └───────────────────────────────────────────────────────┘ │ task envelopes ▼ ┌───────────────────────────────────────────────────────┐ │ LAYER 3 — WORKERS (clean-context specialists) │ │ Linux · Windows · macOS · Network · Memory · Report │ └───────────────────────────────────────────────────────┘ │ findings + evidence ▼ ┌───────────────────────────────────────────────────────┐ │ ADVERSARIAL DEFENSES (M1–M6) │ │ M1 input sanitization M4 ensemble validation │ │ M2 hypothesis diversity M5 red-team round │ │ M3 tamper detection M6 evidence chain (SHA-256)│ └───────────────────────────────────────────────────────┘ │ ▼ Signed Hunt Dossier · ATT&CK Navigator layer D3FEND remediation map · IOC table · timeline ``` 六项防御对应于论文 §5.3 中的机制 M1–M6。消融测试工具（ablation harness）会逐一禁用这些机制，以便审阅者可以复现 §5.4 中“每项机制贡献度”的分析。 ## 安装 请根据您的情况选择合适的选项。这三种方式最终都会使 `/hunt` 命令在 Claude Code 中可用。 ### 选项 A — 作为 Claude Code 插件（推荐普通用户使用） ``` # 当公开发布时，这一条命令即可安装所有内容： claude plugin install https://github.com/pmatheus/mas-hunt # 验证 claude plugin list | grep mas-hunt ``` ### 选项 B — 手动软链接（推荐开发者使用） ``` # 1. Clone 论文 repo（其中包含此 plugin） git clone https://github.com/pmatheus/dissertacao ~/dissertacao # 2. Symlink 此 plugin 至 Claude Code 的 plugins 目录中 mkdir -p ~/.claude/plugins ln -s ~/dissertacao/mas-hunt-plugin ~/.claude/plugins/mas-hunt # 3. 重启 Claude Code 并验证 claude plugin list | grep mas-hunt ``` ### 选项 C — 从论文源码树安装 ``` # 1. Clone 论文 git clone https://github.com/pmatheus/dissertacao cd dissertacao/mas-hunt-plugin # 2. 就地使用该 plugin — Claude Code 会自动发现它，来自 # 若你将其指向此处，`.claude-plugin/plugin.json` 清单。 export CLAUDE_PLUGIN_PATH="$PWD" claude ``` ## 快速开始 查看 MAS-Hunt 端到端运行的最快方式是使用内置的固件（fixture）： ``` claude # 在 Claude Code 中： /hunt ./tests/fixtures/tiny-evidence ``` 该固件是一段 6 行的 syslog 捕获记录，它会执行文件夹模式摄取、M1–M6 防御、单轮狩猎以及 Hunt Dossier 输出——在 Opus 4.7 上通常不到 90 秒即可完成。输出的 dossier 会保存在 `.orchestration/hunt//dossier.md` 中，并附带一条 SHA-256 证据链。 若要针对真实的 SIEM 进行实战演练： ``` /hunt --siem https://elastic.local:9200 --index winlogbeat-* --window 24h ``` ## 复现论文实验 该插件将论文中的每种实验变体作为一等命令提供。论文章节/图表与命令的对应关系如下： | 论文参考 | 变体 | 命令 | | --- | --- | --- | | §5.2 — 完整架构 (C1) | C1 full | `/hunt` | | 表 5.3 — 朴素基线 (C2) | C2 naive | `/hunt-naive` | | §5.4 — 消融实验 M1–M5 | 关闭 M1 净化 | `/hunt-ablation --condition m1` | | §5.4 — 消融实验 M1–M5 | 关闭 M2 多样性 | `/hunt-ablation --condition m2` | | §5.4 — 消融实验 M1–M5 | 关闭 M3 篡改检测 | `/hunt-ablation --condition m3` | | §5.4 — 消融实验 M1–M5 | 关闭 M4 集成验证 | `/hunt-ablation --condition m4` | | §5.4 — 消融实验 M1–M5 | 关闭 M5 红队轮次 | `/hunt-ablation --condition m5` | | §5.5 — 对抗性测试 | 提示词注入测试工具 | `/hunt-adversarial` | | §5.6 — 完整实验矩阵 | 扫描全部 6 种条件 | `/hunt-experiment` | | §B.1 — Linux 演练 | 针对 Linux 的完整运行 | `/hunt-linux` | | §B.2 — Windows 演练 | 针对 Windows 的完整运行 | `/hunt-windows` | 每条命令都会在 `.orchestration/hunt//` 下写入确定性的构建产物，因此结果可在不同机器间复现。每次运行中，结合了检测精确度、召回率、验证者一致性和档案完整性的综合得分将记录在 `metrics.json` 中。 ### 复现完整的表 5.x 扫描 ``` # 从一个干净的工作目录 /hunt-experiment --runs 5 --conditions c1,c2,m1,m2,m3,m4,m5 ``` 实验工具会在请求的矩阵上编排 `/hunt-experiment`，并输出一个单独的 `experiment-summary.json`，审阅者可以将其与论文中发布的数值进行差异比对。 ## 架构详情 ### 董事会角色（第 1 层，论文 §5.1） 董事会包含五个匿名审议角色——战略家（Strategist）、怀疑论者（Skeptic）、对手（Adversary）、审计员（Auditor）和主席（Chair）。每个角色将其立场发布到密封的审议日志中，主席每轮轮换以打破平局动态，且全体一致被视为群体思维（groupthink）的标志，而非高置信度。八项反迎合机制（强制独立、匿名立场、强制挑战配额等）被应用于确保董事会在字面解释模型下保持公正。 ### M1–M6 治理机制 | ID | 机制 | 防御对象 | | --- | --- | --- | | M1 | 输入净化 | 来自日志内容的间接提示词注入 | | M2 | 假设多样性 | 过早收敛于单一 TTP | | M3 | 篡改检测 | 工作者对证据的自我修改 | | M4 | 集成验证（新鲜记忆） | 验证者被规划上下文捕获 | | M5 | 红队轮次 | 循环中对手的证伪 | | M6 | 证据链 (SHA-256) | 事后档案篡改 | M6 是结构性的，而非智能体层面的——写入 `.orchestration/hunt//` 的每一个产物都会被哈希，并且清单（manifest）会在 dossier 渲染之前进行签名。 ### 规则语料库 一个由 SQLite 支持的规则存储库（`data/rules.sqlite`，模式定义见 `skills/hunt-campaign/reference.md`）保存着带有“2 次活动晋升门槛”的检测规则：一条规则必须在至少两次不同的活动中触发，才能从 `staging` 晋升为 `production`。这可以防止一次性误报污染未来的运行，并使语料库可审计。 ### MITRE ATT&CK ↔ D3FEND 映射 内置的 `data/d3fend-map.json` 提供了 14 种 ATT&CK 技术 → D3FEND 对策的映射，供 Hunt Dossier 渲染器使用。当发出发现（finding）时，dossier 会同时包含 ATT&CK Navigator JSON 层和相应的 D3FEND 缓解行动手册，以便蓝团队能够在单一的产物中从检测过渡到缓解。 ## 依赖项 | 组件 | 要求版本 | | --- | --- | | Python | 3.11+ | | `uv` | 最新版（安装 `hunt-campaign` 包并运行测试） | | Claude Code | v1.0+（支持插件清单） | | Elasticsearch | 9+（仅在使用 `--siem` 模式时需要；文件夹模式无 SIEM 要求） | | 操作系统 | macOS 或 Linux（Windows 可通过 WSL2 运行） | `tests/fixtures/tiny-evidence` 下的文件夹模式固件在零外部依赖的情况下即可运行——这对于在搭建 Elasticsearch 之前进行快速的审阅者验证非常有用。 ## 测试 ``` cd skills/hunt-campaign uv run pytest # 预期：70 个通过 ``` 测试套件覆盖了活动循环、证据链完整性、规则晋升逻辑、ATT&CK→D3FEND 映射、M1–M6 机制以及 Hunt Dossier 渲染。 ## 仓库布局 ``` mas-hunt-plugin/ ├── .claude-plugin/ │ ├── plugin.json # Plugin manifest │ └── marketplace.json # Marketplace registry entry ├── agents/ # 7 specialist agents (board, managers, workers, validator) ├── commands/ # /hunt, /hunt-{linux,windows,naive,ablation,experiment,adversarial}, /kgb ├── skills/ # 11 domain skills (hunt-campaign + 10 supporting) │ └── hunt-campaign/ # Python package: 14 modules, 70 tests ├── hooks/ # 1 hook (enforce-es-query-safety: PreToolUse:Bash, blocks ES writes) ├── data/ │ └── d3fend-map.json # 14 ATT&CK → D3FEND mappings ├── docs/ │ └── 2026-04-24-hunt-autonomous-design.md # Autonomous loop design spec ├── examples/ # End-to-end run examples ├── tests/ │ └── fixtures/ # tiny-evidence (6-line syslog) + larger reproducibility sets ├── README.md # This file ├── LICENSE # MIT ├── CHANGELOG.md # Version history └── plugin.json # (legacy alias — manifests live under .claude-plugin/) ``` ## 许可证 MIT — 详见 [LICENSE](./LICENSE)。版权所有 (c) 2026 Paulo Matheus。 ## 致谢 此插件是在巴西利亚大学 理工学院电气工程研究生项目（PPGEE / PPGENE）答辩的专业硕士论文的可复现产物，答辩时间为 2026 年 9 月。一旦答辩委员会最终确定，导师和答辩委员会的姓名将出现在这里——请参阅论文源码中的 `partes/informacoes.tex` 以获取官方列表。 Kagebushin 3 层编排借鉴了 Silva 等人的 MAS-Hunt（《Engineering Proceedings》2026, 123）的多智能体治理设计，以及先前在对抗性多智能体系统和检索增强威胁狩猎方面的工作。 ## 联系方式 问题与可复现性质疑：请在 提交 GitHub issue。学术通信：请通过论文扉页上列出的 UnB PPGEE 项目联系方式与作者取得联系。

标签：AI智能体, Claude, CVE检测, DLL 劫持, Elasticsearch, FTP漏洞扫描, Kagebushin架构, PFX证书, PyRIT, TruffleHog, 人工智能, 代码复现, 多智能体系统, 大语言模型, 子域名变形, 学术研究, 学术论文, 安全编排, 弹性系统, 插件系统, 攻击检测, 无线安全, 用户模式Hook绕过, 硕士论文, 网络安全, 网络安全审计, 网络攻防, 证据链, 逆向工具, 隐私保护, 验证器