Mengamankan penyebaran agen AI

Panduan untuk mengamankan penyebaran Claude Code dan Agent SDK dengan isolasi, manajemen kredensial, dan kontrol jaringan

Claude Code dan Agent SDK dapat menjalankan kode, mengakses file, dan berinteraksi dengan layanan eksternal atas nama Anda.

Tidak seperti perangkat lunak tradisional yang mengikuti jalur kode yang telah ditentukan sebelumnya, alat ini menghasilkan tindakan mereka secara dinamis berdasarkan konteks dan tujuan. Fleksibilitas inilah yang membuat mereka berguna, tetapi ini juga berarti perilaku mereka dapat dipengaruhi oleh konten yang mereka proses: file, halaman web, atau input pengguna. Ini kadang-kadang disebut prompt injection. Misalnya, jika README repositori berisi instruksi yang tidak biasa, Claude Code mungkin menggabungkan instruksi tersebut ke dalam tindakannya dengan cara yang tidak diantisipasi oleh operator. Panduan ini mencakup cara praktis untuk mengurangi risiko ini.

Tidak setiap penyebaran memerlukan keamanan maksimal. Pengembang yang menjalankan Claude Code di laptop mereka memiliki persyaratan yang berbeda dari perusahaan yang memproses data pelanggan di lingkungan multi-tenant. Panduan ini menyajikan opsi mulai dari fitur keamanan bawaan Claude Code hingga arsitektur produksi yang dikeraskan, sehingga Anda dapat memilih apa yang sesuai dengan situasi Anda.

Model ancaman

Agen dapat mengambil tindakan yang tidak diinginkan karena prompt injection (instruksi yang tertanam dalam konten yang mereka proses) atau kesalahan model. Model Claude dirancang untuk menahan ini; lihat model overview dan kartu sistem untuk model yang Anda sebarkan untuk detail evaluasi.

Pertahanan berlapis masih merupakan praktik yang baik. Misalnya, jika agen memproses file berbahaya yang menginstruksikannya untuk mengirim data pelanggan ke server eksternal, kontrol jaringan dapat memblokir permintaan itu sepenuhnya.

Fitur keamanan bawaan

Claude Code mencakup beberapa fitur keamanan yang mengatasi kekhawatiran umum. Lihat dokumentasi keamanan untuk detail lengkap.

• Sistem izin: Aturan izin menentukan apakah sebuah panggilan tool dijalankan, diblokir, atau meminta persetujuan terlebih dahulu. Untuk bentuk-bentuk yang tidak tercakup oleh aturan Bash dan cara aturan dikombinasikan dengan mode izin, lihat Apa yang tidak dicocokkan oleh aturan Bash dan Mengonfigurasi izin. Administrator juga dapat menetapkan aturan di pengaturan terkelola.
• Penghapusan jalur kritis: Dengan mode izin diatur ke default, perintah rm atau rmdir yang dikenali sebagai menghapus direktori kerja Anda atau jalur kritis lainnya memerlukan persetujuan. Aturan allow yang cocok tidak melewati persetujuan tersebut. Ini adalah gerbang izin, bukan sandbox. Untuk mengontrol apa yang dapat ditulis oleh agent, gunakan kontrol filesystem.
• Ringkasan pencarian web: Hasil pencarian diringkas daripada melewatkan konten mentah langsung ke dalam konteks, mengurangi risiko prompt injection dari konten web berbahaya.
• Mode sandbox: Perintah Bash dapat berjalan di lingkungan sandbox yang membatasi akses filesystem dan jaringan. Lihat dokumentasi sandboxing untuk detail.

Prinsip keamanan

Untuk penyebaran yang memerlukan pengerasan tambahan di luar default Claude Code, prinsip-prinsip ini memandu opsi yang tersedia.

Batas keamanan

Batas keamanan memisahkan komponen dengan tingkat kepercayaan yang berbeda. Untuk penyebaran keamanan tinggi, Anda dapat menempatkan sumber daya sensitif (seperti kredensial) di luar batas yang berisi agen. Jika ada yang salah di lingkungan agen, sumber daya di luar batas itu tetap terlindungi.

Misalnya, daripada memberikan agen akses langsung ke kunci API, Anda dapat menjalankan proxy di luar lingkungan agen yang menyuntikkan kunci ke dalam permintaan. Agen dapat melakukan panggilan API, tetapi tidak pernah melihat kredensial itu sendiri. Pola ini berguna untuk penyebaran multi-tenant atau saat memproses konten yang tidak terpercaya.

