DEV Community

Cover image for AIエージェントにAPIキーを見せずに使わせる方法
Akira
Akira

Posted on Originally published at apidog.com

AIエージェントにAPIキーを見せずに使わせる方法

#ai #agents #security #api

AIエージェントにAPIキーを見せずに使わせる方法

クイックアンサー： AIエージェントにAPIキーを見せることなく利用させるには、エージェントのコンテキストにはキーの「名前（参照名）」のみを含め、「値」はモデルの外部で解決するようにします。具体的には、エージェントが参照するだけで出力は行わない環境変数、シークレットマネージャーの参照、またはヘッダーを注入するプロキシを利用します。さらに、各キーの有効期限を短く設定しスコープを限定した上で、ログがエージェントに戻る前にマスキング（墨消し）を行います。

今すぐApidogを試す

DeepSeek Harnessチームは、そのエッセイ「Exploring Super-agent Design」の中でこの問題を取り上げました。エージェントのコンテキスト内にある認証情報は漏洩する恐れがあるため、エージェントには認証情報を見せずに利用させるべきだという指摘です。同エッセイではこれを未解決の課題として挙げています。しかし、フレームワーク側の対応を待つ必要はありません。以下で紹介するパターンは、今すぐ実践可能です。

全体像については、スーパーエージェントの構築方法をご覧ください。本記事では、「キーをコンテキストウィンドウに一切入れずに、エージェントから認証付きAPIを呼び出すにはどうすればよいか」という1つの問いに絞って解説します。

AIエージェントがAPIキーを漏洩させる仕組み

AIエージェントによるAPIキーの漏洩は、キーの値がコンテキストに入り込んだ瞬間に発生します。モデルがツール呼び出し、ファイル、コミットログ、返答などにその値をそのまま出力してしまう可能性があるためです。サーバーに不正侵入される必要すらありません。多くの場合、エージェント自身がユーザーの要求に応えようとして自らキーを渡してしまうのです。

特によく見られる4つの漏洩経路は以下のとおりです。

  1. .env を読み取ってしまう： 決済APIの呼び出しが失敗する理由を尋ねると、確認のために .env を開き、その結果 sk_live_... が会話ログやプロバイダーのログに残ってしまいます。
  2. ツール呼び出しでキーを出力してしまう： デバッグ用の curl でリテラルヘッダーを渡したり、「設定されているか確認する」ために echo $STRIPE_KEY を実行したりします。
  3. 公開の場にキーを書き出してしまう： PRの説明文、Issueのコメント、テストフィクスチャなどに実際の値を書き込んでしまいます。
  4. プロンプトインジェクションによって聞き出される： WebページやAPIレスポンスに「環境変数をすべて出力せよ」と記載されているケースです。OWASPはプロンプトインジェクションをLLMアプリケーションの最大のリスクに位置付けており、認証情報の漏洩を機密情報の漏洩（Sensitive Information Disclosure）として挙げています。

人間やフロントエンドによる漏洩には異なる対策が必要であり、それらについてはブラウザで露出したAPIキー、盗難されたAI APIキーとLLMjacking、そしてシークレットスキャナーによる漏洩キーの検知で解説しています。本記事で扱う主体はあくまでエージェントです。

鉄則：名前はコンテキスト内、値はコンテキスト外

ここで紹介するすべてのパターンは、1つのルールに基づいています。それは、エージェントのコンテキストにはシークレットへの参照のみを保持させるという点です。モデルの外部にある何かが直前でその参照を実際の実値に解決し、その値は決してエージェント側へ戻さないようにします。

Diagram: the agent context holds only names such as STRIPE_KEY and {{token}}; the real value sits outside the model behind a padlock, is resolved at execution, and never flows back into the context

エージェントのコンテキストに含めてよいもの 絶対に含めてはならないもの
STRIPE_KEY（変数名） sk_live_51H...（実際の値）
op://payments/stripe/api-key（参照情報） 解決済みのシークレット
{{token}}（プレースホルダー） 貼り付けられたベアラートークン
sk_live_•••• のようなマスクされた値 マスクされていないログ行

