コンテンツにスキップ

API 概要と認証

CSIRT-Pro は REST API を提供する。 取り込み、検索、ケース管理、組織設定など主要機能をプログラムから操作できる。

API は役割ごとに分かれた複数のサービスで構成される。 取り込みと検索を担う高性能なコア API1 と、組織やユーザー、取り込み定義、Playbook などの設定を担う管理 API が中心である。 生成 AI 機能は別のバックエンドサービスが担う。

ベース URL

https://<your-domain>/api/

高性能な取り込みと検索を担うコア API:

https://<your-domain>/api/v2/

認証方式

OAuth2 / OIDC (SSO)

認証基盤（OIDC ベースの IdP）を用いた OAuth2 Authorization Code フロー（PKCE 対応）で SSO を行う。

ログインフロー

  1. クライアントが GET /api/auth/login/?json=1 を呼び出し、認証 URL を取得する。
  2. ユーザーが認証画面でログインする（認証基盤の IdP）。
  3. 認証コード付きでリダイレクトされる。
  4. クライアントが GET /api/auth/callback/?code=xxx でコールバックを受ける。
  5. サーバーがトークン交換を行い、jwt Cookie をセットする。

トークン

トークン 有効期限 用途
Access Token 24 時間 API リクエストの認証
Refresh Token 1 日 Access Token の更新

Cookie 名

Web セッションの JWT は Cookie jwt として設定される（access_token ではない）。 トークン交換（POST /api/auth/token/）はログイン成功時に 201 を返す。 この Cookie は管理 API とコア API の双方で認証に使われる。

セッション JWT は署名付きトークンとしてサーバー側で検証する。

API キー

プログラムからのアクセスには API キーを使う。

curl -H "X-API-Key: <api_key>" \
  https://<domain>/api/user/<user_id>/search/

API キーは 組織管理画面 から作成する。 権限は scope で制御される。

Web UI では jwt Cookie によるセッション認証を使う。

curl -H "Cookie: jwt=<jwt_token>" \
  https://<domain>/api/user/<user_id>/search/

認証 API エンドポイント

ログイン開始

SSO ログインフローを開始する。

GET /api/auth/login/

クエリパラメータ:

パラメータ 型 説明
json string 1 を指定すると JSON で auth_url を返す

レスポンス:

{
  "auth_url": "https://idp.example.com/oauth/v2/authorize?..."
}

コールバック

OAuth2 コールバックを処理する。

GET /api/auth/callback/

トークン交換

認証コードを JWT トークンに交換する。 成功時は 201 を返す。

POST /api/auth/token/

リクエストボディ:

{
  "email": "user@example.com",
  "password": "********"
}

レスポンス:

{
  "userid": "user-uuid",
  "username": "user@example.com"
}

トークンリフレッシュ

Access Token を更新する。

POST /api/auth/refresh/

ログアウト

セッションを無効化する。

POST /api/auth/logout/

認証ステータス確認

現在の認証状態を確認する。

GET /api/auth/status/

レスポンス:

{
  "authenticated": true,
  "user_id": "user-uuid",
  "organization_id": "org-uuid"
}

現在のユーザー情報

GET /api/auth/current-user/

Passkey (WebAuthn) API

提供状況

Passkey は認証基盤を経由した限定サポートである。 me/passkeys（一覧、登録、検証、削除）として提供される。 下記の独立した Passkey ログイン用ルートは環境によって無効化されている場合がある。 最新の有効ルートは実装で確認すること。

登録オプション取得

POST /api/auth/passkey/register/options/

登録完了

POST /api/auth/passkey/register/

ログインチャレンジ取得

POST /api/auth/passkey/login/options/

ログイン完了

POST /api/auth/passkey/login/

共通ヘッダー

ヘッダー 説明
Content-Type application/json
Cookie jwt=<jwt>
X-API-Key <api_key>（API キー利用時）
X-SOCEngine-Tags タグフィルタ（JSON 形式）

エラーレスポンス

API エラーは次の形式で返る。

{
  "error": "エラーメッセージ",
  "detail": "詳細な説明"
}

HTTP ステータスコード

コード 説明
200 成功
201 作成成功（ログイン成功を含む）
400 リクエスト不正
401 認証エラー
403 権限不足
404 リソースが見つからない
429 レート制限超過
500 サーバーエラー

レート制限

組織ごとにリクエストレート制限が設定される。 制限に達すると 429 Too Many Requests が返る。 制御状態はインメモリデータストアで管理される。

現在のスロットル状態は次のエンドポイントで確認できる。

GET /api/user/<user_id>/organization/throttle/

生成 AI 機能の API

生成 AI 機能（AI Investigate、ケースの AI 分析など）は、コア API や管理 API とは別の AI バックエンドサービスが担う。 フロントエンドは設定された API URL 経由でアクセスする。 このサービスは独立して稼働する。 環境によっては未起動の場合があり、その際は AI 機能のみ利用できない。

主なエンドポイントの概要を示す。

パス 用途
POST /analyze/alert/{user_id} アラートの自律調査と FP/TP 判定レポート生成
POST /ask/stream/chat/{user_id} AI アシスタント（SSE ストリーミング、ツール実行型）
POST /ask/{user_id} / POST /generate/prql/{user_id} 自然言語からの検索 / PRQL 生成
POST /generate/messages-filter/{user_id} 自然言語からケース検索フィルタを生成
POST /generate/playbook/{user_id} 自然言語から SOAR Playbook の編集案を生成

AI は対応を自動実行しない

生成 AI はマネージド生成 AI 基盤上の大規模言語モデルを利用する。 調査と提案は読み取り専用で行われる。 書き込みを伴うのは SOAR 申請（submit_case_soar）のみで、適用は承認制である（申請 → 承認 → 適用）。 AI が対応、修復、通信遮断、ケースのクローズを自動実行することはない。

OpenAPI ドキュメント

Swagger UI と ReDoc による API ドキュメントも利用できる。

URL 説明
/swagger/ Swagger UI
/swagger.json OpenAPI スペック (JSON)
/swagger.yaml OpenAPI スペック (YAML)
/redoc/ ReDoc UI

  1. 検索（PRQL）、ログ取り込み、HEC 互換取り込み、認証検証、レート制御、課金リソース制御、監査を担うネイティブ実装のサービス。後述の /api/v2/ がこのコア API に対応する。 ↩