Bayangkan punya security engineer AI yang bisa membaca seluruh isi repository kamu, menemukan celah keamanan seperti SQL injection, hardcoded credential, atau path traversal, lalu membuktikan bahwa celah itu benar-benar bisa dieksploitasi — bahkan langsung membetulkan kodenya. Itulah yang dilakukan Codex Security, CLI terbaru dari OpenAI untuk finding, validating, and fixing security vulnerabilities di kode kamu.

Di tutorial ini kamu akan belajar memakainya dari nol: install CLI-nya, login, menjalankan scan pertama, membaca laporan hasil, memperbaiki temuan secara otomatis, hingga memasangnya sebagai gate di pipeline CI/CD. Semua perintah di bawah sudah diuji dan bisa langsung kamu jalankan.

Apa Itu Codex Security?

Codex Security (@openai/codex-security) adalah CLI dan TypeScript SDK yang memakai model AI untuk menemukan, mengonfirmasi, dan memperbaiki kerentanan keamanan di repository yang kamu miliki atau yang kamu punya izin untuk menilainya. Berbeda dari static analyzer biasa yang hanya melaporkan pola mencurigakan, Codex Security bekerja layaknya pentester: ia menelusuri alur kode, menilai apakah sebuah temuan valid, lalu menyusun langkah remediasinya.

Hasilnya disimpan sebagai laporan terstruktur (Markdown, JSON, dan SARIF) sehingga mudah dibaca manusia sekaligus mudah diotomasi di CI/CD.

Codex Security dirilis publik oleh OpenAI. Menjalankan scan memerlukan akses Codex Security melalui akun ChatGPT atau API key OpenAI. Beberapa permintaan keamanan siber dan temuan yang dilindungi memerlukan persetujuan lewat program Trusted Access for Cyber (chatgpt.com/cyber).

Prasyarat

Sebelum mulai, pastikan environment kamu sudah siap:

  • Node.js versi 22.13.0 atau lebih baru (mendukung 22, 24, dan 26). Cek dengan node --version.
  • Python versi 3.10 atau lebih baru — dibutuhkan untuk scan, bulk scan, export, riwayat scan, dan temuan tersimpan. Cek dengan python3 --version.
  • Sebuah repository yang kamu miliki atau berizin untuk dinilai.
  • Akun ChatGPT (untuk login interaktif) atau OpenAI API key (untuk CI/otomasi).
Langkah 1: Install dan Verifikasi CLI

Kamu tidak perlu install global — jalankan saja lewat npx. Cek versi untuk memastikan package bisa diunduh dan berjalan:

bash
npx @openai/codex-security --version

Untuk melihat versi package sekaligus versi plugin yang dibundel, jalankan:

bash
npx @openai/codex-security info --json

Terakhir, lihat daftar perintah yang tersedia:

bash
npx @openai/codex-security --help

Kalau kamu sering memakainya, kamu bisa install global dengan npm install -g @openai/codex-security lalu panggil codex-security langsung tanpa npx. Contoh di tutorial ini tetap memakai npx agar bisa dijalankan tanpa setup tambahan.

Langkah 2: Login / Autentikasi

Untuk pemakaian lokal, login dengan akun ChatGPT kamu:

bash
npx @openai/codex-security login

Di mesin remote atau tanpa browser, pakai device authentication:

bash
npx @openai/codex-security login --device-auth

Untuk CI dan workflow otomatis lainnya, cukup set API key sebagai environment variable:

bash
export OPENAI_API_KEY="sk-..."

Kalau API key dan sesi ChatGPT sama-sama aktif, kamu bisa memilih sumber autentikasi secara eksplisit:

bash
npx @openai/codex-security scan . --auth chatgpt   # pakai sesi ChatGPT
npx @openai/codex-security scan . --auth api-key  # wajib pakai API key
Langkah 3: Persiapan Scan (Dry Run)

Sebelum scan beneran, siapkan lokasi hasil di luar repository agar hasil scan tidak ikut ter-commit. Definisikan variabel REPOSITORY dan SCAN_DIR:

bash
REPOSITORY=/path/ke/repository
SCAN_DIR=/path/di-luar/repository/codex-security-results

