EVTX, Auditd, Sysmon for Linux, XML, CSV 또는 JSONL/NDJSON 로그를 위한 독립 실행형 SIGMA 기반 탐지 도구

Zircolite는 Python 3로 작성된 독립 실행형 도구로, 다음 로그에 SIGMA 규칙을 사용할 수 있게 해줍니다:

• MS Windows EVTX (EVTX, XML, JSONL 형식)
• Auditd 로그
• Sysmon for Linux
• EVTXtract
• CSV 및 XML 로그
• JSON 배열 로그

주요 기능

• 빠른 속도: 452,554개 이벤트를 4,319개 Sigma 규칙에 대해 11.6초 만에 처리 — 동일한 로그에서 Rust로 작성된 Hayabusa보다 2.1배, Chainsaw보다 9.8배 빠릅니다. 벤치마크를 참조하세요.
• 자동 로그 유형 탐지: 매직 바이트, 콘텐츠 분석, 정규식 기반 폴백을 사용하여 로그 형식과 타임스탬프 필드를 자동으로 식별합니다. 대부분의 경우 형식 플래그를 지정할 필요가 없습니다.
• 다양한 입력 형식: EVTX, JSON Lines, JSON Arrays, CSV, XML 등 다양한 로그 형식을 지원합니다. 압축 또는 아카이브된 로그(gzip, bzip2, ZIP, 7-Zip)를 지원하며, 암호화된 ZIP/7z에는 --archive-password를 사용하세요.
• 네이티브 Sigma 지원: Zircolite는 pySigma로 변환하여 네이티브 Sigma 규칙(YAML)을 직접 사용할 수 있습니다.
• SIGMA 백엔드: SIGMA 백엔드(SQLite)를 기반으로 하며 내부적인 SIGMA-to-something 변환을 사용하지 않습니다.
• 고급 로그 조작: 입력 로그를 필드 분할 및 변환 적용으로 조작할 수 있어 보다 유연하고 강력한 로그 분석이 가능합니다.
• 필드 변환: 처리 중 필드에 사용자 정의 Python 변환을 적용합니다(예: Base64 디코딩, hex-to-ASCII 변환).
• 유연한 내보내기: Zircolite는 Jinja 템플릿을 사용하여 결과를 JSON, CSV, JSONL, Splunk, Elastic, OpenSearch, Timesketch, SARIF, ATT&CK Navigator 등 여러 형식으로 내보낼 수 있습니다.
• 풍부한 터미널 출력: 탐지 결과가 심각도별로 정렬된 테이블에 MITRE ATT&CK 기법 ID, ATT&CK 전술 히트맵, 규칙 커버리지 지표, 클릭 가능한 출력 파일 링크와 함께 표시됩니다.

Zircolite를 Python으로 직접 사용하거나, Python 설치가 필요 없는 독립 실행형 바이너리를 다운로드할 수 있습니다.

문서는 여기(전용 사이트) 또는 여기(저장소 디렉터리)에서 확인할 수 있습니다.

요구 사항 / 설치

[!NOTE] 이 섹션의 모든 내용은 Zircolite를 소스에서 실행할 때만 적용됩니다. 독립 실행형 바이너리와 Docker 이미지는 자체 Python, 모든 종속성, 컴파일된 커널을 포함하므로 Python, 패키지 관리자, C 컴파일러가 필요하지 않습니다.

이 프로젝트는 Python 3.10 이상에서 테스트되었습니다. 종속성은 pyproject.toml에 선언되어 있으며, 복제한 저장소에서 PDM(pdm install), uv(uv sync) 또는 Poetry(poetry install)로 설치하세요.

아래 예제는 python3 zircolite.py를 실행합니다. 도구가 생성한 환경을 활성화하거나, pdm run, uv run, poetry run을 앞에 붙이세요.

종속성

• 필수: orjson, xxhash, rich, rich-argparse, RestrictedPython, requests, urllib3, pySigma, evtx (pyevtx-rs), jinja2, lxml, chardet, psutil, pyyaml, py7zr, ijson, pyahocorasick, pyroaring
• py7zr는 .7z 입력을 열 때만 가져옵니다. ZIP, gzip, bzip2는 표준 라이브러리를 사용합니다.

⚠️ 먼저 C 컴파일러를 설치하세요

