cumakurt/saru

# Saru (猿) [](https://github.com/cumakurt/saru/actions/workflows/ci.yml) [](./LICENSE) [](./Cargo.toml) **单一二进制、本地优先的 Linux 安全情报：** 收集主机上下文（`/proc`、`/etc`、packages、SSH、cron、containers 等），**日志尾部**（auth、syslog/messages、journal、audit），**运行中的进程**，**cron**，**bash 历史记录样本**，以及可选的 **WASM** 插件；运行 **75+** 条内置启发式规则及可选的 **TOML** 规则（包括通过 CLI 导入的 **[SigmaHQ](https://github.com/SigmaHQ/sigma) Linux 规则**）；可选择存储 **SQLite** 快照以监控差异和趋势；导出 **终端**、**JSON**、**SARIF**、**STIX** 或 **CSV** 格式 —— 此外还有交互式的 **HTML** 报告。 | | | |---|---| | **代码库** | [github.com/cumakurt/saru](https://github.com/cumakurt/saru) | | **开发者** | **Cuma KURT** — **LinkedIn:** [linkedin.com/in/cuma-kurt-34414917](https://www.linkedin.com/in/cuma-kurt-34414917/) | | **用户指南 (mdBook)** | [`docs/book/`](./docs/book/) — 在 `docs/book` 中运行 `mdbook build` | | **许可证** | [AGPL-3.0](./LICENSE) | **质量标准。** CI 运行 `cargo fmt`、`clippy -D warnings`、`cargo test` 以及 **`cargo deny`**；发布构建目标为 **x86_64** 和 **aarch64** 架构上的 musl（二进制文件大小上限 **15 MiB**）。目录测试强制要求最低内置规则数量（**≥20**、**≥40**、**≥75**）。 ## Saru 的功能 | 领域 | 您将获得的内容 | |------|----------------| | **评估** | 完整的主机信息收集、规则引擎、适用的 CVSS、**CIA 风格风险评分**、嵌入扫描输出中的启发式**攻击路径**摘要。 | | **持久化** | SQLite 中的可选快照（默认为 `state.db`）：列出、导出、删除、清理，对比两次扫描的**差异**，风险趋势的**时间线**。 | | **威胁情报** | **攻击**路径（图启发式），**模拟**假设性修复方案，**解释**单条规则，**MITRE** 覆盖范围和 Navigator 层导出，**合规性**（源自 CIS 的配置文件）。 | | **制品** | **HTML 报告**（全新扫描；文件名会添加 `_.html`），**取证** JSON，可选的 IOC JSON，可选的 **tar** 打包文件包含清单及可选的 **GPG** 分离签名。 | | **实时操作** | **监控**路径（`inotify`），轮询进程/监听器，auth 日志尾部；可选的 TUI 和 **webhook/syslog/PagerDuty** 警报。带有可选逃逸风险启发式算法的 **容器** 列表。 | | **自动化** | **守护进程** 循环：定期扫描 + 快照 + 保留策略。**CI**：`scan --exit-code --fail-on`。 | **Crates（供贡献者参考）：** `saru-core`（类型、CVSS、配置、评分），`saru-collector`，`saru-state`（SQLite），`saru-intel`（规则、差异、攻击图、合规性、MITRE 等），`saru-cli`。 ## 目录 1. [安装](#install) 2. [初始命令](#first-commands) 3. [命令参考](#command-reference) - [scan](#scan) · [fingerprint](#fingerprint) · [snapshot](#snapshot) · [diff](#diff) · [timeline](#timeline) · [daemon](#daemon) - [attack](#attack) · [simulate](#simulate) · [explain](#explain) · [compliance](#compliance) · [mitre](#mitre) - [report](#report) · [forensic](#forensic) · [rules](#rules) - [watch](#watch) · [container](#container) · [completion & update](#completion--update) 4. [全局选项与配置](#global-options--configuration) 5. [收集数据亮点](#collected-data-highlights) 6. [Sigma 规则 (导入)](#sigma-rules-import) 7. [构建与开发](#building--development) 8. [在 GitHub 上发布](#publishing-on-github) 示例假设 `saru` 已在您的 **`PATH`** 中。如果是开发构建，请使用 `./target/release/saru`。 ## 安装 **网络安装程序**（克隆仓库并使用 Cargo 构建 — 需要安装 [Rust](https://rustup.rs/)）： ``` curl -fsSL https://raw.githubusercontent.com/cumakurt/saru/main/install.sh | sh ``` - **root 用户：** 默认安装在 **`/usr/local/bin`** - **非 root 用户：** 安装在 **`~/.local/bin`** — 如有需要，请添加 `export PATH="$HOME/.local/bin:$PATH"` **通过克隆安装：** ``` sh install.sh PREFIX=/usr/local/bin sh install.sh sh install.sh --tag v0.1.0 sh install.sh --release v0.1.0 ``` ## 初始命令 ``` saru scan saru fingerprint saru scan --output json | head ``` ## 命令参考 ### 扫描 完整收集 + 规则 + 风险评分 + 攻击路径摘要 + JSON 格式或嵌入式快照中的可选合规性配置。 默认包含内置的高级规则集。 ``` saru scan saru scan --min-severity high saru scan --quiet saru scan --show-fixes saru scan --cloud-probe saru scan --no-cloud-probe saru scan --tags ssh --tags network saru scan --exclude SARU-SSH-001 --exclude 'SARU-NET*' saru scan --plugin-dir /path/to/wasm/plugins ``` **机器可读输出** ``` saru scan --output json saru scan --output csv > findings.csv saru scan --output sarif > results.sarif saru scan --output stix > bundle.stix.json ``` **输出中的快照与合规性** ``` saru scan --save-snapshot saru scan --save-snapshot --retain 100 saru scan --compliance-benchmark cis-ubuntu-24 saru scan --no-compliance ``` **修复脚本（运行前请检查）** ``` saru scan --fix-script /tmp/remediate.sh saru scan --fix-script /tmp/run.sh --fix-script-run --yes-understand-risk ``` **CI 退出码** ``` saru scan --exit-code --fail-on high ``` ### 指纹 轻量级主机摘要（计数、polkit 预览、攻击图入口点等）。 ``` saru fingerprint saru fingerprint --output json saru fingerprint --output csv ``` ### 快照 存储的扫描结果保存在 SQLite 中（除非使用 `--db` 或配置文件，否则默认为 `~/.saru/state.db`）。 ``` saru snapshot list saru snapshot list --limit 50 saru snapshot list --since-days 14 --output json saru snapshot list --output csv saru snapshot export -f /tmp/backup.json saru snapshot delete saru snapshot prune 100 ``` **配合 `scan` 使用** ``` saru scan --save-snapshot --retain 50 ``` 请参阅 [Daemon](#daemon) 以获取定期快照。 ### 对比 比较两个已存储的快照，或时间窗口内最早与最新的快照。 ``` saru diff --from --to saru diff --between saru diff --since-hours 24 saru diff --output json saru diff --output csv ``` ### 时间线 基于近期快照的 ASCII 风险趋势图（以及可选的合规性趋势）。 ``` saru timeline saru timeline --limit 20 saru timeline --since-days 30 --limit 20 saru timeline --since-hours 6 --limit 24 saru timeline --output json saru timeline --output csv ``` ### daemon 定期扫描 + 快照循环（在前台运行；按 **Ctrl+C** 停止）。 ``` saru daemon --interval-secs 3600 saru daemon --interval-secs 3600 --retain 100 ``` 示例单元：[`contrib/saru-daemon.service`](./contrib/saru-daemon.service)。 ### 攻击 启发式攻击路径摘要（监听器 → 权限 → `ROOT`），按成本排序；可选的 MITRE 和 Graphviz。 ``` saru attack saru attack --mitre saru attack --focus ssh,sudo,polkit,journal saru attack --max-paths 12 saru attack --output json saru attack --output csv > attack-paths.csv saru attack --export graphviz | dot -Tpng -o attack.png ``` 支持的输出格式：**终端 (terminal)**、**json**、**csv**（不支持 SARIF/STIX）。 ### 模拟 假设移除某些修复类别后的假设性风险评估。 ``` saru simulate --fix ssh,sudo,polkit,filesystem saru simulate --compare ``` ### 解释 重新运行扫描，并打印针对某条规则 ID 的 WHY/HOW/FIX 原因说明。 ``` saru explain SARU-SSH-001 saru explain SARU-POLKIT-001 ``` ### 合规 基于 CIS 的主机检查（子集；配置文件取决于操作系统）。 ``` saru compliance saru compliance --benchmark host saru compliance --benchmark cis-lite saru compliance --benchmark cis-ubuntu-24 saru compliance --benchmark cis-debian-12 saru compliance --benchmark cis-rhel-9 saru compliance --dry-run-fixes saru compliance --fix-script /tmp/cis-fix.sh saru compliance --output csv ``` ### mitre 当前扫描的覆盖范围和技术细节；内置 Linux 矩阵；ATT&CK Navigator 层导出。 ``` saru mitre saru mitre --coverage saru mitre --matrix saru mitre --tactic privilege --technique T1548 saru mitre --export-layer /tmp/navigator-layer.json saru mitre --export-layer /tmp/layer.json --layer-name "Production host" ``` ### 报告 运行一次**全新扫描**并生成单个**交互式 HTML** 报告。 写入的文件路径带有**时间戳**：`_YYYYMMDD_HHMMSS.html`（与 `-f` 所在目录相同）。 使用 `--no-timestamp` 可保留确切的文件名。 使用 `--open` 可在默认浏览器/查看器中打开生成的报告。 ``` saru report -f /tmp/report.html --benchmark host # 例如写入 /tmp/report_20260414_153045.html saru report -f /tmp/audit.html --no-compliance # 例如写入 /tmp/audit_20260414_153102.html saru report -f /tmp/fixed-name.html --no-timestamp # 确切写入 /tmp/fixed-name.html saru report -f /tmp/ops.html --open # 写入带有时间戳的 HTML 并自动打开 saru report -f /tmp/report.html --output json # 打印机器可读的元数据（path、scan_id、risk_overall 等） ``` ### 取证 易失性 + 收集到的主机 JSON，可选的 IOC 包，可选的签名 tar 归档文件。 ``` saru forensic -f /tmp/forensic.json saru forensic -f /tmp/full.json --with-findings saru forensic -f /tmp/host.json -i /tmp/ioc.json saru forensic --archive /tmp/bundle.tar -f /tmp/forensic.json saru forensic --archive /tmp/bundle.tar -f /tmp/host.json -i /tmp/ioc.json --gpg-sign ``` ### 规则 内置目录，可选的 TOML 集合，以及 **Sigma Linux 导入**（请参阅 [Sigma 规则 (导入)](#sigma-rules-import)）。 ``` saru rule list saru rule list --tags ssh saru rule list --output json saru rule list --output csv # 从目录合并额外的 TOML bundles（或使用 config `rules_path` —— 相同的合并行为） saru rule list --extra-rules ~/.saru/rules saru rule test /path/to/custom-rules.toml saru rule validate /path/to/custom-rules.toml # 将内置元数据导出为 Sigma 风格的 YAML *stubs*（用于 SIEM 文档 —— 而非检测） saru rule export sigma -f /tmp/saru-sigma.yml saru rule export sigma ``` **将 [SigmaHQ/sigma](https://github.com/SigmaHQ/sigma) 的 `rules/linux/` 导入为 Saru TOML**（首先克隆 Sigma 仓库）： ``` git clone --depth 1 https://github.com/SigmaHQ/sigma.git saru rule import-sigma ./sigma -f ~/.saru/rules/sigma_linux.toml saru rule validate ~/.saru/rules/sigma_linux.toml ``` 配合扫描使用：将 `*.toml` 放在一个目录下，然后传入 **`--rules-path`** 或在配置中设置 **`rules_path`**。 自定义规则在 TOML 中使用 `[[rule]]`；匹配类型包括以下内置类型，以及用于导入 Sigma 规则的 **`sigma_line_match`** 和 **`sigma_keyword_lines`**。 ### watch 实时文件系统（`inotify`）、进程/监听器轮询、auth 日志尾部；可选的 **ratatui** TUI；警报（**webhook**、**syslog**、**PagerDuty**）。 ``` saru watch saru watch /etc/hosts saru watch --tui saru watch --interval 3 --threshold high saru watch --alert 'webhook:https://hooks.example.com/notify' saru watch --alert 'syslog:saru-watch' --alert 'pagerduty:' ``` 请使用 **`--alert webhook:URL`**，而不是单独使用 `--webhook` 标志。 ### container 在可用时列出 Docker/Podman 容器；基于 inspect 的可选逃逸风险启发式评估。 ``` saru container saru container --escape saru container --escape --output json ``` ### 补全与更新 ``` saru completion bash > ~/.local/share/bash-completion/completions/saru saru completion zsh > ~/.zfunc/_saru saru completion fish > ~/.config/fish/completions/saru.fish saru update ``` ## 全局选项与配置 | 选项 | 作用 | |--------|------| | `--output terminal\|json\|sarif\|csv\|stix` | 默认输出格式（并非每个命令都支持所有格式）。 | | `--no-color` | 禁用 ANSI 颜色。 | | `--db ` | SQLite 快照数据库路径（**覆盖**配置中的 `db_path`）。 | | `--config ` | TOML 配置文件（默认值与 **`SARU_*`** 环境变量合并）。 | | `--exclude ` | 跳过规则（可重复使用；`*` 后缀用于匹配前缀）。 | | `--tags ` | 仅运行这些目录类别中的规则（可重复使用）。 | | `--cloud-probe` / `--no-cloud-probe` | 云元数据探测（覆盖配置中的 `cloud_probe`）。 | | `--rules-path ` | 额外的 `*.toml` 规则（**覆盖**配置中的 `rules_path`）。 | **保留策略** | 机制 | 行为 | |-----------|----------| | 配置中的 `retain_snapshots` | 在 `scan --save-snapshot` 或每个 `daemon` 循环之后，保留最新的 **N** 条记录。 | | `SARU_RETAIN_SNAPSHOTS` | 与 `retain_snapshots` 作用相同。 | | `scan --save-snapshot --retain N` | 设置后**覆盖**配置。 | | `daemon --retain N` | 设置后**覆盖**配置。 | | `snapshot prune N` | 一次性清理。 | **`~/.saru/config.toml` 示例** ``` db_path = "/home/you/.saru/state.db" rules_path = "/home/you/.saru/rules" min_severity = "medium" fail_on = "critical" cloud_probe = false retain_snapshots = 100 ``` **自定义规则匹配类型**（请参阅 `crates/saru-intel/src/toml_rules.rs`）：`listening_port`、`ssh_setting`、`proc_sys`、`file_exists`、`package_installed`、`user_in_group`、`user_shadow_auth_hint`、`polkit_hit`、`kernel_module_loaded`、`world_writable_etc_count`（+ **`min_count`**）、**`sigma_line_match`**（在指定的文本集合上应用 Sigma 的 AND-of-OR 组合逻辑）、**`sigma_keyword_lines`**（带有可选类 glob 语法的 `*` / `?` 关键字列表）等。 **开发者：** [`deny.toml`](./deny.toml) — `cargo deny check licenses bans sources`。 ## 收集数据亮点 高信号收集器会为 **scan**、**diff**、**fingerprint**、**IOC**、**forensic**、**HTML 报告** 和 **STIX** 备注提供数据。 | 主题 | 应用场景 | |--------|------------------| | **Polkit**（`/etc/polkit-1/rules.d`，`Result.YES`） | 规则、差异、模拟 `--fix polkit`、监控、报告、STIX。 | | **Sudo NOPASSWD** | 通过 `sudo_nopasswd_lines` 实现相同的模式。 | | **内核模块**（`/proc/modules`） | 差异、、IOC、TOML `kernel_module_loaded`。 | | **全局可写的 `/etc`** | 规则 `SARU-FS-002`；模拟 `--fix filesystem`。 | | **Auth 日志**（`/var/log/auth.log` 或 `/var/log/secure`） | 差异、IOC、内置日志规则、Sigma 关键字 / 行匹配。 | | **Syslog / messages**（`/var/log/syslog` 或 `/var/log/messages`） | 同上；在非 journald 设置下作为 journal 的补充。 | | **Journal**（`journalctl` 短日志尾部） | 差异、IOC、HTML“文件系统与日志”。 | | **Audit 日志**（可读时读取 `/var/log/audit/audit.log`） | 源自 auditd 的 Sigma 规则（在原始行上进行子字符串 / 模式匹配）。 | | **Bash 历史记录**（从用户 `~/.bash_history` 中采样） | Sigma“可疑命令”风格的关键字规则。 | | **关键文件的 SHA-256 和 MACB** | 摘要差异、forensic/HTML/IOC。 | | **MITRE** | 内置数据；`saru mitre --technique Txxxx`。 | 攻击路径详情：[`docs/book/src/attack-paths.md`](./docs/book/src/attack-paths.md)。 ## Sigma 规则 (导入) Saru **不是** SIEM：它针对**本地收集的**字符串（进程命令行、日志尾部、cron 行、历史记录样本）评估模式。CLI 可以将官方 Sigma 仓库的 **`rules/linux/`** 目录树**转换**为一个包含 `[[rule]]` 条目的**单一 Saru TOML 集合**。 | 步骤 | 命令 | |------|---------| | 克隆 Sigma | `git clone https://github.com/SigmaHQ/sigma.git` | | 导入 | `saru rule import-sigma /path/to/sigma -f ~/.saru/rules/sigma_linux.toml` | | 验证 | `saru rule validate ~/.saru/rules/sigma_linux.toml` | | 扫描 | `saru scan --rules-path ~/.saru/rules` | **范围。** 仅导入 **`rules/linux/`**（专注于 Linux 的 YAML）。Sigma 仓库中的 Windows / macOS / 网络设备规则不在此工具的处理范围内。 **语义。** 转换支持常见的 Sigma 结构：`condition: selection`、`condition: all of selection_*` 以及 `condition: keywords`。使用否定、`1 of` 或复杂括号的规则将被**跳过**；该命令会打印已写入与已跳过规则的数量统计。导入的规则属于**尽力而为**的匹配，可能与完整的 Sigma 引擎有所差异 —— 请在您的环境中进行验证（`saru rule test`）。 ## 构建与开发 ``` git clone https://github.com/cumakurt/saru.git && cd saru cargo build --release -p saru-cli ./target/release/saru scan ``` | 主题 | 位置 / 命令 | |--------|-------------------| | **CI** | [`.github/workflows/ci.yml`](./.github/workflows/ci.yml) | | **基准测试**（可选） | `cargo bench -p saru-core`，`cargo bench -p saru-intel` | | **属性测试** | `saru-core` 中的 `proptest` | | **冒烟测试** | `./scripts/selftest.sh` | | **静态 musl** | `rustup target add x86_64-unknown-linux-musl` + `musl-tools`；请参阅 [`.cargo/config.toml`](./.cargo/config.toml)；`SARU_MUSL=1 sh install.sh` | | **文档** | 在 [`docs/book/`](./docs/book/) 中运行 `mdbook build` | ## 在 GitHub 上发布 本节适用于负责打标签发布版本并保持默认分支通过测试（green）的**维护者**。 | 检查项 | 备注 | |-------|--------| | **默认分支** | `main`（CI 也接受 `master`）。 | | **发布前** | `cargo fmt --all`，`cargo clippy --workspace --all-targets -- -D warnings`，`cargo test --workspace`，`cargo deny check`（请参阅 [`deny.toml`](./deny.toml)）。 | | **版本号** | 在根目录的 [`Cargo.toml`](./Cargo.toml) 中更新 `[workspace.package] version`；打上 **`v0.x.y`** 标签以保持一致。 | | **二进制文件** | 使用仓库中的 [`install.sh`](./install.sh)，或在适用时附上由 CI 生成的 musl 产物。 | | **许可证** | [AGPL-3.0](./LICENSE) — 在仓库根目录保留完整文本。 | ## 许可证 [AGPL-3.0](./LICENSE)。

标签：Rust, 入侵检测, 威胁情报, 安全审计, 开发者工具, 日志分析, 网络流量审计, 通知系统