Barnacules/ThreatHunter

# ThreatHunter 一款面向蓝队、事件响应人员以及具备安全意识的高级用户的被动、只读 Windows 主机威胁狩猎工具。 ThreatHunter 会全面扫描你的计算机，查找攻击者通常会留下的各种痕迹——持久化条目、隐藏进程、可疑驱动程序、高熵/加壳二进制文件、AMSI / YARA 匹配项、网络 C2 回连、Defender 篡改事件等——并将它们作为结构化发现报告输出到控制台、滚动日志文件、JSONL、syslog 或 webhook。 它**不会**修改你的系统。它**不会**隔离或终止进程。它**不会**开放端口或向外发送心跳。它纯粹是一个枚举/检测工具——阅读输出结果的人类操作员将决定如何处理这些发现。 ## 功能特性 - **持久化扫描** —— Run 键、启动文件夹、IFEO、Winlogon、BHOs、计划任务、服务、WMI 订阅、屏幕保护程序劫持、键盘挂钩 - **隐藏进程检测** —— 将内核进程列表 (`NtQuerySystemInformation`) 与 `psutil`、`EnumProcesses` 和 `Toolhelp32` 进行交叉比对，揪出被 rootkit 隐藏的 PID - **驱动程序检查** —— 包含 Authenticode 签名验证 - **文件熵/加壳检测** —— 以及可选的 AMSI 扫描、YARA 规则匹配和 VirusTotal 信誉查询 - **实时进程监控** —— 监控新进程的创建，并标记 LOLBins、可疑的父子进程链和危险命令行 - **网络 C2 回连检测** —— 利用到达时间间隔的变异系数，标记低抖动的周期性连接（经典的 C2 模式） - **ETW 监控** —— 订阅 Sysmon 和 Defender 事件通道（如果已安装 `pywintrace` 则会使用它，否则回退到 `wevtutil` 轮询） - **Defender 状态检查** —— 如果实时保护、篡改保护或云交付被禁用，则会发出警报 - **多种输出目标** —— 彩色控制台、滚动日志文件、JSONL、syslog (RFC 5424) 和 webhook (JSON POST) ## 兼容性 - **操作系统：** Windows 10 / 11 / Server 2019+（64 位）。该工具使用了大量 Windows 专用 API（通过 `ctypes` 调用 `ntdll`、`psapi`、`winreg`、WMI、ETW），因此**无法在 Linux 或 macOS 上运行**。 - **Python：** 3.10 或更高版本。（推荐使用 3.11+；`tomllib` 已包含在标准库中。） - **权限：** 最好从**提升权限的（管理员）终端**运行，以便完整查看内核结构、系统拥有的进程、驱动程序和 ETW 频道。它也可以在非特权模式下运行，但检测覆盖范围会缩小，并在启动时发出警告。 ## 安装 ``` # 1. Clone git clone https://github.com/Barnacules/ThreatHunter.git cd ThreatHunter # 2. （推荐）创建 virtualenv python -m venv .venv .\.venv\Scripts\Activate.ps1 # 3. Install dependencies pip install -r requirements.txt ``` ### 依赖项 `requirements.txt` 会引入： | 包名 | 用途 | |--------------|---------------------------------------------------------------| | `psutil` | 进程 / 网络枚举 | | `colorama` | 彩色控制台输出 | | `requests` | Webhook 输出目标 + VT 备用 | | `WMI` | WMI 订阅 / 服务枚举 | | `pywin32` | Win32 API 访问（事件日志、注册表、安全） | | `yara-python`| 针对扫描文件进行 YARA 规则匹配 | | `vt-py` | VirusTotal API 客户端（文件信誉查询） | | `tomli` | TOML 解析器（仅在 Python < 3.11 时需要） | | `pywintrace` | 可选的原生 ETW 后端（回退到 `wevtutil`） | 如果某个包安装失败（例如你没有用于 `yara-python` 的 C 语言工具链），ThreatHunter 会优雅降级——相应的检测器将被直接跳过，并在启动时发出警告，告诉你缺少哪项功能。 #### 复杂依赖项说明 - **`yara-python`** 为大多数 Python/Windows 组合提供了预编译的 wheel；如果 pip 回退到源码编译，你将需要一个 C 编译器。 - **`pywintrace`** 是*可选的*——如果没有它，ETW 事件将通过 `wevtutil` 轮询从 Windows 事件日志中获取，这种方式速度较慢，但可以在标准系统上运行。 ## VirusTotal API 密钥（执行 VT 查询时必填） **在已发布的代码库中，此项故意留空。你必须添加自己的密钥才能使文件信誉查询正常工作。** 1. 在 注册一个免费帐户，并从你的帐户个人资料中获取 API 密钥。 2. 打开代码库根目录下的 `config.toml`。 3. 找到 `[virustotal]` 部分，并粘贴你的密钥： [virustotal] api_key = "PASTE_YOUR_KEY_HERE" enabled = true 4. 保存。如果密钥为空，ThreatHunter 将打印启动警告，提示你 VT 查询已被禁用。 ## 用法 ``` # 默认：安静控制台 — 仅显示 WARN / HIGH / CRITICAL 发现结果 + 60 秒 # 心跳。所有内容（包括 INFO/DEBUG）均进入 threathunter.log # 和 threathunter.jsonl。 python threathunter.py # 在控制台显示所有活动（除 DEBUG 外的所有内容） python threathunter.py --verbose # 详细模式 + DEBUG 级别诊断（firehose — 在排查问题时很有用） python threathunter.py --debug # 自定义日志文件路径 python threathunter.py --log-file C:\logs\hunter.log # 每 30 秒一次心跳，而非 60 秒 python threathunter.py --stats-interval 30 # 完全禁用心跳 python threathunter.py --no-stats # 使用不同的配置文件 python threathunter.py --config C:\configs\hunter.toml # 列出将要运行的 detectors python threathunter.py --list-detectors # 所有选项 python threathunter.py --help ``` ### 输出模式一览 | 模式 | 控制台显示 | 日志文件记录 | |-----------|------------------------------------------------|------------------------------| | (默认) | WARN, HIGH, ALERT, CRITICAL + 心跳信息行 | 全部 | | `-v` | 除 DEBUG 外的所有严重级别 | 全部 | | `-d` | 包括 DEBUG 在内的所有信息 | 全部 | 默认模式被有意设计得非常安静：如果工具运行正常且你的计算机是干净的，你只会看到每分钟跳动一次的心跳信息。任何比这更嘈杂的输出都是你应该关注的问题。 ### 60 秒心跳信息 每隔一分钟（可配置），该工具会打印一行状态更新： ``` [2026-05-15 01:46:13.290] HEARTBEAT: heartbeat — uptime=60s files=128 procs=412 conns=87 detectors=13 findings=2 (HIGH=2) ``` 这行信息告诉你它仍在运行，以及自启动以来完成了多少工作——扫描的文件、检查的进程、网络连接、运行的检测器，以及按严重级别分类的发现结果。 ### 停止运行 在控制台窗口中按 **ESC**，或者按 **Ctrl-C**。 ## 配置 `config.toml` 控制着扫描间隔、扫描路径、白名单、输出目标以及启用的检测器。默认配置对大多数桌面/工作站来说都很合理——阅读文件中的注释，即可针对你的环境进行调整。 输出目标位于 `[output]` 下： - `console = true/false` - `jsonl_path = "threathunter.jsonl"` - `syslog_host`、`syslog_port`、`syslog_proto` - `webhook_url` ## 故障排除 - **"Running without admin"（无管理员权限运行）** —— 在提升权限的 PowerShell / cmd.exe 中重新启动，以启用内核级检查和 ETW。 - **"YARA not available"（YARA 不可用）** —— 执行 `pip install yara-python`。在 Windows 上，预编译的 wheel 通常可以正常工作；如果遇到构建错误，请安装 MSVC C++ Build Tools 或使用有已发布 wheel 的 Python 版本。 - **"VirusTotal API key not set"（未设置 VirusTotal API 密钥）** —— 参见上文 VT 相关章节。 - **首次运行时出现大量 HIGH（高）级别发现** —— 这属于正常现象。ThreatHunter 会列出所有值得注意的内容；其中许多将是你安装的合法软件（供应商自动运行条目、已签名的驱动程序等）。进行一次分类，然后将无害的条目添加到 `config.toml` 的白名单中。 ## 许可证 MIT —— 参见 `LICENSE`（如果你进行了分支，请添加你首选的许可证文件）。 ## 免责声明 ThreatHunter 是一款**检测**工具。它会列出可疑的痕迹；但不会判断它们是否为恶意软件，也不会进行修复。请将输出结果作为参考，交由合格的响应人员进行调查。作者对基于其输出所采取（或未采取）的任何行动概不负责。

标签：AMSI扫描, API接口, C2检测, Conpot, CSV导出, DeepSeek, DNS信息、DNS暴力破解, DNS 反向解析, DNS 解析, ETW监控, IP 地址批量处理, LOLBins检测, Python, Qt, Sysmon, WindowsDefender, Windows安全, YARA规则, 事件日志分析, 只读扫描, 安全态势, 库, 应急响应, 打包器检测, 持久化检测, 无代理安全, 无侵入, 无后门, 熵值分析, 紫队, 网络信息收集, 网络信标检测, 逆向工具, 隐藏进程检测, 驱动签名验证