Go to Qiita Advent Calendar Top
LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@Chisho

Keeper管理者向けREST APIで監査イベントを取得する（お試し編）

Posted at

この記事では、Keeper管理者向けREST API を使って監査イベントを取得する手順をまとめます。

具体的には、

  1. Keeperコマンダーで APIトークンの生成
  2. Scalarから Keeper管理者向けREST API /public/events を呼び出して 監査イベント を取得
  3. Python スクリプトで audit_event = "open_record" のイベントだけをフィルタリング

という流れで解説します。

1. Keeperコマンダーで APIトークンの生成

まずは、Keeper管理者向けREST API を呼び出すために APIトークンを生成します。これは Keeperコマンダーの public-api-key コマンドから実行できます。

1-1. 既存の APIトークンを確認

My Vault> public-api-key list

public-api-key list を実行すると、Enterprise ID ごとに現在有効な APIトークンが次のようなテーブル形式で一覧表示されます。

Enterprise ID  Name              Status    Issued Date          Expiration Date      Integration
------------   ----------------  --------  -------------------  -------------------  -------------
        1234   SIEM Integration  Active    2025-12-06 19:52:06  2026-01-05 19:52:03  SIEM:1

1-2. ヘルプの確認

My Vault> public-api-key generate --help
usage: public-api-key generate [-h] --name NAME --integrations INTEGRATIONS [--expires {24h,7d,30d,1y,never}]
                               [--format {table,json}] [--output OUTPUT]

Generate a new enterprise API key.

options:
  -h, --help            show this help message and exit
  --name NAME           API key name. Examples: "SIEM Integration", "Billing Tool", "Backup Tool", "Monitoring
                        Service"
  --integrations INTEGRATIONS
                        Integration with action type. Format: "RoleName:ActionType" Available integrations: SIEM,
                        BILLING Action types: 1=READ (read-only), 2=READ_WRITE (full access) Examples: --integrations
                        "SIEM:2" # SIEM role with read-write access --integrations "SIEM:1" # SIEM role with read-only
                        access --integrations "BILLING:2" # BILLING role with read-write access --integrations
                        "BILLING:1" # BILLING role with read-only access
  --expires {24h,7d,30d,1y,never}
                        Expiration time for the API key: 24h = 24 hours from now (temporary access) 7d = 7 days from
                        now (short-term projects) 30d = 30 days from now (monthly integrations) 1y = 1 year from now
                        (long-term integrations) never = never expires (permanent access, use with caution) Default:
                        never
  --format {table,json}
                        Output format: table = human-readable table format (default) json = JSON format for
                        programmatic use
  --output OUTPUT       Output file name (only used with --format json). Examples: --output api_key.json --output
                        /path/to/keys/siem_key.json If not specified, JSON output is printed to console.

Examples:
  # Generate API key with SIEM role and 30-day expiration
  public-api-key generate --name "SIEM Integration" --integrations "SIEM:2" --expires 30d

  # Generate API key with BILLING role and 24-hour expiration
  public-api-key generate --name "Billing Tool" --integrations "BILLING:2" --expires 24h

  # Generate permanent API key with read-only access
  public-api-key generate --name "Monitoring Tool" --integrations "SIEM:1" --expires never

  # Generate API key with BILLING role and save details to JSON file
  public-api-key generate --name "Billing Integration" --integrations "BILLING:2" --expires 1y --format json --output billing_key.json

1-3. SIEM向けの APIトークンの生成

例えば、SIEM 連携用として読み取り専用のキーを 30 日間有効で発行すると、次のようになります。

My Vault> public-api-key generate --name "SIEM Integration" --integrations "SIEM:1" --expires 30d
API Key generated successfully
Name: SIEM Integration
Token: XyZ123ABCfakeTokenExample987
Enterprise ID: 9999
Expires: 2026-01-05 19:52:03
Integrations:
  - SIEM: READ (1)

コマンドが成功すると、JSON またはテーブル形式で結果が表示され、その中に token フィールドがあります。この token の値を Keeper管理者向けREST API の認証で使用します（1回しか表示されないので安全な場所に保管してください）。

2. Scalar から Keeper管理者向けREST API を呼び出す

次に、Scalar を使って Keeper管理者向けREST API の /public/events エンドポイントから 監査イベント を取得します。

2-1. エンドポイントの基本

ドキュメントに記載されているエンドポイントは次の通りです。

GET https://keepersecurity.jp/api/rest/public/events

クエリパラメータ:

  • start_date（必須）
  • end_date（必須）
  • limit（任意）
  • continuation_token（任意）

2-2. 認証ヘッダー（Bearer プレフィックスに注意）

ドキュメント上は x-api-token ヘッダーを使用すると記載されていますが、実際には 値の先頭に Bearer プレフィックスを付ける必要があります。

x-api-token: Bearer <token>

最初、Scalar で次のように Bearer なしでリクエストしたところ、

x-api-token: XyZ123ABCfakeTokenExample987

レスポンスは 403 Forbidden で、ボディには以下のようなエラーが返却されました。

