offseq/threat-finderScanner de vulnerabilidades em tempo de execução: encontra CVEs nos serviços realmente em execução em um host e os classifica por exposição de rede.
# 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)
O **threat-finder** localiza o software vulnerável _realmente em execução_ em um host — não
o que um manifesto afirma — e informa quais achados são **alcançáveis pela rede**.
Ele resolve cada serviço em execução (e, com `--scope all`, cada pacote de SO
instalado) para um [Package-URL](https://github.com/package-url/purl-spec) exato e o
compara com o catálogo [OffSeq Radar](https://radar.offseq.com) usando
regras de versão nativas do ecossistema, para que builds com backport/corrigidas não sejam sinalizadas falsamente.
```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.
```
## Instalação
```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
```
Arquivos pré-compilados para Linux/macOS (x86_64 + arm64) e Windows (x86_64) estão na
[página de releases](https://github.com/offseq/threat-finder/releases/latest).
Requer Rust ≥ 1.87 para compilar a partir do código-fonte. Linux, macOS, os BSDs e Windows
são todos suportados.
## Início rápido
```sh
export OFFSEQ_API_KEY=... # from https://radar.offseq.com/console
threat-finder
```
Escaneia os serviços em execução, exibe um resumo classificado por risco e grava o relatório
JSON completo em `/tmp/threats.json`. Adicione `--scope all` para também escanear todos os
pacotes de SO instalados.
## Uso
```sh
threat-finder [OPTIONS]
```
| Flag | Descrição |
|------|-----------|
| `-o, --output <PATH>` | Grava o relatório JSON em `PATH` (padrão: solicitação interativa, ou `/tmp/threats.json`) |
| `--json` | Exibe o relatório JSON na saída padrão em vez de um arquivo |
| `--scope <SCOPE>` | `running` (padrão) ou `all` (+ todos os pacotes de SO instalados) |
| `--severity <LEVEL>` | Relata apenas achados em/não abaixo de `critical\|high\|medium\|low` |
| `--strict` | Descarta achados sem confirmação de coordenada (relata apenas confirmados) |
| `--fail-on <WHAT>` | Sai com código `5` se houver achados correspondentes: `any\|critical\|high\|medium\|low\|kev\|exposed` |
| `--sarif <PATH>` | Também grava um relatório SARIF 2.1.0 (para UIs de code-scanning) |
| `--include <GLOB>` / `--exclude <GLOB>` | Filtra ativos por glob de nome (repetível) |
| `-q, --quiet` | Suprime o banner, o progresso e o resumo |
| `--no-color` | Desativa cores ANSI |
| `-y, --yes` | Assume padrões, nunca solicita (CI/cron) |
| `--reset` | Reinsere a chave de API, ignorando a salva |
| `--register` | Registra o host escaneado no Radar para monitoramento contínuo (sem prompt) |
| `--no-register` | Não registra nem solicita monitoramento nesta execução |
| `--host-name <NAME>` | Nome amigável de host a enviar com um registro |
| `--unregister` | Remove o inventário deste host do Radar e sai |
| `--windows-missing-updates` | (Windows) Lista também atualizações de segurança pendentes do Windows Update Agent (scan online; executar elevado) |
| `-h, --help` / `-V, --version` | Ajuda / versão |
```sh
# CI: apenas achados de severidade high+, JSON na saída padrão, sem prompts
OFFSEQ_API_KEY=… threat-finder --yes --json --severity high > report.json
# Falha o build apenas quando um serviço exposto à rede tem uma CVE conhecida como explorada
OFFSEQ_API_KEY=… threat-finder --yes --quiet --fail-on exposed
```
**Códigos de saída:** `0` ok · `1` erro de consulta/IO · `2` sem chave de API · `3` SO
não suportado · `4` limite de taxa/cota, ou acesso à API exigido (upgrade necessário) · `5`
limiar de `--fail-on` atingido.
**Chave de API** (obtenha uma no [Radar Console](https://radar.offseq.com/console)),
resolvida nesta ordem:
1. Variável de ambiente `OFFSEQ_API_KEY` (ideal para CI/cron).
2. A chave salva em `$XDG_CONFIG_HOME/offseq-rust/config.toml` (`0600`),
a menos que `--reset` seja fornecido.
3. Um prompt interativo e oculto em um TTY — depois salvo para a próxima vez.
Sem chave disponível e sem modo interativo (`--yes` / sem TTY), sai com código `2`.
Defina `OFFSEQ_CONFIG_DIR` para sobrescrever onde a configuração fica (padrão: o diretório
de configuração por usuário do SO) — útil para contêineres/CI que precisam de um caminho determinístico.
## Como funciona
**Correspondência por coordenada exata.** Cada ativo vira um purl carregando sua _versão_
completa (epoch + revisão da distribuição) e um qualificador `?distro=`, por exemplo,
`pkg:deb/ubuntu/openssh-server@1:8.9p1-3ubuntu0.6?distro=jammy`. O inventário é
comparado em chamadas `POST /match/batch` em lote (uma requisição por bloco do tamanho do tier)
**no lado do servidor, com regras de versão nativas do ecossistema** (dpkg/rpm/apk/semver) — então
um build com backport e corrigido como `1.18.0-6+deb11u3` não é sinalizado corretamente, e
não há adivinhação de versão no cliente. Os achados são divididos pelo flag
`confirmed` da API: achados confirmados são relatados; correspondências de coordenada cuja
versão não pode ser confirmada são exibidas separadamente como **não confirmados / triagem**
(excluídos da contagem, de `byCve` e de `--fail-on`; descarte-os com `--strict`).
**Correlação de exposição à rede.** Scanners de manifesto (Trivy, Grype, osv-scanner)
leem listas de pacotes; scanners externos (Nessus, OpenVAS) precisam de um segundo host. Esta
ferramenta mapeia o processo de cada serviço em execução para os sockets em que ele está
**escutando** (`/proc/net` no Linux, `lsof` nos outros Unixes, `Get-NetTCPConnection` /
`netstat` no Windows) e classifica a alcançabilidade —
`loopback` / `private` / `public`. Um serviço vulnerável em `0.0.0.0` é um risco
muito diferente de um em `127.0.0.1`: os achados são classificados com os expostos primeiro e
`--fail-on exposed` condiciona o CI exatamente a isso. Nenhum pacote é enviado. Os achados também
carregam **KEV** da CISA e **EPSS**.
**Priorização ciente de exposição.** Cada achado recebe um `riskScore` (0–100) e uma
faixa de `decision` no estilo SSVC — **`act-now` · `soon` · `schedule` · `track`** — fundidos
a partir de severidade, EPSS, KEV e da **exposição de rede** do ativo proprietário. O resumo
inicia cada linha com um badge no estilo `[ACT-NOW 92]` e ordena por ele, de modo que o punhado
de problemas voltados ao público e conhecidos como explorados flutua para o topo de um host ruidoso. O
score usa a mesma fórmula localmente e no servidor (a visão de monitoramento do Radar
adiciona um pequeno bônus quando um achado KEV passou da data de vencimento — uma data que a CLI
não tem), e aparece em `--json` e SARIF (`properties`).
## Monitoramento contínuo
Um scan pontual é um retrato do momento. Registre um host uma vez e o Radar continua observando:
quando uma **CVE recém-publicada** afeta uma de suas coordenadas, você recebe um alerta
(email + Console), priorizado por exposição — sem necessidade de novo scan.
Após um scan interativo, a ferramenta pergunta:
```text
Add these 42 services to Radar for continuous monitoring & alerts? [Y/n/never]
```
`Y` registra este host; `n` pula esta execução; `never` lembra sua escolha (fica
salva na configuração e você não será perguntado novamente). Em um novo scan, ela também relata
**drift** (`+added / -removed / ~changed`) e quaisquer achados **novos desde seu último
scan**. Gerencie seus hosts — alterne monitoramento, veja achados, cancele registro — em
**Inventory** no [Radar Console](https://radar.offseq.com/console).
Para automação, pule o prompt: `--register` registra de forma não interativa (desligado por
padrão em CI), `--no-register` opta por não registrar, `--host-name <NAME>` rotula o host, e
`--unregister` o remove. Um id estável por host e sua preferência de prompt ficam em
`$XDG_CONFIG_HOME/offseq-rust/config.toml`. O registro nunca altera o código de saída —
um soluço no monitoramento não fará seu scan falhar. Exige um plano Basic/Pro/Enterprise
(ou Pro Console).
## Escopo e cobertura
`--scope running` (padrão) escaneia serviços ativos — o conjunto pequeno e de alto sinal
cuja exposição pode ser correlacionada. `--scope all` adicionalmente enumera **todos
os pacotes de SO instalados** (`dpkg`/`rpm`/`pacman`/`apk`/`brew`/`pkg`/`pkg_info`),
expandindo a superfície correspondida em 10–50×. Um pacote que também dá suporte a um processo
ativo e exposto mantém essa exposição (os ativos são deduplicados e mesclados por
coordenada). O kernel é coberto como seu pacote (`linux-image…`) sob
`--scope all`.
> `--scope all` pode produzir centenas–milhares de pacotes. No nível gratuito
> (15 consultas/hora), isso causará rate-limit; a ferramenta avisa quando o inventário
> excede o orçamento. (As consultas já são enviadas em lote; um cache de resultados local está no
> roadmap.)
## Suporte por SO
| SO | Descoberta | Fonte de coordenada |
|----|-----------|---------------------|
| Linux (systemd) | `ListUnits` → `/proc/<pid>/exe` | dpkg / rpm / pacman / apk |
| Linux (SysV/OpenRC) | `service --status-all` / `rc-status` | banco de dados de pacotes |
| macOS | `launchctl list` → `ps` (apenas terceiros) | Homebrew |
| FreeBSD / DragonFly | `service -e` | `pkg` |
| OpenBSD | `rcctl ls started` | `pkg_info` |
| NetBSD | status de `/etc/rc.d` | `pkg_info` |
| Solaris / illumos | `svcs` → `svcprop` | probe (`--version`) |
| Windows | `Win32_Service` → `Get-NetTCPConnection` / `netstat` | registro / winget / Appx / Chocolatey / Scoop → CPE; npm / pip / dotnet → purl; o build do SO → CPE |
Onde nenhum pacote é dono de um binário, a versão recorre a um probe `--version`
endurecido (apenas caminho absoluto, env saneado). No macOS, os serviços de sistema da Apple
(`com.apple.*`, caminhos protegidos por SIP) são ignorados — eles são cobertos pela versão
do SO, e sondar centenas deles é inútil.
No **Windows**, tudo é coletado via `powershell.exe` embutido
(sem runtime extra, sem admin para o inventário principal). Os aplicativos instalados são mapeados para
CPEs do NVD por meio de uma tabela de nomes curada (aplicativos não mapeados recorrem a uma busca
por nome em vez de um palpite errado); a edição/build do SO vira um CPE de SO com qualificadores de
recurso (por exemplo, `windows_11_23h2`); e `--windows-missing-updates` adiciona um aviso
opt-in do Windows Update Agent sobre patches de segurança pendentes.
## Saída
JSON, com chaves determinísticas (ordenadas) e sem timestamp, para que relatórios tenham diff limpo:
- **`services`** — `pkg@version` → achados confirmados (`cveId`, `severity`,
`cvssScore`, `epss`, `kev`, `riskScore`, `decision`, `confirmed`, `matchedRange`,
`matchBasis`, `fixedVersions`, `remediation`, `cwes`, `references`, `radarUrl`),
maior risco primeiro.
- **`unconfirmed`** — correspondências de coordenada cuja versão não pôde ser confirmada (triagem).
- **`assets`** — `pkg@version` → `{ exe, versionSource, exposed, reachability, listeners }`
(`versionSource` = `package-db` | `probe`; `reachability` cobre TCP **e** UDP).
- **`byCve`** — cada CVE consolidada em todos os ativos afetados ("corrija uma vez, resolva muitos").
- **`errors`** — falhas de consulta por ativo, para que uma falha nunca pareça "limpo".
- **`registration`** — presente quando a execução registrou o host: `host_id`,
`monitoring`, `drift`, `summary`, `newSinceLastCount`.
- **`meta`** — `{ tool, version, schemaVersion }` (`schemaVersion` 2).
Um relatório SARIF 2.1.0 (`--sarif`) também está disponível para UIs de code-scanning.
## O ecossistema OffSeq
| | |
|---|---|
| [**OffSeq**](https://offseq.com) | Auditorias de segurança na UE, monitoramento de ameaças, CISO-como-Serviço, conformidade com NIS2 |
| [**Radar**](https://radar.offseq.com) | Inteligência de ameaças em tempo real — o catálogo contra o qual o threat-finder faz correspondência |
| [**Radar Console**](https://radar.offseq.com/console) | Assinaturas, feeds personalizados e sua `OFFSEQ_API_KEY` |
| [**Radar API**](https://radar.offseq.com/api-docs) | Documentação REST para o endpoint `/match` usado aqui |
| [**Radar Threats**](https://radar.offseq.com/threats) | Banco de dados pesquisável de CVEs / malware / atores de ameaça |
| [**Radar Feeds**](https://radar.offseq.com/feeds) | Feeds personalizados que agregam CISA, CIRCL, ThreatFox, … |
| [**Radar Pricing**](https://radar.offseq.com/pricing) | Do nível gratuito ao Enterprise |
| [**Breach**](https://breach.offseq.com) | Monitoramento de vazamento de dados e credenciais expostas na dark web |
| [**Veil**](https://veil.offseq.com) | Esteganografia PNG no lado do cliente (AES-256-GCM) |
| [**Guard**](https://offseq.com/guard/) | Analista de segurança e conformidade de sites com IA |
| [**Training**](https://training.offseq.com) | Cursos de segurança e privacidade credenciados pela PECB |
## Desenvolvimento
```sh
cargo build --release
cargo test # unit tests
cargo test -- --ignored # + macOS live-discovery smoke test
cargo clippy --all-targets
```
O mecanismo é uma crate de biblioteca (`find_threats`) com uma abstração `Collector`
(serviços em execução e pacotes de SO hoje; lockfiles / contêineres / SBOM a seguir), de modo
que o binário é um CLI fino sobre ela.
## Licença
Dual-licenciado sob [MIT](https://github.com/offseq/threat-finder/blob/main/LICENSE) ou [Apache-2.0](https://github.com/offseq/threat-finder/blob/main/LICENSE), à sua escolha.