Menginstal dan mengonfigurasi CLI

CodeMender adalah agen keamanan kode AI otonom yang memindai, memverifikasi, dan memperbaiki kerentanan keamanan siber yang mendalam dalam codebase Anda. Sebelum menjalankan CodeMender, download CLI dan inisialisasi opsi ruang kerja.

Arsitektur dan model keamanan

CodeMender menggunakan model eksekusi local-first:

  • Mesin penalaran yang dihosting: Penalaran agentik, pemodelan ancaman, dan logika orkestrasi berjalan dengan aman di Google Cloud Gemini Enterprise Agent Platform.
  • CLI eksekusi lokal: Kode sumber tidak pernah keluar dari workstation atau container CI/CD Anda secara massal. Alat CLI cm lokal menjalankan pembacaan file, pemeriksaan build lokal, dan verifikasi eksploitasi proof-of-concept (PoC) di sandbox lokal Anda, hanya mengirimkan cuplikan kode yang tepat dan hasil eksekusi alat ke backend cloud melalui Interactions API di Gemini Enterprise Agent Platform.

Penyiapan lingkungan

Untuk mulai menggunakan CodeMender, siapkan project Google Cloud , download dan instal CLI, konfigurasi kredensial, dan lakukan inisialisasi ruang kerja.

Penyiapan project dan izin IAM

Sebelum mendownload CLI dan mengonfigurasi kredensial, pastikan project Google Cloud target disiapkan dengan benar menggunakan API dan izin yang diperlukan.

API yang diperlukan

Pastikan Google Cloud API berikut diaktifkan di project Anda:

  1. Vertex AI API (aiplatform.googleapis.com) — Mendukung streaming dan pengelolaan sesi aktif.
  2. Cloud Resource Manager API (cloudresourcemanager.googleapis.com) — Memvalidasi status autentikasi pengguna dan metadata project.

Untuk menjalankan perintah CLI, pengguna harus diberi peran IAM berikut:

  • Vertex AI User (roles/aiplatform.user) — Memungkinkan pengguna membuat, melakukan streaming, dan mengelola sesi aktif.

Mendownload dan menginstal CodeMender CLI

Biner CLI CodeMender dihosting di Artifact Registry. Pilih tab untuk sistem operasi Anda guna mendownload dan menginstal CLI.

Linux x86_64

Untuk mendownload dan menginstal CodeMender CLI untuk Linux (x86_64):

  1. Download paket menggunakan salah satu metode berikut:
    • gcloud CLI: Jalankan perintah berikut:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-linux-amd64.zip \
        --destination=./
    • curl: Jalankan perintah berikut:
      curl -L -o cm-linux-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-amd64.zip:download?alt=media"
  2. Instal CLI:
    unzip cm-linux-amd64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

Linux ARM64

Untuk mendownload dan menginstal CodeMender CLI untuk Linux (ARM64):

  1. Download paket menggunakan salah satu metode berikut:
    • gcloud CLI: Jalankan perintah berikut:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-linux-arm64.zip \
        --destination=./
    • curl: Jalankan perintah berikut:
      curl -L -o cm-linux-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-linux-arm64.zip:download?alt=media"
  2. Instal CLI:
    unzip cm-linux-arm64.zip
    chmod +x cm
    sudo mv cm /usr/local/bin/cm

macOS Intel

Untuk mendownload dan menginstal CodeMender CLI untuk macOS (Intel):

  1. Download paket menggunakan salah satu metode berikut:
    • gcloud CLI: Jalankan perintah berikut:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-darwin-amd64.zip \
        --destination=./
    • curl: Jalankan perintah berikut:
      curl -L -o cm-darwin-amd64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-amd64.zip:download?alt=media"
  2. Instal CLI:
    unzip cm-darwin-amd64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

Apple silicon macOS

