업데이트로 돌아가기
New releaseSep 9, 2026

detection-rules dev-v2.2.0

Elastic Security용 SIEM 탐지 규칙을 개발, 검증, 게시하기 위한 도구로, Python CLI 도구, KQL 파싱, Kibana 통합, 패키지화된 위협 헌팅 쿼리를 제공합니다.

공유

Supported Python versions Unit Tests Chat ATT&CK navigator coverage

Detection Rules

Detection Rules는 Elastic Security에서 사용하는 규칙의 본거지입니다. 이 저장소는 Elastic Security의 Detection Engine용 규칙의 개발, 유지 관리, 테스트, 검증 및 릴리스에 사용됩니다.

이 저장소는 Elastic 블로그 게시물 Elastic Security, 공개 탐지 규칙 저장소 오픈에서 처음 발표되었습니다. 추가 콘텐츠는 관련 웨비나 Elastic Security: 공개 탐지 규칙 저장소 소개를 참조하세요.

목차

이 저장소 개요

Detection Rules에는 정적 규칙 파일만 있는 것이 아닙니다. 이 저장소에는 Detections-as-Code 파이프라인 구축, Python 단위 테스트, Kibana의 Detection Engine과의 통합을 위한 코드도 포함되어 있습니다.

folder설명
detection_rules/규칙 파싱, 검증 및 패키징을 위한 Python 모듈
etc/ECS 및 Beats 스키마, 구성 파일 등 기타 파일
hunting/위협 헌팅 패키지와 쿼리가 저장되는 루트 디렉터리
kibana/Kibana 및 Detection Engine에 대한 API 호출을 처리하는 Python 라이브러리
kql/Kibana Query Language를 파싱하고 검증하는 Python 라이브러리
rules/규칙이 저장되는 루트 디렉터리
rules_building_block/빌딩 블록 규칙이 저장되는 루트 디렉터리
tests/규칙 단위 테스트를 위한 Python 코드

시작하기

규칙은 .toml 파일을 수동으로 만들어 추가할 수도 있지만 권장하지 않습니다. 이 저장소에는 규칙 생성과 단위 테스트를 돕는 Python 모듈도 포함되어 있습니다. Python 3.12+가 설치되어 있다고 가정하고, 아래 명령어를 실행하여 makefile로 의존성을 설치하세요:

✗ make
python3.12 -m pip install --upgrade pip setuptools
Looking in indexes: https://pypi.org/simple
Requirement already satisfied: pip in /opt/homebrew/lib/python3.12/site-packages (24.0)
Requirement already satisfied: setuptools in /opt/homebrew/lib/python3.12/site-packages (69.1.1)
python3.12 -m venv ./env/detection-rules-build
./env/detection-rules-build/bin/pip install --upgrade pip setuptools
Looking in indexes: https://pypi.org/simple
Requirement already satisfied: pip in ./env/detection-rules-build/lib/python3.12/site-packages (24.0)
Collecting setuptools
  Using cached setuptools-69.1.1-py3-none-any.whl.metadata (6.2 kB)
Using cached setuptools-69.1.1-py3-none-any.whl (819 kB)
Installing collected packages: setuptools
Successfully installed setuptools-69.1.1
Installing kql and kibana packages...
...

또는 다음 명령어로 의존성을 설치할 수 있습니다:

$ pip3 install ".[dev]"
Collecting jsl==0.2.4
  Downloading jsl-0.2.4.tar.gz (21 kB)
Collecting jsonschema==3.2.0
  Downloading jsonschema-3.2.0-py2.py3-none-any.whl (56 kB)
     |████████████████████████████████| 56 kB 318 kB/s
Collecting requests==2.22.0
  Downloading requests-2.22.0-py2.py3-none-any.whl (57 kB)
     |████████████████████████████████| 57 kB 1.2 MB/s
Collecting Click==7.0
  Downloading Click-7.0-py2.py3-none-any.whl (81 kB)
     |████████████████████████████████| 81 kB 2.6 MB/s
...

참고: kibana 및 kql 패키지는 PyPI에서 사용할 수 없으며 lib 디렉터리에서 설치해야 합니다. hunting 패키지에는 선택적 의존성이 있으며 pip3 install ".[hunting]"으로 설치할 수 있습니다.


# Install from the repository
pip3 install git+https://github.com/elastic/detection-rules.git#subdirectory=lib/kibana
pip3 install git+https://github.com/elastic/detection-rules.git#subdirectory=lib/kql

# Or locally for development
pip3 install lib/kibana lib/kql

가상 환경을 사용하는 경우 해당 가상 환경을 활성화해야 합니다. make로 설치한 경우 관련 가상 환경은 env/detection-rules-build/에 생성됩니다. Python 3.12 환경 사용에 문제가 있다면 문제 해결 가이드의 관련 섹션을 참조하세요.

모든 것이 제대로 설치되었는지 확인하려면 --help 플래그로 실행하세요:

$  python -m detection_rules --help

Usage: detection_rules [OPTIONS] COMMAND [ARGS]...

  Commands for detection-rules repository.

Options:
  -D, --debug / -N, --no-debug  Print full exception stacktrace on errors
  -h, --help                    Show this message and exit.

Commands:
  build-limited-rules     Import rules from json, toml, or Kibana exported rule file(s), filter out unsupported ones, and write to output NDJSON file.
  build-threat-map-entry  Build a threat map entry.
  create-rule             Create a detection rule.
  custom-rules            Commands for supporting custom rules.
  dev                     Commands related to the Elastic Stack rules release lifecycle.
  es                      Commands for integrating with Elasticsearch.
  export-rules-from-repo  Export rule(s) and exception(s) into an importable ndjson file.
  generate-rules-index    Generate enriched indexes of rules, based on a KQL search, for indexing/importing into elasticsearch/kibana.
  import-rules-to-repo    Import rules from json, toml, or yaml files containing Kibana exported rule(s).
  kibana                  Commands for integrating with Kibana.
  mass-update             Update multiple rules based on eql results.
  normalize-data          Normalize Elasticsearch data timestamps and sort.
  rule-search             Use KQL or EQL to find matching rules.
  test                    Run unit tests over all of the rules.
  toml-lint               Cleanup files with some simple toml formatting.
  typosquat               Commands for generating typosquat detections.
  validate-all            Check if all rules validates against a schema.
  validate-rule           Check if a rule staged in rules dir validates against a schema.
  view-rule               View an internal rule or specified rule file.

참고:

  • 가상 환경을 사용하는 경우 위 명령어를 실행하기 전에 반드시 활성화하세요.
  • Windows를 사용하는 경우 Python 버전에 따라 <venv_directory>\Scripts\pywin32_postinstall.py -install도 실행해야 할 수 있습니다.

기여 가이드는 Detection Rules에 기여할 때 create-rule 및 test 명령어를 사용하여 새 규칙을 만들고 테스트하는 방법을 설명합니다.

더 고급 CLI(명령줄 인터페이스) 사용법은 CLI 가이드를 참조하세요.

기여 방법

Detection Rules에 대한 기여를 환영합니다! 기여하기 전에 이 저장소, 디렉터리 구조, 그리고 규칙 생성에 관한 철학을 숙지하시기 바랍니다. 기여할 준비가 되면 기여 가이드를 읽고 탐지 아이디어를 프로덕션 규칙으로 전환하고 테스트를 통해 검증하는 방법을 알아보세요.

더 읽기

카테고리

Defensive ToolsThreat IntelligenceIntrusion DetectionCurated ResourcesAnomaly DetectionLog Analysis