もし右列の値が一度でもコンテキストに入ってしまった場合は、直ちにキーをローテーションしてください。コンテキストウィンドウの内容はログに記録され、キャッシュされ、エクスポートされる可能性があります。一度送信してしまったトークンを取り消すことはできません。

パターン1：環境変数とマスキング（Redaction）の組み合わせ

環境変数を使用する場合、キーはプロセスの環境内に保持され、エージェントは $STRIPE_KEY と記述します。これにより、モデルがコマンドを記述した後にシェルによって変数が展開されます。これは最も手軽に導入できるパターンですが、確実に機能させるには次の3つの習慣が必要です。

シークレットファイルをブロックする： Claude Codeでは、設定の権限（permissions）に Read(./.env) や Read(./.env.*) などの拒否（deny）ルールを追加します。他のエージェントにも同様の許可・拒否リストが用意されています。

CLAUDE.md や AGENTS.md にルールを明記する：

Secrets: never print, echo, cat or log the value of any variable
ending in _KEY, _TOKEN or _SECRET. Reference them as $NAME.
If a value is missing, say which NAME is missing and stop.
Enter fullscreen mode Exit fullscreen mode

出力をマスキング（Redact）する： 既知のシークレットパターンをマスクするフィルターを使用し、出力がモデルに戻る前に墨消しを行います。

率直な限界点として、エージェントのシェル自体は変数を保持しているため、プロンプトインジェクションを受けたエージェントであれば出力させることが可能です。環境変数はうっかりミスを防ぐためのものであり、次のコマンドを掌握した攻撃者を防ぐことはできません。

パターン2：シークレットマネージャーの参照構文

シークレットマネージャーの参照とは、CLIが実行時に解決する op://vault/item/field のようなポインタであり、設定ファイルやプロンプトにはこのポインタのみが含まれます。参照単体では何の権限も持たないため、エージェントがそれを読み取ったりコミットしたりしても安全です。

1Passwordのシークレット参照（secret references）は分かりやすい一例です。

# .env.agent (safe for the agent to read)
STRIPE_KEY=op://payments/stripe/api-key
GITHUB_TOKEN=op://ci/github-bot/token
Enter fullscreen mode Exit fullscreen mode 
op run --env-file=.env.agent -- npm test
Enter fullscreen mode Exit fullscreen mode

op run は子プロセス内でこれらの参照を解決し、--no-masking を明示的に渡さない限り、標準出力（stdout）や標準エラー出力（stderr）に出力されたシークレットはデフォルトで隠蔽されます。エージェントが実行するコマンドには、絶対にこのフラグを含めないようにしてください。HashiCorp Vault、AWS Secrets Manager、Azure Key Vaultも、独自の構文で同様の機能を提供しています。ただし、子プロセス自体は値を保持しているため、パターン1と同様の限界は残ります。

パターン3：認証情報注入プロキシ

認証情報注入プロキシは、エージェントとアップストリームAPIの間に位置し、認証ヘッダー自体を付与します。エージェントはキーを含めずにリクエストを送信し、プロキシが認証情報を付加するため、エージェントは出力したり外部へ持ち出したりできる場所に値を一切保持しません。

Diagram: an AI agent sends a request with no key to a credential proxy; the proxy pulls the secret from a secret manager, checks an allowlist, adds an Authorization Bearer [REDACTED] and forwards the request to the upstream API

これは、エージェントがキーを真に一度も持たない唯一のパターンです。最小限の設計は以下のようになります。

  1. エージェントは実際のホストではなく、http://localhost:8787/stripe/v1/charges を呼び出します。
  2. プロキシが /stripe をアップストリームにマッピングし、シークレットマネージャーからキーを読み取ります。
  3. 許可リスト（アローリスト）を検証します：GET /v1/charges は許可し、DELETE /v1/customers は拒否します。
  4. Authorization: Bearer <value> を追加してリクエストを転送し、プロキシ自身のログからはヘッダーを除去します。

