AI コーディングエージェントでシークレットを安全に使用する

AI コーディングエージェントにシェルまたはAWS API アクセスがある場合、コンテキストウィンドウでプレーンテキストシークレットを呼び出しget-secret-valueて受信できます。これにより、シークレット値が会話履歴、ログ、またはダウンストリームツール呼び出しに漏れる可能性があるという複数のリスクが生じます。

これを防ぐには、 エージェントツールキットAWSのシークレット安全スキルを使用します。このスキルは、実行時に解決された動的参照を使用するように AI エージェントに教えるため、エージェントはプレーンテキストの値を見ずにシークレットの使用を調整します。

仕組み

シークレット安全スキルは、次の 2 つの保護レイヤーを提供します。

前提条件

プラグインをインストールする

エージェントプラットフォーム用の aws-coreプラグインをインストールします。シークレット安全スキルとフックは自動的にアクティブ化されます。

Claude コードの場合:

claude plugin add ./plugins/aws-core

OpenAI Codex の場合:

codex plugin add ./plugins/aws-core

サポートされている他のプラットフォームについては、「エージェントツールキット for AWS README」を参照してください。

{{resolve:...}} 構文

エージェントがシークレットをコマンドに渡す必要がある場合、 を呼び出す代わりに動的参照を使用しますget-secret-value。

{{resolve:secretsmanager:<secret-id>:<field-type>:<json-key>:<version-stage>}}

asm-exec を使用してシークレットでコマンドを実行する

asm-exec は、コマンド引数の{{resolve:...}}参照を解決し、ターゲットコマンドを実行するラッパースクリプトです。シークレット値は子プロセスにのみ存在します。

asm-exec -- <command> [arguments with {{resolve:...}} references]

asm-exec は、利用可能な最初のバックエンドを通じて参照を解決します。

asm-exec -- psql \
  "host=mydb.example.com \
  user={{resolve:secretsmanager:prod/db-creds:SecretString:username}} \
  password={{resolve:secretsmanager:prod/db-creds:SecretString:password}}" \
  -c "SELECT * FROM users LIMIT 10"

asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \
  https://api.example.com/data

asm-exec -- mysql \
  -h {{resolve:secretsmanager:prod/mysql:SecretString:host}} \
  -u {{resolve:secretsmanager:prod/mysql:SecretString:username}} \
  -p{{resolve:secretsmanager:prod/mysql:SecretString:password}} \
  -e "SHOW TABLES"

asm-exec -- docker run \
  -e "DB_PASSWORD={{resolve:secretsmanager:prod/db:SecretString:password}}" \
  myapp:latest

クロスリージョンシークレット

デフォルトのリージョンとは異なるリージョンに保存されているシークレットの場合は、完全な ARN (リージョンを含む) を使用するか、AWS_REGION環境変数を設定します。

# Using full ARN (region is extracted automatically)
asm-exec -- curl -H "X-Api-Key: {{resolve:secretsmanager:arn:aws:secretsmanager:eu-west-1:123456789012:secret:prod/key-a1b2c3}}" \
  https://eu.api.example.com/data

# Using AWS_REGION
export AWS_REGION=eu-west-1
asm-exec -- curl -H "X-Api-Key: {{resolve:secretsmanager:prod/key}}" \
  https://eu.api.example.com/data

セキュリティに関する考慮事項

フックがシークレットへの直接アクセスをブロックする方法

aws-core プラグインを有効にすると、PreToolUseフックは実行前に を傍受します。これは以下をブロックします。

通話がブロックされると、エージェントは拒否メッセージを受信し、asm-exec代わりに で{{resolve:...}}参照を使用するように指示します。

トラブルシューティング

「シークレットが見つかりません」エラー

シークレットが存在し、IAM ロールに アクセスsecretsmanager:GetSecretValue許可があることを確認します。シークレット名では大文字と小文字が区別されます。

AWSワークロード認証情報プロバイダーの接続が拒否されました

AWSワークロード認証情報プロバイダーが実行されていない可能性があります。これは致命的ではありません。SigV4-signed付き MCP エンドポイントにasm-execフォールスルーされます。バックエンドが認証できるように、AWS認証情報が使用可能であることを確認します。

「失敗」エラー

両方のバックエンドに到達できませんでした。AWSワークロード認証情報プロバイダーが実行されているか、AWS認証情報が有効 (aws sts get-caller-identity) であること、シークレットのリージョンが正しいこと、および ID がシークレットsecretsmanager:GetSecretValueにあることを確認します。

解決により空の文字列が生成されます

JSON キーがシークレット値に存在しない可能性があります。AWSコンソールでシークレット構造を確認するか、シークレット所有者に使用可能なキーの確認を依頼します。

フックは通話をブロックしません

エージェントセッションの開始時にフックロードします。セッション中にプラグインをインストールした場合は、フックを有効にするエージェントセッションを再起動します。