Jalankan --dry-run untuk memeriksa input lokal (termasuk path --knowledge-base kalau ada) tanpa memulai Codex, memuat kredensial, atau menyentuh interpreter Python plugin:

bash
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --dry-run

Hanya scan repository yang kamu percaya dan berizin untuk dinilai. Scan memakai izin sistem operasi lokal kamu, tidak berhenti untuk meminta persetujuan, dan prosesnya bisa mewarisi environment kamu. Hapus kredensial yang tidak relevan sebelum mulai, dan simpan hasil scan di lokasi privat.

Langkah 4: Menjalankan Scan Pertama

Jalankan scan standar dan simpan hasilnya ke SCAN_DIR:

bash
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR"

Di terminal interaktif, kamu akan melihat dashboard scan secara live. Kalau tidak interaktif (misalnya di CI), tambahkan --headless agar progress ditampilkan sebagai baris teks biasa:

bash
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --headless

Saat selesai, CLI mencetak ringkasan seperti ini (ke stderr, bukan stdout):

python
REPORT    /path/di-luar/repository/codex-security-results/report.md

  FINDINGS  2 (2 confirmed this scan; 0 previously found; 1 high, 1 medium)
  COVERAGE  complete
  ELAPSED   42s
  RESULTS   /path/di-luar/repository/codex-security-results

Kalau butuh hasil lengkap dalam format JSON yang bisa diproses mesin, minta output terstruktur secara eksplisit:

bash
npx @openai/codex-security scan "$REPOSITORY" --output-dir "$SCAN_DIR" --json
Langkah 5: Membaca Hasil Scan

Buka report.md untuk laporan yang mudah dibaca manusia. Selain itu, direktori hasil berisi file terstruktur untuk otomasi:

python
codex-security-results/
├── scan-manifest.json   # target, scope, producer, artefak
├── findings.json        # severity, confidence, lokasi, bukti, remediasi
├── coverage.json        # permukaan yang direview & area yang ditunda
├── report.md            # laporan yang mudah dibaca
├── artifacts/
└── exports/
    └── results.sarif    # jika diproduksi

Berikut contoh isi findings.json (disederhanakan) yang memuat severity, confidence, lokasi, bukti, dan langkah remediasi untuk setiap temuan:

json
{
  "findings": [
    {
      "id": "FIND-001",
      "severity": "high",
      "confidence": "high",
      "title": "SQL injection pada endpoint /search",
      "locations": [
        { "file": "app/routes.py", "line": 42 }
      ],
      "evidence": "Query dibangun dari input user tanpa parameterisasi...",
      "remediation": "Gunakan parameterized query / ORM untuk memisahkan data dari SQL."
    }
  ]
}

Perhatikan coverage.json: nilai coverage bisa complete, partial, atau unknown. Baca dulu area yang deferred atau pertanyaan yang belum terjawab sebelum kamu menganggap hasil scan sebagai bukti review menyeluruh.

Langkah 6: Memperbaiki Temuan (Patch Otomatis)

Setelah scan interaktif selesai dan ada temuan, CLI menawarkan finding browser untuk meninjau bukti dan memilih temuan mana yang diperbaiki. Kalau kamu mau langsung mem-patch temuan high dan critical tanpa browser, pakai flag --patch:

bash
npx @openai/codex-security scan "$REPOSITORY" --patch --patch-severity high --json

Tambahkan --create-pr untuk langsung commit patch yang sudah terverifikasi dan membuka pull request di GitHub:

bash
npx @openai/codex-security scan "$REPOSITORY" --patch --patch-severity high --create-pr
Langkah 7: Scan Perubahan (Diff & Working Tree)

Daripada scan seluruh repository setiap kali, kamu bisa meninjau perubahan saja. Untuk melihat commit antara origin/main dan HEAD:

bash
npx @openai/codex-security scan "$REPOSITORY" --diff origin/main --head HEAD

Untuk meninjau perubahan yang sudah staged dan belum staged terhadap HEAD:

bash
npx @openai/codex-security scan "$REPOSITORY" --working-tree --base HEAD

Catatan: scan --diff dan --working-tree mengharapkan argumen repository berupa root Git worktree. Pastikan revisi yang diseleksi sudah di-fetch sebelum scan diff.

