運用・セキュリティ

allowlist / blocklist

本番接続先 (sic-poc1-verify) のテーブルアクセスは Settings で制御されます。

bq.source_allowlist (既定)

["xhro_01.*", "xhro_02.*", "xhro_03.*", "xhro_04.*", "xhro_view.*", "xhro_04_modeling_v2.*"]

bq.source_blocklist (既定)

["xhro", "xhro_backup", "tmp", "clns", "dataflow_dev"] — allowlist より強い

サービスアカウント鍵

• 本番: bq.service_account_key (Settings 経由、KMS 暗号化済 secret)。
• ローカル開発: .keys/suntory-analytics-bq.json (600 権限、git 管理外)。
• WIF (Workload Identity Federation): bq.workload_identity_audience を設定すると鍵レス認証に切替可能。
• ローテーション: SA 鍵を発行し直したら同じ path に上書きするだけ。古い鍵は gcloud iam service-accounts keys delete で取り消し。

SQL の安全性

• 全クエリは dry_run.estimate(query, purpose) を通す (FR-X2)。`purpose` は ui_preview / preview_window / analysis_dataset / export のいずれか必須。
• SQL テンプレは packages/bq-access/templates/ 配下に Jinja2 でハードコード。動的 SQL を生成する経路はない。
• identity 解決: UI / API は public_id のみ。BQ 発火直前に subject_id_map から KMS 復号して raw uid を取得し、WHERE uid = ? に渡す。raw uid はログ / audit payload に出さない。

cost 監視と通知

• BQ ジョブ完了時に audit_log に cost_usd を記録。日次集計で bq.daily_*_cap_usd 判定。
• notify.events.cost_threshold = true の user / tenant admin に Slack / メールで通知。
• LLM コストは copilot.cost_alert_usd_per_day (既定 5.00 USD) を超えると Copilot Pane に黄帯表示。
• 大規模 export (bq.cost_cap_usd.export 適用) は admin 事前承認画面が出る。

API での宣言的強制

from fastapi import Depends
from studio_api.auth.rbac import require_perm

@router.post("/v1/bundles", dependencies=[Depends(require_perm("studio:bundle:build"))])
async def create_bundle(req: BuildRequest, ...): ...

# 違反時: 403 Forbidden + audit_log に "rbac.deny" 記録

Agent / Copilot からの呼び出し制御

# canUseTool callback (claude-agent-sdk)
async def can_use_tool(tool_name, tool_input, ctx) -> PermissionResult:
    HUMAN_ONLY = {
        "mcp__studio__studio.build_bundle",
        "mcp__hypothesis__hypothesis.pre_register",
        "mcp__model__model.pre_register",
        "mcp__annotation__annotation.freeze_set",
    }
    if tool_name in HUMAN_ONLY and ctx.invoked_by_ai:
        return { "behavior": "deny",
                 "message": "Human approval required. Proposed but not executed." }

    if not rbac_allows(ctx.user.role, tool_name, tool_input):
        return { "behavior": "deny",
                 "message": f"Role {ctx.user.role} cannot call {tool_name}." }

    return { "behavior": "allow" }

制限

• ファイルシステム: read-only Bundle mount + scratch tmpfs (`/tmp` 1 GB)。Bundle 以外への書き込み禁止。
• ネットワーク: sandbox.allow_network = false 既定 (Settings)。外向き通信不可。
• CPU: sandbox.cpu_cores = 2 (Settings)
• メモリ: sandbox.memory_mb = 2048
• Wall time: sandbox.wall_time_sec.feature = 15 / sandbox.wall_time_sec.hypothesis = 120
• stdout: JSON envelope に限定。生 print は捕捉されない。

許可される import

• 標準ライブラリ全般
• numpy, pandas, scipy, scikit-learn, statsmodels
• lightgbm, xgboost, torch, lifelines
• sn.ecg.* (built-in 特徴量), sn.bundle (Bundle 読み出しヘルパ), sn.ann (AnnotationSet 読み出し)

禁止 import (deny list)

• requests, urllib, socket (network)
• subprocess, os.system (shell)
• importlib 動的ロード (sandbox 突破防止)

監査対象

テーブル構造

CREATE TABLE audit_log (
  id          bigserial PRIMARY KEY,
  actor_id    text,
  tenant_id   text,
  action      text NOT NULL,           -- "bundle.build.start", "settings.update", ...
  target_kind text,                    -- "bundle" / "hypothesis" / "settings_key"
  target_id   text,
  payload     jsonb,                   -- 操作のスナップショット (PII 禁止)
  ip          inet,
  user_agent  text,
  occurred_at timestamptz NOT NULL DEFAULT now()
);
CREATE INDEX ON audit_log (tenant_id, occurred_at DESC);
CREATE INDEX ON audit_log (action, occurred_at DESC);

夜次エクスポート

audit.export_destination = gcs / audit.export_bucket = (任意) を設定すると、日次バッチで gs://<bucket>/_audit-export/YYYY-MM-DD/... に JSONL 形式で書き出されます。長期保管・SIEM 連携用。

削除ポリシー

