기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# AI 코딩 에이전트에서 보안 암호를 안전하게 사용
<a name="retrieving-secrets-ai-agents"></a>

AI 코딩 에이전트는 쉘 또는AWS API 액세스 권한이 있는 경우 컨텍스트 창에서 일반 텍스트 암호를 호출`get-secret-value`하고 수신할 수 있습니다. 이로 인해 여러 위험이 발생합니다. 보안 암호 값은 대화 기록, 로그 또는 다운스트림 도구 호출로 유출될 수 있습니다.

이를 방지하려면 [Agent Toolkit for AWS](https://github.com/aws/agent-toolkit-for-aws)의 *보안 암호 안전* 기술을 사용합니다. 스킬은 AI 에이전트에게 런타임 시 확인된 동적 참조를 사용하도록 교육하므로 에이전트는 일반 텍스트 값을 보지 않고 보안 암호 사용을 오케스트레이션합니다.

**중요**  
이는 보안 경계가 아닌 최선의 방어입니다. 가장 일반적인 누출 경로를 방지하지만 모든 회피 벡터를 중지할 수는 없습니다. IAM 최소 권한, CloudTrail 모니터링 및 VPC 엔드포인트 정책과 결합합니다.

## 작동 방식
<a name="retrieving-secrets-ai-agents-how-it-works"></a>

보안 암호 안전 기술은 두 가지 보호 계층을 제공합니다.

1. **스킬 지침** - 런타임 시 참조를 확인하는 래퍼 스크립트`asm-exec`인를 사용하여 `{{resolve:secretsmanager:...}}` 동적 참조를 사용하도록 에이전트를 티치합니다. 일반 텍스트 값은 하위 프로세스에만 존재하며 에이전트의 컨텍스트 창에 절대 들어가지 않습니다.

1. **구조 적용(후크)** - `PreToolUse` 후크는 SDK AWS CLI, MCP 도구를 `batch-get-secret-value` 통해 `get-secret-value` 또는를 호출하거나AWS워크로드 자격 증명 공급자 데몬에 직접 액세스하려는 모든 시도를 자동으로 차단합니다. 수동 구성은 필요하지 않습니다.

## 사전 조건
<a name="retrieving-secrets-ai-agents-prerequisites"></a>
+ [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 또는 [OpenAI Codex](https://openai.com/index/codex/)와 같은 플러그인을 지원하는 AI 코딩 에이전트입니다.
+ `aws-core` 플러그인[용 에이전트 도구 키트AWS](https://github.com/aws/agent-toolkit-for-aws)가 설치되었습니다.
+ 다음 보안 암호 확인 백엔드 중 하나:
  + 에서 실행되는 **AWS워크로드 자격 증명 공급자입니다**`localhost:2773`. [AWS워크로드 자격 증명 공급자 사용](workload-credentials-provider.md)을(를) 참조하세요.
  + AWS MCP 엔드포인트에 대한 요청에 서명할 수 있는 **AWS자격 증명**입니다.
+ IAM 권한: 확인하려는 보안 암호에 `secretsmanager:GetSecretValue` 대한 권한입니다.

## 플러그인 설치
<a name="retrieving-secrets-ai-agents-install"></a>

에이전트 플랫폼용 `aws-core` 플러그인을 설치합니다. 보안 암호 안전 기술과 후크가 자동으로 활성화됩니다.

Claude 코드의 경우:

```
claude plugin add ./plugins/aws-core
```

OpenAI Codex의 경우:

```
codex plugin add ./plugins/aws-core
```

지원되는 다른 플랫폼은 [README용AWS에이전트 툴킷](https://github.com/aws/agent-toolkit-for-aws)을 참조하세요.

## `{{resolve:...}}` 구문
<a name="retrieving-secrets-ai-agents-syntax"></a>

에이전트가 명령에 암호를 전달해야 하는 경우를 호출하는 대신 동적 참조를 사용합니다`get-secret-value`.

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


| 구성 요소 | 필수 | 기본값 | 설명 | 
| --- | --- | --- | --- | 
| secret-id | 예 | – | 보안 암호 이름 또는 전체 ARN | 
| field-type | 아니요 | SecretString | SecretString이어야 합니다. | 
| json-key | 아니요 | (전체 값) | JSON 보안 암호 값에서 추출할 키 | 
| version-stage | 아니요 | AWSCURRENT | 버전 단계 레이블 | 

## `asm-exec`를 사용하여 보안 암호로 명령 실행
<a name="retrieving-secrets-ai-agents-asm-exec"></a>

`asm-exec`는 명령 인수의 `{{resolve:...}}` 참조를 확인한 다음 대상 명령을 실행하는 래퍼 스크립트입니다. 보안 암호 값은 하위 프로세스에만 존재합니다.

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

`asm-exec`는 사용 가능한 첫 번째 백엔드를 통해 참조를 확인합니다.

1. 의 **AWS워크로드 자격 증명 공급자** `localhost:2773` - 로컬로 캐시됩니다.

1. **AWS MCP 엔드포인트** SigV4-signed 요청입니다.AWS

**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
```

## 교차 리전 보안 암호
<a name="retrieving-secrets-ai-agents-cross-region"></a>

기본 리전과 다른 리전에 저장된 보안 암호의 경우 전체 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
```

## 보안 고려 사항
<a name="retrieving-secrets-ai-agents-security"></a>
+ **하위 프로세스 격리** - 대상 명령은를 통해 실행됩니다`subprocess.run`. 보안 암호 값은 `asm-exec` 프로세스 메모리와 하위 프로세스 인수에만 존재합니다.

## 후크가 직접 보안 암호 액세스를 차단하는 방법
<a name="retrieving-secrets-ai-agents-hook"></a>

`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 호출을 통한 작업

통화가 차단되면 에이전트는 `{{resolve:...}}` 참조를 `asm-exec` 대신 사용하도록 지시하는 거부 메시지를 수신합니다.

## 문제 해결
<a name="retrieving-secrets-ai-agents-troubleshooting"></a>

### "보안 암호를 찾을 수 없음" 오류
<a name="retrieving-secrets-ai-agents-ts-not-found"></a>

보안 암호가 존재하고 IAM 역할에 `secretsmanager:GetSecretValue` 권한이 있는지 확인합니다. 보안 암호 이름은 대/소문자를 구분합니다.

### AWS워크로드 자격 증명 공급자 연결이 거부됨
<a name="retrieving-secrets-ai-agents-ts-connection-refused"></a>

AWS워크로드 자격 증명 공급자가 실행되고 있지 않을 수 있습니다. 이는 치명적이지 않습니다.는 SigV4-signed MCP 엔드포인트로 `asm-exec` 폴스루됩니다. 백엔드가 인증할 수 있도록AWS자격 증명을 사용할 수 있는지 확인합니다.

### “해결 실패” 오류
<a name="retrieving-secrets-ai-agents-ts-failed-resolve"></a>

두 백엔드에 모두 연결할 수 없었습니다.AWS워크로드 자격 증명 공급자가 실행 중이거나AWS자격 증명이 유효한지(`aws sts get-caller-identity`), 보안 암호의 리전이 올바른지, 자격 증명이 보안 암호`secretsmanager:GetSecretValue`에 있는지 확인합니다.

### 해결 방법으로 빈 문자열 생성
<a name="retrieving-secrets-ai-agents-ts-empty-string"></a>

JSON 키가 보안 암호 값에 존재하지 않을 수 있습니다.AWS콘솔에서 보안 암호 구조를 확인하거나 보안 암호 소유자에게 사용 가능한 키를 확인하도록 요청합니다.

### 후크가 호출을 차단하지 않음
<a name="retrieving-secrets-ai-agents-ts-hook-not-blocking"></a>

에이전트 세션 시작 시 후크 로드. 세션 중 플러그인을 설치한 경우 후크가 활성화되도록 에이전트 세션을 다시 시작합니다.