設定の変更

config.yml の全項目リファレンスと Settings ページの使い方

設定変更

URSUS の動作設定は config.yml 1 ファイルに集約されています。 これを編集する方法が 2 つあります。

Settings ページの使い方

ブラウザから http://127.0.0.1:8080/settings にアクセスすると、 config.yml の全項目がフォームとして表示されます。

画面構成

• amber バナー: 「保存後はプロセス再起動が必要」リマインダ
• セクション別カード: database / sensor / detector / ui / logging が個別カードに分かれる
• Save ボタン: 入力値を JSON で POST /settings に送信。Pydantic 検証 → 通れば config.yml をアトミック書き込み
• Reload from disk: フォームの編集中身を破棄して、ディスクから読み直す（= ページリロード）
• 「現在のディスク上の config.yml」: ページ末尾の details で生 YAML を読み取り専用表示

バリデーション

Save 時に型違反や制約違反があれば、ページ上部に赤いバナーでエラー一覧が出ます。

入力エラーがあります:
  • ui.bind_host — Value error, ui.bind_host must be loopback; got '0.0.0.0'
  • database.retention_days — Input should be a valid integer

エラーが残っている間は config.yml は書き換わりません。

設定項目リファレンス

database

sensor.hostname

sensor.process

プロセスコレクタは netlink (cn_proc) で kernel から push 通知を受けます。 ポーリング間隔等の設定はありません。詳細は Process Collector。

sensor.file

sensor.network

sensor.auth

detector

detector.response

使用可能なアクション一覧

ui

logging

systemd で常駐させる

URSUS は scripts/install.sh によって systemd ユニットとして登録できる。 インストール後は 3 つの service unit (ursus-sensor / ursus-detector / ursus-ui) が /etc/systemd/system/ に配置される。

インストール

$ git clone https://github.com/<user>/ursus.git
$ cd ursus
$ sudo ./scripts/install.sh

インストールスクリプトの動作:

1. システムユーザー ursus を作成 (UI の実行アカウント)
2. リポジトリ内容を /opt/ursus/ に rsync (.git / .venv / data / docs は除外)
3. /opt/ursus/.venv/ に venv を作って pip install -e
4. 権限を設定 (sensor/detector は root、UI は ursus user で動作)
5. systemd ユニットを /etc/systemd/system/ に配置し daemon-reload

起動と停止

start.sh は 3 サービスを順に起動して状態を 1 行ずつ表示する。

$ sudo /opt/ursus/scripts/start.sh

>>> starting URSUS
status:
  ursus-sensor         active
  ursus-detector       active
  ursus-ui             active

  ui   :  http://127.0.0.1:8080/
  logs :  journalctl -u ursus-sensor -u ursus-detector -u ursus-ui -f

$ sudo /opt/ursus/scripts/stop.sh

boot 時自動起動を有効化

start.sh は単に起動するだけで boot 時の自動起動は設定しない。 有効化するには systemctl enable を直接実行する。

$ sudo systemctl enable ursus-sensor ursus-detector ursus-ui

状態とログの確認

アンインストール

# 既定: data / config.yml / rules / quarantine を残してコードのみ削除
$ sudo /opt/ursus/scripts/uninstall.sh

# 完全削除 (data / config.yml / rules / quarantine / ursus ユーザーまで消す)
$ sudo /opt/ursus/scripts/uninstall.sh --purge

インストールレイアウト

/opt/ursus/                  root:root  755
├── src/                     # コード本体
├── rules/                   # 検知ルール YAML
├── systemd/                 # service ファイル原本 (参照用に同梱)
├── scripts/                 # start.sh / stop.sh / uninstall.sh / measure_resources.py
├── .venv/                   # 仮想環境 (pip install -e で配置)
├── config.yml               root:ursus 660  # ui (ursus) が Settings 経由で書く
└── data/                    root:ursus 770  # sensor が書き、detector/ui が読む
    ├── edr.db               root:ursus 660  (UMask=0027 で sensor が作成)
    ├── edr.db-wal
    └── edr.db-shm

/var/quarantine/ursus/       root:root  700  # detector の quarantine_file 移動先

/etc/systemd/system/
├── ursus-sensor.service
├── ursus-detector.service
└── ursus-ui.service