Untuk mendownload dan menginstal CodeMender CLI untuk macOS (Apple silicon):

  1. Download paket menggunakan salah satu metode berikut:
    • gcloud CLI: Jalankan perintah berikut:
      gcloud artifacts generic download \
        --project=cmoc-prod \
        --location=us \
        --repository=codemender-cli-production \
        --package=cm \
        --version=stable \
        --name=cm-darwin-arm64.zip \
        --destination=./
    • curl: Jalankan perintah berikut:
      curl -L -o cm-darwin-arm64.zip "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-darwin-arm64.zip:download?alt=media"
  2. Instal CLI:
    unzip cm-darwin-arm64.zip
    chmod +x cm
    mv cm /usr/local/bin/cm

Windows x86_64

Untuk mendownload dan menginstal CodeMender CLI untuk Windows (x86_64):

  1. Download paket menggunakan salah satu metode berikut:
    • gcloud CLI: Jalankan perintah berikut di PowerShell:
      gcloud artifacts generic download `
        --project=cmoc-prod `
        --location=us `
        --repository=codemender-cli-production `
        --package=cm `
        --version=stable `
        --name=cm-windows-amd64.zip `
        --destination=./
    • PowerShell: Jalankan perintah berikut:
      Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-amd64.zip:download?alt=media" -OutFile cm-windows-amd64.zip
  2. Instal CLI:
    Expand-Archive -Path cm-windows-amd64.zip -DestinationPath ./
    # Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

Windows ARM64

Untuk mendownload dan menginstal CodeMender CLI untuk Windows (ARM64):

  1. Download paket menggunakan salah satu metode berikut:
    • gcloud CLI: Jalankan perintah berikut di PowerShell:
      gcloud artifacts generic download `
        --project=cmoc-prod `
        --location=us `
        --repository=codemender-cli-production `
        --package=cm `
        --version=stable `
        --name=cm-windows-arm64.zip `
        --destination=./
    • PowerShell: Jalankan perintah berikut:
      Invoke-WebRequest -Uri "https://artifactregistry.googleapis.com/download/v1/projects/cmoc-prod/locations/us/repositories/codemender-cli-production/files/cm%3Astable%3Acm-windows-arm64.zip:download?alt=media" -OutFile cm-windows-arm64.zip
  2. Instal CLI:
    Expand-Archive -Path cm-windows-arm64.zip -DestinationPath ./
    # Move cm.exe to a permanent folder and add it to your system PATH (e.g. Environmental Variables)

Mengonfigurasi kredensial Google Cloud

Karena CodeMender CLI berinteraksi dengan mesin penalaran yang dihosting di cloud melalui Interactions API, Anda harus mengonfigurasi Google Cloud Kredensial Default Aplikasi (ADC) di lingkungan Anda.

Untuk mengautentikasi, jalankan perintah berikut dan ikuti perintah login:

gcloud auth application-default login

Lakukan inisialisasi ruang kerja

Setelah Anda mengautentikasi, langkah selanjutnya adalah melakukan inisialisasi CodeMender di lingkungan lokal Anda. Menginisialisasi CodeMender akan menyiapkan ruang kerja lokal Anda dengan membuat file pelacakan status dan menetapkan setelan koneksi ke mesin penalaran yang dihosting di cloud.

Jalankan cm init dari direktori root codebase Anda untuk membuat file pelacakan status lokal dan menetapkan konfigurasi dasar:

cm init

Gunakan tanda --verify untuk menguji konektivitas ke mesin penalaran yang dihosting di cloud dan memverifikasi setelan ruang kerja:

cm init --verify

Parameter konfigurasi (config.yaml)

Tujuan utama config.yaml adalah untuk menyelaraskan perilaku agen CodeMender dengan keamanan, batasan lingkungan, dan kebutuhan performa sistem lokal Anda.

Karena agen AI yang dihosting menjalankan perintah lokal (seperti membuat kode, menjalankan pengujian, atau mengedit file) menggunakan klien daemon lokal Anda, file konfigurasi ini bertindak sebagai batas yang menentukan apa yang boleh dan tidak boleh dilakukan agen.

