Karib0u/rustinel
GitHub: Karib0u/rustinel
基于 Rust 的高性能用户态 Windows EDR，通过 ETW 采集遥测数据，结合 Sigma/YARA/IOC 实现威胁检测并以 ECS 格式输出告警。
Stars: 64 | Forks: 11
# Rustinel
**高性能、用户态 Windows EDR（Rust 实现）**
Rustinel 是一款使用 **Rust** 编写的**高吞吐量 Windows EDR 代理**。它通过 **ETW** 收集**内核遥测数据**，将事件标准化为 **Sysmon 兼容的 schema**，使用 **Sigma** + **YARA** 检测威胁，并输出 **ECS NDJSON** 格式的警报，以便直接导入 SIEM。
## 为什么选择 Rustinel？
Rustinel 专为希望获得以下能力的防御者构建：
- **无内核风险的内核级遥测**（ETW，用户态）
- **高负载下的性能表现**（异步 pipeline + 缓存 + 噪声抑制）
- **检测兼容性**（针对 Sigma 的 Sysmon 风格标准化）
- **运维简单**（磁盘上的 NDJSON 警报，易于发送至 SIEM）
## 功能概览
Rustinel 通过以下方式监控 Windows 端点：
- 通过 **ETW** 收集内核事件（进程、网络、文件、注册表、DNS、PowerShell、WMI、服务、任务）
- 将 ETW 事件标准化为 **Sysmon 兼容**字段
- 使用 **Sigma 规则**和 **YARA 扫描**检测威胁
- 检测**原子 IOC**（哈希、IP/CIDR、域名、路径正则）
- 无需重启进程即可热重载本地 Sigma/YARA/IOC 文件
- 以 **ECS NDJSON** 格式写入警报
## 核心特性
- **仅用户态**：无需内核驱动
- **双重检测引擎**：
- **Sigma** 用于行为检测
- **YARA** 用于进程启动时的文件扫描
- **原子 IOC 检测**：哈希、IP/CIDR、域名、路径正则
- **本地热重载**：Sigma、YARA 和 IOC 文件通过原子交换原地重载
- **噪声抑制**：
- ETW 会话级别的关键字过滤
- 路由级别的高流量网络事件过滤
- 可选的网络连接聚合
- **热路径优化**：
- Sigma 规则在加载时按 `category`/`product`/`service` 过滤
- Sigma 条件在启动及热重载时转译 + 预编译
- 进程上下文富化附加在警报上，而非每个事件
- **信息富化**：
- NT → DOS 路径标准化
- PE 元数据提取
- 父进程关联
- SID → `DOMAIN\User` 解析
- DNS 缓存和反向映射
- **Windows 服务支持**（安装/启动/停止/卸载）
- **ECS NDJSON 警报**，便于 SIEM 接入
- **可选主动响应**（试运行模式或在严重警报时终止）
## 环境要求
- Windows 10/11 或 Server 2016+
- 管理员权限（ETW + 服务管理）
- Rust 1.92+（从源码构建）
## 快速开始
**选项 1：下载 Release（推荐）**
1. 从 [GitHub Releases](https://github.com/Karib0u/rustinel/releases) 下载最新版本。
2. 解压归档文件。
3. 在已提升权限的 PowerShell 中运行：
.\rustinel.exe run --console
**选项 2：从源码构建**
```
# 构建
cargo build --release
# 运行（控制台输出）
.\target\release\rustinel.exe run --console
```
不带参数运行等同于 `rustinel run`。
## 2 分钟演示
### Sigma 演示
本仓库附带了一个示例规则：`rules/sigma/example_whoami.yml`
1. 启动 Rustinel（管理员 Shell）：
```
cargo run -- run --console
```
2. 触发规则：
```
whoami /all
```
3. 验证是否写入了警报：
* `logs/alerts.json.YYYY-MM-DD`
### YARA 演示
本仓库附带了一个示例规则：`rules/yara/example_test_string.yar`
1. 构建演示二进制文件：
```
rustc .\examples\yara_demo.rs -o .\examples\yara_demo.exe
```
2. 运行它：
```
.\examples\yara_demo.exe
```
3. 验证警报是否包含规则名称：
* `ExampleMarkerString`
**注意：** 演示二进制文件会循环运行以展示主动响应。启用响应且 `prevention_enabled = true` 时，当 YARA 规则触发时进程将被自动终止（YARA 匹配被视为 `critical` 严重级别）。
## 服务模式
```
.\target\release\rustinel.exe service install
.\target\release\rustinel.exe service start
.\target\release\rustinel.exe service stop
.\target\release\rustinel.exe service uninstall
```
**注意事项**
* `service install` 注册的是 *当前可执行文件路径* —— 请从最终位置运行。
* 配置和规则路径根据工作目录解析；对于服务，建议使用绝对路径或环境变量覆盖。
* 服务运行时不接收 CLI 参数；请通过 `config.toml` 或 `EDR__LOGGING__LEVEL` 设置日志级别。
## 配置
配置优先级：
1. CLI 参数（最高，仅限运行模式）
2. 环境变量
3. `config.toml`
4. 内置默认值
示例 `config.toml`：
```
[scanner]
sigma_enabled = true
sigma_rules_path = "rules/sigma"
yara_enabled = true
yara_rules_path = "rules/yara"
[reload]
enabled = true
debounce_ms = 2000
[allowlist]
paths = [
"C:\\Windows\\",
"C:\\Program Files\\",
"C:\\Program Files (x86)\\",
]
[logging]
level = "info"
directory = "logs"
filename = "rustinel.log"
console_output = true
[alerts]
directory = "logs"
filename = "alerts.json"
match_debug = "off" # off | summary | full
[response]
enabled = false
prevention_enabled = false
min_severity = "critical"
channel_capacity = 128
allowlist_images = []
[network]
aggregation_enabled = true
aggregation_max_entries = 20000
aggregation_interval_buffer_size = 50
[ioc]
enabled = true
hashes_path = "rules/ioc/hashes.txt"
ips_path = "rules/ioc/ips.txt"
domains_path = "rules/ioc/domains.txt"
paths_regex_path = "rules/ioc/paths_regex.txt"
default_severity = "high"
max_file_size_mb = 50
```
`allowlist.paths` 默认在以下位置共享：
- `response.allowlist_paths`
- `ioc.hash_allowlist_paths`
- `scanner.yara_allowlist_paths`
如果显式设置了特定模块的列表，则仅该模块会覆盖共享列表。
匹配调试输出：
1. `alerts.match_debug = "off"` 禁用警报中的匹配详情（默认）。
2. `alerts.match_debug = "summary"` 添加规则条件 + 匹配的字段/模式。
3. `alerts.match_debug = "full"` 添加匹配的值和 YARA 字符串片段。
环境变量覆盖：
```
set EDR__LOGGING__LEVEL=debug
set EDR__SCANNER__SIGMA_RULES_PATH=C:\rules\sigma
set EDR__RELOAD__DEBOUNCE_MS=2000
set EDR__ALLOWLIST__PATHS=["C:\\Windows\\","C:\\Program Files\\"]
# 可选的特定模块覆盖：
set EDR__SCANNER__YARA_ALLOWLIST_PATHS=["C:\\Windows\\","D:\\Trusted\\"]
```
CLI 覆盖（最高优先级，仅限运行模式）：
```
rustinel run --log-level debug
```
注意：规则逻辑评估错误仅在 `warn`、`debug` 或 `trace` 级别记录（在 `info` 级别被抑制）。
### 热重载
| 选项 | 默认值 | 描述 |
|--------|---------|-------------|
| `enabled` | `true` | 启用基于本地文件的 Sigma、YARA 和 IOC 输入热重载 |
| `debounce_ms` | `2000` | 合并突发文件变更的防抖窗口（在重建/交换之前） |
注意事项：
- 轮询间隔为 `max(reload.debounce_ms, 2000ms)`。
- 出于安全考虑，空的重载结果将被拒绝（保留先前编译的引擎）。
### 主动响应
| 选项 | 默认值 | 描述 |
|--------|---------|-------------|
| `enabled` | `false` | 启用主动响应引擎 |
| `prevention_enabled` | `false` | 若为 `false`，仅记录试运行操作 |
| `min_severity` | `critical` | 触发响应的最低严重级别（Sigma 使用规则 `level`，YARA 始终视为 `critical`） |
| `channel_capacity` | `128` | 响应任务的队列大小（溢出时丢弃） |
| `allowlist_images` | `[]` | 要跳过的镜像基名或完整路径 |
| `allowlist_paths` | 继承 `allowlist.paths` | 要跳过的路径前缀（不区分大小写）。可选的模块特定覆盖 |
更多详情：`docs/active-response.md`。
### 原子 IOC 检测
| 选项 | 默认值 | 描述 |
|--------|---------|-------------|
| `enabled` | `true` | 启用原子 IOC 检测 |
| `hashes_path` | `rules/ioc/hashes.txt` | 哈希 IOC 文件（MD5/SHA1/SHA256） |
| `ips_path` | `rules/ioc/ips.txt` | IP 和 CIDR IOC 文件 |
| `domains_path` | `rules/ioc/domains.txt` | 域名 IOC 文件 |
| `paths_regex_path` | `rules/ioc/paths_regex.txt` | 路径/文件名正则 IOC 文件 |
| `default_severity` | `high` | 分配给 IOC 警报的严重级别 |
| `max_file_size_mb` | `50` | 跳过大于此大小（MB）的文件哈希计算 |
| `hash_allowlist_paths` | 继承 `allowlist.paths` | 跳过哈希计算的路径前缀（不区分大小写）。可选的模块特定覆盖 |
## 规则
### Sigma
* 将 `.yml` / `.yaml` 文件放置在 `rules/sigma/` 下
* 规则在启动时编译，并在文件更改时热重载
* 支持的类别包括：
`process_creation`, `network_connection`, `file_event`, `registry_event`,
`dns_query`, `image_load`, `ps_script`, `wmi_event`, `service_creation`, `task_creation`
### YARA
* 将 `.yar` / `.yara` 文件放置在 `rules/yara/` 下
* 规则在启动时编译，并在文件更改时热重载
* 扫描在 **进程创建** 时触发（在后台 worker 中运行）
* 位于白名单路径前缀下的文件会被跳过（默认为 `allowlist.paths` 或 `scanner.yara_allowlist_paths` 覆盖）
### 原子 IOC
将指标文件放置在 `rules/ioc/` 下：
* `hashes.txt` — MD5, SHA1, SHA256 哈希（根据长度自动检测）
* `ips.txt` — IP 地址和 CIDR 范围
* `domains.txt` — 精确域名或使用 `*.`/`.` 前缀进行后缀匹配
* `paths_regex.txt` — 与文件路径匹配的不区分大小写的正则
哈希检查在进程创建时于专用后台 worker 中运行。位于白名单路径（默认共享 `allowlist.paths`，或覆盖 `ioc.hash_allowlist_paths`）下的文件以及超过 `max_file_size_mb` 的文件会自动跳过。域名、IP 和路径检查在内联运行，开销极小。
IOC 文件在更改时也会热重载。
## 输出
Rustinel 生成：
* **运维日志**：`logs/rustinel.log.YYYY-MM-DD`
* **安全警报**（ECS NDJSON）：`logs/alerts.json.YYYY-MM-DD`
示例警报（每行一个 JSON 对象）：
```
{
"@timestamp": "2025-01-15T14:32:10Z",
"event.kind": "alert",
"event.category": "process",
"event.action": "process_creation",
"rule.name": "Whoami Execution",
"rule.severity": "low",
"rule.engine": "Sigma",
"process.executable": "C:\\Windows\\System32\\whoami.exe",
"process.command_line": "whoami /all",
"user.name": "DOMAIN\\username"
}
```
## 开发
```
# 单元测试
cargo test
# 格式化 + lint
cargo fmt
cargo clippy
# 验证 Sigma + YARA 规则
cargo run --bin validate_rules
```
项目布局（高层概览）：
```
src/
├── collector/ # ETW collection + routing
├── normalizer/ # Sysmon-style normalization + enrichment
├── engine/ # Sigma engine
├── scanner/ # YARA scanning worker
├── ioc/ # Atomic IOC detection (hashes, IPs, domains, paths)
├── state/ # caches (process/sid/dns/aggregation)
└── bin/validate_rules.rs
```
## 路线图
短期路线图：
- YARA 扩展（内存扫描 + 周期性扫描）。
- 资源调控器（Windows Job Objects CPU 限制）。
- 自我防御加固（DACL/ACL 限制 + 防注入）。
- 看门狗边车，用于在主进程死亡时重启服务。
- ETW 完整性检查以检测致盲/篡改。
- 通过堆栈跟踪进行深度检查以发现“浮动代码”。
## 状态
Rustinel 处于 **Alpha** 阶段。可用于实验、实验室部署和迭代加固。
在 schema 和引擎成熟期间，可能会发生破坏性变更。
## 许可证
Apache 2.0 — 详见 `LICENSE`。
标签：DNS 解析, ECS 格式, ETW, HTTP工具, IOC 检测, IP 地址批量处理, Rust, SIEM 采集, Sigma 规则, Sysmon, URL发现, Windows EDR, YARA, 事件日志, 云资产可视化, 内核遥测, 可视化界面, 域名分析, 安全检测, 开源安全工具, 用户模式, 端点可见性, 端点防护, 网络安全, 网络安全审计, 网络流量审计, 逆向工程平台, 通知系统, 通知系统, 隐私保护