riverrisk/marlinspike-malware
GitHub: riverrisk/marlinspike-malware
基于 Rust 的高性能网络 IOC 检测引擎，通过 YAML 规则包对网络遥测数据进行恶意软件和威胁指标匹配，支持完全离线运行并覆盖 ICS/OT 专用威胁。
Stars: 0 | Forks: 0
# marlinspike-malware
用于 MarlinSpike 套件中进行恶意软件和 IOC 检测的共享 Rust crate。
`marlinspike-malware` 是
[MarlinSpike](https://github.com/riverrisk/marlinspike) repo 家族中的 Rust 引擎之一，与
`marlinspike-dpi` 并存。它加载 YAML 规则包，根据这些规则评估通用的观测事件，并输出结构化的发现结果。该引擎有意设计为产品中立，以便 MarlinSpike 和 Fathom 都能将其自身的遥测数据适配到同一规则层面。
运行时操作完全在本地进行。设备在物理隔离（air-gapped）环境下仍能保持功能。公共订阅源（ThreatFox、URLhaus、MalwareBazaar）可以通过兄弟
[marlinspike-malware-rules](https://github.com/riverrisk/marlinspike-malware-rules)
仓库离线规范化为 YAML schema。
## 架构
```
marlinspike-dpi
|
Bronze events
|
marlinspike-malware
/ \
YAML rule packs ObservedEvent stream
\ /
MalwareFinding[]
|
MarlinSpike report
(analysis block)
```
#### 扫描流程
```
marlinspike-malware scan
--rules-dir → load + compile YAML packs
--events → ObservedEvent[] JSON (from _ms_engine.py)
--output → MalwareFinding[] JSON (back to _ms_engine.py)
```
该引擎位于 MarlinSpike 管道中，介于 DPI 事件发出和报告组装之间。它消费 Bronze 风格的观测事件（DNS 查询、HTTP 主机/URI、TLS SNI、工件哈希、IP 地址、协议元数据），并根据编译后的规则包对其进行评估，以生成 `MalwareFinding` 记录。
### 集成契约
本引擎遵循为 MarlinSpike 套件定义的 [可扩展性契约](https://github.com/riverrisk/marlinspike/blob/main/docs/extensibility-contracts.md)：
| 层面 | 角色 |
|---------|------|
| **Rust engine** | 面向数据包/事件，高吞吐量 IOC 匹配 |
| **YAML rule packs** | 声明式 IOC 和签名内容 |
| **Python plugin** | 面向报告的富化（由其他模块处理） |
引擎接受一个规则目录，将其编译成规范化的包，并处理成批的 `ObservedEvent` 结构体。它不负责拓扑评分、ATT&CK 映射或 UI 行为。
### Bronze 消费者契约
`marlinspike-malware` 消费与核心 MarlinSpike 引擎相同的 Bronze 事件层。它可以评估来自以下来源的事件：
- `protocol_transaction` — 带有提取出的观测数据的网络会话
- `extracted_artifact` — 文件哈希、二进制签名、工件密钥
- `asset_observation` — 主机级指标
完整的消费者规则请参见 [bronze-consumer-contract.md](https://github.com/riverrisk/marlinspike/blob/main/docs/bronze-consumer-contract.md)。
## 规则引擎
### 可观测字段
规则与从 Bronze 事件中提取的以下可观测字段进行匹配：
| 字段 | 描述 | 示例 |
|-------|-------------|---------|
| `dns_query` | DNS 查询域名 | `evil.example.com` |
| `dns_answer` | DNS 响应数据 | `185.215.113.x` |
| `http_host` | HTTP Host 头 | `c2.badactor.invalid` |
| `http_uri` | HTTP 请求 URI | `/api/v1/beacon` |
| `tls_sni` | TLS 服务器名称指示 | `update.malware.invalid` |
| `artifact_sha256` | 提取工件的 SHA-256 哈希 | `a1b2c3d4...` |
| `artifact_key` | 命名工件标识符（互斥体、注册表键、文件路径） | `HKLM\Software\Malware` |
| `src_ip` | 源 IP 地址 | `10.0.0.50` |
| `dst_ip` | 目的 IP 地址 | `45.33.32.156` |
| `src_mac` | 源 MAC 地址 | `aa:bb:cc:dd:ee:ff` |
| `dst_mac` | 目的 MAC 地址 | `ff:ee:dd:cc:bb:aa` |
| `hostname` | 设备主机名 | `ENG-WS-014` |
| `protocol` | 协议标识符 | `modbus`, `s7comm` |
| `any_text` | 匹配所有文本字段 | 协议工件的兜底匹配 |
### 匹配运算符
| 运算符 | 行为 |
|----------|----------|
| `equals` | 精确字符串匹配（默认） |
| `contains` | 子字符串匹配 |
| `prefix` | 字符串以值开头 |
| `suffix` | 字符串以值结尾 |
所有运算符均支持 `case_sensitive: true/false`（默认值：false）。
### 匹配模式
| 模式 | 行为 |
|------|----------|
| `any` | 如果**任一**条件匹配则触发（默认，OR 逻辑） |
| `all` | 仅当**所有**条件匹配时才触发（AND 逻辑） |
### 发现严重级别
`info` | `low` | `medium` | `high` | `critical`
### 发现输出 Schema
`scan` 命令发出的每个 `MalwareFinding` 包含以下字段：
| 字段 | 类型 | 描述 |
|-------|------|-------------|
| `finding_id` | string | 此发现结果的唯一标识符 |
| `rule_id` | string | 匹配规则的 ID |
| `rule_name` | string | 人类可读的规则名称 |
| `family` | string | 恶意软件家族（如 `cobaltstrike`, `emotet`） |
| `severity` | string | `info` \| `low` \| `medium` \| `high` \| `critical` |
| `confidence` | float | 置信度分数 (0.0–1.0) |
| `summary` | string | 匹配结果的人类可读描述 |
| `observable_field` | string | 匹配到的字段（如 `dns_query`, `tls_sni`） |
| `observable_value` | string | 触发匹配的值 |
| `event_id` | string | 源事件 ID |
| `capture_id` | string | 捕获会话 ID |
| `timestamp` | string | 事件的 ISO 8601 UTC 时间戳 |
| `src_ip` | string? | 源 IP 地址（若存在） |
| `dst_ip` | string? | 目的 IP 地址（若存在） |
| `src_mac` | string? | 源 MAC 地址（若存在） |
| `dst_mac` | string? | 目的 MAC 地址（若存在） |
| `references` | string[] | 指向公告、ATT&CK 技术等的 URL |
| `tags` | string[] | 分类标签（如 `apt`, `c2`, `dns`） |
| `source_feed` | string? | 归因订阅源名称（若适用） |
| `metadata` | object | 来自规则或事件的任意键值元数据 |
## 规则包 Schema
```
version: v1
name: "Pack Name"
source:
name: "attribution source"
url: "https://..."
license: "Apache-2.0"
description: "Source description"
rules:
- id: unique-rule-id
name: "Human-readable rule name"
family: "malware-family"
severity: critical
confidence: 0.90
description: "What this rule detects and why"
tags: [apt, c2, dns]
references:
- "https://attack.mitre.org/techniques/T1071/"
- "https://www.cisa.gov/..."
match_mode: any
conditions:
- field: dns_query
op: suffix
value: ".malware.invalid"
case_sensitive: false
- field: tls_sni
op: contains
value: "beacon"
```
## 内置规则包
`rules/` 目录附带了 29 个精选包，涵盖完整威胁 landscapes 的 919 条检测规则。
### 威胁覆盖
| 包 | 规则数 | 覆盖范围 |
|------|-------|----------|
| **Malware Loaders** | 24 | BazarLoader, Emotet, QakBot, IcedID, Bumblebee, SocGholish, Gootloader, Raspberry Robin, Pikabot, GuLoader |
| **C2 Frameworks** | 18 | Cobalt Strike, Metasploit, Sliver, Havoc, Brute Ratel, Mythic, PoshC2, Covenant, Empire, Nighthawk |
| **RATs** | 32 | AsyncRAT, DarkComet, njRAT, Remcos, QuasarRAT, Agent Tesla, NanoCore, Warzone, DcRAT, XWorm, NetWire, Gh0st RAT |
| **Ransomware** | 34 | LockBit, BlackCat/ALPHV, Royal/BlackSuit, Cl0p, Black Basta, Akira, Play, Rhysida, Medusa, BianLian, Hive, Conti |
| **Infostealers** | 24 | RedLine, Raccoon, Vidar, LummaC2, Rhadamanthys, StealC, META, Aurora, Mystic, Titan, FormBook/XLoader |
| **ICS/OT Threats** | 32 | TRITON, Industroyer 1+2, PIPEDREAM, BlackEnergy, Havex, Stuxnet-derived, FrostyGoop, CosmicEnergy, IRONGATE |
| **Suspicious Patterns** | 38 | DNS tunneling, DGA, dynamic DNS abuse, encoded payloads, cryptomining, Tor, phishing lookalikes, exfiltration |
| **APT Tooling** | 40 | APT28, APT29, APT41, Lazarus, Turla, Kimsuky, Sandworm, MuddyWater (SUNBURST, ShadowPad, PlugX, Snake, etc.) |
| **Wipers** | 27 | WhisperGate, HermeticWiper, CaddyWiper, AcidRain, Shamoon, ZeroCleare, Dustman, Meteor, Agrius |
| **Botnets** | 31 | Mirai variants, TrickBot, Dridex, ZLoader, Qakbot, Androxgh0st, Volt Typhoon, Emotet, Phorpiex, Amadey |
| **Webshells** | 36 | China Chopper, Godzilla, Behinder, AntSword, ASPXSpy, HAFNIUM/ProxyShell drops, IIS backdoors, generic patterns |
| **Backdoors & Implants** | 31 | ShadowPad, PlugX, MATA, Daxin, BPFDoor, Symbiote, BlackLotus, CosmicStrand, Derusbi, GoldMax |
| **Exploit Delivery** | 35 | Log4Shell, ProxyShell/Logon/NotShell, MOVEit, Confluence, Citrix Bleed, FortiGate, Ivanti, Spring4Shell, exploit kits |
| **Proxy & Tunneling** | 31 | Chisel, frp, ngrok, Cloudflare Tunnel, reGeorg, Ligolo, Plink, GOST, residential proxies, Shadowsocks |
| **Credential Theft** | 30 | Mimikatz, LSASS dumps, Kerberoasting, Rubeus, Impacket, Responder, BloodHound, Evilginx, CrackMapExec |
| **Data Exfiltration** | 31 | Cloud storage, Rclone, DNS exfil, ICMP tunneling, Telegram/Discord/Slack webhooks, paste sites, file hosting |
| **Mobile & Spyware** | 34 | Pegasus, Predator, FinFisher, Hermit, Candiru, stalkerware, FluBot, SharkBot, Xenomorph, Cerberus, TeaBot |
| **Cryptocurrency Threats** | 33 | Wallet drainers, clipbankers, fake exchanges, cryptojacking, DPRK crypto theft, mixers, fake wallet apps |
| **Lateral Movement** | 34 | PsExec, WMI, WinRM, DCOM, RDP tunneling, EternalBlue, PrintNightmare, SCShell, CobaltStrike lateral |
| **Supply Chain** | 37 | 3CX, SolarWinds, Kaseya, Codecov, Polyfill.io, npm/PyPI typosquatting, dependency confusion, CDN compromise |
| **Recon & Scanning** | 41 | Nmap, Masscan, Nuclei, Shodan, ADFind, BloodHound, Gobuster, SQLMap, WPScan, cloud enumeration |
| **Defense Evasion** | 41 | Certutil, mshta, bitsadmin, AMSI bypass, ETW patching, LOLBins, PowerShell cradles, reflective injection |
| **Phishing-as-a-Service** | 39 | Tycoon 2FA, EvilProxy, Greatness, W3LL Panel, Rockstar 2FA, FlowerStorm, OAuth phishing, quishing |
| **Cloud & SaaS Threats** | 35 | TeamTNT, Kinsing, Denonia, SCARLETEEL, SCATTERED SPIDER, container escapes, K8s exploitation, cloud C2 |
| **DNS Abuse** | 35 | DoH C2, DNS rebinding, subdomain takeover, IDN homograph, sinkholes, malicious nameservers, fast-flux |
| **Email Threats** | 35 | BEC infrastructure, malspam, HTML smuggling, callback phishing, OneNote/ISO abuse, OAuth consent phishing |
| **IoT Threats** | 34 | Camera/router exploitation, Moobot, Fodcha, RapperBot, Zerobot, AVrecon, UPnP/SSDP/MQTT/CWMP abuse |
| **Ransomware Ecosystem** | 35 | IAB marketplaces, OFAC-sanctioned exchanges, SystemBC, affiliate tools, loader handoffs, payment infra |
| **Adware & PUPs** | 32 | Fireball, DealPly, Conduit, Superfish, BADBOX, tech support scams, SocGholish distribution, click fraud |
### 严重级别分布
| 严重级别 | 规则数 |
|----------|-------|
| Critical | ~380 |
| High | ~380 |
| Medium | ~110 |
Low | ~30 |
| Info | ~19 |
| **Total** | **919** |
### IOC 来源
所有规则均源自公开的威胁情报：
- **政府公告**：CISA, NSA, FBI, NCSC-UK, CERT-UA
- **MITRE**：ATT&CK Enterprise + ICS 框架
- **供应商研究**：Mandiant, CrowdStrike, ESET, Kaspersky, Unit 42, SentinelOne, Sophos, ThreatFabric, Cleafy
- **民间社会**：Amnesty International, Citizen Lab
- **社区**：MalwareBazaar, abuse.ch, stalkerware-indicators
- **标准机构**：OFAC 制裁指定
## CLI
该 crate 包含一个用于规则包验证和编译的 CLI：
```
# 验证所有 rule packs
cargo run -- validate --rules-dir rules/
# 使用 JSON output 进行验证
cargo run -- validate --rules-dir rules/ --json
# 编译为 normalized JSON bundle
cargo run -- compile --rules-dir rules/ --output build/bundle.json --pretty
# 根据 rules 扫描 observed events
cargo run -- scan --rules-dir rules/ --events events.json --output findings.json
```
`scan` 子命令读取一个 `ObservedEvent[]` JSON 数组，根据所有加载的规则评估每个事件，并将生成的 `MalwareFinding[]` JSON 写入输出路径。
验证检查：
- 包和规则字段的完整性
- 置信度范围 (0.0-1.0)
- 每条规则至少有一个条件
- 所有包中没有重复的规则 ID
- 有效的字段名和运算符
## MarlinSpike 集成
该引擎在分析管道的 **Stage 4b** 期间由 MarlinSpike 的 Python 引擎（`_ms_engine.py`）作为子进程调用。
### 二进制文件自动发现
MarlinSpike 按顺序检查以下位置来定位 `marlinspike-malware` 二进制文件：
1. `MARLINSPIKE_MALWARE_BIN` 环境变量
2. `PATH`
3. `~/marlinspike-malware/target/release/`
4. `~/marlinspike-malware/target/debug/`
### 规则自动发现
规则包按顺序检查以下位置来定位：
1. `MARLINSPIKE_MALWARE_RULES` 环境变量
2. `~/marlinspike-malware/rules/`
3. `~/marlinspike-malware-rules/packs/`
### 事件转换
`_ms_engine.py` 在将 MarlinSpike 会话对象传递给引擎之前，会将其转换为 `ObservedEvent` JSON。提取以下观测数据：
- DNS 查询和应答
- IP 地址（源和目的）
- MAC 地址
- 协议标识符
- Bronze 透传属性（HTTP 主机/URI、TLS SNI、工件哈希等）
### 发现结果转换
引擎的 `MalwareFinding[]` 输出被转换回 MarlinSpike 报告结构：
- 类型为 `MALWARE_IOC_MATCH` 的 **`c2_indicators`**
- 附加到分析报告的 **`risk_findings`**
### 可选阶段
Stage 4b 是可选的。如果找不到二进制文件或规则目录，分析将继续进行，但不进行恶意软件匹配。当向 MarlinSpike 传递 `--fast` 参数时，恶意软件匹配将被完全跳过。
## Library API
```
use marlinspike_malware::{MalwareEngine, ObservedEvent, ObservedValue, MatchField};
// Load rules from a directory
let engine = MalwareEngine::from_rule_dir("rules/")?;
println!("Loaded {} rules", engine.rule_count());
// Process observed events
let findings = engine.process_observed_batch("bronze-dpi", &events);
for finding in &findings {
println!(
"[{}] {} — {} (confidence: {:.0}%)",
finding.severity.as_str(),
finding.rule_name,
finding.summary,
finding.confidence * 100.0,
);
}
```
### 关键类型
| 类型 | 描述 |
|------|-------------|
| `MalwareEngine` | 编译后的规则集，处理事件批次 |
| `ObservedEvent` | 带有元数据和观测数据的单个网络事件 |
| `ObservedValue` | 事件中的一个可观测字段+值对 |
| `MalwareFinding` | 带有规则元数据、严重级别、证据的检测结果 |
| `RulePack` | 反序列化的 YAML 规则包 |
| `CompiledRuleBundle` | 可序列化的编译包（用于 JSON 导出） |
## 兄弟仓库
| Repo | 用途 |
|------|---------|
| [marlinspike](https://github.com/riverrisk/marlinspike) | 套件 repo — 引擎、工作台、插件 |
| [marlinspike-dpi](https://github.com/riverrisk/marlinspike-dpi) | Rust DPI 引擎 — 数据包解析、Bronze 事件发出 |
| [marlinspike-malware-rules](https://github.com/riverrisk/marlinspike-malware-rules) | 发布的规则内容 — 手动包 + 公共订阅源导入 |
| [marlinspike-mitre](https://github.com/riverrisk/marlinspike-mitre) | Python 插件 — 基于报告结果的 ATT&CK 映射 |
### 与 marlinspike-malware-rules 的关系
本仓库（`marlinspike-malware`）是**引擎**。兄弟仓库
`marlinspike-malware-rules` 是**发布的内容**：
```
marlinspike-malware marlinspike-malware-rules
├── src/ ├── packs/
│ ├── engine.rs │ ├── manual/ ← curated rules
│ ├── rules.rs │ └── public/ ← ThreatFox, URLhaus, MalwareBazaar
│ ├── finding.rs ├── manifests/
│ └── observed.rs │ └── index.yaml
├── rules/ └── scripts/
│ └── (dev/bundled rules) ├── build_index.py
└── Cargo.toml └── update_public_feeds.py
```
本仓库中的 `rules/` 目录附带了用于开发和独立使用的内置检测内容。对于生产部署，规则内容在 `marlinspike-malware-rules` 中管理，并通过 CLI 编译成包。
## 开发
```
# 构建
cargo build
# 测试
cargo test
# 验证 bundled rules
cargo run -- validate --rules-dir rules/
# 编译 production bundle
cargo run -- compile --rules-dir rules/ --output build/marlinspike-malware-bundle.json --pretty
```
### 添加规则
1. 在 `rules/` 下选择合适的包（或创建新目录）
2. 按照上述 YAML schema 添加规则
3. 运行 `cargo run -- validate --rules-dir rules/` 检查错误
4. 确保规则 ID 在所有包中全局唯一
### 规则 ID 约定
规则 ID 遵循模式 `{category}-{family}-{description}`：
```
c2-cobaltstrike-default-beacon-uri
rat-asyncrat-default-mutex
ics-triton-triconex-udp
loader-emotet-epoch4-c2
ransomware-lockbit-leak-site
```
## 许可证
`marlinspike-malware` 仅根据 GNU Affero General Public License v3.0 进行许可。参见 [LICENSE](LICENSE)。
标签：AWS, DPI, Fathom, Homebrew安装, HTTP/HTTPS抓包, IOC检测, MalwareBazaar, MarlinSpike, Rust, TCP/UDP协议, ThreatFox, URLhaus, YAML规则, 云计算, 可视化界面, 威胁情报, 安全工具开发, 开发者工具, 态势感知, 文档结构分析, 离线检测, 网络安全, 网络流量审计, 自动化分析, 规则引擎, 跨站脚本, 逆向工具, 通知系统, 隐私保护