elastic/detection-rulesElastic Security용 SIEM 탐지 규칙을 개발, 검증, 게시하기 위한 도구로, Python CLI 도구, KQL 파싱, Kibana 통합, 패키지화된 위협 헌팅 쿼리를 제공합니다.
[](https://www.python.org/downloads/)
[](https://github.com/elastic/detection-rules/actions)
[](https://ela.st/slack)
[](https://ela.st/detection-rules-navigator-trade)
# Detection Rules
Detection Rules는 Elastic Security에서 사용하는 규칙의 본거지입니다. 이 저장소는 Elastic Security의 Detection Engine용 규칙의 개발, 유지 관리, 테스트, 검증 및 릴리스에 사용됩니다.
이 저장소는 Elastic 블로그 게시물 [Elastic Security, 공개 탐지 규칙 저장소 오픈](https://elastic.co/blog/elastic-security-opens-public-detection-rules-repo)에서 처음 발표되었습니다. 추가 콘텐츠는 관련 웨비나 [Elastic Security: 공개 탐지 규칙 저장소 소개](https://www.elastic.co/webinars/introducing-the-public-repository-for-detection-rules)를 참조하세요.
## 목차
- [Detection Rules](#detection-rules)
- [목차](#table-of-contents)
- [이 저장소 개요](#overview-of-this-repository)
- [시작하기](#getting-started)
- [기여 방법](#how-to-contribute)
- [Detections as Code (DaC)](#detections-as-code-dac)
- [RTAs](#rtas)
- [라이선스](#licensing)
- [질문? 문제? 제안?](#questions-problems-suggestions)
## 이 저장소 개요
Detection Rules에는 정적 규칙 파일만 있는 것이 아닙니다. 이 저장소에는 Detections-as-Code 파이프라인 구축, Python 단위 테스트, Kibana의 Detection Engine과의 통합을 위한 코드도 포함되어 있습니다.
| folder | 설명 |
|------------------------------------------------ |------------------------------------------------------------------------------------ |
| [`detection_rules/`](https://github.com/elastic/detection-rules/blob/main/detection_rules) | 규칙 파싱, 검증 및 패키징을 위한 Python 모듈 |
| [`etc/`](https://github.com/elastic/detection-rules/blob/main/detection_rules/etc) | ECS 및 Beats 스키마, 구성 파일 등 기타 파일 |
| [`hunting/`](https://github.com/elastic/detection-rules/blob/main/hunting) | 위협 헌팅 패키지와 쿼리가 저장되는 루트 디렉터리 |
| [`kibana/`](https://github.com/elastic/detection-rules/blob/main/lib/kibana) | Kibana 및 Detection Engine에 대한 API 호출을 처리하는 Python 라이브러리 |
| [`kql/`](https://github.com/elastic/detection-rules/blob/main/lib/kql) | Kibana Query Language를 파싱하고 검증하는 Python 라이브러리 |
| [`rules/`](https://github.com/elastic/detection-rules/blob/main/rules) | 규칙이 저장되는 루트 디렉터리 |
| [`rules_building_block/`](https://github.com/elastic/detection-rules/blob/main/rules_building_block) | 빌딩 블록 규칙이 저장되는 루트 디렉터리 |
| [`tests/`](https://github.com/elastic/detection-rules/blob/main/tests) | 규칙 단위 테스트를 위한 Python 코드 |
## 시작하기
규칙은 `.toml` 파일을 수동으로 만들어 추가할 수도 있지만 권장하지 않습니다. 이 저장소에는 규칙 생성과 단위 테스트를 돕는 Python 모듈도 포함되어 있습니다. Python 3.12+가 설치되어 있다고 가정하고, 아래 명령어를 실행하여 makefile로 의존성을 설치하세요:
```console
✗ 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...
...
```
또는 다음 명령어로 의존성을 설치할 수 있습니다:
```console
$ 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]"`으로 설치할 수 있습니다.
```console
# 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 환경 사용에 문제가 있다면 [문제 해결 가이드](https://github.com/elastic/detection-rules/blob/main/Troubleshooting.md)의 관련 섹션을 참조하세요.
모든 것이 제대로 설치되었는지 확인하려면 `--help` 플래그로 실행하세요:
```console
$ 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`도 실행해야 할 수 있습니다.
[기여 가이드](https://github.com/elastic/detection-rules/blob/main/CONTRIBUTING.md)는 Detection Rules에 기여할 때 `create-rule` 및 `test` 명령어를 사용하여 새 규칙을 만들고 테스트하는 방법을 설명합니다.
더 고급 CLI(명령줄 인터페이스) 사용법은 [CLI 가이드](https://github.com/elastic/detection-rules/blob/main/CLI.md)를 참조하세요.
## 기여 방법
Detection Rules에 대한 기여를 환영합니다! 기여하기 전에 이 저장소, [디렉터리 구조](#overview-of-this-repository), 그리고 규칙 생성에 관한 [철학](https://github.com/elastic/detection-rules/blob/main/PHILOSOPHY.md)을 숙지하시기 바랍니다. 기여할 준비가 되면 [기여 가이드](https://github.com/elastic/detection-rules/blob/main/CONTRIBUTING.md)를 읽고 탐지 아이디어를 프로덕션 규칙으로 전환하고 테스트를 통해 검증하는 방법을 알아보세요.
## Detections as Code (DaC)
Detection Rules 저장소에는 "as code" 철학으로 규칙을 관리하는 데 도움이 되는 여러 명령어가 포함되어 있습니다. 전략 및 권장 설정 정보는 [DaC 특화 문서](https://dac-reference.readthedocs.io/en/latest/)부터 시작하는 것이 좋습니다. 바로 시작하고 싶다면, 이 저장소를 커스텀 규칙과 함께 사용하도록 구성하는 방법에 대한 [detections as code 문서](https://github.com/elastic/detection-rules/blob/main/docs-dev/detections-as-code.md) 및 [커스텀 규칙 문서](https://github.com/elastic/detection-rules/blob/main/docs-dev/custom-rules-management.md)를 참조한 후, 규칙 가져오기 및 내보내기 명령어에 대한 [CLI 문서](https://github.com/elastic/detection-rules/blob/main/CLI.md)를 참조하세요.
## RTAs
공격자 기법을 에뮬레이션하고 규칙을 검증하는 데 사용되는 Red Team Automations(RTA)은 전용 저장소인 [Cortado](https://github.com/elastic/cortado)에서 찾을 수 있습니다.
## 라이선스
이 저장소의 모든 것(규칙, 코드 등)은 [Elastic License v2](https://github.com/elastic/detection-rules/blob/main/LICENSE.txt)에 따라 라이선스가 부여됩니다. 이러한 규칙은 Elastic Security 애플리케이션 내 Detection Engine 맥락에서 사용되도록 설계되었습니다. [Elastic Cloud 관리 서비스](https://www.elastic.co/cloud/) 또는 [전체 무료 기능](https://www.elastic.co/subscriptions)이 포함된 기본 Elastic Stack 소프트웨어 배포판을 사용하는 경우, 탐지 엔진으로 처음 이동할 때 최신 규칙을 받게 됩니다.
때때로 MIT 또는 Apache 2.0과 같이 이미 라이선스가 있는 다른 저장소의 규칙을 가져오고 싶을 수 있습니다. 해당 라이선스가 Elastic License v2에 따른 서브라이선스를 허용한다면 환영합니다. 해당 라이선스 고지는 `NOTICE.txt`에 보관하며 다른 모든 규칙과 함께 Elastic License v2로 서브라이선스합니다. 또한 모든 Elastic 저장소에 코드를 기여하기 전에 기여자는 [기여자 라이선스 계약](https://www.elastic.co/contributor-agreement)에 서명해야 합니다.
## 질문? 문제? 제안?
- Detection Engine에 대해 더 알고 싶으신가요? Kibana의 [개요](https://www.elastic.co/guide/en/security/current/detection-engine-overview.html)를 확인하세요.
- 이 저장소에는 아직 릴리스되지 않은 새 규칙과 업데이트된 규칙이 포함되어 있습니다. 스택과 함께 릴리스된 최신 규칙 세트는 [사전 빌드 규칙 참조](https://www.elastic.co/guide/en/security/current/prebuilt-rules-downloadable-updates.html)를 참조하세요.
- 오탐(false positive) 또는 다른 유형의 버그를 신고하려면 GitHub 이슈를 생성하고 먼저 기존 이슈가 있는지 확인하세요.
- Detection Rules에 대한 도움이 필요하신가요? [Security Discuss 포럼](https://discuss.elastic.co/c/security/)에 이슈를 게시하거나 [Slack 워크스페이스](https://www.elastic.co/blog/join-our-elastic-stack-workspace-on-slack)의 **#security-detection-rules** 채널에서 질문하세요.
- DaC 관련 사례는 [지원 및 범위 문서](https://github.com/elastic/detection-rules/blob/main/docs-dev/detections-as-code.md#support-and-scope)에서 자세한 정보를 확인하세요.