Langkah 8: Mode Deep, Model, dan Anggaran

Secara default, scan memakai model gpt-5.6-sol dengan reasoning effort xhigh. Untuk review yang lebih dalam, gunakan deep mode dan kontrol jumlah worker:

bash
npx @openai/codex-security scan "$REPOSITORY" --mode deep --workers 2 --subagents 0 --stop-after-no-new 3 --max-discovery-runs 10 --max-time-hours 1.5

Kamu juga bisa mengganti model dan tingkat reasoning. Level effort yang didukung: minimal, low, medium, high, xhigh, dan max:

bash
npx @openai/codex-security scan "$REPOSITORY" --model gpt-5.6-terra --effort high

Untuk mengendalikan biaya, set anggaran maksimal (dalam USD) — scan akan berhenti saat estimasi biaya model melebihi batas:

bash
npx @openai/codex-security scan "$REPOSITORY" --max-cost 5

Kamu bisa memberikan konteks arsitektur, threat model, atau kebijakan keamanan agar AI menilai temuan sesuai cara sistemmu benar-benar bekerja:

bash
npx @openai/codex-security scan "$REPOSITORY" --knowledge-base /path/architecture.md --knowledge-base /path/security-policies

Deep mode mendukung target repository dan path, bukan scan --diff atau --working-tree. Opsi seperti --workers, --subagents, dan --max-time-hours hanya berlaku di deep mode. Pantau biaya bila kamu menaikkan effort atau memakai deep mode.

Langkah 9: Pre-commit Hook & Integrasi CI

Agar perubahan berisiko tidak lolos ke commit, pasang pre-commit hook keamanan di repository. Hook ini akan men-scan perubahan staged dan belum staged sebelum setiap commit, lalu memblokir temuan ber-severity high dan error scan — tanpa menimpa script pre-commit yang sudah ada:

bash
npx @openai/codex-security install-hook

Untuk CI, cukup set OPENAI_API_KEY sebagai secret dan jalankan perintah scan dengan --headless plus severity threshold agar pipeline gagal saat ada temuan serius. Hasil results.sarif bisa di-upload ke GitHub Code Scanning untuk visualisasi di tab Security.

Langkah 10: Bulk Scan & Docker

Punya banyak repository? Login ke GitHub dulu, lalu jalankan flow interaktif untuk menemukan dan memilih repository (repository yang diarsipkan dan fork otomatis dikecualikan):

bash
gh auth login
npx @openai/codex-security bulk-scan

Untuk daftar repository yang sudah disiapkan, berikan CSV dan direktori output. Jalankan ulang perintah yang sama untuk resume — repository yang sudah selesai akan dilewati:

bash
npx @openai/codex-security bulk-scan repositories.csv --output-dir /path/security-scans --workers 4

Kalau aksesmu menyertakan image Docker Codex Security, kamu bisa menjalankan bulk scan di container dengan Compose:

bash
docker compose run --rm codex-security bulk-scan /input/repositories.csv --output-dir /output --workers 4
Langkah 11: Provider Inference Lain

Selain OpenAI, Codex Security bisa memakai provider lain. Set API key provider tersebut lalu pilih model dengan --provider dan --model. Contoh memakai OpenRouter:

bash
export OPENROUTER_API_KEY="..."
npx @openai/codex-security scan . --provider openrouter --model anthropic/claude-sonnet-4.5

Provider yang didukung antara lain Amazon Bedrock, OpenRouter, dan Fireworks — detail lengkapnya ada di dokumentasi CLI reference resmi.

Kesimpulan

Codex Security mengubah review keamanan dari aktivitas manual yang memakan waktu menjadi langkah otomatis yang bisa dipasang di mana saja: lokal saat ngoding, sebagai pre-commit hook, hingga gate di CI/CD. Alurnya sederhana — login → scan → baca report.md → --patch — tapi fleksibel lewat deep mode, knowledge base, anggaran biaya, dan multi-provider.

Coba mulai dari repository kecil milikmu sendiri, pelajari laporan findings.json, lalu perluas ke scan diff di setiap pull request. Selamat mengamankan kode — dan jangan lupa selalu review temuan AI sebelum menggabungkannya ke production.