{
  "additional_info": "Missing Bearer prefix - x-api-token",
  "location": "public_api_filter",
  "error": "invalid_token",
  "message": "invalid_token"
}

そのため、Scalar の Authentication 設定で、必ず Bearer <token> という形式に修正する必要があります。

2-3. 日付時刻フォーマット（ISO 8601 + Z が必須）

次にハマりやすいポイントは、start_date / end_date のフォーマットです。

直感的に次のような日付だけを指定したくなりますが、

start_date=2025-12-01
end_date=2025-12-04

これでリクエストすると、サーバー側で次のようなエラーが発生します。

{
  "path": "/api/rest/public/events, GET",
  "location": "default exception manager - Text '2025-12-01' could not be parsed at index 10",
  "error": "unknown",
  "message": "An unexpected server error occurred (Text '2025-12-01' could not be parsed at index 10)."
}

Keeper管理者向けREST API は フルの日時（ISO 8601形式） を期待しているため、次のように T と Z を含む形式で指定する必要があります。

start_date=2025-12-01T00:00:00Z
end_date=2025-12-04T23:59:59Z

2-4. 実際のリクエスト例

最終的な設定は概ね次のようになります。

  • メソッド: GET

  • URL: https://keepersecurity.jp/api/rest/public/events

  • Headers

    • x-api-token: Bearer XyZ123ABCfakeTokenExample987

  • Query Parameters

    • start_date=2025-12-01T00:00:00Z
    • end_date=2025-12-04T23:59:59Z
    • limit=100

レスポンスとして、events 配列と continuation_token が返ってきます。continuation_token が存在する場合は、次のページを取得する際にクエリパラメータに付けて再度リクエストします。
image.png

3. Python で特定の 監査イベント をフィルタリングする

/public/events エンドポイントには、現時点では audit_event ごとのサーバーサイドフィルタリング機能はありません。そのため、クライアント側で取得後にフィルタリングする必要があります。

ここでは Python（requests ライブラリ）を使って、audit_event が open_record のイベントだけを抽出し、かつタイムスタンプを日本時間（JST）に変換して表示する例を紹介します。

3-1. サンプルスクリプト

import requests
from datetime import datetime, timedelta

# ===== 設定 =====
API_TOKEN = "XyZ123ABCfakeTokenExample987"  # <-- 生成したAPIトークン文字列を指定

BASE_URL = "https://keepersecurity.jp/api/rest/public/events"
PARAMS = {
    "start_date": "2025-12-01T00:00:00Z",
    "end_date": "2025-12-01T23:59:59Z"
}

HEADERS = {
    "x-api-token": f"Bearer {API_TOKEN}"
}


# ===== ヘルパー関数 =====
def ts_ms_to_tokyo(ts_ms: int) -> str:
    """タイムスタンプを日本時間に変換する。"""
    dt_utc = datetime.utcfromtimestamp(ts_ms / 1000)
    dt_tokyo = dt_utc + timedelta(hours=9)
    return dt_tokyo.strftime("%Y-%m-%d %H:%M:%S JST")


# ===== メイン処理 =====
all_open_record_events = []
params = PARAMS.copy()

while True:
    resp = requests.get(BASE_URL, params=params, headers=HEADERS)
    resp.raise_for_status()
    data = resp.json()

    events = data.get("events", [])
    open_record_events = [
        e for e in events
        if e.get("audit_event") == "open_record"
    ]
    all_open_record_events.extend(open_record_events)

    continuation = data.get("continuation_token")
    if not continuation:
        break  # no more pages

    params["continuation_token"] = continuation

# ===== 出力 =====
print(f"Found {len(all_open_record_events)} open_record events\n")

for e in all_open_record_events:
    ts_ms = e.get("timestamp")
    ts_str = ts_ms_to_tokyo(ts_ms) if ts_ms is not None else "N/A"
    user = e.get("username")
    ip = e.get("remote_address")
    category = e.get("category")
    client_ver = e.get("client_version")

    print(
        f"{ts_str} | user={user} | ip={ip} | "
        f"event={e.get('audit_event')} | category={category} | client={client_ver}"
    )

まとめ

本記事では、

  1. Keeperコマンダーで public-api-key generate を使って APIトークンの生成方法

  2. Scalar から Keeper管理者向けREST API /public/events を呼び出す際のハマりポイント

    • x-api-token の値に Bearer プレフィックスが必須
    • start_date / end_date は YYYY-MM-DDTHH:MM:SSZ 形式の日時が必須

  3. Python スクリプトで audit_event = "open_record" のイベントだけを抽出し、日本時間で読みやすく表示する方法

を紹介しました。

補足
本記事は英語版ドキュメントの内容をベースに検証したものです。日本語ドキュメントでは、管理コンソールから APIトークンを生成できる機能にも触れられていますが、現時点では一部のお客様向けの機能です。そのため、本記事では汎用的に利用できる方法として、Keeperコマンダーによる APIトークンの生成手順のみを扱っています。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?