• Bundle の物理削除は admin のみ。通常は archived フラグで論理削除。
• 被験者 erasure (GDPR / 個人情報保護法) 時のカスケード規則は別途定義 (`docs/08-data-governance.md` 未作成)。現状は admin が手動で関連 Bundle / AnnotationSet を archive。
• Evidence / 監査ログは 長期保管前提。retention を短くする場合は法務確認が必要。

構造化ログのフィールド

# structlog で全 API リクエストに以下を注入
{
  "timestamp":  "2026-05-25T12:34:56.789Z",
  "level":      "info",
  "service":    "studio-api",
  "version":    "0.1.0",
  "trace_id":   "abc123...",          # OpenTelemetry trace ID
  "span_id":    "def456...",
  "tenant_id":  "tnt_01HZMX...",
  "user_id":    "usr_01HZMX...",
  "request_id": "req_01HZMX...",
  "method":     "POST",
  "path":       "/v1/bundles",
  "status":     202,
  "duration_ms": 145,
  "message":    "bundle build enqueued"
}

メトリクス (Prometheus 形式)

• sn_api_requests_total{method,path,status} — リクエストカウンタ
• sn_api_request_duration_seconds{method,path} — レイテンシヒストグラム
• sn_bundle_build_duration_seconds{phase,status} — Build phase レイテンシ
• sn_bundle_build_cost_usd_total — BQ コスト累計
• sn_settings_changes_total{scope,key} — 設定変更カウンタ
• sn_copilot_tokens_used_total{model} — LLM トークン使用量

SLO / アラート (推奨設定例)

• Studio API 5xx 率 > 1% (5min) → critical
• Studio API p95 latency > 2s (5min) → warning
• Worker queue depth > 100 (5min) → warning
• Bundle build failure rate > 5% (1h) → critical
• BQ daily cost > 80% of bq.daily_tenant_cap_usd → warning

各 phase のガード

resume の冪等性

• resume は 新しい job_id を作らない (同 job の続行)。
• 同 canonical_hash の Bundle が既に ready なら、resume は再実行せず done を返す (FR-X6)。
• checkpoint の中間 Parquet (gs://.../_staging/{job_id}/<phase>/) は GCS Object Lifecycle で 7 日後に自動削除。

長時間 stuck の対処

• Stuck on extract: BQ side の遅延。bq jobs describe <job_id> で確認。タイムアウトは 30 分で自動 cancel。
• Stuck on register: Postgres トランザクション競合。pg_stat_activity で確認。最大 5 分で release。
• Worker クラッシュ: Arq は最大 3 回まで自動 retry。失敗時は jobs.error_code = "worker_crashed" で記録、Slack 通知。

手動オペレーション

# 全 stuck ジョブの確認
psql $SN_DB_URL -c "
  SELECT id, status, phase, progress, created_at, NOW() - created_at AS age
  FROM jobs
  WHERE status IN ('queued', 'running', 'paused', 'canceling')
    AND created_at < NOW() - interval '1 hour'
  ORDER BY created_at;"

# 手動キャンセル (admin)
curl -X POST -H "Cookie: ..." http://api.local/v1/jobs/job_01HZMX.../cancel

# checkpoint クリーンアップ (Object Lifecycle が動かない場合)
gsutil -m rm -r "gs://sn-bundles/_staging/job_01HZMX.../"

イベント種別

Slack 連携

# Settings (Tenant scope)
notify.channel.slack         = true
notify.slack_webhook_url     = <Incoming Webhook URL>   # KMS 暗号化済 secret

# 通知メッセージ例
[Bundle Ready] bdl_01HZMX... (XHRO-04 / XH015) — 12.4 MB, USD 0.0023
[Job Failed] job_01HZMX... bq_cost_cap_exceeded — 詳細を見る: <URL>
[Cost Alert] tenant tnt_01HZMX... reached 80% of daily cap (USD 80 / 100)

日次サマリ

notify.daily_digest_time_local (既定 09:00) に、前日のサマリ (作成 Bundle 数 / 失敗ジョブ / コスト / アクティブ user) を user に送信。Slack の場合は DM ではなくチャンネル投稿可能。

Postgres バックアップ

• GCP Cloud SQL の自動バックアップ (毎日 02:00 JST、7 日保持)。
• Point-in-time recovery (PITR): 直近 7 日間の任意時点へ復元可能。
• 本番リカバリ手順は infra/runbooks/postgres-recovery.md (未作成、別途整備)。

GCS バケット

• Bundle バケット (storage.bucket) は Object Versioning + Object Lifecycle 設定。
• 削除後 30 日以内なら復元可能。
• リージョン: us-central1 (本番) / us-east1 (DR 用)。
• Bundle は immutable なので、Object Versioning は staging のみで実質意味あり。

Settings の外部保存

JSON エクスポート機能で Tenant 設定をまるごと外部保存可能 (機密は除外)。インシデント時の再構成用。

# Tenant 設定のエクスポート
curl -H "Cookie: ..." http://api.local/v1/settings/tenant/tnt_01HZMX.../export \
  > tenant-settings-backup-2026-05-25.json

# 別環境への流し込み
curl -X POST -H "Cookie: ..." -d @tenant-settings-backup-2026-05-25.json \
  http://newapi.local/v1/settings/tenant/tnt_01HZMX.../import