Panduan Lengkap Keamanan Claude Code: Kunci API, Izin, dan Perlindungan Produksi

Claude Code memiliki kemampuan manipulasi file dan eksekusi perintah yang powerful — tetapi konfigurasi yang salah dapat menyebabkan kecelakaan yang tidak dapat diperbaiki. Melakukan commit file .env, menghapus database produksi secara tidak sengaja, mencetak kunci API ke log — ini semua adalah insiden nyata yang disebabkan oleh penggunaan Claude Code tanpa perlindungan yang memadai.

Artikel ini memberikan penjelasan tingkat implementasi tentang praktik terbaik keamanan untuk Claude Code. Fokusnya bukan pada teori, melainkan pada konfigurasi siap pakai dan kode preventif yang bisa langsung Anda salin dan terapkan.

Mengapa Claude Code Membutuhkan Langkah Keamanan

Tidak seperti editor teks biasa, Claude Code memiliki kemampuan berikut:

• Membaca, menulis, dan menghapus file apa pun (Read / Write / Edit / Bash(rm))
• Menjalankan perintah shell (Bash)
• Akses jaringan (WebFetch / panggilan API)
• Posting ke layanan eksternal (GitHub, Slack, dll.)

Semua ini dapat dieksekusi dengan persetujuan pengguna. Masalahnya adalah menyetujui setiap prompt secara mekanis membiarkan operasi yang tidak diinginkan lolos. Langkah keamanan berarti menghilangkan ruang untuk kesalahan secara struktural.

Langkah 1: Manajemen Kunci API — .env + .gitignore sebagai Fondasi

Yang TIDAK Boleh Dilakukan

// ❌ Ditulis langsung di kode sumber
const client = new Anthropic({ apiKey: "PASTE_REAL_API_KEY_HERE" });

// ❌ Ditulis di CLAUDE.md atau file konfigurasi
// ANTHROPIC_API_KEY=PASTE_REAL_API_KEY_HERE

// ❌ Disertakan dalam prompt claude -p
// Gunakan QIITA_TOKEN=PASTE_REAL_TOKEN_HERE untuk posting

Pendekatan yang Benar

# .env (dikecualikan dari git, disimpan hanya di mesin lokal)
ANTHROPIC_API_KEY=<anthropic-api-key>
QIITA_TOKEN=<qiita-token>
SLACK_BOT_TOKEN=<slack-bot-token>
DATABASE_URL=postgresql://...

# Selalu tambahkan ke .gitignore
.env
.env.*
.env.local
!.env.example   # ← File contoh boleh di-commit
*.pem
*.key
credentials.json
*-service-account.json

# .env.example (aman untuk di-commit, nilai dikosongkan)
ANTHROPIC_API_KEY=
QIITA_TOKEN=
SLACK_BOT_TOKEN=
DATABASE_URL=

Membaca Variabel dalam Kode

// ✅ Baca dari environment variables
import { config } from "dotenv";
config();

const token = process.env.QIITA_TOKEN;
if (!token) throw new Error("QIITA_TOKEN belum diset. Harap periksa file .env Anda.");

Dokumentasikan Larangan di CLAUDE.md

## Larangan Keamanan
- Jangan pernah menyertakan kunci API atau token dalam prompt
- Jangan pernah membaca dan menampilkan isi file .env
- Jangan pernah menulis nilai environment variable di log atau komentar
- Jangan pernah console.log isi process.env

Langkah 2: Pemindaian Secret Sebelum Commit

Bahkan dengan .env di .gitignore, entri yang tidak sengaja di file lain atau kesalahan copy-paste masih bisa terjadi. Tambahkan pemindaian otomatis pre-commit.

Pemeriksaan Pre-Commit dengan Hooks

.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/secret-scan.mjs"
          }
        ]
      }
    ]
  }
}

scripts/secret-scan.mjs:

import { execSync } from "child_process";

// Dapatkan perubahan yang di-staging
const diff = execSync("git diff --cached").toString();

