eBPFと機械学習を活用した、Linux向けの振る舞い異常検知。
GuarddはLinuxホストの通常の振る舞いを学習し、そのベースラインから逸脱した アクティビティを検知します。カーネルセンサーがプロセスの実行と外向きTCP 接続の試行を収集し、Isolation Forestが生成された1分間のアクティビティ ウィンドウをスコアリングします。アラートにはスコア、振る舞いのコンテキスト、 調査を支援する説明が含まれます。
バックグラウンドデーモンが収集、学習、検知を処理します。デスクトップGUIと ターミナルインターフェースにより、デーモンが稼働し続ける間もアラートと リソース使用状況を確認できます。
ステータス: 実験的かつ活発に開発中です。検知品質はワークロード、 ベースライン、感度設定に依存します。
インストール · 使用方法 · 設定 · 仕組み · 更新 · トラブルシューティング
デスクトップのスクリーンショットでは、サンプルのアラートとシミュレートされた サービスの状態を使用しています。
付属のインストーラーはapt-getとsystemdを使用します。Ubuntu 24.04 LTSが
実用的な出発点です。Debianシステムでは同等のパッケージが必要です。その他の
ディストリビューションでは依存関係を手動でインストールする必要があります。
python3として利用可能なPython 3.11以降。Ubuntu 22.04のデフォルトの
Python 3.10はパッケージの要件を満たしません。/sys/kernel/btf/vmlinuxのBTF、および必要なプロセスとソケットの
トレースポイントを備えたLinuxカーネル。bpftool**。Ubuntuでは、インストーラーを実行する前にGitとカーネルツールをインストール してください:```bash sudo apt-get update sudo apt-get install -y git linux-tools-common "linux-tools-$(uname -r)" python3 --version bpftool version test -r /sys/kernel/btf/vmlinux && echo "Kernel BTF available"
kernel-tools パッケージは実行中のカーネルと一致している必要があります。Debian では、`bpftool` は別のパッケージとして利用可能です。インストーラーは他のビルドおよび Python 依存関係を提供しますが、`bpftool` を明示的にはインストールしません。
### デーモンとデスクトップ GUI のインストール```bash
git clone https://github.com/benny-e/guardd.git
cd guardd
sudo bash install.sh --gui
ヘッドレスインストールの場合は、代わりに sudo bash install.sh を実行してください。
インストーラーはアプリケーションを /opt/guardd にコピーし、仮想環境を作成し、eBPF コレクターをビルドし、/usr/local/bin/guardd をインストールし、起動時に guardd.service を有効化します。サービスは起動しません。--gui を指定すると、Qt ランタイム依存関係、デスクトップランチャー、アイコンもインストールされます。
初回起動の前に、インストール済みの設定ファイルを開きます:```bash sudoedit /opt/guardd/config.toml
`[paths]` セクションを絶対パスに設定します:```toml
[paths]
sensor_path = "/opt/guardd/ebpf/guardd"
db_path = "/opt/guardd/data/features.db"
model_path = "/opt/guardd/data/model.bundle"
リポジトリの設定は相対パスを使用しています。これらはサービスの
/opt/guardd 作業ディレクトリからは機能しますが、デスクトップランチャーは別の場所から起動する可能性があります。
絶対パスを使用すると、デーモン、GUI、CLI が同じデータを使用できます。
Configuration のトレーニング設定を確認してから、次を実行して開始します:```bash sudo systemctl start guardd.service systemctl status guardd.service sudo journalctl -u guardd.service -f
最初の実行では、モデルが利用可能になる前にデータを収集します。アクティブなサービスはまだこの収集フェーズにある可能性があります。トレーニングと検出についてはログを確認してください。
## 使用方法
### デスクトップ GUI
アプリケーションメニューから **Guardd** を開くか、次を実行します:```bash
guardd gui
GUI は通常のデスクトップユーザーとして実行します。既存のデータベースを読み取り、5 秒ごとに更新します。閉じてもデーモンは実行されたままです。
| ページ | できること |
|---|---|
| Overview | サービス、本日のアラート、モデルファイルの可用性、CPU/メモリ使用量、PID、稼働時間、ホスト/カーネルの詳細、60 秒ウィンドウサイズ、最近のテレメトリを確認できます。最近のアラートを選択して検査できます。 |
| Alerts | プロセス名、パス、宛先、理由を検索できます。重大度と、直近 24 時間、7 日間、30 日間、または全期間でフィルタリングできます。アラートを選択して、そのスコア、しきい値、説明、アクティビティ、コンテキストを表示できます。 |
即時更新には Refresh を使用します。時刻はローカルタイムゾーンで表示され、Overview の日次合計はフィルターとは独立してローカルの暦日を対象とします。
別のデータベースを選択したり、表示されるアラート上限を増やしたりするには:```bash guardd gui --db-path /opt/guardd/data/features.db --model-path /opt/guardd/data/model.bundle --limit 500
GUI は読み取り専用ビューアです。収集、トレーニング、サービスの制御はデーモンと CLI を通じて行われます。モデルの可用性とはファイルが存在することを意味し、その内容が有効であることや検出が開始されたことを意味するものではありません。GUI は pickle 化されたモデルを読み込みません。リソースメトリクスはセンサーを含む systemd サービス全体を対象とし、CPU 100% は 1 論理コアを表します。最初の CPU 読み取りには 2 回のサンプルが必要です。
### ターミナルインターフェース```bash
sudo guardd tui
TUI は 2 秒ごとに更新され、アラートの詳細とデーモンの統計情報を表示します。
GUI とは異なり、書き込み可能なデータベース接続を通じてストレージを初期化します。
標準の root 所有のインストールでは sudo が必要になる場合があります。
| キー | 操作 |
|---|---|
↑ / k、↓ / j | アラートを選択します。 |
/ | 検索。Enter で適用、Esc でキャンセルします。 |
r | 検索をクリアし、最初のアラートに戻ります。 |
q / Esc | 終了します。 |
sudo systemctl stop guardd.service sudo systemctl start guardd.service sudo systemctl restart guardd.service systemctl status guardd.service sudo journalctl -u guardd.service -n 100 --no-pager sudo journalctl -u guardd.service -f
設定を編集した後、サービスを再起動します。起動時の自動起動を有効または無効にするには、`sudo systemctl enable guardd.service` または
`sudo systemctl disable guardd.service` を使用します。
### CLI と手動操作
一度に1つのコレクターを実行します。手動で収集または検出する前に systemd サービスを停止し、手動コレクターを停止してからそのモデルをトレーニングします。
| コマンド | 目的 |
| --- | --- |
| `guardd` または `guardd daemon` | 自動収集 → トレーニング → 検出のライフサイクルを実行します。 |
| `guardd daemon --mode collect` | 自動トレーニングなしでウィンドウを収集します。 |
| `guardd daemon --mode detect` | 既存の互換モデルを使用してウィンドウをスコアリングします。 |
| `guardd collect` | ライブウィンドウを SQLite に収集します。 |
| `guardd train` | 保存されたウィンドウからモデルをトレーニングし、そのサマリーを出力します。 |
| `guardd detect` | ライブウィンドウをスコアリングし、アラートを発行します。 |
| `guardd ingest` | デバッグ用に解析されたセンサーイベントを出力します。 |
| `guardd gui` / `guardd tui` | デスクトップまたはターミナルインターフェースでアラートを閲覧します。 |
標準インストールからの手動ワークフローは次のとおりです:```bash
sudo systemctl stop guardd.service
sudo guardd collect --sensor-path /opt/guardd/ebpf/guardd --db-path /opt/guardd/data/features.db
# Press Ctrl+C after collecting enough representative activity.
sudo guardd train --db-path /opt/guardd/data/features.db --model-out /opt/guardd/data/model.bundle
sudo guardd detect --sensor-path /opt/guardd/ebpf/guardd --db-path /opt/guardd/data/features.db --model-path /opt/guardd/data/model.bundle
手動検出を停止するには Ctrl+C を押し、その後 systemd サービスを再起動してバックグラウンド動作を再開します。フォアグラウンドの自動デーモンには sudo guardd daemon を使用します。生のテレメトリには sudo guardd ingest --sensor-path /opt/guardd/ebpf/guardd --pretty を使用します。
任意のコマンドに --help を付けるとそのオプションが表示されます。検出は --print-all-scores、--print-features、--print-windows、--no-store をサポートしています。--no-store は特徴量ウィンドウの書き込みを無効にしますが、検出された異常は引き続き保存されます。
Guardd は次の順序で最初に存在するファイルを読み込みます：
./guardd.toml。/etc/guardd/config.toml。/opt/guardd/config.toml。ファイルはマージされません。チェックアウト内の config.toml はテンプレートであり、自動的に検出される開発用設定ではありません。ローカル環境で使用するには、それを guardd.toml にコピーしてパスを調整してください。
以下は、頻繁なブートストラップ試行とより長い初期トレーニング期間を設定したインストール済みシステムの例です：```toml [paths] sensor_path = "/opt/guardd/ebpf/guardd" db_path = "/opt/guardd/data/features.db" model_path = "/opt/guardd/data/model.bundle"
[logging] debug = false
[daemon] mode = "auto" bootstrap_retry_seconds = 600 retrain_interval_seconds = 604800 print_windows = false print_features = false print_all_scores = false no_store = false
[train] min_training_rows = 1380 baseline_fraction = 0.2 limit = 50000 contamination = 0.01 n_estimators = 200 random_state = 42 threshold_percentile = 10.0
[gui] limit = 200