detflow: pip로 설치할 수 있는 탐지 엔지니어링 코파일럿
Source: Dev.to
TL;DR 🚀
저는 detflow(https://pypi.org/project/detflow/)를 PyPI에 배포했습니다 — 오픈소스이며 벤더에 구애받지 않는 탐지 엔지니어링 코파일럿입니다. 매번 탐지‑as‑code 워크플로우에서 제가 직접 다시 구현하던 네 가지 작업을 수행합니다: 자연어(Sigma 혹은 Cortex XSIAM XQL)로 탐지를 초안 만들기, 오프라인으로 lint 하기, 이미 실행 중인 규칙과 중복 확인하기, 그리고 시니어 탐지 엔지니어처럼 리뷰하기. 🛡️
2가지 포맷
Sigma 혹은 Cortex XQL 로 초안 및 리뷰 — 하나는 포터블, 하나는 네이티브
1가지 프로토콜
모든 모델을 사용할 수 있음: OpenAI 호환 엔드포인트 혹은 LangChain 장애조치 체인
0번 충돌
lint와 overlap는 모델이 필요 없으며, 리뷰는 결정론적 기본값으로 낮아집니다
이는 iocflow의 탐지 측면 형제 프로젝트입니다. iocflow는 인디케이터 라이프사이클을 다루고, detflow는 룰 라이프사이클을 다룹니다. 동일한 설계 DNA: 먼저 결정론적 기본 기능을 제공하고, LLM은 선택적 보강 수단이며, 실패해도 도구 전체가 중단되지 않도록 설계되었습니다. 🧱
문제점
탐지‑as‑code 파이프라인(룰을 리뷰·테스트된 머지 리퀘스트로 만드는 과정)에는 벤더와 무관한 단계가 몇 가지 있습니다:
- 이 룰이 유효한가? (lint / 스키마 검사)
- 분석가는 행동을 설명할 수 있지만 Sigma를 능숙하게 쓰지는 못한다 — 첫 버전을 초안 만들 수 있을까?
- 이미 보유하고 있는 커버리지를 또 배포하려는 건가? (카탈로그와 중복 검사)
- 시니어 엔지니어가 승인할까, 어떤 점을 지적할까? (품질, 오탐 위험, ATT&CK 매핑, 빈틈)
이 네 단계를 저는 여러 번 구현해봤습니다. 이들은 일반적인 것이며, 실제 파이프라인에서 벤더‑특정 부분은 쿼리 언어로 컴파일하고 테넌트에서 드라이런하는 것뿐입니다. 그래서 저는 탐지‑as‑code 워크벤치에서 이 네 가지를 추출해 깔끔한 공개 라이브러리로 만들었습니다. 🧰
사용 예시
문장 하나로 탐지를 초안 만들기 — 두 언어 중 선택:
import detflow
sigma = detflow.draft("powershell with an encoded command spawned from a Word macro")
print(sigma.rule) # 완전한 Sigma 룰, lint 준비 완료
xql = detflow.draft("same thing, but for Cortex XSIAM", fmt="cortex-xql")
print(xql.rule) # dataset = ... | filter ... | limit 100오프라인 lint — 모델, 네트워크, 키가 필요 없습니다:
report = detflow.lint(sigma.rule) # 또는 lint_sigma / lint_xql
print(report.status, report.summary) # "pass" / "warn" / "fail"
for f in report.findings:
print(f.level, f.message)시니어 엔지니어처럼 리뷰하고, 자체 인벤토리와 중복 제거:
catalog = [
{"name": "Encoded PowerShell", "source": "crowdstrike", "techniques": ["T1059.001"]},
{"name": "WMI Process Create", "source": "sigma", "techniques": ["T1047"]},
]
result = detflow.review(sigma.rule, catalog=catalog)
print(result.quality_score, result.false_positive_risk, result.verdict)
for o in result.overlaps: # "you may already cover this"
print(" •", o.source, o.name, "—", o.reason)전체 흐름, 엔드‑투‑엔드:
flowchart LR
NL([plain English]) -->|draft| RULE[Sigma / XQL rule]
RULE -->|lint| LINT[schema + best-practice findings]
RULE -->|find_overlaps| OV[catalog dedup]
LINT --> REV{{review}}
OV --> REV
REV --> V([quality · FP risk · ATT&CK · verdict])터미널·CI 사용자용 CLI도 제공됩니다:
detflow draft "credential dumping via comsvcs MiniDump" -f cortex-xql
detflow lint rule.yml
detflow review rule.yml --catalog catalog.json --json의도적으로 모델 비종속 설계 🔌
detflow는 SDK를 임포트하거나 특정 공급자를 하드코딩하지 않습니다. “모델”이란 다음 메서드만 있으면 됩니다:
def complete(self, system: str, user: str, *, json: bool = False) -> str: ...이를 통해 세 가지 접근 방식을 제공합니다. 내장 OpenAIChatModel은 OpenAI‑호환 엔드포인트(예: OpenAI, Azure, 로컬 vLLM/Ollama 서버, 게이트웨이)와 연결됩니다. default_model()은 DETFLOW_LLM_* 환경 변수로 모델을 구성합니다. 혹은 어떤 LangChain 채팅 모델이든 래핑할 수 있습니다:
from langchain_failover import FailoverChatModel
from detflow.llm import LangChainModel
chain = FailoverChatModel(models=[primary, local_fallback])
model = LangChainModel(chain)
detflow.review(rule, catalog=catalog, model=model) # 장애조치 체인 사용FailoverChatModel은 제가 별도 패키지로 공개한 langchain-failover이며, 기본 모델에 장애가 발생하면 자동으로 보조 모델로 전환됩니다. 제 OSS 패키지 세 개가 서로의 도그푸드를 조용히 먹고 있습니다. 🐕
절대 예외를 발생시키지 않는 결정론적 기본값
제가 가장 중요하게 생각하는 계약: detflow는 다운되지 않고, 성능이 낮아질 뿐입니다. 🎯
- Lint와 overlap는 모델이 전혀 필요 없으며, 순수 파이썬 표준 라이브러리와 PyYAML만 사용해 CI에서 비밀 없이 실행됩니다.
- Drafting은 모델이 필요하지만, 모델 오류는
error필드가 있는 결과 객체로 반환될 뿐 예외가 발생하지 않습니다. - Review는 모델이 있으면 사용하고, 없을 경우 결정론적 기본값으로 대체됩니다. lint 결과, 카탈로그 중복, 파싱된 ATT&CK 기술은 여전히 제공되며
review()는 절대 예외를 던지지 않습니다.
따라서 detflow는 LLM이 가끔 제공되고 가끔은 제공되지 않는 파이프라인에 안전하게 삽입할 수 있습니다. 지루하고 테스트 가능한 부분은 언제나 동작하고, AI는 가능할 때만 판단을 보태는 구조입니다.
왜 두 가지 포맷인가
Sigma는 포터블하고 벤더에 구애받지 않는 표준으로, 깔끔하게 lint가 가능하고 다양한 SIEM에 이식됩니다. Cortex XSIAM XQL은 실제 해당 플랫폼에서 실행되는 언어입니다. 두 포맷을 모두 지원하면 포터블성을 위해 Sigma로 작성하거나, 플랫폼 고유의 표현력을 원할 때 XQL로 바로 작성할 수 있습니다. detflow는 어느 쪽이든 lint와 리뷰를 수행합니다. 초안 프롬프트는 언어별 특성을 인식하도록 설계돼 있어, XQL 프롬프트는 startswith/endswith가 없고 | filter를 사용한다는 점을 반영해 SQL 형태의 환각을 방지합니다. 🧠
더 큰 패턴
IOC 작업과 동일한 교훈입니다: AI를 엔지니어링에 보여주고 싶을 때는 모든 것을 LLM 호출로 만들기 쉽지만, 더 견고하고 배포 가능한 접근법은 결정론적 기본 기능 + 선택적 AI입니다. 스키마 검사와 중복 제거는 지루하고 테스트 가능하며, 모델은 판단이 필요한 부분(작성·리뷰)에서만 사용됩니다. 모델이 느리거나 없을 때도 시스템은 정상 작동합니다.
detflow는 Python 3.9+에서 동작하고, import detflow만으로 가벼운 의존성을 유지합니다(LLM 클라이언트는 별도). py.typed를 제공해 다운스트림 타입 체크를 지원하며, 각 구성 요소가 독립적으로도