メインコンテンツまでスキップ

Security

OWASP API Security Top 10 2023 を acceptance criteria に含める。

最小権限 (Principle of Least Privilege)​

  • API key は 用途別 に発行 (CI / BI / 連携 SaaS など)
  • scope は 読み取りだけで足りるなら write は付けない
  • 組織で発行する場合は admin に依頼し、 個人 key と混ぜない
  • token の有効期限は短く設定 (例: 30 日)、 自動 rotation を運用

Token 取り扱い​

  • 発行直後の token は 1 回しか表示されない。 安全な vault (1Password, AWS Secrets Manager, etc.) に保管
  • Git / Slack / メール / Markdown PR テンプレに貼らない
  • .env を commit しない。 .env.local を .gitignore に
  • 漏洩疑い時は 即時 revoke (/settings/developer)、 そして:
    • audit log で利用範囲を調査 (authentication.md)
    • 影響範囲を組織内で共有
    • 新 token を発行

サーバー間連携の推奨​

  • ブラウザ SPA から直接 API key を使わない → 前段 BFF サーバーを置く
  • mobile アプリ内に token を埋め込まない → OAuth 経由 + secure storage
  • shared 環境 (Lambda 等) では env var + KMS

BOLA (Broken Object Level Authorization) 対策​

すべての /v1/... は:

actor + scope + organization membership + room membership + room type deny

を AND 評価する。 「scope だけで通る endpoint」「path 上の id を素通しする endpoint」は 無い。

「存在しない」「アクセス権がない」は両方とも 404 (room_not_found 等) で返す。 権限有無を ID 列挙で漏らさないため。

Webhook 受信側​

  • HMAC 署名は raw body bytes で検証 (webhooks.md)
  • timestamp で replay window 5 分
  • secret rotation 中は current / next の両方を試す
  • 受信エンドポイントは HTTPS のみ、 内部 IP 拒否

SSRF / network 制限​

  • Webhook URL と connector URL は private network 制限を policy 化
  • OpenClaw private / tailnet 例外は明示 allow (openclaw-connector.md)
  • DNS rebinding 対策: connector runtime の HTTP client で IP を毎回解決し、 RFC1918 / link-local / metadata service (169.254.169.254 等) を block

Prompt injection (agent 経路)​

  • agent connector は read scope と write scope を分離
  • write は idempotency key + audit log + 必要なら human approval を通す
  • 外部入力 (Web 検索、 メール) をそのまま write tool に渡さない
  • tool 呼び出し結果は監査ログに記録される

監査ログ​

監査ログに 全 /v1 リクエスト を保存:

  • requestId, surface, method, route pattern, status code
  • auth method, actor, scopes
  • organization / user / api key / external token / app id
  • API units cost
  • error code (失敗時)

保持期間: 7 年 (法令上限 + 内部監査要件)。

OAuth refresh token​

  • rotation 必須
  • reuse detection: 1 回 rotate された refresh token が再度使われたら family 単位で revoke
  • 再認証 = 新規認可フロー

Webhook secret rotation​

  • current / next を併存可能
  • 新規発行から 24 時間以内に切替推奨
  • rotation を支援する admin UI / API

インシデント対応 runbook​

  1. 疑わしいログイン / API call を観測
    • Audit log で api_key_id / actor / ip_address を確認
    • 影響範囲 (どの organization / room) を特定
  2. 影響範囲の token を revoke
    • /settings/developer で当該 key を revoke (即時失効)
    • OAuth は admin API から family 全体を revoke
  3. 代替 token を発行
    • 必要最小 scope のみ
  4. ステークホルダー通知
    • 組織 admin / セキュリティ担当 / 法務
  5. ポストモーテム
    • 漏洩経路 / 修正 / 再発防止策

チェックリスト (開発者向け)​

  • 必要最小 scope だけ要求しているか
  • token を sourcemap / production build に埋め込んでいないか
  • HTTPS 通信か (http:// で書いていないか)
  • 監視に Tascha-Api-Units-Remaining の閾値アラートを置いているか
  • 429 / 503 のリトライ戦略があるか (Retry-After を尊重)
  • Webhook 受信側で raw body 署名検証しているか
  • secret 漏洩時の revoke 手順を runbook に書いているか

参考​