Privilege minimal

Jika diperlukan, Anda dapat membatasi agen hanya ke kemampuan yang diperlukan untuk tugas spesifiknya:

Pertahanan berlapis

Untuk lingkungan keamanan tinggi, melapisi beberapa kontrol memberikan perlindungan tambahan. Opsi termasuk:

• Isolasi kontainer
• Pembatasan jaringan
• Kontrol filesystem
• Validasi permintaan di proxy

Kombinasi yang tepat tergantung pada model ancaman dan persyaratan operasional Anda.

Teknologi isolasi

Teknologi isolasi yang berbeda menawarkan trade-off yang berbeda antara kekuatan keamanan, kinerja, dan kompleksitas operasional.

[!NOTE]

Dalam semua konfigurasi ini, Claude Code (atau aplikasi Agent SDK Anda) berjalan di dalam batas isolasi (sandbox, kontainer, atau VM). Kontrol keamanan yang dijelaskan di bawah membatasi apa yang dapat diakses agen dari dalam batas itu.

Sandbox runtime

Untuk isolasi ringan tanpa kontainer, sandbox-runtime memberlakukan pembatasan filesystem dan jaringan di tingkat OS.

Keuntungan utama adalah kesederhanaan: tidak ada konfigurasi Docker, citra kontainer, atau setup jaringan yang diperlukan. Proxy dan pembatasan filesystem sudah tertanam.

Cara kerjanya:

• Filesystem: Menggunakan primitif OS (bubblewrap di Linux, sandbox-exec di macOS) untuk membatasi akses baca/tulis ke jalur yang dikonfigurasi
• Jaringan: Menjalankan perintah di namespace jaringannya sendiri (Linux) atau di bawah profil Seatbelt (macOS) dan merutekan lalu lintasnya melalui proxy bawaan yang mengizinkan domain yang dikonfigurasi. Koneksi ke host luar yang melewati proxy akan gagal.
• Konfigurasi: Daftar izin berbasis JSON untuk domain dan jalur filesystem

Setup:

Untuk langkah instalasi, konfigurasi, dan peluncuran, lihat Menyiapkan dan meluncurkan runtime.

Pertimbangan keamanan:

1. Kernel host yang sama: Tidak seperti VM, proses sandbox berbagi kernel host. Kerentanan kernel secara teoritis dapat memungkinkan escape. Untuk beberapa model ancaman ini dapat diterima, tetapi jika Anda memerlukan isolasi tingkat kernel, gunakan gVisor atau VM terpisah.

2. Tidak ada inspeksi TLS: Secara default, proxy menerapkan allowlist domain berdasarkan nama host yang disediakan klien dan tidak menghentikan atau memeriksa lalu lintas terenkripsi. Kode yang berjalan di dalam sandbox dapat berpotensi menggunakan domain fronting atau teknik serupa untuk menjangkau host di luar allowlist. Jika model ancaman Anda memerlukan jaminan yang lebih kuat, gunakan proxy yang menghentikan TLS dan memeriksa lalu lintas, seperti yang dijelaskan di Penerusan lalu lintas. Untuk informasi lebih lanjut, lihat batasan keamanan sandboxing.

3. Kredensial untuk domain yang diizinkan: Jika agent memiliki kredensial permisif untuk domain yang diizinkan, pastikan agent tidak dapat menggunakan domain itu untuk memicu permintaan jaringan lain atau untuk mengeksfiltrasi data.

Untuk banyak kasus penggunaan pengembang tunggal dan CI/CD, sandbox-runtime meningkatkan standar secara signifikan dengan setup minimal. Bagian di bawah mencakup kontainer dan VM untuk penyebaran yang memerlukan isolasi yang lebih kuat.

Kontainer

Kontainer menyediakan isolasi melalui namespace Linux. Setiap kontainer memiliki pandangan sendiri tentang filesystem, pohon proses, dan stack jaringan, sambil berbagi kernel host.

Konfigurasi kontainer yang dikeraskan keamanan mungkin terlihat seperti ini:

