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 秒で処理 — 同じログに対して Hayabusa より 2.1 倍、Chainsaw より 9.8 倍高速です (いずれも Rust 製ツール)。ベンチマークを参照してください。
• ログタイプの自動検出: マジックバイト、コンテンツ解析、正規表現ベースのフォールバックを使用してログ形式とタイムスタンプフィールドを自動的に識別します -- ほとんどの場合、形式フラグを指定する必要はありません。
• 複数の入力形式: EVTX、JSON Lines、JSON 配列、CSV、XML など、さまざまなログ形式をサポートします。圧縮またはアーカイブされたログ (gzip、bzip2、ZIP、7-Zip) もサポートされ、暗号化された ZIP/7z には --archive-password を使用します。
• ネイティブ Sigma サポート: Zircolite は pySigma で変換することで、ネイティブな Sigma ルール (YAML) を直接使用できます。
• SIGMA バックエンド: SIGMA バックエンド (SQLite) に基づいており、内部で SIGMA から何かへの変換は行いません。
• 高度なログ操作: 入力ログをフィールド分割や変換によって操作でき、より柔軟で強力なログ分析が可能です。
• フィールド変換: 処理中にフィールドへカスタム Python 変換を適用できます (例: Base64 デコード、16 進数から 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 は rules/rules_windows_merged.json を使用し、 これは Sysmon と一般的な Windows チャネルをカバーします。

ネイティブ 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 に対して測定し、 データベースモード (共有データベース 1 つ、またはファイルごとに 1 つ) を選択し、それらを並列で 処理する価値があるかどうかを判断します — その後、実行中にメモリ負荷に応じてワーカー数を適応させます。

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

--no-auto-mode、--unified-db (すべてのファイルに対して 1 つのデータベース。これはファイル間相関ルールが必要とするものです)、--no-parallel、または --parallel-workers N で上書きできます。選択がどのように行われるかは Automatic Processing Optimization を参照してください。

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 configuration を参照してください。

デフォルトルールセットの更新

python3 zircolite.py -U

ソースから実行する場合、これはリポジトリの rules/ を書き換えます。スタンドアロンバイナリは 実行ファイルの隣にある rules/ ディレクトリに書き込み、そこに書き込めない場合は警告とともに 作業ディレクトリの ./rules にフォールバックします。

あるいは、Task (go-task) を使用している場合は、プロジェクトルートから task update-rules を実行して Zircolite-Rules-v2 からルールを更新します。その他のタスク (Docker ビルド、クリーンなど) については docs を参照してください。

[!IMPORTANT]
これらのルールセットは Zircolite をすぐに使えるように提供されていますが、独自のルールセットを生成すべきです。ノイズが多かったり遅かったりする可能性があるためです。これらの自動更新されるルールセットは専用リポジトリ Zircolite-Rules-v2 で入手できます。

フィールド分割と変換

取り込み時にイベントを形成する 2 つの設定機能があり、どちらも config/config.yaml にあります:

• フィールド分割は、詰め込まれたキーと値のフィールドをクエリ可能なフィールドに変換します。Sysmon の Hashes フィールド (SHA1=abc123,MD5=def456,SHA256=789xyz) は、個別の SHA1、MD5、SHA256 フィールドになり、ルールがハッシュを直接マッチできるようになります。
• フィールド変換は、フィールドの値に対してサンドボックス化された Python を実行します — base64 コマンドラインのデコード、IOC の抽出、LOLBin のフラグ付けなど — そして元の値を置き換えるのではなく、結果を新しいフィールドに書き込むことができます。Zircolite には 11 カテゴリにわたる 55 個の変換が同梱されており、2 つの auditd 用を除いてデフォルトでは無効です。

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

完全な設定、Zircolite が同梱する変換、および独自の変換をテストする方法については、Field Splitting と Field Transforms を参照してください。

ベンチマーク

Zircolite は 3 つの中で最速です: Hayabusa より 2.1 倍、Chainsaw より 9.8 倍高速 — そして Rust で書かれた 2 つのツールに対して、Python で書かれた唯一のツールです。

同じ 4 つの Sysmon EVTX ファイル (478 MB、452,554 イベント) を、各ツールをデフォルト設定で それぞれのルールとともに使用し、10 コアの Apple M1 Max で実行。3 回の実行の中央値:

Zircolite はその速度と引き換えにメモリを使用します。ファイルごとに 1 つのワーカープロセスを 実行し、上記の数値はその合計です。--no-parallel は単一プロセスに抑えます。

ルールセットが異なるため、検出数は比較できません。セットアップ、注意事項、および tools/tool-benchmark.py で再現する方法については Benchmark を参照してください。

ドキュメント

完全なドキュメントはこちらで入手できます。

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 チャレンジの write-up も公開しています。

参考文献

• Florian Roth は 2021 年 10 月の EU ATT&CK Workshop での講演中に、自身の 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 の解析には evtx (pyevtx-rs) を使用しており、MIT または Apache-2.0 ライセンスの下にあります。リリースパッケージには、同梱されるすべてのライブラリとそのライセンスが THIRD_PARTY_LICENSES に記載されています。
• ルールは Detection Rule License (DRL) 1.1 の下でリリースされています。