--platform ` — 计算 MD5/SHA1/SHA256 + ssdeep/TLSH 模糊哈希、香农熵（Shannon entropy）和文件类型；将样本以惰性方式存储（重命名为其 SHA-256，权限设为 `0400`，或使用标准的 `infected` 密码进行 zip 加密）；记录所有信息。高熵样本会被标记为可能加壳（packed）。
- `threat_meister triage [ [--save-iocs] [--deep]` — 提取 ASCII + UTF-16LE 字符串，提取候选的 URL / IPv4 / 域名，可选择运行 radare2 导入分析，并持久化 IOC。绝不执行样本。
- `threat_meister show ][ [--json]`, `threat_meister list [--category …]`, `threat_meister stats` — 查询 catalog。`][` 可以是 id、完整的 SHA-256 或明确的哈希前缀。
- `threat_meister set ][ family `, `threat_meister tag`, `threat_meister attack ][ T1486 …`, `threat_meister note ][ "…" --phase static` — 在分析过程中不断丰富记录。
- `threat_meister yara-new ][` — 根据样本最强特征字符串构建结构化规则脚手架，并附带一个元数据块（`description`、`author`、`date`、`reference`、`hash`、`malware_family`、`category`、`tlp`），其结构专为匹配 Wazuh YARA 集成所期望的格式而设计。它会立即编译结果。
- `threat_meister yara-test [--against ][]` — 编译规则并扫描单个样本或整个存储库，以便您可以在*部署前*检查真阳性（true positives）并在语料库中搜寻假阳性（false positives）。
- `threat_meister yara-bundle` — 将每个实验室规则连接成一个可编译的 `exports/lab_rules.yar`（Wazuh 的 `yara.sh` 接收单个 `.yar` 文件）。
- `threat_meister clamsig` — 为 ClamAV 输出 `lab.hdb` (MD5:size:name) 哈希特征码。
- `threat_meister ioc-export --format csv|json` — 导出哈希值 + 网络 IOC。
威胁情报命令（`threathunt` 桥接）：
- `threat_meister enrich ][ | --all` — 将样本自身的哈希值及其提取的 IOC 发送给 VirusTotal，对每一项进行评分，并将最高风险反映回样本中，体现为 `vt_score`、`vt:` 标签和一份细分笔记。随后的 `show` 和 `list` 会显示该分数，因此在一个视图中即可同时查看静态分类*和*信誉度。
- `threat_meister hunt [threathunt args]` — 对 Wazuh/Rita/UniFi 导出数据执行全面搜寻（`--wazuh`、`--rita`、`--unifi`、`--report hunt.md`、`--min-score N`）。具备目录感知能力：匹配到已知样本的指示器（indicators）会被注释并提高评分。
- `threat_meister intel ` — 对 IP/域名/哈希进行临时的 VirusTotal 检查，同样具备目录感知能力。
这些命令需要一个 VirusTotal API 密钥（`export VT_API_KEY=…`、`--api-key` 或 `.env`）。它们共享实验室根目录下的一个 SQLite 存储（`threathunt.db`），并遵守 VT 免费层级的限制（4次/分钟，500次/天），同时对溢出请求使用恢复队列。`threathunt.py` 依然可以独立运行 —— threat_meister 集成是一组默认关闭的钩子（hooks），只有在 threat_meister 驱动它们时才会激活。
该工具仅使用标准库（stdlib-only）；可选的库/二进制文件会被自动检测，并且在缺少它们时能够优雅降级。
## 日常工作流 (SOP)
1. **摄取（Intake）。** 将样本移入 `quarantine/`。使用您初步的分类将其摄取：
`threat_meister ingest quarantine/sample.bin --family agenttesla --category infostealer --platform pe --source coursework --tag pmap`
2. **静态分类（Static triage）。** `threat_meister triage --save-iocs --deep`。阅读字符串和导入信息；如果熵较高，记录加壳器（packer）（使用 `detect-it-easy` 确认）。
3. **随时记录发现。** `threat_meister attack T1055 T1071.001`, `threat_meister note "PE, UPX-packed, HTTP beacon to , persistence via Run key" --phase static`。
4. **编写检测。** `threat_meister yara-new --author "$USER" --reference "PMAP module N"`。打开 `.yar` 文件，剔除微弱/通用的字符串，收紧条件。
5. **验证。** `threat_meister yara-test --against `（必须匹配），然后 `threat_meister yara-test `（扫描整个存储库，注意有无不需要的匹配）。
6. **丰富数据。** `threat_meister enrich ` — 使用 VirusTotal 对样本的哈希及其 C2 IOC 进行评分；样本会获得 `vt_score` 和 `vt:` 标签。重新运行 `threat_meister show ` 即可同时查看静态分类和信誉度。
7. **部署。** `threat_meister yara-bundle`，然后通过 scp 将 `exports/lab_rules.yar` 传送到 agent（见下文）。可选择执行 `threat_meister clamsig` 并加载哈希集。
8. **验证流水线。** 将一个匹配的测试文件放入 dropzone；确认 Wazuh 仪表板中出现了告警。
9. **定期搜寻。** `threat_meister hunt --wazuh alerts.json --rita beacons.csv --report hunt-$(date +%F).md` — 任何能够关联回已编目样本的指示器都会在报告中被标记为已知的实验室基础设施。
## Arch 工具
`setup_lab.sh` 从官方仓库安装：`yara`, `clamav`, `rkhunter`, `jq`, `radare2`, `binutils`, `file`, `ssdeep`, `chkrootkit`, `lynis`。从 AUR（通过 yay/paru）安装：`capa`（ATT&CK 能力分析）, `detect-it-easy`（加壳器识别）, `pev`（PE 工具包）, `python-tlsh` 和 `wazuh-agent`。它会移除 ClamAV 配置中的 `Example` 行，启用 `clamav-freshclam` + `clamav-daemon`，对 rkhunter 进行基线处理（`--propupd`）并添加每周扫描的计时器，创建 `/opt/threat_meister/dropzone`，并初始化 catalog。
注意：在 Arch 上，YARA 二进制文件位于 `/usr/bin/yara`，因此管理器的 `extra_args` 使用 `-yara_path /usr/bin`（Wazuh 文档使用 `/usr/local/bin`，因为他们是在 Ubuntu 上从源码编译的）。
## Wazuh 配置接入
文件位于 `wazuh/` 目录中。划分如下：解码器（decoders） + 规则（rules） + AR 绑定位于 **manager** 上；FIM + 日志收集位于 **agent**（您的分析主机）上。
在 **manager** 上：
1. 将 `wazuh/local_decoder.xml` 追加到 `/var/ossec/etc/decoders/local_decoder.xml`。
2. 将 `wazuh/local_rules.xml` 追加到 `/var/ossec/etc/rules/local_rules.xml`。
3. 将 `wazuh/ossec_manager_snippet.conf` 合并到 `/var/ossec/etc/ossec.conf`。
4. `sudo systemctl restart wazuh-manager`。
在 **agent** 上：
1. 安装 AR 脚本：
`sudo cp wazuh/yara.sh /var/ossec/active-response/bin/yara.sh`
`sudo chown root:wazuh /var/ossec/active-response/bin/yara.sh`
`sudo chmod 750 /var/ossec/active-response/bin/yara.sh`
2. 部署您的规则包：
`sudo install -Dm750 -o root -g wazuh exports/lab_rules.yar /var/ossec/active-response/bin/yara/rules/lab_rules.yar`
3. 将 `wazuh/ossec_agent_snippet.conf` 合并到 `/var/ossec/etc/ossec.conf`。
4. `sudo systemctl restart wazuh-agent`。
触发流程：FIM 检测到 `/opt/threat_meister/dropzone` 中的创建/修改操作 → 触发规则 `100201`/`100200` → Active Response 对更改的文件运行 `yara.sh` → 匹配项将 `wazuh-yara: INFO - Scan result: ` 写入 `active-responses.log` → manager 解码它们（`yara_decoder`）→ 规则 `108001` 引发级别为 12 的告警（如果是勒索软件/擦除软件（wiper）规则名称，则通过 `108010` 引发级别为 14 的告警）。
ClamAV daemon/freshclam 日志和 rkhunter 警告通过 agent 配置片段中的 `` 块和 rkhunter 命令 wodle 进行收集，因此它们会与 YARA 告警一起显示。
## 仪表板与告警
在 Wazuh 仪表板的 **Threat Hunting → Events** 中，筛选 `rule.groups` *为* `yara` 以查看匹配项，或筛选 `rule.groups` *为* `threat_meister` 查看整个流水线。
适用于作品集仪表板的有用的已保存可视化图表：
- YARA 匹配时间的变化，按 `data.yara_rule`（其中编码了家族信息）拆分。
- 最常匹配的规则 / 家族（基于 `data.yara_rule` 的数据表）。
- FIM dropzone 活动（`rule.id` 100200/100201）作为前置指标。
- ClamAV 检测（内置的 clamd 规则）和 rkhunter 警告显示在同一面板上，从而在一个屏幕上展示所有三个引擎的结果。
要进行外部告警，可将电子邮件/webhook Active Response 或 `` 绑定到规则 ID `108001`/`108010`。
## 安全说明
- `threat_meister` 不会执行任何样本；它是纯静态的。如果您要进行动态引爆（detonation），请在您现有的隔离 VM 中进行，而不是在运行 agent 的主机上。
- dropzone 是一个**检测测试**层面，而不是样本存储。请将真实的语料库保存在处于惰性状态的 `store/` 中。不要将暴露于网络的服务指向其中任何一个。
- 样本在存储时会被重命名为其哈希值，并且权限设为 `0400` 或使用常规的 `infected` 密码进行 zip 加密，以防止意外执行，并避免主机上的 AV 软件隔离您自己的语料库。
- 请将 ClamAV 哈希 `.hdb` 和 YARA 包视为从目录重新生成的工件 —— 编辑目录、重新导出、重新部署；切勿手动编辑已部署的文件。
```
## License
Released under the MIT License — Copyright (c) 2026 meistsec. See `LICENSE`.
Threat Meister orchestrates several GPL-licensed tools (ClamAV, YARA, rkhunter,
Wazuh) as external processes and generates configuration for them; it does not
link or incorporate their source, so their copyleft does not extend to this
project. Each source module carries an `SPDX-License-Identifier: MIT` header.
```
]