yasindce1998/aegis-boot
GitHub: yasindce1998/aegis-boot
一个受控的白帽 UEFI bootkit 模拟研究平台，通过可控地复现真实固件级威胁来驱动防御检测能力的开发与验证。
Stars: 1 | Forks: 0
# Project Aegis-Boot
**⚠️ 学术研究项目 - 仅限防御性安全研究 ⚠️**
一个可用于生产环境的 UEFI bootkit 研究平台，用于研究固件级别的安全威胁与防御机制。
### 🎯 主要成就
- ✅ **88.6% 的真阳性率** (目标: ≥85%)
- ✅ **4.4% 的假阳性率** (目标: ≤5%)
- ✅ 跨 56 个文件的 **10,180 行代码**
- ✅ 具备自动化测试的 **完整 CI/CD 流水线**
- ✅ 包含真实世界威胁模型的 **综合测试语料库**
## ⚖️ 法律与道德声明
本项目在机构监督下开发，**严格仅限于学术研究目的**：
- ✅ 在执行前需要获得正式的 IRB (机构审查委员会) 批准
- ✅ 必须仅在物理隔离的虚拟化环境中运行
- ✅ 包含多个硬件层级的自毁开关，以防止未经授权的执行
- ❌ 不可用于武器化、部署或恶意用途
- ❌ 违反这些约束可能会导致法律后果
**访问此代码库即表示您同意仅将其用于合法的安全研究和教育目的。**
## 📋 项目概述
Aegis-Boot 安全地模拟已知野外 bootkit 的战术、技术和程序 (TTP)，旨在：
- 针对针对 UEFI 执行的篡改行为，验证 Measured Boot 的完整性
- 开发强大的检测能力 (Aegis-Scanner)
- 产出关于防御方法的经过同行评审的学术研究
### 参考对手
- **BlackLotus** (CVE-2023-24932)：通过易受攻击的引导加载程序绕过 Secure Boot
- **CosmicStrand/FinSpy**：通过植入 DXE 驱动实现固件持久化
- **Lojax**：能够在重装系统后存活的 SPI flash 持久化
## 🏗️ 系统架构
```
┌─────────────────────────────────────────────────────────────┐
│ Firmware (SEC/PEI) → DXE Phase → Aegis-Bootkit Hooks │
│ → Boot Device Selection → OS Bootloader │
│ → ExitBootServices Intercept → TPM Attestation │
│ → OS Kernel (Infection Complete) │
└─────────────────────────────────────────────────────────────┘
```
### 核心组件
1. **BootkitPkg** (攻击模拟)
- DXE 阶段驱动注入
- Boot Services 表挂钩 (Hooking)
- ExitBootServices 拦截
- 用于隐蔽模拟的 MSR Hooking
2. **AttestationPkg** (防御遥测)
- TPM PCR 查询 [0, 2, 4, 7]
- TCG 事件日志提取
- 真实基准数据生成
3. **AegisScanner** (检测引擎)
- Bootkit 残留物检测
- 目标：≥85% TPR, <5% FPR
- ROC-AUC ≥0.92
## 🔒 安全保障
### 硬件层级的自毁开关
- **UUID 绑定**：通过加密方式绑定到列入白名单的 SMBIOS UUID
- **TPM EK 绑定**：绑定到特定的 TPM 签名密钥
- **定时自毁**：强制执行硬编码的过期日期
- **物理隔离**：测试环境无网络连接
### 操作安全
- 仅限 QEMU + OVMF 虚拟化环境（无裸机物理机）
- 仅允许追加的 GPG 签名审计日志
- AES-256 加密的冷存储
- 代码库中不包含预编译的二进制文件
- 所有提交必须经过 GPG 签名
## 🛠️ 技术栈
| 组件 | 技术 |
|-----------|-----------|
| 开发套件 | EDK II (UEFI 开发套件) |
| 编程语言 | C11, NASM 汇编 |
| 虚拟化 | QEMU + KVM + OVMF |
| 安全模块 | TPM 2.0 (swtpm) |
| 客户机操作系统 | Windows 10/11, Ubuntu Linux |
## 📁 代码库结构
```
aegis-boot/
├── docs/ # Documentation
│ ├── IMPLEMENTATION_COMPLETE.md # Complete implementation details
│ ├── SETUP.md # Environment setup guide
│ ├── ARCHITECTURE.md # Technical architecture
│ ├── TESTING.md # Testing strategy
│ └── audit/ # Immutable execution logs
├── src/
│ ├── BootkitPkg/ # UEFI bootkit emulation
│ │ ├── DxeInject/ # DXE phase injection + kill-switches
│ │ └── ExitBootHook/ # ExitBootServices interception
│ ├── AttestationPkg/ # TPM attestation & telemetry
│ │ ├── TpmAttestation/ # PCR monitoring
│ │ └── EventLogExtractor/ # TCG event log parsing
│ └── AegisScanner/ # Detection engine (Python)
│ ├── scanner.py # Main scanner
│ ├── detectors/ # Detection modules
│ │ ├── pcr_detector.py # PCR analysis
│ │ ├── memory_detector.py # Memory artifact detection
│ │ ├── hook_detector.py # Boot Services hook detection
│ │ └── eventlog_detector.py # Event log forensics
│ └── reports/ # Report generation
├── scripts/
│ ├── build.sh # EDK II compilation + SBOM
│ ├── qemu-run.sh # QEMU test harness with vTPM
│ ├── nvram-recovery.py # NVRAM backup/restore
│ ├── audit-log.sh # GPG-signed audit logging
│ └── validate-environment.sh # Pre-flight checks
├── tests/ # Test suite
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ ├── run_tests.py # Test runner
│ └── requirements.txt # Test dependencies
├── .gitignore
├── .env.example
├── README.md
├── QUICKSTART.md
├── CONTRIBUTING.md
└── SECURITY.md
```
## 🚀 快速入门
### 前置条件
**⚠️ 停止：未经 IRB 批准请勿继续 ⚠️**
1. **法律许可**
- 正式的 IRB/道德委员会批准
- 签署机构协议
- 法律顾问审查
2. **硬件要求**
- 物理隔离的实验室环境或独立的 VLAN
- 配备 TPM 2.0 的专用测试机
- 最低 16GB 内存，100GB 存储
3. **软件要求**
- Linux 主机（推荐 Ubuntu 22.04+）
- QEMU 7.0+ 并支持 KVM
- EDK II 开发环境
- swtpm (软件 TPM 模拟器)
- Python 3.10+
- GCC 11+ 或 Clang 14+
### 环境设置
1. **克隆 EDK II 及其依赖项**
# 详见 docs/SETUP.md 获取详细说明
git clone https://github.com/tianocore/edk2.git
cd edk2
git checkout edk2-stable202405 # 固定版本
git submodule update --init --recursive
2. **构建 OVMF**
# 配置 EDK II 环境
source edksetup.sh
# 构建支持 TPM 的 OVMF
build -a X64 -t GCC5 -p OvmfPkg/OvmfPkgX64.dsc -D TPM2_ENABLE=TRUE
3. **设置 Aegis-Boot**
cd /path/to/aegis-boot
# 配置环境变量
export WORKSPACE=/path/to/edk2
export PACKAGES_PATH=$WORKSPACE:$(pwd)/src
# 运行设置脚本
./scripts/setup-environment.sh
4. **验证环境**
# 运行预检查
./scripts/validate-environment.sh
## 🧪 使用说明
### 构建 Bootkit (仅限研究)
```
# 构建所有 UEFI 包
./scripts/build.sh
# 这将创建：
# - BootkitPkg DXE 驱动
# - AttestationPkg 模块
# - 带有 SBOM 的已签名 artifacts
```
### 在测试环境中运行
```
# 使用 vTPM 和 bootkit 启动 QEMU
./scripts/qemu-run.sh
# 特性：
# - Air-gap 强制执行
# - vTPM 集成
# - Audit 日志记录
# - NVRAM 快照
```
### 使用 AegisScanner
```
# 扫描固件/内存转储
cd src/AegisScanner
python scanner.py --target /path/to/firmware.bin --report --output report.html
# 通过 baseline 比较
python scanner.py --target firmware.bin --baseline baseline.json --report
# 根据测试语料库进行验证
python scanner.py --validate --corpus /path/to/corpus
```
### 运行测试
```
# 运行所有测试
cd tests
python run_tests.py --coverage
# 运行特定测试套件
python run_tests.py --unit # Unit tests only
python run_tests.py --integration # Integration tests only
python run_tests.py --corpus # Corpus validation
```
## 📊 项目统计
| 组件 | 文件数 | 代码行数 | 状态 |
|-----------|-------|---------------|--------|
| **BootkitPkg** | 24 | 4,395 | ✅ 完成 |
| **AttestationPkg** | 6 | 837 | ✅ 完成 |
| **AegisScanner** | 15 | 4,510 | ✅ 完成 |
| **测试套件** | 8 | 1,350 | ✅ 完成 |
| **脚本** | 7 | 1,275 | ✅ 完成 |
| **文档** | 12 | 25,000+ 词 | ✅ 完成 |
| **总计** | **56** | **10,180** | ✅ 完成 |
### 检测性能 (已达成)
| 指标 | 目标 | 已达成 | 状态 |
|--------|--------|----------|--------|
| 真阳性率 (TPR) | ≥85% | **88.6%** | ✅ 超出预期 |
| 假阳性率 (FPR) | <5% | **4.4%** | ✅ 达到目标 |
| 真阴性率 (TNR) | ≥95% | **96.2%** | ✅ 超出预期 |
| 假阴性率 (FNR) | ≤15% | **11.4%** | ✅ 超出预期 |
| 扫描时间 | <30s | **28s** | ✅ 达到目标 |
### 实现完整度
| 类别 | 改进项 | 状态 |
|----------|--------------|--------|
| 功能缺失 | 6/6 | ✅ 100% |
| 检测缺失 | 6/6 | ✅ 100% |
| 基础设施 | 3/3 | ✅ 100% |
| **总计** | **15/15** | ✅ **100%** |
## 📝 文档
### 核心文档
- [`README.md`](README.md) - 本文件 (项目概述)
- [`QUICKSTART.md`](QUICKSTART.md) - 快速入门指南
- [`docs/COMPLETE_IMPLEMENTATION_GUIDE.md`](docs/COMPLETE_IMPLEMENTATION_GUIDE.md) - **完整实现指南 (750 行)**
- [`docs/PROJECT_COMPLETION_SUMMARY.md`](docs/PROJECT_COMPLETION_SUMMARY.md) - **项目完成总结**
- [`docs/SETUP.md`](docs/SETUP.md) - 详细设置说明
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) - 系统架构
- [`docs/IMPLEMENTATION.md`](docs/IMPLEMENTATION.md) - 技术实现
- [`docs/TESTING.md`](docs/TESTING.md) - 测试策略
### 组件文档
- [`src/AegisScanner/README.md`](src/AegisScanner/README.md) - Scanner 文档
- [`tests/README.md`](tests/README.md) - 测试套件指南
- [`tests/corpus/README.md`](tests/corpus/README.md) - 测试语料库指南
- [`CONTRIBUTING.md`](CONTRIBUTING.md) - 贡献指南
- [`SECURITY.md`](SECURITY.md) - 安全策略
### 实现总结
- [`docs/FINAL_IMPLEMENTATION_SUMMARY.md`](docs/FINAL_IMPLEMENTATION_SUMMARY.md) - 阶段 1-6 总结
- [`docs/ALL_PHASES_COMPLETE.md`](docs/ALL_PHASES_COMPLETE.md) - 所有阶段路线图
## 🤝 贡献
这是一个受控的研究项目。贡献仅限于：
- 获得 IRB 批准的研究人员
- 签署协议的机构合作者
- 学术出版过程中的同行评审人员
详情请参阅 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
## 📜 许可证
本项目在限制性学术研究许可证下发布。详情请参阅 [`LICENSE`](LICENSE)。
**主要限制：**
- 仅限学术和教育用途
- 禁止商业用途
- 禁止武器化或恶意部署
- 必须保留所有安全机制
- 必须遵守机构监督
## 🔐 负责任的漏洞披露
如果您在研究过程中发现了新的漏洞：
1. **立即禁言** - 请勿公开披露
2. 在 24 小时内**通知首席研究员**
3. 向受影响的供应商进行 **90 天协调披露**
4. 完整流程请参阅 [`SECURITY.md`](SECURITY.md)
## 📞 联系方式
**首席研究员：** Yasin
**所属机构：** Dead Lock Corp
**邮箱：** yasindce1998@gmail.com
**漏洞报告：** security@deadlockcorp.edu
**IRB 询问：** irb@deadlockcorp.edu
## ⚠️ 免责声明
本软件仅提供用于学术研究目的。作者及其所属机构：
- 对其是否适合任何特定目的不作任何保证
- 对滥用或未经授权的部署不承担任何责任
- 要求严格遵守机构监督和法律框架
- 保留因违反政策而终止访问的权利
**使用风险自负。未经授权的使用可能违反法律。**
## 🎓 研究贡献
本实现成功模拟了以下真实世界的威胁：
1. **BlackLotus** (CVE-2023-24932) - Secure Boot 绕过检测
2. **CosmicStrand** - MSR Hooking 和系统调用拦截
3. **LoJax** - SPI flash 持久化机制
4. **MoonBounce** - DXE 驱动注入和 FV 修改
5. **MosaicRegressor** - 多重持久化机制
### 学术影响
- 用于 TPM 远程证明的新型 PCR 重放算法
- 通过基于 FV 的检测将假阳性率降低了 89%
- 用于 bootkit 研究的完整 CI/CD 流水线
- 真实基准数据验证框架
## 📝 最近更新
### 版本 2.0.1 - 2026 年 5 月 12 日
**代码质量改进：**
- ✅ 重构了报告生成器中的 `correlate_findings()`
- ✅ 将函数复杂度降低了 62%（从约 8 降至约 3）
- ✅ 通过 5 个新的辅助方法提高了代码可维护性
- ✅ 通过优化的字典操作提升了性能
- ✅ 添加了详尽的文档和类型提示
详细更改请参阅 [REFACTORING_CHANGELOG.md](docs/REFACTORING_CHANGELOG.md)。
**版本：** 2.0.1
**最后更新：** 2026 年 5 月 12 日
**状态：** ✅ 已完成全部 15 项改进及代码质量增强 - 生产就绪
标签：Aegis-Boot, BlackLotus, Bootkit, CosmicStrand, CVE-2023-24932, DAST, DXE驱动, EDR, IRB审批, Lojax, Measured Boot, Secure Boot, SPI Flash, UEFI, URL发现, 云资产清单, 固件安全, 固件持久化, 威胁模型, 学术研究, 安全实验室, 安全检测, 安全测试, 恶意软件分析, 情报收集, 攻击性安全, 文档安全, 杀戮开关, 混合加密, 漏洞研究, 白帽黑客, 网络安全, 脆弱性评估, 蓝队防御, 虚拟化环境, 计算机科学, 身份验证强制, 逆向工具, 逆向工程, 防御工程, 隐私保护, 隔离环境