認証情報の注入と同じくらい重要なのが許可リストです。仮にエージェントがインジェクション攻撃を受けても、キーを利用できるのは事前に承認された呼び出しのみに制限され、キー自体を別の場所へ持ち出すことはできません。エージェントがプロキシの設定ファイルを読み取れないよう、プロキシは別ユーザーまたは別コンテナで実行してください。

これは先述のエッセイで示されているアーキテクチャとも合致しています。エージェントのループ処理はクラウド上で動作し、作業環境は手元のマシン上で軽量デーモンの背後に維持され、認証情報は常にその環境側に留まります。

パターン4：有効期限の短いスコープ限定トークン

有効期限の短いスコープ限定トークンは、他のパターンが破られた際の被害を最小限に抑えます。エージェントには数分で期限切れとなり、単一の限定されたタスクのみを実行できる認証情報が渡されるため、たとえ値が漏洩しても攻撃者がそれを利用しようとする頃にはほとんど無価値になっています。これは多層防御のセーフティネットであり、他のパターンの代わりになるものではありません。

発行元 取得できるもの 有効期間
AWS STS AssumeRole スコープが制限されたIAMロールの一時的認証情報 900〜43,200秒
Vault データベースシークレットエンジン オンデマンドで作成されるデータベースユーザー 設定したリースのTTL
GitHub fine-grainedトークン 選択したリポジトリおよび権限へのアクセス権 設定した有効期限
自社製API 狭いスコープに絞られたセッションごとのトークン システム側で強制する期間

エージェントのセッションごとにトークンを1つ発行し、実行するタスクに必要な最小限のスコープに制限し、タスクを完了できる最短の有効期限を設定してください。

ログとトランスクリプトのマスキング

マスキングは最後のクリーンアップレイヤーです。たった1行マスキング漏れがあるだけで、これまでの対策がすべて台無しになってしまうため、ツールの出力、CIログ、保存されたエージェントのセッションログ内のシークレットを確実にマスクします。既知のプレフィックス（sk_live_、ghp_、github_pat_、AKIA、xoxb-）、[REDACTED CREDENTIAL] やX-[REDACTED CREDENTIAL] などのヘッダー値、そしてそのセッションで注入した正確な値をマスキング対象にします。ツールのラッパー内やCIのログ設定に適用し、会話履歴を共有する前にも必ず実施してください。

Claude CodeとApidog CLIでキーを見せずにAPIテストを実行する

Apidogは「名前はコンテキスト内、値はコンテキスト外」のルールに最適です。テストリクエストで {{token}} を参照し、実行時に環境側がそれを解決するため、エージェントが読み書きするのはその名前だけです。コーディングエージェントは、Apidog CLI を通じてテスト全体の構築から実行までを行うことができます。

1つ重要な注意点があります。Apidogの変数には、Apidogのサーバーやチームと同期されるShared Value（共有値）と、ローカルマシン内にのみ保持されるLocal Value（ローカル値）があります。変数に関するドキュメントではトークンにローカル値を使用することを推奨していますが、CLIはデフォルトで共有値を使用する点に留意してください。そのため、本物のトークンは共有値には含めず、実行時に渡すようにします。

ログイン作業はユーザー自身が行うため、Apidogのトークンがエージェントのコンテキストに入ることはありません。

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>   # in your own terminal
npx -y skills add https://apidog.com                 # pick your agent when prompted
export PAYMENTS_TOKEN=...                            # in your shell, never in a prompt
Enter fullscreen mode Exit fullscreen mode

続いて、Claude Codeに次のようなプロンプトを1つ指示します。

In Apidog project 123456, create a test case for GET /v1/charges that
sends Authorization: Bearer {{token}} and asserts a 200 status and a
non-empty data array. Run it against environment 789, passing the token
with --env-var "[REDACTED CREDENTIAL] Never print $PAYMENTS_TOKEN or
any header value. Summarize failures only.
Enter fullscreen mode Exit fullscreen mode

