View a markdown version of this page

Gunakan rahasia dengan aman dengan Agen Pengkodean AI - AWS Secrets Manager
Cara kerjanyaPrasyaratPasang plugin{{resolve:...}} sintaksisGunakan asm-exec untuk menjalankan perintah dengan rahasiaCross-region rahasiaPertimbangan keamananBagaimana hook memblokir akses rahasia langsungPemecahan masalah

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Gunakan rahasia dengan aman dengan Agen Pengkodean AI

Ketika agen pengkodean AI memiliki akses shell atau AWS API, mereka dapat menelepon get-secret-value dan menerima rahasia teks biasa di jendela konteks mereka. Ini menciptakan banyak risiko: nilai rahasia dapat bocor ke riwayat percakapan, log, atau panggilan alat hilir.

Untuk mencegah hal ini, gunakan keterampilan keamanan rahasia di Agen Toolkit untuk AWS. Keterampilan ini mengajarkan agen AI untuk menggunakan referensi dinamis yang diselesaikan saat runtime, sehingga agen mengatur penggunaan rahasia tanpa pernah melihat nilai plaintext.

penting

Ini adalah pertahanan upaya terbaik, bukan batas keamanan. Ini mencegah jalur kebocoran yang paling umum tetapi tidak dapat menghentikan semua vektor penghindaran. Kombinasikan dengan kebijakan hak istimewa, pemantauan, dan titik akhir VPC CloudTrail IAM.

Cara kerjanya

Keterampilan keamanan rahasia memberikan dua lapisan perlindungan:

  1. Panduan keterampilan — Mengajarkan agen untuk menggunakan referensi {{resolve:secretsmanager:...}} dinamis denganasm-exec, skrip pembungkus yang menyelesaikan referensi saat runtime. Nilai plaintext hanya ada dalam proses anak dan tidak pernah memasuki jendela konteks agen.

  2. Penegakan struktural (hook) - PreToolUse Hook secara otomatis memblokir setiap upaya untuk memanggil get-secret-value atau batch-get-secret-value melalui AWS CLI, SDK, alat MCP, atau akses langsung ke daemon Penyedia Kredensyal AWS Beban Kerja. Tidak diperlukan konfigurasi manual.

Prasyarat

Pasang plugin

Instal aws-core plugin untuk platform agen Anda. Keterampilan keamanan rahasia dan kait diaktifkan secara otomatis.

Untuk Kode Claude:

claude plugin add ./plugins/aws-core

Untuk OpenAI Codex:

codex plugin add ./plugins/aws-core

Untuk platform lain yang didukung, lihat Toolkit Agen untuk AWS README.

{{resolve:...}} sintaksis

Ketika agen perlu meneruskan rahasia ke perintah, ia menggunakan referensi dinamis alih-alih memanggilget-secret-value:

{{resolve:secretsmanager:<secret-id>:<field-type>:<json-key>:<version-stage>}}
Komponen Diperlukan Default Deskripsi
secret-id Ya – Nama rahasia atau ARN lengkap
field-type Tidak SecretString Harus SecretString
json-key Tidak (nilai penuh) Kunci untuk mengekstrak dari nilai rahasia JSON
version-stage Tidak AWSCURRENT Label tahap versi

Gunakan asm-exec untuk menjalankan perintah dengan rahasia

asm-execadalah skrip pembungkus yang menyelesaikan {{resolve:...}} referensi dalam argumen perintah, lalu menjalankan perintah target. Nilai rahasia hanya ada dalam proses anak.

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

asm-execmenyelesaikan referensi melalui backend pertama yang tersedia:

  1. AWS Penyedia Kredensial Beban Kerja aktif localhost:2773 — di-cache secara lokal.

  2. AWS MCP endpoint — SigV4-signed permintaan menggunakan kredensyal yang tersedia AWS.

contoh Connect ke database 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"
contoh Lakukan panggilan API dengan token pembawa
asm-exec -- curl -H "Authorization: Bearer {{resolve:secretsmanager:prod/api-token}}" \
  https://api.example.com/data
contoh Connect ke MySQL dengan beberapa rahasia
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"
contoh Berikan rahasia sebagai variabel lingkungan ke wadah Docker
asm-exec -- docker run \
  -e "DB_PASSWORD={{resolve:secretsmanager:prod/db:SecretString:password}}" \
  myapp:latest

Cross-region rahasia

Untuk rahasia yang disimpan di wilayah yang berbeda dari wilayah default Anda, gunakan ARN lengkap (yang mencakup wilayah) atau setel variabel AWS_REGION lingkungan.

# 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

Pertimbangan keamanan

  • Isolasi subproses — Perintah target berjalan melaluisubprocess.run. Nilai rahasia hanya ada dalam memori asm-exec proses dan argumen proses anak.

Bagaimana hook memblokir akses rahasia langsung

Ketika aws-core plugin diaktifkan, PreToolUse hook mencegat panggilan alat sebelum eksekusi. Ini memblokir:

  • aws secretsmanager get-secret-valuedan batch-get-secret-value melalui CLI

  • get_secret_valuedan batch_get_secret_value melalui panggilan SDK dalam skrip

  • Akses langsung ke jalur daemon Penyedia Kredensial AWS Beban Kerja () localhost:2773/secretsmanager/get

  • GetSecretValueoperasi melalui alat MCP atau panggilan AWS API terstruktur

Ketika panggilan diblokir, agen menerima pesan penolakan yang mengarahkannya untuk menggunakan {{resolve:...}} referensi asm-exec sebagai gantinya.

Pemecahan masalah

Kesalahan “Rahasia tidak ditemukan”

Verifikasi rahasia itu ada dan peran IAM Anda memiliki secretsmanager:GetSecretValue izin. Nama rahasia peka huruf besar/kecil.

AWS Beban Kerja Kredensyal Koneksi penyedia ditolak

Penyedia Kredensyal AWS Beban Kerja mungkin tidak berjalan. Ini tidak fatal — asm-exec jatuh ke titik akhir SigV4-signed MCP. Pastikan AWS kredensyal tersedia sehingga backend dapat mengautentikasi.

Kesalahan “Gagal menyelesaikan”

Kedua backend tidak dapat dijangkau. Periksa apakah Penyedia Kredensyal AWS Beban Kerja sedang berjalan atau AWS kredensialnya valid (aws sts get-caller-identity), bahwa wilayah rahasia sudah benar, dan identitas Anda ada di rahasia tersebut. secretsmanager:GetSecretValue

Resolusi menghasilkan string kosong

Kunci JSON mungkin tidak ada dalam nilai rahasia. Verifikasi struktur rahasia di AWS konsol atau minta pemilik rahasia untuk mengonfirmasi kunci yang tersedia.

Hook tidak memblokir panggilan

Kait dimuat saat sesi agen dimulai. Jika Anda menginstal plugin pertengahan sesi, mulai ulang sesi agen agar hook dapat diaktifkan.