docker run \
  --cap-drop ALL \
  --security-opt no-new-privileges \
  --security-opt seccomp=/path/to/seccomp-profile.json \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --tmpfs /home/agent:rw,noexec,nosuid,size=500m \
  --network none \
  --memory 2g \
  --cpus 2 \
  --pids-limit 100 \
  --user 1000:1000 \
  -v /path/to/code:/workspace:ro \
  -v /var/run/proxy.sock:/var/run/proxy.sock:ro \
  agent-image

Berikut adalah apa yang dilakukan setiap opsi:

Arsitektur soket Unix:

Dengan --network none, pencarian DNS atau koneksi langsung ke host lain akan gagal di dalam kontainer. Agar kode di dalam kontainer dapat menjangkau host lain, jalankan proxy di host dan pasang soket Unix-nya ke dalam kontainer. Jika Anda mengarahkan ANTHROPIC_BASE_URL atau HTTP_PROXY ke port di localhost, seperti yang ditunjukkan di Mengonfigurasi Claude Code untuk menggunakan proxy, teruskan port tersebut di dalam kontainer ke soket.

Anda dapat menyiapkan proxy ini untuk memberlakukan allowlist domain, menyuntikkan kredensial, dan mencatat semua lalu lintas.

[!WARNING]

Di dalam allowlist proxy Anda, agent dapat mengirim data ke domain mana pun yang diizinkan. Izinkan hanya domain yang dibutuhkan agent.

Opsi pengerasan tambahan:

gVisor

Kontainer standar berbagi kernel host: ketika kode di dalam kontainer membuat system call, itu langsung ke kernel yang sama yang menjalankan host. Ini berarti kerentanan kernel dapat memungkinkan escape kontainer. gVisor mengatasi ini dengan mengintersepsi system call di userspace sebelum mereka mencapai kernel host, mengimplementasikan lapisan kompatibilitas sendiri yang menangani sebagian besar syscall tanpa melibatkan kernel nyata.

Jika agen menjalankan kode berbahaya (mungkin karena prompt injection), kode itu berjalan di kontainer dan dapat mencoba exploit kernel. Dengan gVisor, permukaan serangan jauh lebih kecil: kode berbahaya perlu mengeksploitasi implementasi userspace gVisor terlebih dahulu dan akan memiliki akses terbatas ke kernel nyata.

Untuk menggunakan gVisor dengan Docker, instal runtime runsc dan konfigurasikan daemon:

{
  "runtimes": {
    "runsc": {
      "path": "/usr/local/bin/runsc"
    }
  }
}

Kemudian jalankan kontainer dengan:

docker run --runtime=runsc agent-image

Pertimbangan kinerja:

Untuk lingkungan multi-tenant atau saat memproses konten yang tidak terpercaya, isolasi tambahan sering kali sepadan dengan overhead.

Mesin virtual

VM menyediakan isolasi tingkat hardware melalui ekstensi virtualisasi CPU. Setiap VM menjalankan kernel sendiri, menciptakan batas yang kuat. Kerentanan di kernel guest tidak secara langsung mengkompromikan host. Namun, VM tidak secara otomatis "lebih aman" daripada alternatif seperti gVisor. Keamanan VM sangat bergantung pada hypervisor dan kode emulasi perangkat.

Firecracker dirancang untuk isolasi microVM yang ringan. Itu dapat boot VM dalam waktu kurang dari 125ms dengan overhead memori kurang dari 5 MiB, menghilangkan emulasi perangkat yang tidak perlu untuk mengurangi permukaan serangan.

Dengan pendekatan ini, VM agen tidak memiliki antarmuka jaringan eksternal. Sebaliknya, itu berkomunikasi melalui vsock (soket virtual). Semua lalu lintas merutekan melalui vsock ke proxy di host, yang memberlakukan daftar izin dan menyuntikkan kredensial sebelum meneruskan permintaan.

Penyebaran cloud

Untuk penyebaran cloud, Anda dapat menggabungkan teknologi isolasi apa pun di atas dengan kontrol jaringan asli cloud:

1. Jalankan kontainer agen di subnet pribadi tanpa internet gateway
2. Konfigurasikan aturan firewall cloud (AWS Security Groups, GCP VPC firewall) untuk memblokir semua egress kecuali ke proxy Anda
3. Jalankan proxy (seperti Envoy dengan filter credential_injector nya) yang memvalidasi permintaan, memberlakukan daftar izin domain, menyuntikkan kredensial, dan meneruskan ke API eksternal
4. Tetapkan izin IAM minimal ke akun layanan agen, merutekan akses sensitif melalui proxy jika memungkinkan
5. Catat semua lalu lintas di proxy untuk tujuan audit

