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
<a name="retrieving-secrets-ai-agents"></a>

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](https://github.com/aws/agent-toolkit-for-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
<a name="retrieving-secrets-ai-agents-how-it-works"></a>

Keterampilan keamanan rahasia memberikan dua lapisan perlindungan:

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

1. **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
<a name="retrieving-secrets-ai-agents-prerequisites"></a>
+ [Agen pengkodean AI yang mendukung plugin, seperti [Claude Code atau](https://docs.anthropic.com/en/docs/claude-code) OpenAI Codex.](https://openai.com/index/codex/)
+ [Agen Toolkit untuk AWS](https://github.com/aws/agent-toolkit-for-aws) `aws-core` plugin diinstal.
+ Salah satu backend resolusi rahasia berikut:
  + **AWS Penyedia Kredensial Beban Kerja** berjalan. `localhost:2773` Lihat [Menggunakan AWS Penyedia Kredensyal Beban Kerja](workload-credentials-provider.md).
  + **AWS kredensyal** yang dapat menandatangani permintaan ke titik akhir AWS MCP.
+ Izin IAM: `secretsmanager:GetSecretValue` pada rahasia yang ingin Anda selesaikan.

## Pasang plugin
<a name="retrieving-secrets-ai-agents-install"></a>

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](https://github.com/aws/agent-toolkit-for-aws).

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

Ketika agen perlu meneruskan rahasia ke perintah, ia menggunakan referensi dinamis alih-alih memanggil`get-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
<a name="retrieving-secrets-ai-agents-asm-exec"></a>

`asm-exec`adalah 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-exec`menyelesaikan referensi melalui backend pertama yang tersedia:

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

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

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

**Example Lakukan panggilan API dengan token pembawa**  

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

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

**Example 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
<a name="retrieving-secrets-ai-agents-cross-region"></a>

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
<a name="retrieving-secrets-ai-agents-security"></a>
+ **Isolasi subproses** — Perintah target berjalan melalui`subprocess.run`. Nilai rahasia hanya ada dalam memori `asm-exec` proses dan argumen proses anak.

## Bagaimana hook memblokir akses rahasia langsung
<a name="retrieving-secrets-ai-agents-hook"></a>

Ketika `aws-core` plugin diaktifkan, `PreToolUse` hook mencegat panggilan alat sebelum eksekusi. Ini memblokir:
+ `aws secretsmanager get-secret-value`dan `batch-get-secret-value` melalui CLI
+ `get_secret_value`dan `batch_get_secret_value` melalui panggilan SDK dalam skrip
+ Akses langsung ke jalur daemon Penyedia Kredensial AWS Beban Kerja () `localhost:2773/secretsmanager/get`
+ `GetSecretValue`operasi 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
<a name="retrieving-secrets-ai-agents-troubleshooting"></a>

### Kesalahan “Rahasia tidak ditemukan”
<a name="retrieving-secrets-ai-agents-ts-not-found"></a>

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
<a name="retrieving-secrets-ai-agents-ts-connection-refused"></a>

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”
<a name="retrieving-secrets-ai-agents-ts-failed-resolve"></a>

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
<a name="retrieving-secrets-ai-agents-ts-empty-string"></a>

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
<a name="retrieving-secrets-ai-agents-ts-hook-not-blocking"></a>

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