carbon-evolution/ics-yara-scanner

# icsyara 将来自多个上游仓库的公共 YARA 规则聚合为一个经过验证、去重的本地规则集，并使用 [YARA-X](https://github.com/VirusTotal/yara-x) 引擎扫描**工程工作站 (EWS)** 和**固件转储 (firmware dumps)** 以检测恶意软件。 专为 OT/ICS 事件响应构建，但规则集具有广泛的通用恶意软件覆盖能力——EWS 本质上是一台 Windows 主机，而通用的勒索软件/RAT 往往是更可能被发现的威胁。其中包含了 ICS 恶意软件家族（如 Industroyer、TRITON/TRISIS、Stuxnet、Havex 等），并标记了 ATT&CK-for-ICS 技术。 ## 工作原理 ``` flowchart LR subgraph SRC["17 public repos (sources.yml)"] A1[signature-base] A2[Yara-Rules] A3[Elastic] A4[ESET / Nozomi ICS] A5[... 13 more] end SRC -->|git clone| F[fetch → cache/] F --> S[split multi-rule files] S --> V{compile-validate
with YARA-X} V -->|broken| Q[(rules/_broken/)] V -->|ok| D[dedupe by body hash] D --> IDX[(rules/ + index.json
18k unique rules)] IDX --> C[compile all rules] T1[EWS filesystem]:::tgt --> C T2[firmware .bin]:::tgt -->|binwalk extract| C C --> SCAN[concurrent scan] SCAN --> R[matches → console / JSON / CSV
exit 0 clean · 1 hit · 2 error] classDef tgt fill:#21262d,stroke:#e0b83a,color:#f0f6fc; ``` **收集器** (`icsyara update`) 构建规则集；**引擎** (`icsyara scan`) 使用该规则集。除了共享 `rules/` 目录外，它们互不干涉，因此你可以按照各自的计划独立刷新规则或执行扫描。 ## 功能说明 - **`icsyara update`** — 克隆 `sources.yml` 中的每一个源，拆分多规则文件，**使用 YARA-X 对每条规则进行编译验证**（损坏的规则会被隔离到 `rules/_broken/`），跨源去重，并生成 `rules/` 目录及 `rules/index.json` 文件。 - **`icsyara list [--family F] [--sources]`** — 规则清单。 - **`icsyara scan PATH [--firmware] [--json f] [--csv f] [--max-size MB]`** — 并发遍历目录/EWS 挂载点并报告规则匹配情况。 `--firmware` 会首先运行 `binwalk` 解包提取压缩的二进制大文件 (blob)，然后扫描提取出的目录树。退出代码：`0` 表示干净，`1` 表示发现匹配，`2` 表示发生错误。 ## 前置条件 ### 系统工具 | 工具 | 用途 | 最低要求 | |------|-----------------|---------| | **Go toolchain** | 编译程序（使用 CGO） | 1.24+（基于 1.26 开发） | | **YARA-X C API** (`libyara_x_capi`) | 扫描/验证引擎；由 CGO 进行链接 | 1.19+ | | **C 编译器** (clang/gcc) | CGO 需要它来链接 YARA-X 库 | 任意近期版本 | | **pkg-config** | 告知 Go 构建系统 YARA-X 库的位置 | 任意版本 | | **git** | `icsyara update` 使用它克隆规则源仓库 | 任意版本 | | **binwalk** | 固件提取——仅用于 `scan --firmware` | 2.x 或 3.x | ### 安装前置依赖 **macOS (Homebrew):** ``` brew install go yara-x binwalk pkg-config # yara-x 自动附带 libyara_x_capi + header + pkg-config 文件 ``` **Linux (Debian/Ubuntu):** ``` sudo apt-get update && sudo apt-get install -y golang git pkg-config binwalk build-essential # YARA-X capi 未被打包；使用 cargo 构建一次（需要 Rust toolchain）： curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # if you don't have cargo cargo install --git https://github.com/VirusTotal/yara-x yara-x-capi --root /usr/local ``` ### Go 模块依赖（由 `go build` 自动获取） | 模块 | 用途 | |--------|---------| | `github.com/VirusTotal/yara-x/go` | 官方 YARA-X Go 绑定（编译 + 扫描） | | `gopkg.in/yaml.v3` | 解析 `sources.yml` | | `github.com/stretchr/testify`, `google.golang.org/protobuf` | 间接依赖（用于测试 / 绑定） | 其他所有内容均来自 Go 标准库。确切的锁定版本记录在 `go.mod` / `go.sum` 中。 ## 构建与运行 `Makefile` 会自动为 Homebrew 安装的 YARA-X 设置 `PKG_CONFIG_PATH`/`DYLD_LIBRARY_PATH`： ``` make build # -> ./icsyara make update # fetch + validate + index all sources (~45s, ~18k rules) ./icsyara list --sources ./icsyara scan /path/to/ews/mount --json findings.json ./icsyara scan --firmware device_firmware.bin ``` 如果不使用 `make` 构建，请自行导出这些路径： ``` export PKG_CONFIG_PATH="$(brew --prefix)/lib/pkgconfig:$PKG_CONFIG_PATH" export DYLD_LIBRARY_PATH="$(brew --prefix)/lib:$DYLD_LIBRARY_PATH" go build -o icsyara ./cmd/icsyara ``` ## 规则来源与误报 一次常规的 `icsyara update` 会生成约 18,400 条经过验证的唯一规则。它们的来源如下： ``` pie showData title Rules by source (unique, after validation + dedup) "Yara-Rules project" : 11323 "signature-base" : 3203 "Elastic protections" : 2407 "ReversingLabs" : 1240 "Mandiant" : 171 "bartblaze / citizenlab / others" : 700 "ICS (ESET, Nozomi, MDudek)" : 158 ``` 源列表位于 `sources.yml` 中（包括 signature-base、Yara-Rules、Elastic protections-artifacts、ReversingLabs、Mandiant、ESET、Nozomi 等）。最大化的公共规则集非常庞大，且部分上游规则具有干扰性；Yara-Rules 的 `utils/`、`email/`、`crypto/`、`capabilities/` 和 `antidebug_antivtm/` 类别（纯指示器/构建块规则，会匹配任何文本或合法软件）已被刻意排除。你可以通过编辑 `sources.yml` 并重新运行 `icsyara update` 来添加或禁用源。 `rules/` 和 `cache/` 由 `update` 重新生成，并已加入 gitignore——该仓库不存储任何规则主体，仅存储源目录。每条规则的上游许可证均记录在 `index.json` 中。 ## 适用范围说明 YARA 扫描的是**静态字节 (bytes at rest)**——即 EWS 上的文件或固件转储中的文件。 它无法读取运行中 PLC 的实时故障/诊断状态；那属于协议层面的任务（S7/Modbus/CIP），由配套的 `ot-nmap-blue-team` 工具包处理，而不是此工具。 ## 许可证 扫描器自身的源代码基于 **GNU Affero General Public License v3.0** (AGPL-3.0) 授权。详见 [`LICENSE`](LICENSE)。简而言之：它是自由软件——你可以使用、学习、修改和重新分发它，但任何已分发或通过网络提供的修改版本，也必须在相同的许可证下公开其源代码。 **聚合的 YARA 规则不受此许可证的约束。** 它们是在运行时从第三方仓库获取的，每条规则均保留其各自的上游许可证（按规则记录在 `rules/index.json` 中；仓库级别的许可证设置在 `sources.yml` 中）。本项目不会重新分发任何规则主体——`rules/` 和 `cache/` 均为本地生成且被 gitignore 忽略。 如果你重新分发生成的规则集，你必须遵守每条上游规则的许可证（GPL-2.0、BSD、MIT、Elastic-2.0、Detection-Rule-License 等）。请参阅 [`NOTICE`](NOTICE) 获取源/许可证归属列表。 ``` icsyara — public YARA rule aggregator and EWS/firmware scanner Copyright (C) 2026 Arthur Lin This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed WITHOUT ANY WARRANTY; see the GNU AGPL for details . ```

标签：EVTX分析, Go, PKINIT, Ruby工具, YARA, 云资产可视化, 威胁情报, 工控安全, 开发者工具, 恶意软件扫描, 日志审计, 网络信息收集