Manajemen kredensial

Agen sering memerlukan kredensial untuk memanggil API, mengakses repositori, atau berinteraksi dengan layanan cloud. Tantangannya adalah memberikan akses ini tanpa mengekspos kredensial itu sendiri.

Pola proxy

Pendekatan yang direkomendasikan adalah menjalankan proxy di luar batas keamanan agen yang menyuntikkan kredensial ke dalam permintaan keluar. Agen mengirim permintaan tanpa kredensial, proxy menambahkannya, dan meneruskan permintaan ke tujuannya.

Pola ini memiliki beberapa manfaat:

1. Agen tidak pernah melihat kredensial aktual
2. Proxy dapat memberlakukan daftar izin endpoint yang diizinkan
3. Proxy dapat mencatat semua permintaan untuk audit
4. Kredensial disimpan di satu lokasi aman daripada didistribusikan ke setiap agen

Mengonfigurasi Claude Code untuk menggunakan proxy

Claude Code mendukung dua metode untuk merutekan permintaan sampling melalui proxy:

Opsi 1: ANTHROPIC_BASE_URL (sederhana tetapi hanya untuk permintaan API sampling)

export ANTHROPIC_BASE_URL="http://localhost:8080"

Ini memberitahu Claude Code dan Agent SDK untuk mengirim permintaan sampling ke proxy Anda daripada langsung ke API Claude. Proxy Anda menerima permintaan HTTP plaintext, dapat memeriksa dan memodifikasinya (termasuk menyuntikkan kredensial), kemudian meneruskan ke API nyata.

Opsi 2: HTTP_PROXY / HTTPS_PROXY (system-wide)

export HTTP_PROXY="http://localhost:8080"
export HTTPS_PROXY="http://localhost:8080"

Claude Code dan Agent SDK menghormati variabel lingkungan standar ini, merutekan semua lalu lintas HTTP melalui proxy. Untuk HTTPS, proxy membuat terowongan CONNECT terenkripsi: itu tidak dapat melihat atau memodifikasi konten permintaan tanpa intersepsi TLS.

Mengimplementasikan proxy

Anda dapat membangun proxy Anda sendiri atau menggunakan yang sudah ada:

• Envoy Proxy: proxy tingkat produksi dengan filter credential_injector untuk menambahkan header auth
• mitmproxy: proxy yang menghentikan TLS untuk memeriksa dan memodifikasi lalu lintas HTTPS
• Squid: proxy caching dengan daftar kontrol akses
• LiteLLM: gateway LLM dengan injeksi kredensial dan pembatasan laju

Kredensial untuk layanan lain

Di luar sampling dari API Claude, agen sering memerlukan akses terautentikasi ke layanan lain, seperti repositori git, database, dan API internal. Ada dua pendekatan utama:

Alat kustom

Sediakan akses melalui server MCP atau alat kustom yang merutekan permintaan ke layanan yang berjalan di luar batas keamanan agen. Agen memanggil alat, tetapi permintaan terautentikasi aktual terjadi di luar. Panggilan alat ke proxy yang menyuntikkan kredensial.

Misalnya, server MCP git dapat menerima perintah dari agen tetapi meneruskannya ke proxy git yang berjalan di host, yang menambahkan autentikasi sebelum menghubungi repositori jarak jauh. Agen tidak pernah melihat kredensial.

Keuntungan:

• Tidak ada intersepsi TLS: Layanan eksternal membuat permintaan terautentikasi secara langsung
• Kredensial tetap di luar: Agen hanya melihat antarmuka alat, bukan kredensial yang mendasarinya

Penerusan lalu lintas

Untuk panggilan API Claude, ANTHROPIC_BASE_URL memungkinkan Anda merutekan permintaan ke proxy yang dapat memeriksa dan memodifikasinya dalam plaintext. Tetapi untuk layanan HTTPS lainnya (GitHub, registri npm, API internal), lalu lintas sering dienkripsi end-to-end. Bahkan jika Anda merutekannya melalui proxy melalui HTTP_PROXY, proxy hanya melihat terowongan TLS yang buram dan tidak dapat menyuntikkan kredensial.