サンドボックス設定

各 unit は systemd のサンドボックス機能で隔離されている。主要な設定:

主要な設定の根拠

• PrivateTmp=false (sensor / detector): PrivateTmp=true は unit ごとに名前空間付きの /tmp を割り当てるため、他プロセスが本来の /tmp で行う活動を観測 (sensor) / 操作 (detector の quarantine_file) できなくなる。
• UMask=0027 (sensor): SQLite の WAL/SHM ファイルが root:ursus 660 の権限で 作成されるよう調整するため。これがないと UI (ursus user) が DB を読めない。
• ProtectHome=read-only (sensor): file_collector が /home 配下を inotify で監視するため マウント自体は必要。読み取り専用で十分。
• ProtectHome 未指定 (detector): quarantine_file の対象が /home 配下になる場合があるため。
• ProtectSystem=full (detector): strict にすると /tmp 等への書込ができず quarantine_file が失敗する。full なら /usr / /boot / /etc のみ ro。
• ReadWritePaths=/opt/ursus (ui): Settings からの保存で config.yml.tmp をディレクトリ内に 作成 → rename するアトミック書込のため、ファイル単体ではなく ディレクトリへの書込権が必要。実体ファイルレベルの書込制御は chmod 660 config.yml 側で担保。

設定変更を反映する

config.yml を保存しただけではプロセスは新しい設定を読みません。 反映させるには各プロセスを再起動します。

systemd で動かしている場合

# sensor の watch_paths を変更したら sensor だけ再起動
$ sudo systemctl restart ursus-sensor

# 全部まとめて再起動
$ sudo systemctl restart ursus-sensor ursus-detector ursus-ui

# または stop+start ラッパーで
$ sudo /opt/ursus/scripts/stop.sh
$ sudo /opt/ursus/scripts/start.sh

手動起動の場合

各ターミナルで Ctrl-C → 再度コマンド実行。

$ sudo .venv/bin/ursus-sensor   --config config.yml
$ .venv/bin/ursus-detector  --config config.yml
$ .venv/bin/ursus-ui        --config config.yml

YAML 直接編集の注意点

インデント

YAML はインデントが意味を持ちます。タブは使わずスペース 2 つに統一してください。

リスト記法

list<string> のフィールドは - プレフィックスで列挙します。Settings ページの textarea で 1 行 1 値を入れると、保存時にこの形式に変換されます。

watch_paths:
  - /etc
  - /tmp

特殊文字を含むパターン

glob (*) や正規表現で : や # を含む値はクォートが必要です。

exclude_patterns:
  - "*.swp"
  - "*/.cache/*"

コメント

# 以降がコメント。手書きで残しても、Settings ページから保存すると URSUS の正規コメントに置き換わります。コメントを死守したい場合は直接編集を続けてください。

トラブルシューティング

Detector / UI が起動直後に終了する

config.yml の Pydantic バリデーションに失敗していることが多いです。エラーメッセージを確認してください:

pydantic_core._pydantic_core.ValidationError: 1 validation error for Config
ui.bind_host
  Value error, ui.bind_host must be loopback; got '0.0.0.0'
    [type=value_error, input_value='0.0.0.0', input_type=str]

このケースは ui.bind_host をループバックに戻せば解消します。

Settings から保存ボタンが反応しない

ブラウザの開発者ツールで Console / Network タブを確認してください。

• POST /settings が 400 → 入力エラー (バナーにも表示される)
• POST /settings が 500 → サーバ側エラー (ui プロセスのログ確認)
• そもそもリクエストが飛んでいない → JS エラー

config.yml が「読み取り専用 DB」エラーで保存できない

ui プロセスを root ではなく一般ユーザーで動かしていて、config.yml が root 所有になっているケース:

$ sudo chown $USER:$USER config.yml

変更を保存したのに動作が変わらない

プロセス再起動を忘れていないか確認してください。Settings ページの amber バナー、および各プロセスのログ最初の数行で、現在ロード中の値を確認できます。

関連ドキュメント

• インストールと実行 — 最初の起動と最初のアラート
• 検知ルールの定義 — config.yml ではなく rules/*.yml でルール記述
• レスポンス動作 — allowed_actions の各アクション詳細