Penggunaan

  • Lokasi: Secara default, CLI mencari file ini di ruang kerja yang telah Anda inisialisasi (biasanya .codemender/config.yaml atau direktori konfigurasi global seperti ~/.config/codemender/config.yaml).
  • Eksekusi: Saat Anda menjalankan perintah seperti cm find, cm verify, atau cm fix, klien lokal akan membaca file ini untuk menyiapkan parameter keamanan, menerapkan bypass sistem, dan menentukan file atau direktori mana yang akan diabaikan.

Setelan default inti

Berikut arti parameter default inti:

  • human_confirmation: true (atau require_confirmation: true)

    • Artinya: Secara default, CodeMender tidak dapat mengubah file apa pun di disk Anda atau menjalankan perintah shell tanpa meminta konfirmasi [Y/n] secara eksplisit di terminal.
    • Alasan ini menjadi setelan default: CodeMender dapat membuat patch spekulatif atau mencoba menjalankan skrip eksploit untuk memverifikasi kerentanan. Memaksa konfirmasi pengguna membantu mencegah perubahan sistem yang tidak disengaja atau eksekusi kode yang tidak sah di lingkungan lokal Anda.
    • Lewati: Untuk pipeline CI/CD non-interaktif, opsi ini dapat disetel ke false.
  • confirm_writes: false

    • Artinya: Menonaktifkan dialog interaktif untuk modifikasi file, sehingga memungkinkan agen CodeMender menulis patch keamanan dan mengubah file sumber langsung ke disk lokal Anda tanpa menunggu persetujuan pengguna.
    • Mengapa ini menjadi default: Secara default, CodeMender menetapkan pembatas keamanan ini ke true untuk menerapkan alur kerja "Human-in-the-Loop". Karena CodeMender bertindak pada codebase lokal Anda, yang memerlukan konfirmasi manual (misalnya, Write? [Y/n]) mencegah agen membuat modifikasi spekulatif, salah, atau merusak pada file sumber Anda. Anda hanya boleh mengalihkan setelan ini ke false saat berjalan di sandbox terisolasi dan sekali pakai atau pipeline CI/CD otomatis tanpa antarmuka.
  • include: [".py", ".java", ".go", ".js", ".ts", ".c", ".cc", ".cpp", ".h", ".rb", ".php"]

    • Artinya: Menentukan daftar eksplisit ekstensi file yang Anda izinkan untuk di-ingest dan dianalisis oleh CodeMender saat memindai ruang kerja Anda. CodeMender akan otomatis melewati file apa pun di repositori Anda dengan ekstensi yang tidak ditentukan dalam daftar ini.
    • Alasan ini menjadi default: Daftar ini secara default menggunakan bahasa pemrograman utama untuk memaksimalkan efisiensi pemindaian dan mencegah agen membuang waktu dan token pada file teks, artefak build, atau file biner yang tidak relevan. Namun, karena aplikasi modern sering menyematkan kerentanan dalam konfigurasi deployment atau alat otomatisasi, sebaiknya Anda memperluas daftar default ini secara manual untuk menyertakan file konfigurasi, format skrip, dan file IaC (misalnya, skrip shell, XML, YAML, properti, dan file JSON) sehingga CodeMender tidak mengabaikannya secara diam-diam.
  • exclude_paths: ["node_modules", "vendor", "dist", "bin"]

    • Artinya: CodeMender akan sepenuhnya melewati direktori ini selama pemindaian ruang kerja dan analisis kode.
    • Mengapa ini menjadi default: Folder build atau dependensi yang besar akan memicu penalti token dan latensi yang besar. Memastikan item ini dikecualikan secara default akan menjamin performa tinggi dan waktu respons yang cepat.
  • project_paths: []

    • Artinya: Daftar jalur direktori yang dapat diakses (baca/tulis) oleh CodeMender selama eksekusi alat.
    • Alasan ini menjadi default: Secara default, opsi ini kosong, yang membatasi agen ke direktori target pemindaian, direktori ruang kerja .codemender, dan /tmp. Jika proses build atau pengujian Anda memerlukan akses ke file di luar direktori ini, Anda harus menambahkan jalur tersebut di sini.
  • sandbox:

    • Artinya: Blok konfigurasi untuk lingkungan sandbox tingkat proses.
    • Sub-parameter:
      • enabled: true: (Boolean) Mengaktifkan atau menonaktifkan sandbox. Jika Anda menyetelnya ke true (default), agen akan menjalankan alat di dalam sandbox lokal. Jika Anda menyetelnya ke false, agen akan menjalankan alat langsung di sistem host tanpa isolasi.
      • mounts: (Object)
        • target_dir: ".": (String) Direktori yang akan dipasang sebagai ruang kerja aktif di dalam sandbox. CLI menyelesaikan jalur relatif terhadap root ruang kerja.
      • network: (Object)
        • profile: "permissive-closed": (String) Profil akses jaringan keluar di dalam sandbox. Pemberian izin terperinci untuk domain atau pola URL tertentu belum didukung. Profil yang didukung:
          • permissive-closed (Default): Isolasi jaringan lengkap; sandbox memblokir semua koneksi keluar.
          • permissive-open: Mengizinkan akses jaringan keluar penuh.
  • security:

    • Artinya: Blok konfigurasi untuk kebijakan keamanan.
    • Sub-parameter:
      • protected_files: []: (List of String) File atau direktori di sistem host yang ingin Anda pasang hanya baca di dalam sandbox untuk melindunginya dari modifikasi (misalnya, ["~/.ssh/*"]). Mendukung ekspansi jalur (~) dan karakter pengganti (*).
  • model: "gemini-3.5-flash"

    • Artinya: Mesin kecerdasan default yang mendukung loop penalaran backend.
    • Alasan ini menjadi default: gemini-3.5-flash menawarkan keseimbangan optimal antara kecepatan, biaya, dan penalaran analitis yang diperlukan untuk menyarankan patch. (Pengguna dapat menggantinya menjadi gemini-3.1-pro untuk penalaran yang lebih mendalam dan kompleks jika diperlukan).
  • vcs: { type: "git" }

    • Artinya: Menentukan jenis sistem kontrol versi yang digunakan project Anda melalui kunci vcs. Jika Anda membiarkannya tidak dikonfigurasi, alat ini akan mencoba mengidentifikasi repositori Git atau Mercurial secara otomatis. Jika Anda menyetel vcs ke none, CLI akan menampilkan peringatan, tetapi melanjutkan eksekusi tanpa fungsi VCS. CodeMender mengandalkan setelan ini untuk mengelola perbaikan keamanan spekulatif, melacak modifikasi codebase, dan berintegrasi dengan repositori lokal Anda.
    • Alasan ini menjadi setelan default: CodeMender mendukung konfigurasi VCS Git, Mercurial, atau kustom. Git adalah opsi default karena merupakan standar industri untuk pelacakan kontrol versi, sehingga memastikan integrasi diff yang lancar dan keamanan rollback.
  • build: { command: "make build && make test" }

    • Artinya: Menentukan perintah shell persis yang dijalankan CodeMender untuk mengompilasi dan membangun project Anda, serta menjalankan pengujian unit dan regresi Anda.
    • Mengapa ini menjadi default: Menetapkan perintah build dan pengujian sangat penting untuk alur kerja verifikasi. Hal ini memungkinkan CodeMender mengompilasi project Anda dan menjalankan suite pengujian yang ada di lingkungan sandbox terisolasi untuk membuktikan bahwa patch keamanan yang dihasilkan berhasil memitigasi kerentanan tanpa merusak logika aplikasi yang ada.

