big-comfy/deadairEncontra as regras de deteção no seu SIEM que estão a funcionar às cegas.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
<img alt="deadair - SIEM detection coverage health" src="https://raw.githubusercontent.com/big-comfy/deadair/HEAD/docs/assets/banner-light.svg" width="760">
</picture>
</p>
<p align="center">
<a href="https://github.com/alephnull-sh/deadair/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/alephnull-sh/deadair/actions/workflows/ci.yml/badge.svg"></a>
<a href="https://github.com/alephnull-sh/deadair/releases"><img alt="Release" src="https://img.shields.io/github/v/release/alephnull-sh/deadair"></a>
<img alt="Go 1.26" src="https://img.shields.io/badge/go-1.26-00ADD8">
<a href="https://github.com/big-comfy/deadair/blob/main/LICENSE"><img alt="License: Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
</p>
<p align="center">
<strong>O deadair verifica se as detecções de SIEM habilitadas ainda têm a telemetria de que precisam.</strong><br>
Ele reporta dados ausentes ou obsoletos, atrasos de ingestão e incompatibilidades de schema.
</p>
<p align="center">
Executa localmente · Somente leitura · Sem agente · Sem upload de telemetria
</p>
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/">Leia o artigo técnico</a> ·
<a href="https://www.detectionengineering.net/i/208193682/detection-engineering-gem">Destaque no Detection Engineering Weekly</a> ·
<a href="https://tldrsec.com/p/tldr-sec-341">Destaque no tl;dr sec #341</a>
</p>
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/#elastic-demo"><img alt="Uma varredura do Elastic mostrando entradas ausentes e obsoletas, campos ausentes e eventos atrasados" src="https://assets.kitploit.com/production/public/readmes/791/fc36f93c2d5fcaceffd370452b89b908a930eb10e810c0187fb3bba59cb156dd.png" width="860"></a>
</p>
<p align="center">
<sub>Campos ausentes e eventos atrasados em um laboratório Elastic descartável. Abra a imagem para ver a gravação curta com controles de reprodução, ou reproduza-a com <code>make record-scan-lab</code>.</sub>
</p>
## Por que o deadair
Uma regra pode estar habilitada, agendada e sem erros depois que os dados de que precisa desapareceram. O deadair
lê o inventário de regras ativas, resolve as entradas de cada regra usando a semântica nativa do backend e
verifica as fontes concretas por trás delas.
Ele detecta:
- regras cujos seletores de índice, alias ou data-stream não resolvem para nada;
- regras com seletores mistos em que uma entrada declarada desapareceu enquanto outra ainda resolve;
- regras cujas fontes correspondentes estão todas obsoletas ou vazias;
- no Elastic, regras em execução com campos declarados ausentes;
- no Elastic e em regras Sentinel Scheduled elegíveis, uma janela cega de atraso de ingestão;
- no Sentinel, regras cujas fontes conhecidas usam um plano de tabela Basic ou Auxiliary incompatível;
- no Elastic e OpenSearch, telemetria saudável que nenhuma detecção habilitada lê.
O deadair oferece suporte a Elastic Security, OpenSearch Security Analytics e Microsoft Sentinel.
## Início rápido
Baixe um binário para macOS, Linux ou Windows em
[GitHub Releases](https://github.com/alephnull-sh/deadair/releases), ou instale com Go:
```sh
go install github.com/alephnull-sh/deadair/cmd/deadair@latest
```
Imprima a configuração somente leitura para o seu SIEM:
```sh
deadair setup elastic # Elastic Security
deadair setup opensearch # OpenSearch Security Analytics
deadair setup sentinel # Microsoft Sentinel
```
Execute uma configuração, depois verifique e faça a varredura:
```sh
deadair check # verify the credential can scan
deadair scan # assess live rules and telemetry
```
Os códigos de saída são estáveis: `0` passa no gate configurado, `1` significa achados com gate e `2` significa que a varredura falhou.
Para investigar uma fonte e suas detecções consumidoras:
```sh
deadair scan --json-out report.json --html-out report.html
deadair inspect --source CommonSecurityLog report.json
```
Use um nome de fonte do seu relatório. O [guia de investigação](https://github.com/big-comfy/deadair/blob/main/docs/investigate.md) também aborda
feeds individuais do Sentinel, manutenção e rastreamento de recuperação.
## Como funciona
| Etapa | O que o deadair faz |
|---|---|
| Inventário | lê as detecções habilitadas e as entradas que elas declaram |
| Resolução | usa resolução nativa de índice no Elastic e OpenSearch; no Sentinel, combina análise KQL com evidências de tabela, watchlist, função salva, ASIM e cross-workspace mapeado |
| Medição | verifica a atualidade e o timing da fonte, além de schema e armazenamento onde o backend oferece suporte |
| Relatório | emite terminal, JSON, HTML, rollups de frota e métricas Prometheus com as evidências por trás de cada veredito |
O Sentinel segue o mesmo modelo de regra para fonte e adiciona watchlists literais, funções salvas, parsers
ASIM, workspaces mapeados e linhagem de tabela de resumo. Ele também mostra quando uma fatia filtrada de uma
tabela compartilhada ficou silenciosa ou um pipeline de resumo ficou para trás.
O [guia de uso](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#microsoft-sentinel) descreve as regras de evidência, e o
[registro de validação](https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance) registra a cobertura de testes ao vivo.
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/#sentinel-demo"><img alt="Um feed de firewall de Londres silencioso e sua detecção dependente dentro do Sentinel CommonSecurityLog" src="https://raw.githubusercontent.com/big-comfy/deadair/main/docs/assets/sentinel-lab.png" width="860"></a>
</p>
<p align="center">
<sub>Dois feeds de firewall compartilham <code>CommonSecurityLog</code>. Um para; o outro continua reportando. A gravação mostra as varreduras de falha e recuperação salvas. Veja o <a href="https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance">registro de validação</a> para as condições do laboratório.</sub>
</p>
O deadair verifica se a telemetria de uma detecção está presente e saudável. Ele não valida a lógica
da regra nem prova que um ataque simulado disparará um alerta. Use validação estática de regras e testes
de detecção ponta a ponta para essas tarefas.
## Achados
| Achado | Significado | Primeira verificação |
|---|---|---|
| nenhuma fonte correspondente | nenhuma das entradas da regra resolve para um índice, data stream ou tabela Sentinel visível | mudanças de padrão, integrações ausentes e escopo da credencial |
| todas as fontes obsoletas ou vazias | toda fonte resolvida está inutilizável no momento | cadência da fonte e o caminho de ingestão |
| campos ausentes | um campo declarado pela regra do Elastic está ausente ou não pesquisável em uma ou mais fontes resolvidas após a leitura de todo mapeamento de fonte | mudanças de parser, pacote e mapeamento |
| janela cega de atraso | o atraso de ingestão p95 de eventos pareados excede a margem de lookback da regra | intervalo da regra, lookback, substituição de timestamp e atraso do pipeline |
| cobertura parcial de entrada | a expressão completa resolve, mas um seletor positivo dentro dela resolve vazio | migrações, seletores de fallback e alternativas esperadas; informativo, a menos que a política o controle |
| plano de fonte incompatível | uma regra do Sentinel depende de uma tabela Basic ou Auxiliary que não é elegível para o caminho de evidência de regra analítica | plano da tabela e tipo de regra |
| degradação da fonte | uma fonte está obsoleta, vazia, com baixo volume ou com schema desviado | histórico da fonte e manutenção esperada |
| telemetria não utilizada | no Elastic ou OpenSearch, dados estão sendo armazenados mas nenhuma detecção local habilitada resolve para eles | regras desabilitadas e coleta intencional |
| produtor esperado silencioso | um feed configurado de fornecedor, produto ou dispositivo do Sentinel não reportou dentro do seu limite | o remetente e o coletor desse feed |
| pipeline de resumo não saudável | um job de resumo relevante do Sentinel falhou ou seu último sucesso está atrasado | o registro de execução nativo e a consulta de resumo |
Achados de produtor e de pipeline de resumo afetam o status de saída quando suas classes são selecionadas na
política. Um feed de dispositivo silencioso é reportado separadamente de outros consumidores de sua tabela compartilhada.
Todo veredito é limitado ao que a credencial configurada consegue ver. Relatórios JSON incluem as
expressões configuradas, fontes resolvidas, método de resolução, status de avaliação, metadados do backend
e evidências de capacidade. Veja o [guia de uso](https://github.com/big-comfy/deadair/blob/main/docs/usage.md) para exemplos práticos e triagem.
## Conectar um SIEM
Elastic:
```sh
export DEADAIR_ES_URL=https://es.example.internal:9200
export DEADAIR_KIBANA_URL=https://kibana.example.internal:5601
export DEADAIR_API_KEY=<read-only-api-key>
deadair check
deadair scan --json-out report.json --html-out report.html
```
OpenSearch:
```sh
export DEADAIR_BACKEND=opensearch
export DEADAIR_OPENSEARCH_URL=https://opensearch.example.internal:9200
export DEADAIR_OPENSEARCH_USERNAME=deadair
export DEADAIR_OPENSEARCH_PASSWORD=<password>
deadair check
deadair scan
```
Microsoft Sentinel:
```sh
az login --tenant <tenant-id>
export DEADAIR_BACKEND=sentinel
export DEADAIR_AZURE_SUBSCRIPTION_ID=<subscription-id>
export DEADAIR_AZURE_RESOURCE_GROUP=<resource-group>
export DEADAIR_SENTINEL_WORKSPACE=<workspace-resource-name>
# Optional: JSON allowlist for literal workspace() targets.
# export DEADAIR_SENTINEL_REMOTES=/restricted/path/sentinel-remotes.json
deadair check
deadair scan
```
Antes que o deadair avalie o workspace remoto mapeado de uma regra, esse workspace precisa ter o Sentinel
implantado. Mapeamentos na mesma assinatura podem provar a disponibilidade da fonte. Regras entre assinaturas
precisam de evidência em tempo de execução vinculada à identidade exata da regra. Veja os
[detalhes de uso do Sentinel](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#microsoft-sentinel) para as regras de evidência, limites de workspace e
região, e as orientações de desempenho da Microsoft.
Use as funções somente leitura documentadas para
[Elastic](https://github.com/big-comfy/deadair/blob/main/docs/credentials/elastic.md), [OpenSearch](https://github.com/big-comfy/deadair/blob/main/docs/credentials/opensearch.md) ou
[Microsoft Sentinel](https://github.com/big-comfy/deadair/blob/main/docs/credentials/sentinel.md).
## CI, frotas e monitoramento
```sh
# Gate a candidate rule against live source availability.
deadair scan --rule new-rule.json
# Fail only on new regressions between reports.
deadair diff yesterday.json today.json
# Scan multiple SIEM instances from one process.
deadair scan --fleet fleet.json
# Export cached scan results as Prometheus metrics.
deadair serve --interval 5m
```
`scan --rule` isola uma regra ou detector candidato nativo do backend de um backlog não relacionado. `diff`
funciona com relatórios redigidos criados com a mesma chave mantida pelo chamador. A configuração de frota referencia
segredos por meio de variáveis de ambiente em vez de armazenar valores de segredos.
A [GitHub Action oficial](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#gate-detection-changes) encapsula gates de candidatos de instância única
para Elastic, OpenSearch e Sentinel. Ela escreve um resumo do job, faz upload de um relatório JSON redigido e pode
aplicar uma política do deadair sem instalar uma regra. Fluxos de trabalho do Sentinel autenticam
o runner no Azure primeiro; a Action não define entradas de credencial do Azure.
Veja [comportamento do gate de CI](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#gate-detection-changes),
[implantação de frota e MSSP](https://github.com/big-comfy/deadair/blob/main/docs/mssp.md) e os [exemplos de Prometheus](https://github.com/big-comfy/deadair/blob/main/contrib) para configurações
para testar em seu próprio ambiente.
## Backends testados
| Backend | Validação ao vivo |
|---|---|
| Elastic Security | CI confiável em 8.19.19 e 9.4.4 |
| OpenSearch Security Analytics | CI confiável em 2.19.6 e 3.7.0 |
| Microsoft Sentinel | conformidade opt-in gravada em workspaces descartáveis do UK South; veja [status de validação](https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance) |
A execução de conformidade do Sentinel é manual, não CI agendada.
## Modelo de segurança
- Todas as chamadas de adaptador são somente leitura. Testes confiáveis de Elastic e OpenSearch, além de sondagens
separadas de laboratório do Sentinel, verificam que as identidades de varredura documentadas não conseguem realizar gravações representativas.
- Relatórios, HTML, arquivos de estado e saída de frota são gravados com `0600` em sistemas POSIX.
- Credenciais podem vir de variáveis de ambiente ou arquivos, evitando segredos em argumentos de processo.
- `--redact` substitui identificadores de tenant, regra, fonte, padrão, campo, dependência, linhagem, proveniência,
workspace, watchlist, template e pacote por pseudônimos HMAC com chave. Expressões de sondagem de dependência validadas
e seus argumentos KQL nunca são serializados. Um
`--redact-key-file` gerado a partir de bytes aleatórios também habilita a redação e mantém os nomes estáveis
entre execuções separadas.
- O exportador se vincula ao loopback por padrão.
- O deadair não tem comportamento de phone-home nem telemetria de uso.
Trate relatórios como artefatos sensíveis do SOC: eles identificam detecções cegas, nomes de fontes, lacunas de schema
e coleta não utilizada.
## Documentação
- [Guia de uso](https://github.com/big-comfy/deadair/blob/main/docs/usage.md) — primeiras varreduras, evidências de relatório, achados, gates de CI, estado e frotas
- [Investigar uma lacuna de telemetria](https://github.com/big-comfy/deadair/blob/main/docs/investigate.md) — consumidores de fonte, feeds esperados e recuperação
- [Status de validação](https://github.com/big-comfy/deadair/blob/main/docs/validation.md) — caminhos testados e limites atuais
- [Arquitetura](https://github.com/big-comfy/deadair/blob/main/docs/architecture.md) — contrato de backend, modelo de dados, propriedades de segurança e limites
- [Melhores práticas](https://github.com/big-comfy/deadair/blob/main/docs/best-practices.md) — ordem de implantação, contexto de alerta e roteamento
- [Guia MSSP](https://github.com/big-comfy/deadair/blob/main/docs/mssp.md) — segredos, redação, agendamento e tratamento de falhas de tenant
- [Detecções que executam mas não conseguem ver](https://alephnull-sh.github.io/deadair/) — o problema e uma simulação reproduzível
## Contribuindo
Abra uma issue para bugs, sugestões ou reproduções sanitizadas. Os mantenedores cuidam das mudanças de código.
Veja [CONTRIBUTING.md](https://github.com/big-comfy/deadair/blob/main/CONTRIBUTING.md) para detalhes.
## Licença
Apache-2.0.