big-comfy/deadairSIEM에서 블라인드 상태로 실행 중인 탐지 규칙을 찾아냅니다.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
<img alt="deadair - SIEM 탐지 커버리지 상태" 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>deadair는 활성화된 SIEM 탐지가 여전히 필요한 텔레메트리를 확보하고 있는지 확인합니다.</strong><br>
누락되거나 오래된 데이터, 수집 지연, 스키마 불일치를 보고합니다.
</p>
<p align="center">
로컬에서 실행 · 읽기 전용 · 에이전트 없음 · 텔레메트리 업로드 없음
</p>
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/">기술 문서 읽기</a> ·
<a href="https://www.detectionengineering.net/i/208193682/detection-engineering-gem">Detection Engineering Weekly에 소개됨</a> ·
<a href="https://tldrsec.com/p/tldr-sec-341">tl;dr sec #341에 소개됨</a>
</p>
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/#elastic-demo"><img alt="누락 및 오래된 입력, 누락된 필드, 지연된 이벤트를 보여주는 Elastic 스캔" src="https://assets.kitploit.com/production/public/readmes/791/fc36f93c2d5fcaceffd370452b89b908a930eb10e810c0187fb3bba59cb156dd.png" width="860"></a>
</p>
<p align="center">
<sub>일회용 Elastic 랩에서의 누락된 필드와 지연된 이벤트. 재생 컨트롤이 있는 짧은 녹화를 보려면 이미지를 열거나, <code>make record-scan-lab</code>으로 재현하세요.</sub>
</p>
## deadair를 만든 이유
규칙은 필요한 데이터가 사라진 뒤에도 활성화되고, 예약되고, 오류 없이 실행될 수 있습니다. deadair는
실시간 규칙 인벤토리를 읽고, 백엔드의 네이티브 시맨틱을 사용해 각 규칙의 입력을 해석하며,
그 뒤에 있는 구체적인 소스를 확인합니다.
deadair가 잡아내는 것:
- 인덱스, 별칭, 데이터 스트림 선택자가 아무것도 해석하지 못하는 규칙;
- 선언된 입력 중 하나는 사라졌지만 다른 하나는 여전히 해석되는 혼합 선택자 규칙;
- 일치하는 소스가 모두 오래되었거나 비어 있는 규칙;
- Elastic에서 선언된 필드가 누락된 채 실행되는 규칙;
- Elastic 및 해당되는 Sentinel Scheduled 규칙에서의 수집 지연 블라인드 윈도우;
- Sentinel에서 알려진 소스가 호환되지 않는 Basic 또는 Auxiliary 테이블 플랜을 사용하는 규칙;
- Elastic 및 OpenSearch에서 활성화된 탐지가 읽지 않는 정상 텔레메트리.
deadair는 Elastic Security, OpenSearch Security Analytics, Microsoft Sentinel을 지원합니다.
## 빠른 시작
[GitHub Releases](https://github.com/alephnull-sh/deadair/releases)에서 macOS, Linux, Windows용
바이너리를 다운로드하거나 Go로 설치하세요:
```sh
go install github.com/alephnull-sh/deadair/cmd/deadair@latest
```
사용 중인 SIEM에 대한 읽기 전용 설정을 출력합니다:
```sh
deadair setup elastic # Elastic Security
deadair setup opensearch # OpenSearch Security Analytics
deadair setup sentinel # Microsoft Sentinel
```
설정을 하나 실행한 다음 검증하고 스캔하세요:
```sh
deadair check # 자격 증명이 스캔할 수 있는지 검증
deadair scan # 실시간 규칙 및 텔레메트리 평가
```
종료 코드는 안정적입니다: `0`은 구성된 게이트를 통과, `1`은 게이트된 발견 사항, `2`는 스캔 실패를 의미합니다.
소스와 이를 소비하는 탐지를 조사하려면:
```sh
deadair scan --json-out report.json --html-out report.html
deadair inspect --source CommonSecurityLog report.json
```
보고서에 있는 소스 이름을 사용하세요. [조사 가이드](https://github.com/big-comfy/deadair/blob/main/docs/investigate.md)는 개별 Sentinel 피드,
유지보수, 복구 추적도 다룹니다.
## 작동 방식
| 단계 | deadair가 하는 일 |
|---|---|
| 인벤토리 | 활성화된 탐지와 그들이 선언한 입력을 읽습니다 |
| 해석 | Elastic 및 OpenSearch에서는 네이티브 인덱스 해석을 사용하고, Sentinel에서는 KQL 분석을 테이블, 워치리스트, 저장 함수, ASIM, 매핑된 교차 워크스페이스 증거와 결합합니다 |
| 측정 | 백엔드가 지원하는 경우 소스 신선도와 타이밍, 스키마 및 스토리지를 확인합니다 |
| 보고 | 각 판정의 근거와 함께 터미널, JSON, HTML, 플릿 롤업, Prometheus 메트릭을 출력합니다 |
Sentinel은 동일한 규칙-소스 모델을 따르며 리터럴 워치리스트, 저장 함수, ASIM 파서, 매핑된
워크스페이스, 요약 테이블 계보를 추가합니다. 또한 공유 테이블의 필터링된 슬라이스가 조용해졌거나
요약 파이프라인이 뒤처진 경우도 보여줍니다.
[사용 가이드](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#microsoft-sentinel)는 증거 규칙을 설명하고,
[검증 기록](https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance)은 실시간 테스트 커버리지를 기록합니다.
<p align="center">
<a href="https://alephnull-sh.github.io/deadair/#sentinel-demo"><img alt="Sentinel CommonSecurityLog 내부의 조용한 런던 방화벽 피드와 그에 의존하는 탐지" src="https://raw.githubusercontent.com/big-comfy/deadair/main/docs/assets/sentinel-lab.png" width="860"></a>
</p>
<p align="center">
<sub>두 방화벽 피드가 <code>CommonSecurityLog</code>를 공유합니다. 하나는 멈추고, 다른 하나는 계속 보고합니다. 녹화는 저장된 실패 및 복구 스캔을 보여줍니다. 랩 조건은 <a href="https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance">검증 기록</a>을 참조하세요.</sub>
</p>
deadair는 탐지의 텔레메트리가 존재하고 정상인지 확인합니다. 규칙 로직을 검증하거나 시뮬레이션된
공격이 경보를 발생시키는지 증명하지는 않습니다. 그러한 작업에는 정적 규칙 검증과 종단 간 탐지
테스트를 사용하세요.
## 발견 사항
| 발견 사항 | 의미 | 우선 확인 |
|---|---|---|
| 일치하는 소스 없음 | 규칙의 입력 중 어느 것도 가시적인 인덱스, 데이터 스트림, Sentinel 테이블로 해석되지 않음 | 패턴 변경, 누락된 통합, 자격 증명 범위 |
| 모든 소스가 오래되었거나 비어 있음 | 해석된 모든 소스가 현재 사용 불가 | 소스 주기와 수집 경로 |
| 누락된 필드 | 모든 소스 매핑을 읽은 후 하나 이상의 해석된 소스에서 Elastic 규칙이 선언한 필드가 없거나 검색 불가 | 파서, 패키지, 매핑 변경 |
| 지연 블라인드 윈도우 | 쌍을 이루는 이벤트의 p95 수집 지연이 규칙의 룩백 여유를 초과 | 규칙 간격, 룩백, 타임스탬프 재정의, 파이프라인 지연 |
| 부분 입력 커버리지 | 전체 표현식은 해석되지만 그 안의 양성 선택자 하나가 비어 있게 해석됨 | 마이그레이션, 폴백 선택자, 예상 대안; 정책이 게이트하지 않는 한 정보성 |
| 소스 플랜 비호환 | Sentinel 규칙이 분석 규칙 증거 경로에 적합하지 않은 Basic 또는 Auxiliary 테이블에 의존 | 테이블 플랜과 규칙 유형 |
| 소스 성능 저하 | 소스가 오래되었거나, 비어 있거나, 볼륨이 낮거나, 스키마가 드리프트됨 | 소스 이력과 예상 유지보수 |
| 사용되지 않는 텔레메트리 | Elastic 또는 OpenSearch에서 데이터가 저장되고 있지만 활성화된 로컬 탐지가 이를 해석하지 않음 | 비활성화된 규칙과 의도적 수집 |
| 예상 프로듀서 조용함 | 구성된 Sentinel 벤더, 제품 또는 디바이스 피드가 임계값 내에 보고하지 않음 | 해당 피드의 발신자와 수집기 |
| 요약 파이프라인 비정상 | 관련 Sentinel 요약 작업이 실패했거나 마지막 성공이 지연됨 | 네이티브 실행 기록과 요약 쿼리 |
프로듀서 및 요약 파이프라인 발견 사항은 해당 클래스가 정책에서 선택된 경우 종료 상태에 영향을
줍니다. 조용한 디바이스 피드는 공유 테이블의 다른 소비자와 별도로 보고됩니다.
모든 판정은 구성된 자격 증명이 볼 수 있는 것으로 제한됩니다. JSON 보고서에는 구성된 표현식,
해석된 소스, 해석 방법, 평가 상태, 백엔드 메타데이터, 기능 증거가 포함됩니다. 예제와 트리아지는
[사용 가이드](https://github.com/big-comfy/deadair/blob/main/docs/usage.md)를 참조하세요.
## 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
```
deadair가 규칙의 매핑된 원격 워크스페이스를 평가하기 전에, 해당 워크스페이스에는 Sentinel이
배포되어 있어야 합니다. 동일 구독 매핑은 소스 가용성을 증명할 수 있습니다. 교차 구독 규칙은
정확한 규칙 ID에 연결된 런타임 증거가 필요합니다. 증거 규칙, 워크스페이스 및 리전 제한,
Microsoft의 성능 지침은 [Sentinel 사용 세부 정보](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#microsoft-sentinel)를 참조하세요.
[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),
[Microsoft Sentinel](https://github.com/big-comfy/deadair/blob/main/docs/credentials/sentinel.md)에 대해 문서화된 읽기 전용 역할을 사용하세요.
## CI, 플릿, 모니터링
```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`은 백엔드 네이티브 후보 규칙 또는 탐지를 관련 없는 백로그로부터 격리합니다. `diff`는
동일한 호출자 보유 키로 생성된 편집된 보고서와 함께 작동합니다. 플릿 구성은 비밀 값을 저장하는
대신 환경 변수를 통해 비밀을 참조합니다.
[공식 GitHub Action](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#gate-detection-changes)은 Elastic, OpenSearch, Sentinel용
단일 인스턴스 후보 게이트를 래핑합니다. 작업 요약을 작성하고, 편집된 JSON 보고서를 업로드하며,
규칙을 설치하지 않고도 deadair 정책을 적용할 수 있습니다. Sentinel 워크플로는 먼저 러너를
Azure에 인증합니다; Action은 Azure 자격 증명 입력을 정의하지 않습니다.
자체 환경에서 테스트할 구성은 [CI 게이트 동작](https://github.com/big-comfy/deadair/blob/main/docs/usage.md#gate-detection-changes),
[플릿 및 MSSP 배포](https://github.com/big-comfy/deadair/blob/main/docs/mssp.md), [Prometheus 예제](https://github.com/big-comfy/deadair/blob/main/contrib)를 참조하세요.
## 테스트된 백엔드
| 백엔드 | 실시간 검증 |
|---|---|
| Elastic Security | 8.19.19 및 9.4.4에서 신뢰할 수 있는 CI |
| OpenSearch Security Analytics | 2.19.6 및 3.7.0에서 신뢰할 수 있는 CI |
| Microsoft Sentinel | 일회용 UK South 워크스페이스에서 기록된 옵트인 적합성; [검증 상태](https://github.com/big-comfy/deadair/blob/main/docs/validation.md#sentinel-live-conformance) 참조 |
Sentinel 적합성 실행은 수동이며, 예약된 CI가 아닙니다.
## 보안 모델
- 모든 어댑터 호출은 읽기 전용입니다. 신뢰할 수 있는 Elastic 및 OpenSearch 테스트와 별도의
Sentinel 랩 프로브는 문서화된 스캔 ID가 대표적인 쓰기를 수행할 수 없음을 검증합니다.
- 보고서, HTML, 상태 파일, 플릿 출력은 POSIX 시스템에서 `0600`으로 작성됩니다.
- 자격 증명은 환경 변수나 파일에서 가져올 수 있어 프로세스 인수에 비밀이 노출되는 것을 방지합니다.
- `--redact`는 테넌트, 규칙, 소스, 패턴, 필드, 의존성, 계보, 출처, 워크스페이스, 워치리스트,
템플릿, 패키지 식별자를 키 기반 HMAC 가명으로 대체합니다. 검증된 의존성 프로브 표현식과
그 KQL 인수는 절대 직렬화되지 않습니다. 무작위 바이트로 생성된 `--redact-key-file`도
편집을 활성화하고 별도 실행 간에 이름을 안정적으로 유지합니다.
- 익스포터는 기본적으로 루프백에 바인딩됩니다.
- deadair에는 폰홈 동작이나 사용 텔레메트리가 없습니다.
보고서는 민감한 SOC 아티팩트로 취급하세요: 블라인드 탐지, 소스 이름, 스키마 격차, 사용되지 않는
수집을 식별합니다.
## 문서
- [사용 가이드](https://github.com/big-comfy/deadair/blob/main/docs/usage.md) — 첫 스캔, 보고서 증거, 발견 사항, CI 게이트, 상태, 플릿
- [텔레메트리 격차 조사](https://github.com/big-comfy/deadair/blob/main/docs/investigate.md) — 소스 소비자, 예상 피드, 복구
- [검증 상태](https://github.com/big-comfy/deadair/blob/main/docs/validation.md) — 테스트된 경로와 현재 제한
- [아키텍처](https://github.com/big-comfy/deadair/blob/main/docs/architecture.md) — 백엔드 계약, 데이터 모델, 안전 속성, 제한
- [모범 사례](https://github.com/big-comfy/deadair/blob/main/docs/best-practices.md) — 롤아웃 순서, 경보 컨텍스트, 라우팅
- [MSSP 가이드](https://github.com/big-comfy/deadair/blob/main/docs/mssp.md) — 비밀, 편집, 스케줄링, 테넌트 실패 처리
- [실행되지만 볼 수 없는 탐지](https://alephnull-sh.github.io/deadair/) — 문제와 재현 가능한 시뮬레이션
## 기여
버그, 제안, 정제된 재현 사례는 이슈를 열어주세요. 코드 변경은 메인테이너가 처리합니다.
자세한 내용은 [CONTRIBUTING.md](https://github.com/big-comfy/deadair/blob/main/CONTRIBUTING.md)를 참조하세요.
## 라이선스
Apache-2.0.