소스에서 설치하면 Zircolite의 평탄화 커널을 Cython으로 컴파일합니다. 하지만 C 컴파일러가 이미 있는 경우에만 그렇습니다. 컴파일러가 없으면 설치 자체는 성공하지만, 모든 실행에서 이벤트를 Python으로 평탄화하므로 더 느립니다. 바이너리와 Docker 이미지는 커널이 이미 컴파일된 상태로 빌드되므로 이 문제와 무관합니다.

따라서 pdm install 전에 툴체인을 설치하세요:

Cython 자체는 설치할 필요가 없습니다. 빌드 시 요구 사항으로, 격리된 빌드 환경으로 가져오며 사용자 환경에 추가되지 않습니다.

독립 실행형 바이너리

모든 릴리스는 플랫폼별 자체 포함 패키지를 게시합니다. 각 패키지는 자체 Python과 모든 종속성을 포함하므로 먼저 설치할 필요가 없습니다.

Intel Mac과 Alpine 같은 musl 기반 배포판에는 바이너리가 없습니다. 해당 환경에서는 Python 또는 Docker를 사용하세요.

unzip Zircolite-<version>-linux-x64.zip
cd Zircolite-<version>-linux-x64
./Zircolite --events sysmon.evtx --ruleset rules/rules_windows_merged.json

아래 예제에서 python3 zircolite.py를 실행 파일 경로로 바꾸세요.

바이너리는 코드 서명이 되어 있지 않습니다. macOS는 브라우저로 다운로드한 파일을 격리하고, 추출된 파일이 이 플래그를 상속받으면 Gatekeeper가 실행 파일과 _internal/의 모든 라이브러리를 차단합니다. 첫 실행 전에 전체 디렉터리에서 재귀적으로 해제하세요:

xattr -dr com.apple.quarantine Zircolite-<version>-macos-arm64

빠른 시작

다른 사람들이 만든 (오래된) 튜토리얼(영어, 스페인어, 프랑스어)은 여기에서 확인하세요.

EVTX 파일

도움말은 다음으로 확인할 수 있습니다:

# Don't forget to prefix with "pdm run" or "uv run" or "poetry run" when needed
python3 zircolite.py -h

EVTX 파일의 확장자가 ".evtx"인 경우:

# python3 zircolite.py --evtx <EVTX FOLDER or EVTX FILE> --ruleset <SIGMA RULESET> [--ruleset <OTHER RULESET>]
python3 zircolite.py --evtx sysmon.evtx --ruleset rules/rules_windows_merged.json

--ruleset은 생략할 수 있습니다. 이 경우 Zircolite는 Sysmon과 일반 Windows 채널을 포함하는 rules/rules_windows_merged.json을 사용합니다.

네이티브 Sigma 규칙(YAML) 사용

네이티브 Sigma 규칙(YAML)을 직접 사용할 수 있습니다:

# Single YAML rule
python3 zircolite.py --evtx sample.evtx --ruleset path/to/rule.yml

# Directory of Sigma rules
python3 zircolite.py --evtx sample.evtx --ruleset ./sigma/rules/windows/process_creation

# With pySigma pipelines
python3 zircolite.py --evtx sample.evtx --ruleset rule.yml --pipeline sysmon --pipeline windows-logsources

--pipeline-list는 설치된 파이프라인을 표시합니다. 설치되지 않은 파이프라인을 지정하면 규칙이 변환되기 전에 종료 코드 2와 함께 실행이 중단됩니다.

기타 로그 형식

Zircolite는 대부분의 경우 로그 형식을 자동 감지하므로 명시적 형식 플래그는 선택 사항입니다:

# Auto-detection (recommended) - Zircolite identifies the format automatically
python3 zircolite.py --events auditd.log --ruleset rules/rules_linux.json
python3 zircolite.py --events sysmon.log --ruleset rules/rules_linux.json
python3 zircolite.py --events <JSON_FOLDER_OR_FILE> --ruleset rules/rules_windows_merged.json

# Explicit format flags (override auto-detection)
python3 zircolite.py --events auditd.log --ruleset rules/rules_linux.json --auditd
python3 zircolite.py --events sysmon.log --ruleset rules/rules_linux.json --sysmon4linux
python3 zircolite.py --events <JSON_FOLDER_OR_FILE> --ruleset rules/rules_windows_merged.json --jsononly
python3 zircolite.py --events <JSON_FOLDER_OR_FILE> --ruleset rules/rules_windows_merged.json --json-array
python3 zircolite.py --events <CSV_FOLDER_OR_FILE> --ruleset rules/rules_windows_merged.json --csv-input
python3 zircolite.py --events <XML_FOLDER_OR_FILE> --ruleset rules/rules_windows_merged.json --xml-input

