UEBA API

共通仕様

認証・エラー形式・レート制限・共通ヘッダーは API 概要・認証を参照してください。

UEBA（User and Entity Behavior Analytics）の設定とアセット管理を行う API です。

ここでいう UEBA は、スケジュール実行される検知タスクの管理機能です。各タスクは参照先の Playbook を定期的に起動します。検知ロジックは参照先の Playbook 側にあります。次の専用エンジンは内蔵していません。

統計的ベースライン
機械学習による異常スコアリング
ジオロケーション異常検知

UEBA 設定取得

GET /api/user/<user_id>/UEBA/

レスポンス例:

{
  "task_groups": [
    {
      "type": "group",
      "group_id": "grp-001",
      "group_name": "Authentication Monitoring",
      "description": "認証関連の検知タスクのグループ",
      "playbook_ids": [123, 124],
      "playbook_count": 2,
      "isEnabled": true,
      "interval": 60,
      "asset_count": 1,
      "has_credentials": true
    }
  ],
  "tasks": [
    {
      "type": "task",
      "playbook_id": 125,
      "title": "Brute Force Detection",
      "description": "ブルートフォース攻撃の検知",
      "isEnabled": true,
      "interval": 5,
      "asset_count": 0,
      "has_credentials": false
    }
  ]
}

Note

interval は分単位の整数です。UEBA 設定は組織単位で管理されます。

UEBA 設定更新

PUT /api/user/<user_id>/UEBA/

リクエストボディ:

{
  "task_groups": [
    {
      "group_id": "grp-001",
      "isEnabled": true,
      "interval": 60
    }
  ],
  "tasks": [
    {
      "playbook_id": 125,
      "isEnabled": true,
      "interval": 5
    }
  ]
}

interval は分単位の整数です。成功時のレスポンスは {"message": "update success"} です。

Note

interval を現在の値と異なる値に変更することはできません。異なる値を指定した場合は 403 (Permission denied) が返ります。この API で変更できるのは isEnabled のみです。

アセット管理

アセット一覧

GET /api/user/<user_id>/ueba/assets/

クエリパラメータ:

パラメータ	説明
`q`	名前の部分一致で絞り込み
`page`	ページ番号（既定 1）
`size`	1 ページあたりの件数（既定 50、最大 200）

レスポンス例:

{
  "total": 1,
  "page": 1,
  "size": 50,
  "items": [
    {
      "id": "asset-001",
      "name": "web-server-01",
      "description": "",
      "owner_uuid": "<組織UUID>",
      "created_at": "2025-01-01T00:00:00",
      "has_secret": true
    }
  ]
}

アセット作成

POST /api/user/<user_id>/ueba/assets/

リクエストボディ:

{
  "name": "web-server-01",
  "description": "説明（任意）",
  "credentials": {"username": "...", "password": "..."}
}

name は組織内で一意です（重複時は 400）。 credentials は任意の JSON オブジェクトで、暗号化ストアに保存されます。成功時は 201 が返ります。

アセット更新

PUT /api/user/<user_id>/ueba/assets/<asset_id>/

リクエストボディはアセット作成と同じフィールド（name / description / credentials）を受け付けます。いずれのフィールドも任意です。

アセット削除

DELETE /api/user/<user_id>/ueba/assets/<asset_id>/delete/

タスクとアセットのリンク

タスクのアセット一覧

GET /api/user/<user_id>/ueba/tasks/<playbook_id>/assets/

アセットのリンク

POST /api/user/<user_id>/ueba/tasks/<playbook_id>/assets/link/

リクエストボディ:

{
  "asset_id": "asset-001"
}

単一アセットをリンクします（リンク済みの場合は変更されません）。複数アセットをまとめて設定する場合は後述の「アセット同期」を使用してください。

アセットのリンク解除

DELETE /api/user/<user_id>/ueba/tasks/<playbook_id>/assets/<asset_id>/

アセット同期

PUT /api/user/<user_id>/ueba/tasks/<playbook_id>/assets/sync/

リクエストボディ:

{
  "asset_ids": ["asset-001", "asset-002"]
}

指定した集合でリンクを置き換えます（同期）。

グループアセット管理

グループのアセット一覧

GET /api/user/<user_id>/ueba/groups/<group_id>/assets/

グループアセット同期

PUT /api/user/<user_id>/ueba/groups/<group_id>/assets/sync/

リクエストボディ:

{
  "asset_ids": ["asset-001", "asset-002"]
}

指定した集合でリンクを置き換えます（同期）。グループアセット同期はグループ内の各タスクにも反映されます。

UEBA テンプレート（管理者向け）

テンプレート一覧

GET /api/ueba-templates/

テンプレート作成

POST /api/ueba-templates/

リクエストボディ:

{
  "playbook_id": 123,
  "title": "Brute Force Detection",
  "description": "説明",
  "isDefaultSet": true
}

playbook_id・title・isDefaultSet は必須です。同一 playbook_id のテンプレートが存在する場合は上書きされます。

全テンプレート取得

GET /api/ueba-templates/get_all_templates/

テンプレート追加と全組織同期

POST /api/ueba-templates/add_and_sync/

テンプレートを作成し、すべての組織へ配信します。リクエストボディは「テンプレート作成」と同じです。