翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。 # AI コーディングエージェントでシークレットを安全に使用する AI コーディングエージェントにシェルまたはAWS API アクセスがある場合、コンテキストウィンドウでプレーンテキストシークレットを呼び出し`get-secret-value`て受信できます。これにより、シークレット値が会話履歴、ログ、またはダウンストリームツール呼び出しに漏れる可能性があるという複数のリスクが生じます。 これを防ぐには、 [エージェントツールキットAWS](https://github.com/aws/agent-toolkit-for-aws)のシー*クレット安全*スキルを使用します。このスキルは、実行時に解決された動的参照を使用するように AI エージェントに教えるため、エージェントはプレーンテキストの値を見ずにシークレットの使用を調整します。 **重要** これはベストエフォートの防御であり、セキュリティの境界ではありません。これにより、最も一般的な漏洩経路は防止されますが、すべての回避ベクトルを停止することはできません。を IAM 最小特権、CloudTrail モニタリング、VPC エンドポイントポリシーと組み合わせます。 ## 仕組み シークレット安全スキルは、次の 2 つの保護レイヤーを提供します。 1. **スキルガイダンス** – 実行時に参照を解決するラッパースクリプト`asm-exec`である で`{{resolve:secretsmanager:...}}`動的参照を使用するようにエージェントにトレーニングします。プレーンテキスト値は子プロセスにのみ存在し、エージェントのコンテキストウィンドウに入ることはありません。 1. **構造適用 (フック)** – `PreToolUse`フックは、SDK AWS CLI、MCP ツールを呼び出し`get-secret-value`たり`batch-get-secret-value`、経由で呼び出したり、AWSワークロード認証情報プロバイダーデーモンに直接アクセスしたりしようとする試みを自動的にブロックします。手動設定は必要ありません。 ## 前提条件 + [Claude Code](https://docs.anthropic.com/en/docs/claude-code) や [OpenAI Codex](https://openai.com/index/codex/) などのプラグインをサポートする AI コーディングエージェント。 + [エージェントツールキット for AWS](https://github.com/aws/agent-toolkit-for-aws) `aws-core`プラグインがインストールされました。 + 次のいずれかのシークレット解決バックエンド: + で実行されている**AWSワークロード認証情報プロバイダー**`localhost:2773`。「[AWSワークロード認証情報プロバイダーの使用](workload-credentials-provider.md)」を参照してください。 + AWS MCP エンドポイントへのリクエストに署名できる **AWS認証情報**。 + IAM アクセス許可: 解決するシークレット`secretsmanager:GetSecretValue`。 ## プラグインをインストールする エージェントプラットフォーム用の `aws-core`プラグインをインストールします。シークレット安全スキルとフックは自動的にアクティブ化されます。 Claude コードの場合: ``` claude plugin add ./plugins/aws-core ``` OpenAI Codex の場合: ``` codex plugin add ./plugins/aws-core ``` サポートされている他のプラットフォームについては、[「エージェントツールキット for AWS README](https://github.com/aws/agent-toolkit-for-aws)」を参照してください。 ## `{{resolve:...}}` 構文 エージェントがシークレットをコマンドに渡す必要がある場合、 を呼び出す代わりに動的参照を使用します`get-secret-value`。 ``` {{resolve:secretsmanager::::}} ``` | コンポーネント | [Required] (必須) | デフォルト | [Description] (説明) | | --- | --- | --- | --- | | secret-id | はい | – | シークレット名または完全な ARN | | field-type | いいえ | SecretString | SecretString を指定してください | | json-key | いいえ | (完全な値) | JSON シークレット値から抽出するキー | | version-stage | いいえ | AWSCURRENT | バージョンステージラベル | ## `asm-exec` を使用してシークレットでコマンドを実行する `asm-exec` は、コマンド引数の`{{resolve:...}}`参照を解決し、ターゲットコマンドを実行するラッパースクリプトです。シークレット値は子プロセスにのみ存在します。 ``` asm-exec -- [arguments with {{resolve:...}} references] ``` `asm-exec` は、利用可能な最初のバックエンドを通じて参照を解決します。 1. での**AWSワークロード認証情報プロバイダー** `localhost:2773` – ローカルにキャッシュされます。 1. **AWS MCP エンドポイント** – 使用可能なAWS認証情報を使用した SigV4-signedリクエスト。 **Example PostgreSQL データベースに接続する** ``` 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" ``` **Example ベアラートークンを使用して API コールを行う** ``` asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \ https://api.example.com/data ``` **Example 複数のシークレットを使用して MySQL に接続する** ``` 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" ``` **Example シークレットを環境変数として Docker コンテナに渡す** ``` 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 ``` ## セキュリティに関する考慮事項 + **サブプロセス分離** – ターゲットコマンドは を介して実行されます`subprocess.run`。シークレット値は、`asm-exec`プロセスメモリと子プロセス引数にのみ存在します。 ## フックがシークレットへの直接アクセスをブロックする方法 `aws-core` プラグインを有効にすると、`PreToolUse`フックは実行前に を傍受します。これは以下をブロックします。 + `aws secretsmanager get-secret-value` および CLI `batch-get-secret-value`経由 + `get_secret_value` スクリプトでの SDK 呼び出し`batch_get_secret_value`による および + AWSワークロード認証情報プロバイダーデーモンパスへの直接アクセス (`localhost:2773/secretsmanager/get`) + `GetSecretValue` MCP ツールまたは構造化AWS API コールによる オペレーション 通話がブロックされると、エージェントは拒否メッセージを受信し、`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コンソールでシークレット構造を確認するか、シークレット所有者に使用可能なキーの確認を依頼します。 ### フックは通話をブロックしません エージェントセッションの開始時にフックロードします。セッション中にプラグインをインストールした場合は、フックを有効にするエージェントセッションを再起動します。