• --events 인수는 파일 또는 폴더일 수 있습니다. 폴더인 경우 현재 폴더와 하위 폴더의 모든 로그 파일이 선택됩니다(비활성화하려면 --no-recursion 사용).
• 파일 선택을 위한 사용자 정의 glob 패턴을 지정하려면 --file-pattern을 사용하세요.
• 자동 형식 감지를 비활성화하려면 --no-auto-detect를 사용하세요.

[!TIP] 도구를 사용해보고 싶다면 EVTX-ATTACK-SAMPLES(EVTX 파일)로 테스트할 수 있습니다.

Docker로 실행

# Pull the Docker image
docker pull wagga40/zircolite:latest
# If your logs and rules are in a specific directory
docker run --rm --tty \
    -v $PWD:/case/input:ro \
    -v $PWD:/case/output \
    wagga40/zircolite:latest \
    -e /case/input \
    -o /case/output/detected_events.json \
    -r /case/input/a_sigma_rule.yml

• $PWD를 로그와 규칙/규칙 세트가 저장된 디렉터리(절대 경로만)로 바꾸세요.
• Linux 호스트에서는 --user "$(id -u):$(id -g)"와 -l /case/output/zircolite.log를 추가하세요. 이미지는 권한 없는 사용자로 실행되므로 사용자가 소유한 디렉터리에 쓸 수 없습니다. Docker를 참조하세요.

자동 처리 최적화

여러 파일이 주어지면 Zircolite는 사용 가능한 RAM과 CPU를 기준으로 파일을 측정하고, 데이터베이스 모드(공유 데이터베이스 하나 또는 파일당 하나)를 선택하며, 병렬 처리가 가치가 있는지 판단한 다음 실행 중 메모리 압박에 따라 워커 수를 조정합니다.

python3 zircolite.py --evtx ./logs/ --ruleset rules/rules_windows_merged.json

--no-auto-mode, --unified-db(모든 파일에 대해 데이터베이스 하나, 파일 간 상관 규칙에 필요), --no-parallel 또는 --parallel-workers N으로 재정의할 수 있습니다. 선택 방식은 자동 처리 최적화를 참조하세요.

YAML 구성 파일 사용

복잡하거나 반복적인 분석 워크플로에는 YAML 구성 파일을 사용하세요:

# Generate a fully commented configuration file
python3 zircolite.py --generate-config my_config.yaml

# Run with it
python3 zircolite.py --yaml-config my_config.yaml

# CLI arguments override the file
python3 zircolite.py --yaml-config my_config.yaml --evtx ./other_logs/

생성된 파일은 지원되는 모든 키를 기본값으로 문서화합니다. config/zircolite_example.yaml은 동일한 파일로 저장소에 보관됩니다. 병합 규칙과 YAML에 해당하는 옵션이 없는 옵션은 YAML 구성을 참조하세요.

기본 규칙 세트 업데이트

python3 zircolite.py -U

소스에서 실행하면 저장소의 rules/를 다시 작성합니다. 독립 실행형 바이너리는 실행 파일 옆의 rules/ 디렉터리에 쓰고, 쓸 수 없는 경우 경고와 함께 작업 디렉터리의 ./rules로 폴백합니다.

또는 Task(go-task)를 사용하는 경우 프로젝트 루트에서 task update-rules를 실행하여 Zircolite-Rules-v2의 규칙을 업데이트할 수 있습니다. 다른 작업(Docker 빌드, 정리 등)은 docs를 참조하세요.

[!IMPORTANT]
이 규칙 세트는 Zircolite를 즉시 사용할 수 있도록 제공되지만, 노이즈가 많거나 느릴 수 있으므로 자체 규칙 세트를 생성하는 것이 좋습니다. 이 자동 업데이트 규칙 세트는 전용 저장소 Zircolite-Rules-v2에서 사용할 수 있습니다.

필드 분할 및 변환

두 가지 구성 기능이 이벤트가 수집될 때 형태를 결정하며, 둘 다 config/config.yaml에 있습니다:

• 필드 분할은 압축된 키-값 필드를 쿼리 가능한 필드로 변환합니다. Sysmon의 Hashes 필드(SHA1=abc123,MD5=def456,SHA256=789xyz)는 별도의 SHA1, MD5, SHA256 필드가 되어 규칙이 해시를 직접 일치시킬 수 있습니다.
• 필드 변환은 필드 값에 대해 샌드박스된 Python을 실행합니다. base64 명령줄 디코딩, IOC 추출, LOLBin 플래그 지정 등을 수행하며, 원본을 대체하지 않고 새 필드에 결과를 쓸 수 있습니다. Zircolite는 11개 범주에 걸쳐 55개를 제공하며, 두 개의 auditd 변환을 제외하고 기본적으로 비활성화되어 있습니다.

split:
  Hashes:
    separator: ","
    equal: "="

전체 구성, Zircolite가 제공하는 변환, 자체 변환 테스트 방법은 필드 분할 및 필드 변환을 참조하세요.

벤치마크

Zircolite는 세 도구 중 가장 빠릅니다: Hayabusa보다 2.1배, Chainsaw보다 9.8배 빠릅니다 — 그리고 Rust로 작성된 두 도구와 달리 Python으로 작성된 유일한 도구입니다.

동일한 4개의 Sysmon EVTX 파일(478 MB, 452,554개 이벤트), 각 도구를 자체 규칙과 함께 기본 설정으로, 10코어 Apple M1 Max에서 실행. 세 번 실행의 중앙값:

Zircolite는 그 속도를 위해 메모리를 교환합니다. 파일당 워커 프로세스 하나를 실행하며, 위 수치는 그 총합입니다. --no-parallel은 단일 프로세스로 유지합니다.

규칙 세트가 다르므로 탐지 수는 비교할 수 없습니다. 설정, 주의 사항, tools/tool-benchmark.py로 재현하는 방법은 벤치마크를 참조하세요.

문서

전체 문서는 여기에서 확인할 수 있습니다.

Mini-GUI

Mini-GUI는 완전히 오프라인으로 사용할 수 있습니다. 결과를 표시하고 검색할 수 있습니다. --package 옵션으로 Mini-GUI "패키지"를 자동 생성할 수 있습니다. 출력 디렉터리를 지정하려면 --package-dir을 사용하세요. Mini-GUI 사용 방법은 여기 문서를 확인하세요.

MITRE ATT&CK® 기법 및 심각도 수준별 탐지된 이벤트

탐지된 이벤트 타임라인

매트릭스에 표시된 MITRE ATT&CK® 기법별 탐지된 이벤트

튜토리얼, 참고 자료 및 관련 프로젝트

튜토리얼

• 영어: Russ McRee가 자신의 블로그에 SIGMA와 Zircolite에 대한 자세한 튜토리얼을 게시했습니다.

• 스페인어: César Marín이 스페인어 튜토리얼을 여기에 게시했습니다.

• 프랑스어: IT-connect.fr이 Zircolite에 대한 광범위한 튜토리얼을 프랑스어로 게시했습니다.

• 프랑스어: IT-connect.fr은 Zircolite를 사용한 Hack the Box 챌린지 풀이도 게시했습니다.

참고 자료

• Florian Roth는 2021년 10월 EU ATT&CK 워크숍에서의 발표 중 SIGMA Hall of Fame에서 Zircolite를 언급했습니다.
• Zircolite는 JSAC 2023에서 인용 및 발표되었습니다.
• Zircolite는 여러 연구 논문에서 인용 및 사용되었습니다:
  • CIDRE Team:
    • PWNJUTSU - Website
    • PWNJUTSU - Academic Paper
    • CERBERE: Cybersecurity Exercise for Red and Blue Team Entertainment, Reproducibility
  • Universidad de la República:
    • A Process Mining-Based Method for Attacker Profiling Using the MITRE ATT&CK Taxonomy

라이선스

• 프로젝트의 모든 코드는 GNU Lesser General Public License에 따라 라이선스됩니다.
• EVTX 파싱은 MIT 또는 Apache-2.0 라이선스의 evtx(pyevtx-rs)를 사용합니다. 릴리스 패키지는 번들된 모든 라이브러리와 라이선스를 THIRD_PARTY_LICENSES에 나열합니다.
• 규칙은 Detection Rule License (DRL) 1.1에 따라 배포됩니다.