wislest/DefenderHunting
GitHub: wislest/DefenderHunting
基于 PowerShell 的「检测即代码」框架，通过 Defender API 自动化执行 KQL 威胁狩猎查询，内置 22 个勒索软件家族检测包，帮助安全团队批量追踪 IOC。
Stars: 0 | Forks: 0
# 🛡️ DefenderHunter
## ✨ 功能
- 通过 Defender API，利用 Microsoft Defender Advanced Hunting (KQL) **自动化追踪 IOC**。
- **灵活的 IOC 导入** — 支持 CSV/JSON 输入，并带有**自动哈希类型检测** (MD5 / SHA1 / SHA256)。
- `Queries/` 目录下包含 **22 个勒索软件检测包**（见下文）。
- **模块化 PowerShell** 设计（`Modules/`, `Scripts/`），内置导出 pipeline 和报告功能。
- **默认安全** — 凭据存放在 `config.json` / `.env` 中（已被 git 忽略）；绝不硬编码。详见 [SECURITY.md](SECURITY.md)。
## 🎯 勒索软件覆盖范围 (`Queries/`)
`Akira` · `Babuk Locker` · `BlackByte` · `BlackSuit` · `Cactus` · `Cicada3301` · `EMBARGO` · `Fog` · `Hunters International` · `Inc Ransom` · `Interlock` · `Lockbit 3.0` · `Lynx` · `Medusa` · `Nebula` · `Play` · `RansomHub` · `Rhysida` · `STOP/DJVU` · …（外加通用/未知类别）
## 🚀 快速开始
**前置条件：** PowerShell 5.1+，一个拥有 Microsoft Defender API 权限（`AdvancedHunting.Read.All`）的 Entra ID 应用注册。
```
# 1) 配置 Defender API 凭据
Copy-Item config.json.example config.json
# 编辑 config.json -> TenantId, ClientId, ClientSecret
# 2) （可选）配置导出/报告设置
Copy-Item export-config.json.example export-config.json
# 编辑 export-config.json -> WorkspaceId, ExportPath, EmailRecipient, SmtpServer
# 3) 验证与 Defender API 的连接
.\CheckDefenderAPI.ps1
# 4) 搜寻一组 IOC
.\Main.ps1 -IocsFile .\my-iocs.csv
# ...或运行计划的导出工作流
.\Main.ps1 -ConfigPath .\export-config.json
```
## 📑 IOC 输入格式
包含三列的 CSV；哈希值为 JSON 对象：
```
FullPath,FamilyName,FileHashes
C:\temp\malware.exe,Akira,"{""md5"":""…"",""sha1"":""…"",""sha256"":""…""}"
```
有一个更简单的 `FamilyName,SHA256` 列表？自动转换它（根据长度检测哈希类型）：
```
.\Convert-IocsFormat.ps1 -InputFile simple-iocs.csv -OutputFile formatted-iocs.csv
```
## 📂 仓库结构
| 路径 | 用途 |
|------|---------|
| `Main.ps1` | **入口点** — IOC 追踪 + 计划导出 |
| `CheckDefenderAPI.ps1` | 验证 Defender API 身份验证/连接 |
| `Convert-IocsFormat.ps1` | 将简单的 IOC 列表标准化为所需的 CSV/JSON 格式 |
| `Queries/` | 22 个勒索软件家族 KQL 查询包 |
| `Modules/DefenderHunter/` | PowerShell 模块（导出核心、查询、IOC 追踪器） |
| `Scripts/` | 导出 pipeline 脚本 |
| `config.json.example`, `export-config.json.example` | 配置模板（复制 → 填写 → **切勿提交真实文件**） |
| `SECURITY.md` | 凭据处理与安全指南 |
## 🔐 安全
- **切勿提交 `config.json` / `.env` / `export-config.json`** — 它们包含租户凭据，且默认已被 git 忽略。
- 定期轮换应用的 `ClientSecret`，并授予应用**最小权限**的 Defender API 权限。
- 完整指南请参阅 [SECURITY.md](SECURITY.md)。
## 📄 许可证
基于 **[MIT License](LICENSE)** 发布。
标签：AI合规, DNS 反向解析, IPv6, KQL, Libemu, Microsoft Defender, Microsoft Sentinel, PowerShell, 勒索软件, 检测即代码, 知识库安全