const PATTERNS = [
  { name: "Assignment kunci API Anthropic", re: /\b(?:ANTHROPIC_API_KEY|CLAUDE_API_KEY)\s*[:=]\s*["']?[^"'\s]{20,}/i },
  { name: "Assignment kunci API OpenAI", re: /\bOPENAI_API_KEY\s*[:=]\s*["']?[^"'\s]{20,}/i },
  { name: "Kunci Akses AWS", re: /\bAKIA[0-9A-Z]{16}\b/ },
  { name: "Token Slack", re: /\bxox[baprs]-[0-9A-Za-z-]{10,}\b/ },
  { name: "Secret Generik", re: /\b(?:secret|token|api[_-]?key|password)\s*[:=]\s*["'][^"']{10,}["']/i },
];

const found = PATTERNS.filter(({ re }) => re.test(diff));

if (found.length > 0) {
  console.error("🚨 Secret terdeteksi! Membatalkan commit:");
  found.forEach(({ name }) => console.error(`  - ${name}`));
  console.error("\nSolusi: jalankan `git reset HEAD <file>` untuk unstage file tersebut");
  process.exit(1);  // Exit code 1 → Hook memblokir perintah
}

console.log("✓ Pemindaian secret: tidak ada masalah ditemukan");
process.exit(0);

Ini berarti saat Claude Code mencoba menjalankan git commit, pemindaian otomatis langsung berjalan dan kebocoran yang terdeteksi akan diblokir.

Langkah 3: Konfigurasi Mode Izin

Pengaturan izinkan/tolak Claude Code dapat dikontrol secara granular di tingkat file.

Pengaturan Izin di .claude/settings.json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "default",
    "disableBypassPermissionsMode": "disable",
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(DROP TABLE*)",
      "Bash(truncate*)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(npm publish*)",
      "Bash(wrangler pages deploy*)"
    ]
  },
  "disableAutoMode": "disable"
}

Pengaturan	Arti
allow	Jalankan tanpa konfirmasi
deny	Jangan pernah jalankan (diblokir sepenuhnya)
ask	Memerlukan persetujuan setiap kali

Prinsip utama: Perintah destruktif masuk deny, operasi tulis masuk ask, operasi baca masuk allow.

Pisahkan produksi dan kebijakan organisasi dengan local atau managed settings

Model pengaturan resmi menerapkan scope dalam urutan ini: managed, argumen command-line, local, project, lalu user. Daripada mengandalkan switch file kustom yang tidak resmi, gunakan .claude/settings.local.json untuk terminal produksi pribadi yang lebih ketat dan managed settings untuk aturan organisasi.

Gunakan .claude/settings.local.json sebagai override lokal dan jangan commit ke git.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "plan",
    "disableBypassPermissionsMode": "disable",
    "allow": ["Read(**)", "Glob(**)", "Grep(**)", "Bash(git log*)", "Bash(git diff*)"],
    "deny": ["Write(**)", "Edit(**)", "Bash(git push*)", "Bash(rm*)", "Bash(*deploy*)"],
    "ask": []
  },
  "disableAutoMode": "disable"
}

Untuk kebijakan tim atau perusahaan, letakkan batas yang sama di managed settings. Dengan allowManagedPermissionRulesOnly, pengguna dan repository proyek tidak dapat mendefinisikan ulang aturan allow, ask, atau deny untuk melewati kebijakan organisasi.

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(curl *)"
    ],
    "disableBypassPermissionsMode": "disable"
  },
  "disableAutoMode": "disable",
  "allowManagedPermissionRulesOnly": true
}

Langkah 4: Perlindungan Lingkungan Produksi

Pisahkan Target Koneksi Secara Eksplisit

## CLAUDE.md — Aturan Lingkungan Produksi

## Deteksi Lingkungan
- Jika DATABASE_URL mengandung 'prod' atau 'production', ini adalah **lingkungan produksi**
- Di produksi, jangan pernah jalankan:
  - DROP / TRUNCATE / DELETE (tanpa klausa WHERE)
  - Migrasi (memerlukan konfirmasi sebelumnya)
  - Penghapusan file massal

## Alur Konfirmasi
Semua perubahan produksi harus:
1. Diuji dulu di lingkungan staging
2. Mendapatkan konfirmasi pengguna
3. Melaporkan hasil setelah eksekusi

Kontrol Koneksi dengan Environment Variables

// scripts/db-query.mjs
const env = process.env.NODE_ENV ?? "development";
const dbUrl = process.env.DATABASE_URL;

if (env === "production" && process.argv.includes("--write")) {
  console.error("❌ Menulis ke produksi memerlukan flag --force-production");
  process.exit(1);
}

Langkah 5: Pengaman Operasi File

Otomasi Backup Sebelum Penghapusan

// Hooks di .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(rm *)",
        "hooks": [
          {
            "type": "command",
            "command": "echo '⚠️  Perintah hapus akan segera dijalankan. Tekan Ctrl+C untuk membatalkan.' && sleep 3"
          }
        ]
      }
    ]
  }
}