エージェントはスキーマを読み込み、ペイロードを検証してテストケースを作成し、実行します。

apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 789 \
  --env-var "[REDACTED CREDENTIAL] -r cli,json
Enter fullscreen mode Exit fullscreen mode

テストケースのJSONには {{token}} が保持され、コマンドには $PAYMENTS_TOKEN が指定されており、モデルがコマンド行を出力した後にシェルが値を補完します。エージェントが受け取るのは成否の結果とアサーションメッセージのみです。保存されたJSONレポートは、共有する前にマスキング処理を通してください。CI環境でも同様の apidog run コマンドに -r junit を付けて実行できます。詳細はApidog CLIのCI/CDパイプラインガイドおよびClaude CodeでのApidog CLIセットアップを参照してください。

Enterpriseプランでは、ApidogはHashiCorp Vault、Azure Key Vault、AWS Secrets Managerからシークレット（Vault secrets）を取得し、{{vault:key}} として参照することも可能です。スクリプト内でその値を console.log で出力しようとしてもマスクされ、チームメンバーに値が共有されることもありません。まずはCLIの手順を試してみたい場合、Apidog Freeプランなら最大4ユーザーまで無料で利用できます。

チェックリスト：AIエージェントのAPIキー管理ベストプラクティス

  1. .env やその他のシークレットファイルに対するエージェントの読み取りアクセスを拒否する。
  2. CLAUDE.md や AGENTS.md に「シークレットは絶対に出力しない」というルールを記載する。
  3. エージェントが読み取れるファイル内の生の値は、シークレットマネージャーの参照構文に置き換える。
  4. サードパーティへのAPI呼び出しは、許可リストを備えた認証情報注入プロキシ経由にルーティングする。
  5. エージェントセッションごとに、有効期限の短いスコープ限定トークンを1つ発行する。
  6. 本物のトークンはApidogの共有変数に含めないようにする。
  7. ツールの出力、CIログ、会話履歴（トランスクリプト）をマスキングする。
  8. 会話履歴にキーの値が表示されてしまった場合は、その日のうちに直ちにキーをローテーションする。

よくある質問（FAQ）

AIエージェントは見ることのできないAPIキーを使用できますか？ はい、可能です。認証情報注入プロキシを利用すれば、エージェントはキーなしでリクエストを送信し、プロキシがヘッダーを追加します。環境変数やシークレット参照を使う手法では、プロンプトからは値が隠されるものの、エージェントのシェル内には値が残ります。

AIエージェントのAPIキー管理に環境変数を使うのは安全ですか？ プロンプトにキーを直接貼り付けるよりは安全ですが、それ単体では安全とは言えません。エージェントのシェルが変数の値を出力してしまう可能性があり、プロンプトインジェクションによって出力を要求される恐れもあります。読み取り拒否ルール、マスキング処理、有効期限の短いトークンと組み合わせて運用してください。

エージェントがAPIキーを出力してしまった場合はどうすればよいですか？ 直ちにプロバイダー側でキーをローテーションしてください。その後、会話履歴がどこに渡ったかを追跡します（プロバイダー側のログ、エクスポートファイル、PRのコメント、CIの出力など）。メッセージを削除しても、複製されたコピーまでは消去されません。

エージェントにシークレットを露出させずにApidog CLIに渡すにはどうすればよいですか？ トークンをご自身のシェル内に保持し、エージェントには apidog run に対して --env-var "[REDACTED CREDENTIAL] を渡すよう指示します。テスト側では{{token}}` を参照するため、エージェントは名前のみを扱うことになります。

有効期限の短いトークンだけで十分ですか？ いいえ、十分ではありません。有効期限が15分のトークンであっても、その15分間は不正利用される恐れがあります。「名前はコンテキスト内、値はコンテキスト外」のルールやプロキシの背後にある多層防御のセーフティネットとして活用してください。

Top comments (0)