Sandbox eksekusi

Untuk melindungi workstation Anda dari modifikasi file yang tidak disengaja atau efek samping alat yang tidak terduga, CodeMender CLI berjalan di dalam sandbox tingkat OS secara default. Anda dapat menonaktifkan sandbox secara permanen dalam konfigurasi atau melewatinya per perintah menggunakan flag CLI.

Meskipun sandboxing ini menawarkan lapisan pertahanan awal di workstation Anda, sandboxing ini menawarkan perlindungan keamanan yang lebih lemah daripada menjalankan agen di mesin virtual (VM) yang terisolasi sepenuhnya:

  • Linux: Menggunakan namespace kernel (CLONE_NEWNS, CLONE_NEWUSER, dll.) dan filter seccomp untuk mengisolasi titik pemasangan dan membatasi panggilan sistem.
  • macOS: Menggunakan mekanisme sandbox-exec (Seatbelt) bawaan.
  • Windows (Eksperimental): Menggunakan isolasi AppContainer dan Daftar Kontrol Akses (ACL). Sandbox di Windows bersifat eksperimental dan mungkin memerlukan hak istimewa administratif atau tidak kompatibel dengan beberapa konfigurasi sistem.

Perilaku sandbox

Saat sandbox aktif:

  1. Isolasi sistem file: Agen hanya dapat membaca dan menulis file dalam direktori yang diizinkan. Sandbox mengalihkan semua penulisan di luar direktori ini ke sistem file dalam memori (tmpfs) sementara tanpa memengaruhi sistem host Anda.
  2. Isolasi Jaringan: Sandbox memblokir akses jaringan keluar secara default. Hal ini mencegah agen (atau alat build yang dipanggilnya) membuat koneksi eksternal yang tidak terduga atau mengirimkan data di luar ruang kerja.