Untuk memodifikasi lalu lintas HTTPS ke layanan arbitrer, tanpa menggunakan alat kustom, Anda memerlukan proxy yang menghentikan TLS yang mendekripsi lalu lintas, memeriksa atau memodifikasinya, kemudian mengenkripsi ulang sebelum meneruskan. Ini memerlukan:

1. Menjalankan proxy di luar kontainer agen
2. Memasang sertifikat CA proxy di toko kepercayaan agen (sehingga agen mempercayai sertifikat proxy)
3. Mengonfigurasi HTTP_PROXY/HTTPS_PROXY untuk merutekan lalu lintas melalui proxy

Pendekatan ini menangani layanan berbasis HTTP apa pun tanpa menulis alat kustom, tetapi menambah kompleksitas di sekitar manajemen sertifikat.

Perhatikan bahwa tidak semua program menghormati HTTP_PROXY/HTTPS_PROXY. Sebagian besar alat (curl, pip, npm, git) melakukannya, tetapi beberapa mungkin melewati variabel ini dan terhubung langsung. Misalnya, Node.js fetch() mengabaikan variabel ini secara default; di Node 24+ Anda dapat mengatur NODE_USE_ENV_PROXY=1 untuk mengaktifkan dukungan. Untuk mencakup alat yang mengabaikan variabel ini, Anda dapat menggunakan proxychains untuk mengintersepsi panggilan jaringan, atau mengonfigurasi iptables untuk mengarahkan lalu lintas keluar ke proxy transparan.

[!NOTE]

Proxy transparan mengintersepsi lalu lintas di tingkat jaringan, sehingga klien tidak perlu dikonfigurasi untuk menggunakannya. Proxy reguler memerlukan klien untuk secara eksplisit terhubung dan berbicara HTTP CONNECT atau SOCKS. Proxy transparan (seperti Squid atau mitmproxy dalam mode transparan) dapat menangani koneksi TCP yang dialihkan mentah.

Kedua pendekatan masih memerlukan proxy yang menghentikan TLS dan sertifikat CA terpercaya. Mereka hanya memastikan lalu lintas benar-benar mencapai proxy.

Konfigurasi filesystem

Kontrol filesystem menentukan file apa yang dapat dibaca dan ditulis agen.

Pemasangan kode read-only

Ketika agen perlu menganalisis kode tetapi tidak memodifikasinya, pasang direktori read-only:

docker run -v /path/to/code:/workspace:ro agent-image

[!WARNING]

Bahkan akses read-only ke direktori kode dapat mengekspos kredensial. File umum untuk dikecualikan atau disanitasi sebelum pemasangan:

File	Risiko
.env, .env.local	Kunci API, kata sandi database, rahasia
~/.git-credentials	Kata sandi/token Git dalam plaintext
~/.aws/credentials	Kunci akses AWS
~/.config/gcloud/application_default_credentials.json	Token ADC Google Cloud
~/.azure/	Kredensial CLI Azure
~/.docker/config.json	Token auth registri Docker
~/.kube/config	Kredensial kluster Kubernetes
.npmrc, .pypirc	Token registri paket
*-service-account.json	Kunci akun layanan GCP
*.pem, *.key	Kunci pribadi

Pertimbangkan untuk menyalin hanya file sumber yang diperlukan, atau menggunakan penyaringan gaya .dockerignore.

Lokasi yang dapat ditulis

Jika agen perlu menulis file, Anda memiliki beberapa opsi tergantung pada apakah Anda ingin perubahan bertahan:

Untuk ruang kerja ephemeral di kontainer, gunakan pemasangan tmpfs yang hanya ada di memori dan dihapus saat kontainer berhenti:

docker run \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --tmpfs /workspace:rw,noexec,size=500m \
  agent-image

Jika Anda ingin meninjau perubahan sebelum mempertahankannya, filesystem overlay memungkinkan agen menulis tanpa memodifikasi file yang mendasarinya. Perubahan disimpan di lapisan terpisah yang dapat Anda periksa, terapkan, atau buang. Untuk output yang sepenuhnya persisten, pasang volume khusus tetapi simpan terpisah dari direktori sensitif.

Bacaan lebih lanjut

• Dokumentasi keamanan Claude Code
• Hosting Agent SDK
• Menangani izin
• Sandbox runtime
• The Lethal Trifecta for AI Agents
• OWASP Top 10 for LLM Applications
• Docker Security Best Practices
• gVisor Documentation
• Firecracker Documentation