warden-service

Warden Service

読み取り専用の個人用トークンを使って Warden Service に問い合わせ、範囲を限定した、根拠に基づく回答を返します。

ワークフロー

1. Warden Service のオリジンを特定し、値を表示せずに WARDEN_PAT が設定されていることを確認します。
2. トークンがない場合は、Warden Service のダッシュボードで API access を開くようユーザーに案内します。個人用トークンを作成し、WARDEN_PAT としてエクスポートしてもらいます。チャットやコマンドのリテラルに貼り付けるよう求めてはいけません。
3. references/read-api.md を読み、質問に対応する正確なルート、サポートされるフィルター、ページネーションの動作、レスポンスフィールドを選びます。
4. ユーザーのリポジトリ、期間、スキル、重要度、その他指定された範囲にリクエストを絞り込みます。実行と検出結果には上限付きの limit を使用します。
5. 環境変数から読み取ったトークンを使って GET リクエストを送信します。すべてのクエリ値を URL エンコードします。
6. さらに結果が必要な場合に限り、nextCursor をたどります。元のフィルターをすべて維持し、指定された範囲が満たされたとき、またはレスポンスに nextCursor が含まれなくなったときに停止します。
7. 関連する JSON フィールドを要約します。使用したルートとフィルターを明記し、結果が空だった場合とリクエストが失敗した場合を区別します。

リクエストパターン

クエリ文字列を手動で組み立てず、--data-urlencode を指定した --get を使用します。

curl --fail-with-body --silent --show-error --get \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${WARDEN_PAT}" \
  --data-urlencode 'severity=high' \
  --data-urlencode 'skill=security-review' \
  --data-urlencode 'limit=30' \
  "${WARDEN_SERVICE_URL%/}/api/v1/findings"

トークンは WARDEN_PAT に保持します。認証ヘッダーが漏えいする可能性のある詳細出力やトレース出力を有効にしないでください。

ページネーション

カーソルページネーションを使用するのは /api/v1/runs と /api/v1/findings のみです。nextCursor は不透明な値として扱い、URL エンコードしてそのまま返します。

curl --fail-with-body --silent --show-error --get \
  -H 'Accept: application/json' \
  -H "Authorization: Bearer ${WARDEN_PAT}" \
  --data-urlencode "cursor=${NEXT_CURSOR}" \
  --data-urlencode 'severity=high' \
  --data-urlencode 'limit=100' \
  "${WARDEN_SERVICE_URL%/}/api/v1/findings"

エラー

HTTP ステータスと JSON の error.code および error.message を併せて使用します。

ステータス	意味	対応
400	無効なクエリフィルター	パラメーター名、値、または RFC 3339 タイムスタンプを修正します。
401	認証情報がない、無効、または期限切れ	オリジンを確認し、API access から個人用トークンを再発行します。
403	ロールが不十分、または個人用トークンで許可されていない操作	リクエストを読み取り専用とし、トークンのリポジトリ範囲内に限定します。
404	不明な、またはアクセス権のないルート／リソース	リソースの存在を決めつけず、ドキュメントに記載されたルートまたは ID を確認します。
429	レート制限	待ってから再試行します。短い間隔で再試行を繰り返してはいけません。

制約

• 個人用トークンは GET または HEAD のみに使用します。トークンを使って POST、PUT、PATCH、DELETE を試みてはいけません。
• トークンを開示、ログへの記録、永続化、コマンドリテラルへの埋め込みをしたり、ユーザーに貼り付けを求めたりしてはいけません。
• トークンのテナント、ロール、リポジトリに関する制限を守ります。決して回避しようとしてはいけません。
• references/read-api.md に記載されたルート、フィルター、レスポンスフィールドのみを使用します。
• ユーザーが指定した範囲に必要なデータだけを取得して表示します。エクスポートルートは、ユーザーが明示的にエクスポートを依頼した場合にのみ使用します。
• 読み取り API で質問に回答できない場合は、その旨を伝えます。取り込み、メモリーの想起、トークン管理、保持、削除のリクエストで代用してはいけません。