Akses jaringan selama pembuatan dan validasi

Karena sandbox mengaktifkan isolasi jaringan secara default (sandbox.network.profile secara default adalah permissive-closed), agen tidak dapat mengakses internet selama eksekusi alat.

Hal ini menimbulkan batasan untuk project yang memerlukan pengambilan dependensi eksternal selama langkah-langkah build atau verifikasi (misalnya, menjalankan npm install, pip install, atau go get sebagai bagian dari build.command). Jika proses build Anda mencoba mengakses layanan web eksternal, proses tersebut akan gagal.

Menangani dependensi jaringan

Jika project Anda memerlukan akses jaringan untuk build atau pengujian, Anda memiliki opsi berikut:

  • Mengambil data dependensi terlebih dahulu: Instal semua dependensi yang diperlukan di sistem host sebelum menjalankan perintah cm, sehingga perintah build tidak memerlukan akses jaringan.
  • Aktifkan akses jaringan di sandbox: Ubah profil jaringan di config.yaml Anda untuk mengizinkan koneksi keluar:

    sandbox:
      network:
        profile: "permissive-open"
    
  • Melewati sandbox: Jalankan perintah dengan tanda --unrestricted untuk menonaktifkan sandbox dan batas sistem file sepenuhnya untuk eksekusi tersebut.

Konfigurasi sandbox

Anda dapat mengonfigurasi dan mengontrol sandbox menggunakan opsi berikut:

  • Konfigurasi Persisten (config.yaml): Anda dapat menyesuaikan perilaku sandbox, pemasangan sistem file, akses jaringan, dan kebijakan keamanan dengan menambahkan blok sandbox, execution, dan security ke file config.yaml Anda. Lihat Parameter konfigurasi untuk mengetahui detailnya.
  • Mengontrol sandbox menggunakan CLI (--sandbox): Anda dapat mengaktifkan atau menonaktifkan sandbox secara eksplisit untuk satu kali eksekusi dengan meneruskan --sandbox=true atau --sandbox=false ke cm find, cm verify, atau cm fix.
  • Melewati isolasi menggunakan CLI (--unrestricted): Anda dapat melewati semua perlindungan sandbox untuk satu kali eksekusi dengan meneruskan flag --unrestricted. Tindakan ini akan menonaktifkan batas jalur sistem file (memungkinkan agen mengakses jalur apa pun di host Anda) dan menonaktifkan isolasi container tingkat OS sepenuhnya (termasuk isolasi jaringan).

Memilih tingkat isolasi

Bergantung pada persyaratan keamanan dan lingkungan pengembangan, Anda dapat memilih tingkat isolasi yang sesuai untuk menjalankan CodeMender CLI.