Lindungi File Penting dari Pengeditan yang Tidak Sengaja

## CLAUDE.md — File yang Tidak Boleh Dimodifikasi

File-file berikut **tidak boleh pernah diedit**:
- .env (berisi environment variables dan kunci rahasia)
- wrangler.toml (konfigurasi produksi Cloudflare)
- scripts/deploy.sh (skrip deployment)
- .github/workflows/*.yml (konfigurasi CI/CD)

Jika perubahan diperlukan, konfirmasi dulu dengan pengguna.

5 Jebakan Umum

1. Menambahkan .gitignore setelah fakta sudah terlambat File .env yang sudah di-commit tetap ada di riwayat git meskipun kemudian ditambahkan ke .gitignore.

# Penghapusan lengkap dari riwayat (perhatian: memerlukan force push)
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch .env" \
  --prune-empty --tag-name-filter cat -- --all

# Atau gunakan BFG Repo Cleaner

Jika file sudah di-push ke GitHub, selalu rotasi kunci API Anda terlebih dahulu sebelum membersihkan riwayat.

2. Menyimpan file JSON service account di repositori Kunci service account untuk Google Cloud atau AWS sering didistribusikan sebagai file .json, tetapi menyimpannya di repositori berbahaya. Konversikan ke environment variables atau migrasikan ke Secret Manager (AWS Secrets Manager / GCP Secret Manager).

3. Menjalankan perintah interaktif dengan tool Bash Selama eksekusi headless dengan claude -p, perintah yang memerlukan input interaktif seperti sudo atau vim akan menyebabkan proses hang. Gunakan hanya perintah non-interaktif.

4. Menyertakan kredensial dalam pesan error

// ❌ Berbahaya: kunci API muncul di log
throw new Error(`Autentikasi gagal: token=${process.env.TOKEN}`);

// ✅ Aman: jangan tampilkan nilainya
throw new Error(`Autentikasi gagal: harap periksa environment variable TOKEN`);

5. Menggunakan ulang pengaturan izin yang sama di semua proyek Menggunakan settings.json yang sama untuk proyek pribadi dan pekerjaan berarti pengaturan longgar dari proyek pribadi dapat menimpa persyaratan yang lebih ketat dari proyek pekerjaan. Kelola .claude/settings.json secara terpisah untuk setiap proyek.

Aturan operasional praktis

Jangan mengekspos secret saat kerja normal

Saat meminta Claude Code “perbaiki error ini”, jangan tempel seluruh log atau isi .env. Tetapkan sejak awal bahwa kunci API, token OAuth, cookie, URL database, email pelanggan, ID tagihan, dan private key tidak pernah masuk ke prompt, issue, atau chat.

Jika Claude Code membutuhkan konteks, redaksi nilai dan sisakan bentuk konfigurasinya saja. DATABASE_URL=***REDACTED*** cukup untuk memberi tahu bahwa ada URL database. Nilai asli hampir tidak pernah diperlukan untuk debugging kode aplikasi.

Aman diberikan	Jangan diberikan
Jenis error, nama file di stack trace, langkah reproduksi	Kunci API, private key, session cookie, nilai asli .env
.env.example, nama setting, aturan izin, perintah yang gagal	URL database produksi, data pelanggan, kredensial internal
Log yang disamarkan, data test, nilai contoh lokal	Token asli, JSON service account, screenshot berisi secret

Masukkan tabel ini ke CLAUDE.md agar setiap sesi dimulai dengan batas yang sama. Dalam tim, “jangan mengekspos secret” harus menjadi aturan operasi, bukan pengetahuan informal.

Gandakan pemindaian secret sebelum commit

Hook PreToolUse di atas memblokir commit saat Claude Code menjalankan git commit. Ini tidak mencakup manusia yang commit dari terminal lain atau file hasil CI yang mengandung secret. Di tim produksi, gunakan tiga lapisan: Hook Claude Code, pre-commit lokal, dan secret scan CI yang memblokir merge.

Konfigurasi minimum yang berguna adalah memblokir secara lokal, mengecek ulang di CI, dan menggagalkan pull request saat pola secret muncul. Tool seperti gitleaks atau trufflehog lebih baik untuk deteksi skala CI; script di artikel ini tetap berguna sebagai guard lokal yang cepat.

Contoh kegagalan konkret

Kegagalan 1: membaca .env saat investigasi Developer meminta Claude Code “cek environment variables” dan nilai asli masuk ke percakapan atau log kerja. Perbaikannya adalah menolak pembacaan .env dan hanya memberikan .env.example.

Kegagalan 2: menempel token publikasi Qiita ke prompt Task otomasi memasukkan QIITA_TOKEN langsung ke prompt, sehingga ada risiko tersimpan di subagent atau file log. Alur aman adalah menyimpan token di .env dan membuat command hanya merujuk nama environment variable.

Kegagalan 3: URL database produksi dan staging mirip Instruksi hanya berbunyi “bersihkan database” dan melewati verifikasi koneksi. Jika URL aktif adalah produksi, delete atau migration bisa menjadi insiden. Sebelum operasi tulis, tampilkan NODE_ENV, host, dan nama database, lalu wajibkan konfirmasi eksplisit.

Respons awal setelah insiden

Jika Anda mencurigai secret bocor, langkah pertama bukan membersihkan history. Langkah pertama adalah menonaktifkan kredensial.

1. Rotate atau revoke kunci API, token, atau password yang terdampak segera
2. Periksa audit log GitHub Actions, Cloudflare, AWS, GCP, dan SaaS terkait
3. Catat siapa mengekspos apa, kapan, di repository mana, dan lewat kanal apa
4. Hapus secret dari git history dan log, lalu komunikasikan dampak force push
5. Perketat aturan deny, Hooks, scan CI, dan larangan di CLAUDE.md

Dalam praktik, menghentikan kredensial terlebih dahulu lalu membersihkan history mengurangi kesalahan. Saat incident response, orang sering menempel log tambahan untuk membantu, jadi siapkan template log yang sudah disamarkan sebelumnya.

Jalur belajar dan konsultasi

Keamanan Claude Code tidak selesai dengan satu file settings. Struktur repository, CI, izin deploy, dan alur persetujuan tim juga harus ditinjau.

Di ClaudeCodeLab, jalur belajar untuk developer individu dimulai dari kebersihan .env dan permission rules. Untuk konsultasi tim, pertanyaan pertama adalah di mana managed settings harus dipaksa dan di mana CI secret scan harus memblokir merge. Jika Claude Code sudah dipakai di pekerjaan, mulai dengan memetakan siapa dapat mengakses secret apa sebelum menyetel izin detail.

Daftar Periksa Keamanan

Daftar periksa untuk menyiapkan proyek Claude Code:

### Pengaturan Dasar
- [ ] .env dibuat dan ditambahkan ke .gitignore
- [ ] .env.example dibuat dan dibagikan ke tim
- [ ] Diverifikasi via git log bahwa commit yang ada tidak mengandung secret

### Pengaturan Izin
- [ ] Daftar deny dikonfigurasi di .claude/settings.json
- [ ] Perintah destruktif (rm -rf, DROP TABLE, dll.) ditambahkan ke deny
- [ ] Perintah deploy produksi diset ke ask

### Otomasi
- [ ] Hook pemindaian secret pre-commit dikonfigurasi
- [ ] Larangan keamanan didokumentasikan di CLAUDE.md

### Operasi
- [ ] Jadwal rotasi kunci API ditetapkan (direkomendasikan: setiap 90 hari)
- [ ] Pekerjaan produksi dibatasi dengan .claude/settings.local.json atau managed settings
- [ ] Alur respons insiden didokumentasikan

Ringkasan

Keamanan Claude Code bukan tentang “menerapkan pembatasan” — ini tentang membangun struktur di mana kecelakaan tidak dapat terjadi secara struktural.

Ancaman	Tindakan Pencegahan
Kebocoran kunci API	.env + .gitignore + Hook pemindaian secret
Penghapusan yang tidak diinginkan	Daftar deny + Hook pre-penghapusan
Kesalahan produksi	local/managed settings + larangan CLAUDE.md
Kontaminasi commit	Hook PreToolUse untuk pemindaian pre-commit

Setelah dikonfigurasi, pengaturan ini praktis bebas pemeliharaan. Meluangkan 30 menit hari ini dapat mencegah insiden besar di masa mendatang.

Artikel Terkait

• Panduan Izin Claude Code
• Kasus Kegagalan Keamanan Claude Code
• Panduan Lengkap Integrasi Claude Code + SaaS
• Praktik Terbaik CLAUDE.md

Referensi

• Dokumentasi resmi Claude Code settings
• Dokumentasi resmi Claude Code permissions
• Dokumentasi resmi server managed settings
• Menghapus Secret dari Riwayat dengan git-filter-branch
• BFG Repo Cleaner