SuricataLog

Suricata の使い方を学び始めたとき、eve.json ファイルを検査するためのツールが必要だとすぐに気づきました。世の中のチュートリアルやドキュメントのほとんどは、以下のタスクを実行するためのスタックをインストールすることを勧めていました：

1. ログを中央の場所に保存する
2. イベント、特にアラートを正規化およびエンリッチする
3. フロントエンドを使ってデータを深掘りする

これは非常に便利ですが、イベントをさっと確認したいだけの場合はどうでしょうか？

遅かれ早かれ、以下のような作業に飽き飽きすることになるでしょう：

cat eve.json | jq -r -c 'select(.event_type=="alert")|.payload'| base64 --decode

SuricataLog は、Suricata のログファイル（/var/log/suricata/eve.json など）を解析して表示するためのツール/スクリプトのセットです。

Eve JSON フォーマットはそれほど複雑ではないので、自宅ネットワークの分析に最も役立つと思う機能を備えたいくつかのスクリプトを書きました。

おまけとして、Suricata について学び、テストする方法を学べるチュートリアルとして学習体験を書きました。

Pypi からのインストール

Pypi.org からのインストール

uv pip install SuricataLog

ソースからのインストール

git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
uv build
uv pip install dist/suricatalog-1.1.6-py3-none-any.whl

開発者向けインストール

貢献したいですか？あるいはバグを見つけてパッチを提出できると思いますか？素晴らしい！開発モードで実行するためにできることは以下の通りです：

git clone [email protected]:josevnz/SuricataLog.git
cd SuricataLog
uv build
uv sync --dev
uv pip install --editable .

その後、ユニットテストの実行は非常に簡単です：

(SuricataLog) [josevnz@dmaf5 SuricataLog]$ python -m unittest test/*.py
.........
----------------------------------------------------------------------
Ran 9 tests in 0.334s

OK

ユニットテストが失敗する場合、おそらくそこが最初に修正すべき場所です。

また、textualize コンソールを実行してコンソールメッセージを監視することもお勧めします：

# textual console
textual console --exclude SYSTEM --exclude EVENT

そして別のターミナルで：

textual run --dev --command eve_log --timestamp '2015-01-01 10:41:21.642899' test/eve.json

これにより、コンソールにデバッグメッセージも出力されます（コンソールを '--exclude DEBUG' で再起動すれば、これらを除外できます）

Docker イメージの作成

詳細については DOCKER.md を確認してください。

スクリプトの実行

仮想環境にすべてがインストールされると、スクリプトを呼び出せるようになります。

仮想環境をアクティベートした後、オートコンプリートを使ってインストールされたアプリケーションを確認できます：

eve_[tab][tab]

また、Bash オートコンプリート拡張機能をインストールすると、フラグの候補も表示されます。

シンプルな EVE ログパーサー

実際に自分で見てみるのが一番です（サポートされているオプションを確認するには --help を使ってください）

テーブル形式：

eve_log --timestamp '2015-01-01 10:41:21.642899' --formats TABLE test/eve.json

eve_json.py による定型レポート

(suricatalog) [josevnz@dmaf5 SuricataLog]$ eve_json --help
usage: eve_json [-h] [--nxdomain | --payload | --flow | --netflow NETFLOW | --useragent] eve [eve ...]

This script is inspired by the examples provided on [15.1.3. Eve JSON ‘jq’ Examples](https://suricata.readthedocs.io/en/suricata-6.0.0/output/eve/eve-json-
examplesjq.html) A few things: * The output uses colorized JSON

positional arguments:
  eve                Path to one or more /var/log/suricata/eve.json file to parse.

optional arguments:
  -h, --help         show this help message and exit
  --nxdomain         Show DNS records with NXDOMAIN
  --payload          Show alerts with a printable payload
  --flow             Aggregated flow report per protocol and destination port
  --netflow NETFLOW  Get the netflow for a given IP address
  --useragent        Top user agent in HTTP traffic

以下のいくつかの例を見てください：

NXDOMAIN

eve_json --nxdomain test/eve.json

PAYLOAD

eve_json --payload ~/Downloads/eve.json

FLOW

eve_json --flow test/eve_udp_flow.json

NETFLOW

eve_json --netflow 224.0.0.251 test/eve_udp_flow.json

USERAGENT

eve_json --useragent test/eve.json

eve_* アプリケーションをブラウザで実行する

eve_server ラッパーを使うことで、Suricata Log アプリケーションをブラウザで実行できます：

# Show the flow report on a eve.json file
eve_server --application eve_json -- --flow ~/eve.json

# Show NX domain report
eve_server --application eve_json -- --nxdomain ~/eve.json

# Inspect the eve.json records
eve_server --applications eve_log -- ~/eve.json

これらのオプションが呼び出したい基盤の eve_* に属することをサーバーに伝えるために '--' を渡す必要があります。

Docker からの実行

Docker コンテナから SuricataLog を実行することも可能です。詳細については DOCKER.md を参照してください。

uv での実行

uv があれば、次のようにするだけです：

uvx --from SuricataLog eve_log /var/log/suricata/eve.json
uvx --from SuricataLog eve_json --useragent /var/log/suricata/eve.json
uvx --from SuricataLog eve_server --application eve_json -- --flow /var/log/suricata/eve.json

要領はお分かりいただけるでしょう。

Bash オートコンプリート

8.6 Programmable Completion にできるだけ従うようにしました。

最も一般的なフラグのオートコンプリートを提供しています。すべてのフラグは、いずれかのスクリプトに '--help' を渡すことで確認できます。

オートコンプリートコマンドのインストール

すべての SuricataLog スクリプトに対して Bash オートコンプリートをインストールできます。'eve_autocomplete' を実行して指示に従ってください：

eve_autocomplete --help

サポートされているバージョン

私はこのプロジェクトを余暇に取り組んでおり、世の中のすべての Linux/Python の組み合わせをサポートすることはできません。 これは現在のテスト環境であり、予告なく変更される可能性があります。

SuricataLog	Supported	OS	Python	Suricata
<= 0.8	NO	NA	< 3.8	6.04
0.9+	NO	fedora 37	=> 3.11.4	6.04
0.9+	NO	Armbian 23.02.2 Jammy	=> 3.10.6	6.04
0.9+	NO	Ubuntu 20.04.4 LTS (Focal Fossa)	=> 3.8.10	6.04
1.0.3+	YES	fedora 40	=> 3.11.4	7.0.6

以下のことを歓迎します：

• 新機能やバグ修正を含むパッチの提出。
• バグレポートの作成。できるだけ詳細に記述してください。そうでなければ、クローズするしかありません。

チュートリアル

• Suricata, RaspberryPI4 and Python to secure your home network
• Using SuricataLog to analyze your events