OffSeq Threat Finder

threat-finder 用于发现主机上 实际运行 的易受攻击软件——而非清单所声称的内容——并告知您哪些发现是 网络可达 的。它会将每个运行中的服务（以及使用 --scope all 时的每个已安装 OS 软件包）解析为精确的 Package-URL，并使用生态系统原生的版本规则与 OffSeq Radar 目录进行匹配，因此已向后移植/修复的构建不会被误报。

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.

安装

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）的预构建归档位于发布页面。从源码构建需要 Rust ≥ 1.87。支持 Linux、macOS、各 BSD 和 Windows。

快速开始

export OFFSEQ_API_KEY=...    # from https://radar.offseq.com/console
threat-finder

扫描正在运行的服务，打印按风险排序的摘要，并将完整的 JSON 报告写入 /tmp/threats.json。添加 --scope all 还可扫描每个已安装的 OS 软件包。

用法

threat-finder [OPTIONS]

# 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 获取），按以下顺序解析：

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）——无需重新扫描。

交互式扫描后，工具会询问：

Add these 42 services to Radar for continuous monitoring & alerts? [Y/n/never]

Y 注册该主机；n 跳过本次运行；never 记住您的选择（会保存到配置中，之后不再询问）。重新扫描时，它还会报告 漂移（+added / -removed / ~changed）以及自您上次扫描以来 新增 的发现。您可以在 Radar 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 次查询）下，这会触发速率限制；当清单超出预算时，工具会发出警告。（查询已进行批量处理；本地结果缓存已列入路线图。）

各操作系统支持

当某个二进制文件不属于任何软件包时，版本会回退到经过加固的 --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 生态系统

开发

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 或 Apache-2.0 双许可，任您选择。