View a markdown version of this page

AI 코딩 에이전트에서 보안 암호를 안전하게 사용 - AWS Secrets Manager
작동 방식사전 조건플러그인 설치{{resolve:...}} 구문asm-exec를 사용하여 보안 암호로 명령 실행교차 리전 보안 암호보안 고려 사항후크가 직접 보안 암호 액세스를 차단하는 방법문제 해결

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

AI 코딩 에이전트에서 보안 암호를 안전하게 사용

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

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

중요

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

작동 방식

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

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

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

사전 조건

  • Claude Code 또는 OpenAI Codex와 같은 플러그인을 지원하는 AI 코딩 에이전트입니다.

  • aws-core 플러그인용 에이전트 도구 키트AWS가 설치되었습니다.

  • 다음 보안 암호 확인 백엔드 중 하나:

    • 에서 실행되는 AWS워크로드 자격 증명 공급자입니다localhost:2773. AWS워크로드 자격 증명 공급자 사용을(를) 참조하세요.

    • AWS MCP 엔드포인트에 대한 요청에 서명할 수 있는 AWS자격 증명입니다.

  • IAM 권한: 확인하려는 보안 암호에 secretsmanager:GetSecretValue 대한 권한입니다.

플러그인 설치

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

Claude 코드의 경우:

claude plugin add ./plugins/aws-core

OpenAI Codex의 경우:

codex plugin add ./plugins/aws-core

지원되는 다른 플랫폼은 README용AWS에이전트 툴킷을 참조하세요.

{{resolve:...}} 구문

에이전트가 명령에 암호를 전달해야 하는 경우를 호출하는 대신 동적 참조를 사용합니다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를 사용하여 보안 암호로 명령 실행

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

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

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

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

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

예 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"
예보유자 토큰을 사용하여 API 호출 수행
asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \
  https://api.example.com/data
예여러 보안 암호를 사용하여 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"
예보안 암호를 환경 변수로 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 호출을 통한 작업

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

문제 해결

"보안 암호를 찾을 수 없음" 오류

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

AWS워크로드 자격 증명 공급자 연결이 거부됨

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

“해결 실패” 오류

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

해결 방법으로 빈 문자열 생성

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

후크가 호출을 차단하지 않음

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