elastic/detection-rulesElastic Security용 SIEM 탐지 규칙을 개발, 검증, 게시하기 위한 도구로, Python CLI 도구, KQL 파싱, Kibana 통합, 패키지화된 위협 헌팅 쿼리를 제공합니다.
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.
참고:
<venv_directory>\Scripts\pywin32_postinstall.py -install도 실행해야 할 수 있습니다.기여 가이드는 Detection Rules에 기여할 때 create-rule 및 test 명령어를 사용하여 새 규칙을 만들고 테스트하는 방법을 설명합니다.
더 고급 CLI(명령줄 인터페이스) 사용법은 CLI 가이드를 참조하세요.
Detection Rules에 대한 기여를 환영합니다! 기여하기 전에 이 저장소, 디렉터리 구조, 그리고 규칙 생성에 관한 철학을 숙지하시기 바랍니다. 기여할 준비가 되면 기여 가이드를 읽고 탐지 아이디어를 프로덕션 규칙으로 전환하고 테스트를 통해 검증하는 방법을 알아보세요.