# OffSeq Threat Finder
[](https://github.com/offseq/threat-finder/actions/workflows/ci.yml)
[](https://crates.io/crates/threat-finder)
[](https://docs.rs/threat-finder)
[](#license)
**threat-finder** 用于发现主机上 _实际运行_ 的易受攻击软件——而非清单所声称的内容——并告知您哪些发现是 **网络可达** 的。它会将每个运行中的服务（以及使用 `--scope all` 时的每个已安装 OS 软件包）解析为精确的 [Package-URL](https://github.com/package-url/purl-spec)，并使用生态系统原生的版本规则与 [OffSeq Radar](https://radar.offseq.com) 目录进行匹配，因此已向后移植/修复的构建不会被误报。
```text
Vulnerability summary (highest risk first):
openssh-server@1:8.9p1-3ubuntu0.6 — 1 finding(s) [PUBLIC tcp 0.0.0.0:22]
[ACT-NOW 92] HIGH CVE-2024-6387 [KEV] regreSSHion: remote code execution in OpenSSH
→ fix: 1:8.9p1-3ubuntu0.10 https://radar.offseq.com/threat/…
[email protected] — 1 finding(s)
[SCHEDULE 41] MED CVE-2023-44487 HTTP/2 Rapid Reset
2 confirmed finding(s) across 2 asset(s); 1 exposed, 1 known-exploited.
```
## 安装
```sh
brew install offseq/tap/threat-finder # Homebrew (macOS/Linux), prebuilt
cargo binstall threat-finder # prebuilt binary, no toolchain
cargo install threat-finder # from source
```
适用于 Linux/macOS（x86_64 + arm64）和 Windows（x86_64）的预构建归档位于[发布页面](https://github.com/offseq/threat-finder/releases/latest)。从源码构建需要 Rust ≥ 1.87。支持 Linux、macOS、各 BSD 和 Windows。
## 快速开始
```sh
export OFFSEQ_API_KEY=... # from https://radar.offseq.com/console
threat-finder
```
扫描正在运行的服务，打印按风险排序的摘要，并将完整的 JSON 报告写入 `/tmp/threats.json`。添加 `--scope all` 还可扫描每个已安装的 OS 软件包。
## 用法
```sh
threat-finder [OPTIONS]
```
| Flag | 说明 |
|------|-------------|
| `-o, --output <PATH>` | 将 JSON 报告写入 `PATH`（默认：交互提示，或 `/tmp/threats.json`） |
| `--json` | 将 JSON 报告打印到标准输出而非文件 |
| `--scope <SCOPE>` | `running`（默认）或 `all`（外加每个已安装的 OS 软件包） |
| `--severity <LEVEL>` | 仅报告达到/超过 `critical\|high\|medium\|low` 级别的发现 |
| `--strict` | 丢弃坐标未确认的发现（仅报告已确认项） |
| `--fail-on <WHAT>` | 若存在匹配的发现则以退出码 `5` 退出：`any\|critical\|high\|medium\|low\|kev\|exposed` |
| `--sarif <PATH>` | 同时写入一份 SARIF 2.1.0 报告（用于代码扫描 UI） |
| `--include <GLOB>` / `--exclude <GLOB>` | 按名称 glob 过滤资产（可重复） |
| `-q, --quiet` | 抑制横幅、进度和摘要 |
| `--no-color` | 禁用 ANSI 颜色 |
| `-y, --yes` | 假定默认值，从不提示（CI/cron） |
| `--reset` | 重新输入 API 密钥，忽略已保存的密钥 |
| `--register` | 将扫描的主机注册到 Radar 以进行持续监控（无提示） |
| `--no-register` | 本次运行不注册监控，也不提示 |
| `--host-name <NAME>` | 注册时随附的友好主机名 |
| `--unregister` | 从 Radar 移除该主机的清单并退出 |
| `--windows-missing-updates` | （Windows）同时列出 Windows Update Agent 中的待处理安全更新（在线扫描；请以提升权限运行） |
| `-h, --help` / `-V, --version` | 帮助 / 版本 |
```sh
# CI: only high+ findings, JSON to stdout, no prompts
OFFSEQ_API_KEY=… threat-finder --yes --json --severity high > report.json
# Fail the build only when a network-exposed service has a known-exploited CVE
OFFSEQ_API_KEY=… threat-finder --yes --quiet --fail-on exposed
```
**退出码：** `0` 正常 · `1` 查询/IO 错误 · `2` 没有 API 密钥 · `3` 不支持的 OS · `4` 速率限制/配额，或需要 API 访问权限（需升级） · `5` 达到 `--fail-on` 阈值。
**API 密钥**（可从 [Radar Console](https://radar.offseq.com/console) 获取），按以下顺序解析：
1. `OFFSEQ_API_KEY` 环境变量（最适合 CI/cron）。
2. 保存在 `$XDG_CONFIG_HOME/offseq-rust/config.toml`（权限 `0600`）中的密钥，除非指定了 `--reset`。
3. 在 TTY 上进行交互式隐藏提示——随后保存以备下次使用。
非交互模式（`--yes` / 无 TTY）且无可用密钥时，以退出码 `2` 退出。
设置 `OFFSEQ_CONFIG_DIR` 可覆盖配置的存放位置（默认：操作系统每用户配置目录）——对于需要确定性路径的容器/CI 非常方便。
## 工作原理
**精确坐标匹配。** 每个资产都会成为一个携带其 _完整_ 版本（epoch + 发行版修订号）和 `?distro=` 限定符的 purl，例如 `pkg:deb/ubuntu/openssh-server@1:8.9p1-3ubuntu0.6?distro=jammy`。清单通过批量 `POST /match/batch` 调用（按套餐层级大小分块，每块一个请求）在**服务端使用生态系统原生版本规则**进行匹配（dpkg/rpm/apk/semver）——因此像 `1.18.0-6+deb11u3` 这样已向后移植并修复的构建不会被错误标记，客户端也不会进行版本猜测。发现项按 API 的 `confirmed` 标志区分：已确认的匹配会被报告；版本无法确认的坐标匹配会单独显示为 **未确认 / 待分类**（不计入总数、`byCve` 和 `--fail-on`；使用 `--strict` 可将其丢弃）。
**网络暴露关联。** 清单扫描器（Trivy、Grype、osv-scanner）读取软件包列表；外部扫描器（Nessus、OpenVAS）则需要第二台主机。本工具将每个运行中服务的进程映射到其正在 **监听** 的套接字（Linux 上为 `/proc/net`，其他 Unix 上为 `lsof`，Windows 上为 `Get-NetTCPConnection` / `netstat`），并对其可达性进行分类——`loopback` / `private` / `public`。监听在 `0.0.0.0` 上的易受攻击服务与监听在 `127.0.0.1` 上的风险截然不同：发现项按暴露优先排序，`--fail-on exposed` 正是基于这一点来门控 CI。不会发送任何数据包。发现项还携带 CISA **KEV** 和 **EPSS** 信息。
**暴露感知的优先级排序。** 每条发现都会获得一个 `riskScore`（0–100）和一个 SSVC 风格的 `decision` 区间——**`act-now` · `soon` · `schedule` · `track`**——由严重性、EPSS、KEV 以及所属资产的 **网络暴露** 融合而成。摘要中每行以 `[ACT-NOW 92]` 样式的徽标开头并按此排序，因此少量面向公众、已知被利用的问题会从嘈杂的主机中浮现到顶部。该评分在本地和服务端使用相同的公式（当 KEV 发现超过其截止日期时，Radar 监控视图会添加少量加成——这是 CLI 不掌握的日期），并出现在 `--json` 和 SARIF（`properties`）中。
## 持续监控
一次性扫描只是一个时间点。注册一次主机，Radar 就会持续监控：当 **新发布的 CVE** 影响到其某个坐标时，您会收到一条按暴露程度排序的警报（电子邮件 + Console）——无需重新扫描。
交互式扫描后，工具会询问：
```text
Add these 42 services to Radar for continuous monitoring & alerts? [Y/n/never]
```
`Y` 注册该主机；`n` 跳过本次运行；`never` 记住您的选择（会保存到配置中，之后不再询问）。重新扫描时，它还会报告 **漂移**（`+added / -removed / ~changed`）以及自您上次扫描以来 **新增** 的发现。您可以在 [Radar Console](https://radar.offseq.com/console) 的 **Inventory** 下管理您的主机——切换监控、查看发现、注销。
自动化场景下可跳过提示：`--register` 以非交互方式注册（CI 中默认关闭），`--no-register` 选择退出，`--host-name <NAME>` 为主机打标签，`--unregister` 将其移除。稳定的每主机 id 和您的提示偏好保存在 `$XDG_CONFIG_HOME/offseq-rust/config.toml` 中。注册绝不会改变退出码——监控方面的小故障不会导致您的扫描失败。需要 Basic/Pro/Enterprise 套餐（或 Pro Console）。
## 范围与覆盖
`--scope running`（默认）扫描活动服务——这是一个规模小、信号强的集合，其暴露情况可被关联。`--scope all` 还会枚举 **每个已安装的 OS 软件包**（`dpkg`/`rpm`/`pacman`/`apk`/`brew`/`pkg`/`pkg_info`），将匹配面扩大 10–50 倍。若某个软件包同时支撑着运行中且已暴露的进程，则保留该暴露信息（资产按坐标去重并合并）。在 `--scope all` 下，内核作为其软件包（`linux-image…`）被纳入覆盖。
> `--scope all` 可能产生数百到数千个软件包。在免费套餐（每小时 15 次查询）下，这会触发速率限制；当清单超出预算时，工具会发出警告。（查询已进行批量处理；本地结果缓存已列入路线图。）
## 各操作系统支持
| 操作系统 | 发现方式 | 坐标来源 |
|----|-----------|-------------------|
| Linux (systemd) | `ListUnits` → `/proc/<pid>/exe` | dpkg / rpm / pacman / apk |
| Linux (SysV/OpenRC) | `service --status-all` / `rc-status` | 软件包数据库 |
| macOS | `launchctl list` → `ps`（仅第三方） | Homebrew |
| FreeBSD / DragonFly | `service -e` | `pkg` |
| OpenBSD | `rcctl ls started` | `pkg_info` |
| NetBSD | `/etc/rc.d` 状态 | `pkg_info` |
| Solaris / illumos | `svcs` → `svcprop` | 探测（`--version`） |
| Windows | `Win32_Service` → `Get-NetTCPConnection` / `netstat` | registry / winget / Appx / Chocolatey / Scoop → CPE; npm / pip / dotnet → purl; the OS build → CPE |
当某个二进制文件不属于任何软件包时，版本会回退到经过加固的 `--version` 探测（仅限绝对路径，环境变量已清理）。在 macOS 上，Apple 系统服务（`com.apple.*`、受 SIP 保护的路径）会被跳过——它们由 OS 版本覆盖，探测数百个这样的服务毫无意义。
在 **Windows** 上，所有内容均通过内置的 `powershell.exe` 收集（无需额外运行时，核心清单不需要管理员权限）。已安装应用通过一份精选名称表映射到 NVD CPE（未映射的应用回退到名称搜索，而非错误猜测）；操作系统版本/内部版本会转换为带功能限定的 OS CPE（例如 `windows_11_23h2`）；`--windows-missing-updates` 还会增加一份可选的 Windows Update Agent 待处理安全补丁通告。
## 输出
JSON 格式，使用确定性（排序）键且不含时间戳，因此报告可以干净地进行 diff：
- **`services`** — `pkg@version` → 已确认的发现（`cveId`、`severity`、`cvssScore`、`epss`、`kev`、`riskScore`、`decision`、`confirmed`、`matchedRange`、`matchBasis`、`fixedVersions`、`remediation`、`cwes`、`references`、`radarUrl`），高风险优先。
- **`unconfirmed`** — 版本无法确认的坐标匹配（待分类）。
- **`assets`** — `pkg@version` → `{ exe, versionSource, exposed, reachability, listeners }`（`versionSource` = `package-db` | `probe`；`reachability` 涵盖 TCP **和** UDP）。
- **`byCve`** — 每个 CVE 在所有受影响资产上的汇总（“一次修补，多处修复”）。
- **`errors`** — 各资产的查询失败信息，因此失败绝不会被误读为“干净”。
- **`registration`** — 当本次运行注册了主机时出现：`host_id`、`monitoring`、`drift`、`summary`、`newSinceLastCount`。
- **`meta`** — `{ tool, version, schemaVersion }`（`schemaVersion` 2）。
还提供 SARIF 2.1.0 报告（`--sarif`），供代码扫描 UI 使用。
## OffSeq 生态系统
| | |
|---|---|
| [**OffSeq**](https://offseq.com) | 欧盟安全审计、威胁监控、CISO 即服务、NIS2 合规 |
| [**Radar**](https://radar.offseq.com) | 实时威胁情报——threat-finder 所匹配的目录 |
| [**Radar Console**](https://radar.offseq.com/console) | 订阅、自定义订阅源以及您的 `OFFSEQ_API_KEY` |
| [**Radar API**](https://radar.offseq.com/api-docs) | 此处所用 `/match` 端点的 REST 文档 |
| [**Radar Threats**](https://radar.offseq.com/threats) | 可搜索的 CVE / 恶意软件 / 威胁行为者数据库 |
| [**Radar Feeds**](https://radar.offseq.com/feeds) | 聚合 CISA、CIRCL、ThreatFox 等的自定义订阅源 |
| [**Radar Pricing**](https://radar.offseq.com/pricing) | 从免费套餐到企业版 |
| [**Breach**](https://breach.offseq.com) | 暗网数据泄露与已暴露凭据监控 |
| [**Veil**](https://veil.offseq.com) | 客户端 PNG 隐写术（AES-256-GCM） |
| [**Guard**](https://offseq.com/guard/) | AI 网站安全与合规分析师 |
| [**Training**](https://training.offseq.com) | PECB 认证的安全与隐私课程 |
## 开发
```sh
cargo build --release
cargo test # unit tests
cargo test -- --ignored # + macOS live-discovery smoke test
cargo clippy --all-targets
```
引擎是一个库 crate（`find_threats`），带有 `Collector` 抽象（目前支持运行中服务和 OS 软件包；接下来是锁文件 / 容器 / SBOM），因此该二进制文件只是其上的一个轻量 CLI 层。
## 许可证
采用 [MIT](https://github.com/offseq/threat-finder/blob/main/LICENSE) 或 [Apache-2.0](https://github.com/offseq/threat-finder/blob/main/LICENSE) 双许可，任您选择。
