bsmensah-ctrl/DLL-Injection-Lab
GitHub: bsmensah-ctrl/DLL-Injection-Lab
一个零风险的 DLL 注入遥测模拟与检测实验室，通过合成事件链帮助安全防御者学习和验证多信号关联检测规则，无需虚拟机或管理员权限。
Stars: 1 | Forks: 0
# DLL 注入实验室 🧪
### 查看完整的 DLL 注入遥测链——无需实际注入 DLL。
**模拟它。检测它。打破链条。证明你的规则有效。**
无需虚拟机 (VM)。无需管理员权限。无需恶意软件。不触碰任何实时进程。
[](https://github.com/bsmensah-ctrl/DLL-Injection-Lab/actions/workflows/ci.yml)
[](tests)
[](https://www.python.org/)
[](pyproject.toml)
[](https://attack.mitre.org/techniques/T1055/001/)
[](LICENSE)
## 60 秒内完成你的首次检测
```
git clone https://github.com/bsmensah-ctrl/DLL-Injection-Lab.git
cd DLL-Injection-Lab
python -m pip install -e .
dll-injection-lab demo
```
```
# DLL Injection 实验报告
- Mode: synthetic-event-only
- Findings: 1
| Severity | Finding | Evidence |
|---|---|---|
| HIGH | Synthetic DLL-injection sequence detected | classic-dll-injection-001 |
```
该结果来自完全在内存中生成的确定性五事件链。没有进行任何注入、打开、下载、隐藏或执行操作。
## 为什么会有这个项目
大多数 DLL 注入实验室迫使你在两个糟糕的选项中做出选择：
- 在 Windows 虚拟机中运行攻击性概念验证 (PoC) 代码，仅仅是为了生成遥测数据。
- 阅读演示文稿，却从不测试检测规则是否真正实现了关联。
DLL 注入实验室为你提供了实用的折中方案：**可观察的事件链、干净的对照组、关联逻辑以及可移植的报告——且不包含危险机制。** 这是一个专为防御者、学生、SOC 分析师、讲师和检测工程师构建的道德黑客实验室。
## 你将获得什么
| 功能 | 为何重要 |
|---|---|
| 🧬 完整的合成注入链 | 练习关联五个信号，而不是仅仅匹配一个嘈杂的事件 |
| 🟢 干净的协作控制 | 证明检测器会忽略已批准的同进程插件加载 |
| 🧠 可解释的发现 | 查看精确匹配的动作、流 ID、PID、时钟周期、模块和 ATT&CK 映射 |
| 📦 JSONL 事件生成器 | 将确定性遥测数据输入到你自己的解析器、SIEM 演示或单元测试中 |
| 📊 JSON、Markdown 和 SARIF | 在脚本、报告、GitHub 或课堂提交中使用相同的结果 |
| 🧱 离线边界测试 | 如果包中引入了实时进程库或 Windows 进程内存 API，CI 将会失败 |
| ⚡ 零运行时依赖 | 克隆、安装并运行——不需要服务堆栈或代理 |
## 你的检测器必须捕获的链
内置的 `classic` 场景按顺序发出这些合成观测数据：
```
flowchart LR
A["1 · Cross-process handle"] --> B["2 · Remote memory allocation"]
B --> C["3 · Remote memory write"]
C --> D["4 · Remote thread start"]
D --> E["5 · Module image load"]
E --> F["HIGH · Correlated finding"]
```
检测器要求在一个关联流中包含完整的有序序列，并拒绝同进程活动。阅读[检测指南](docs/DETECTION_GUIDE.md)以了解信号含义、良性解释和 ATT&CK 背景。
## 尝试本实验室
### 1. 捕获经典序列
```
dll-injection-lab demo
```
预期：跨 5 个合成事件的 **1 个高危发现**。
### 2. 运行干净的对照组
```
dll-injection-lab demo --scenario cooperative
```
预期：**0 个发现**。虚构的主机和目标是同一个进程，并且插件加载遵循了明确的合成用户批准。
### 3. 检查原始遥测数据
```
dll-injection-lab simulate --scenario classic --output events.jsonl
dll-injection-lab detect --events events.jsonl --format json
```
从 JSONL 流中删除一个事件并重新运行检测。发现会消失，这使得关联要求变得可见且易于测试。
### 4. 将其转化为 CI 门禁
```
dll-injection-lab detect \
--events events.jsonl \
--format sarif \
--output dll-injection.sarif \
--fail-on-findings
```
只有在提供了 `--fail-on-findings` 参数时，如果有发现存在，CLI 才会以状态码 `1` 退出。默认运行保持探索友好性。
## 发现包含什么
```
{
"type": "synthetic-dll-injection-sequence",
"severity": "high",
"evidence": {
"flow_id": "classic-dll-injection-001",
"actor_pid": 4100,
"target_pid": 4200,
"module": "synthetic://lab/telemetry-demo.dll",
"matched_actions": [
"cross_process_handle_open",
"remote_memory_allocation",
"remote_memory_write",
"remote_thread_start",
"image_load"
],
"attack_technique": "T1055.001",
"synthetic": true
}
}
```
上面的每个标识符和 URI 都是虚构且确定性的。
## 不止一个实验室
最初的 CrossView 引擎仍作为辅助的工件分析模式提供。它比较提供的进程清单导出，并检查提供的函数入口字节，而不从主机收集任何内容：
```
dll-injection-lab artifacts \
--baseline fixtures/inventory_baseline.json \
--observed fixtures/inventory_observed.json \
--entry-bytes fixtures/entry_bytes.json \
--format markdown
```
## 安全承诺
该项目模拟的是**遥测**，而不是注入。该包不包含 `ctypes`、`psutil`、`socket`、`subprocess` 或 `winreg` 导入，也没有 Windows 进程内存 API 调用。它从不枚举主机、打开进程、分配远程内存、写入另一个进程、启动线程、加载 DLL 或请求管理员权限。
一个专门的回归测试会扫描该包，如果出现被禁止的导入或 API token，测试将会失败。每个导入的事件都必须带有 `synthetic=true` 声明。
## 适用人群
- 测试多事件关联逻辑的**检测工程师**。
- 学习注入序列在遥测中是什么样子的 **SOC 分析师**。
- 需要可重复的道德 DLL 注入实验室的**网络安全学生**。
- 希望拥有干净且可疑的对照组以及预期结果的**讲师**。
- 需要小型 JSONL 固定数据和 SARIF 示例的**工具构建者**。
## 自行验证
```
python -m pip install -e ".[dev]"
pytest
ruff check .
ruff format --check .
```
这 30 个测试套件涵盖了模拟器、有序关联、不完整链、同进程干净对照组、格式错误的 JSONL、工件比较、字节前缀分诊、schema 验证、输出格式、CLI 组合以及离线边界。GitHub Actions 会在 Python 3.10、3.11、3.12 和 3.13 上运行该套件。
## 路线图
- [ ] 更多安全的场景：节映射、线程劫持遥测和 APC 风格的事件链
- [ ] 由相同合成固定数据驱动的 Sigma 和 KQL 规则示例
- [ ] 时间轴可视化和交互式事件移除
- [ ] 用于净化后的 Sysmon 和 EDR 导出数据的导入适配器
- [ ] 包含挑战和答案固定数据的讲师包
- [ ] 用于可重复课堂练习的签名场景清单
## 证据胜于炒作
最初的本地 LLM 原型生成了损坏的混合语言代码，后来又突破了自己声称的离线边界。这个代码库被独立重写，其声明基于可执行的测试、schema、包构建和 CI。[LLM 输出审计](docs/LLM_OUTPUT_AUDIT.md)准确展示了哪些部分失败了，哪些部分被废弃了。
## 帮助项目发展
如果你学到了一些东西、使用了固定数据或节省了设置时间：
1. ⭐ **为仓库加星**——这是表明这个项目应该继续发展的最清晰的信号。
2. 🧪 添加合成场景或干净的对照组。
3. 📣 将这个 60 秒的演示分享给 SOC、蓝队或网络安全课程。
4. 🐛 报告误报或令人困惑的证据。
## 许可证
MIT —— 使用它、用它教学，并改进它。参见 [LICENSE](LICENSE)。标签：AMSI绕过, Python, SARIF, 威胁检测, 安全仿真, 安全规则引擎, 文档结构分析, 无后门, 时序数据库, 逆向工具