Metode Deskripsi Kelebihan Kekurangan
Sandbox bawaan (tingkat OS) Diaktifkan secara default; Anda dapat menonaktifkannya di file config.yaml atau melewatinya menggunakan flag CLI. Menggunakan fitur OS bawaan (namespace/seccomp, sandbox-exec, AppContainer (Eksperimental)) untuk mengisolasi eksekusi. Ringan; tidak ada overhead saat memulai; akses langsung ke alat ruang kerja lokal dengan kontrol terperinci. Direkomendasikan untuk pengembangan lokal sehari-hari. Keamanan bergantung pada fitur kernel OS; kurang terisolasi dibandingkan VM penuh; dukungan Windows bersifat eksperimental dan mungkin memerlukan hak istimewa administratif atau tidak kompatibel dengan beberapa konfigurasi.
Container Menjalankan agen di container (misalnya, Docker). Isolasi yang baik; lingkungan standar. Memerlukan runtime container; dapat berat; tidak mengizinkan interaksi langsung dengan alat di komputer lokal.
VM Lengkap Menjalankan agen di VM khusus. Keamanan maksimum; isolasi lengkap. Overhead resource tinggi; startup lambat; tidak mengizinkan interaksi langsung dengan alat di komputer lokal.

Telemetri

Untuk membantu kami memantau dan meningkatkan kualitas produk, kami mengumpulkan data telemetri anonim melalui CLI. Kami sepenuhnya menganonimkan semua data yang dikumpulkan, yang mencakup metrik penggunaan dasar dan diagnostik performa. Telemetri tidak pernah mengumpulkan atau mengirimkan kode sumber, konten file, temuan, patch, atau identitas pengguna.

Secara default, telemetri diaktifkan. Jika Anda ingin menonaktifkan telemetri, tetapkan variabel lingkungan CM_TELEMETRY_OPT_OUT ke 1 atau true.

Mengupdate CLI

CodeMender memiliki mekanisme update bawaan untuk memastikan Anda menjalankan CLI versi terbaru.

Pemeriksaan update otomatis

Secara default, CodeMender CLI otomatis memeriksa update di latar belakang saat Anda menjalankan perintah:

  • Pembatasan: Untuk meminimalkan overhead, pemeriksaan otomatis berjalan paling banyak sekali setiap 24 jam.
  • Terminal Interaktif (TTY) Diperlukan: CLI hanya memeriksa update dan meminta Anda saat berjalan di terminal interaktif. Di lingkungan noninteraktif (seperti pipeline atau skrip CI/CD), pemeriksaan dilewati dan peringatan dicatat ke stderr paling banyak sekali sehari.
  • Meminta: Jika versi baru tersedia, Anda akan diminta di stderr: none 🆕 A new CodeMender release is available: 1.1.0 Update now? (y/N): Jika Anda memilih ya (y atau yes), CodeMender akan mendownload update, mengganti biner, dan keluar. Anda harus menjalankan perintah lagi untuk mengeksekusinya dengan versi baru. Jika Anda memilih tidak, update akan dilewati dan perintah asli Anda akan dieksekusi.
  • Toleransi Offline: Jika Anda offline atau repositori rilis tidak dapat dijangkau, pemeriksaan akan gagal tanpa pemberitahuan dan CodeMender akan terus menjalankan perintah Anda.
  • Melewati: Anda dapat melewati pemeriksaan update otomatis dengan meneruskan flag --yes atau -y ke perintah apa pun.

Update manual (cm update)

Anda dapat memaksa CodeMender untuk segera memeriksa dan menerapkan update dengan menjalankan perintah update:

cm update

Perintah cm update:

  • Mengabaikan pembatasan 24 jam.
  • Mendownload dan menerapkan update segera tanpa meminta konfirmasi (non-interaktif).
  • Tidak memerlukan terminal interaktif (aman untuk skrip dan pengelolaan konfigurasi).

Jika CLI diinstal di direktori sistem yang memerlukan izin yang lebih tinggi, jalankan update dengan sudo:

sudo cm update