FAQ Codex Security CLI

Temukan jawaban atas pertanyaan umum tentang pemindaian repositori dan pengelolaan temuan keamanan dari terminal. Untuk instalasi dan pemindaian pertama, mulailah dengan panduan memulai cepat CLI.

Pemindaian repositori

Mengapa pemindaian menggunakan API key setelah proses masuk

Ketika lingkungan Anda menyertakan OPENAI_API_KEY atau CODEX_API_KEY, pemindaian tanpa terminal interaktif serta pemindaian JSON dan JSONL secara default menggunakan API key dari lingkungan, bahkan setelah berhasil masuk dengan ChatGPT atau token akses. Pemindaian interaktif dengan output teks meminta Anda memilih ketika informasi masuk ChatGPT juga tersedia. Uji coba tidak menampilkan permintaan atau memuat kredensial.

Untuk menggunakan kredensial tersimpan bagi pemindaian, pilih kredensial tersebut secara eksplisit:

npx @openai/codex-security scan . --auth chatgpt

Untuk mewajibkan API key dari OPENAI_API_KEY atau CODEX_API_KEY:

npx @openai/codex-security scan . --auth api-key

Untuk menjadikan kredensial tersimpan sebagai nilai default otomatis, jalankan unset OPENAI_API_KEY CODEX_API_KEY. Untuk semua mode autentikasi yang didukung, lihat referensi CLI.

Apakah pemindaian massal yang terinterupsi dapat dilanjutkan

Ya. Jalankan perintah bulk-scan yang sama dengan CSV dan direktori keluaran semula. Codex Security melewati repositori yang telah selesai.

Tambahkan --max-attempts 3 untuk mencoba kembali kesalahan sementara pada repositori atau pemindaian:

npx @openai/codex-security bulk-scan repositories.csv \
  --output-dir /path/outside/repositories/security-scans \
  --workers 4 \
  --max-attempts 3

Pemindaian yang selesai mempertahankan hasilnya dan tidak dicoba ulang, meskipun masih ada kesenjangan cakupan. Kesenjangan cakupan tidak menyebabkan kampanye berakhir dengan kode 2.

Temuan dan cakupan

Tempat tim dapat menemukan hasil pemindaian sebelumnya

Cantumkan pemindaian tersimpan untuk repositori Anda:

npx @openai/codex-security scans list /path/to/repository

Gunakan ID pemindaian dari hasil untuk memeriksa temuannya:

npx @openai/codex-security scans show SCAN_ID

Setiap pemindaian yang selesai menyimpan laporan, temuan, cakupan, dan artefak pendukungnya secara bersamaan. Lihat Artefak pemindaian untuk tata letak lengkap.

Untuk memeriksa peristiwa pemindaian dan worker yang tersimpan, jalankan scans logs SCAN_ID. Log ini tidak disamarkan dan dapat berisi kode sumber atau kredensial.

Apa yang harus dilakukan jika CLI tidak dapat menyimpan riwayat pemindaian

Codex Security menyimpan riwayat pemindaian dalam basis data workbench. Jika direktori status default tidak dapat ditulis, pilih direktori privat di luar repositori:

export CODEX_SECURITY_STATE_DIR=/path/outside/repository/codex-security-state

Cara pemindaian membedakan temuan baru dan yang sudah diketahui

Cantumkan temuan terbuka dari semua pemindaian suatu repositori:

npx @openai/codex-security findings list /path/to/repository

Daftar tersebut mengidentifikasi temuan yang dikonfirmasi dalam pemindaian terbaru dan temuan terbuka sebelumnya yang tidak dikonfirmasi oleh pemindaian tersebut.

Bandingkan temuan dari kedua pemindaian:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Perbandingan secara otomatis mencocokkan temuan berdasarkan akar penyebab, menggunakan kembali pencocokan yang tersimpan, serta mengidentifikasi temuan baru, persisten, dibuka kembali, tidak teramati, terselesaikan, dan berstatus tidak diketahui. Jika pemindaian berikutnya tidak menemukan temuan sebelumnya dalam kode yang dipindainya, temuan tersebut dianggap tidak teramati. Temuan hanya dianggap terselesaikan setelah secara eksplisit ditutup dengan status sudah diperbaiki. Path yang dikecualikan dan pencocokan yang tidak pasti tetap berstatus tidak diketahui.

Cara kerja umpan balik positif palsu

Periksa pemindaian tersimpan untuk menemukan ID kemunculan:

npx @openai/codex-security scans show SCAN_ID

Catat alasan temuan tersebut tidak berlaku:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The framework escapes this input before it reaches the query"

Pemindaian mendatang pada repositori yang sama menerima penjelasan tersebut sebagai konteks. Pemindaian tersebut tetap memeriksa sumber, kontrol, dan keterjangkauan saat ini secara independen. Penolakan tidak menekan aturan, jalur, atau kelas kerentanan.

Untuk detail perintah, lihat referensi temuan.

Mengapa pemindaian berulang dapat menghasilkan temuan berbeda

Pemindaian berbantuan AI dapat bervariasi, meskipun menggunakan konfigurasi pemindaian yang sama. Mulailah dengan menjalankan ulang pemindaian acuan Anda:

npx @openai/codex-security scans rerun BASELINE_SCAN_ID

Proses menjalankan ulang mempertahankan konfigurasi pemindaian asli dan memerlukan versi plugin yang sama. Jika plugin yang terinstal telah berubah, perintah akan berhenti.

Bandingkan baseline dengan pemindaian baru:

npx @openai/codex-security scans compare BASELINE_SCAN_ID REPEAT_SCAN_ID

Berikan panduan arsitektur dan keamanan bersama ketika konteks yang tidak tersedia mungkin menyebabkan variasi. Pencocokan dapat mengidentifikasi temuan dasar yang sama di berbagai proses, tetapi tidak membuat pemindaian menjadi deterministik. Periksa kembali secara langsung setiap temuan penting yang menghilang.

Cara tim memastikan bahwa perbaikan berhasil

Periksa kembali temuan awal pada checkout yang telah diubah. Dari checkout tersebut, berikan laporannya dan masalah yang ingin Anda validasi:

npx @openai/codex-security validate /path/to/original/findings.json \
  "Recheck the SQL injection in src/orders.ts:42 against the current code"

Tinjau bukti bahwa jalur yang rentan telah ditutup dan perilaku yang sah masih berfungsi. Jalankan reproduksi awal atau pengujian regresi jika tersedia. Jika pemeriksaan tidak dapat dijalankan, catat ketidakpastian yang tersisa dalam hasilnya.

Perbandingan pemindaian dapat menunjukkan perubahan temuan, tetapi hilangnya suatu temuan saja tidak memverifikasi perbaikan.

Arti cakupan tidak lengkap

Tinjau coverage.json untuk mengetahui path yang dikecualikan, area yang ditunda, dan pertanyaan yang belum terjawab. Hasil baru tidak menyertakan field kelengkapan cakupan. Periksa scan.status di scan-manifest.json untuk mengetahui status eksekusi.

Kesenjangan cakupan tidak mengubah kode keluar pemindaian yang selesai. Kode keluar 0 tidak berarti setiap file telah ditinjau. Pemindaian berikutnya tidak dapat memastikan bahwa temuan sebelumnya sudah tidak ada jika pemindaian tersebut tidak mencakup path asal temuan itu.

Otomatisasi dan biaya

Bagaimana cara kerja batas waktu pemindaian mendalam

Tetapkan tenggat waktu pekerja saat memulai pemindaian mendalam:

npx @openai/codex-security scan . --mode deep --max-time-hours 1.5

Nilai default adalah 96 jam. Gunakan nilai positif hingga 96, termasuk pecahan. Saat batas waktu tercapai, Codex Security menghentikan worker yang belum selesai, mempertahankan hasil pemindaian standar yang telah selesai, dan menggabungkannya ke dalam laporan akhir. Periksa laporan untuk mengetahui area yang ditinjau dan pekerjaan yang ditunda. Batas waktu saja tidak menentukan kode keluar; status eksekusi dan kebijakan tingkat keparahanlah yang menentukannya.

Untuk pengaturan persisten atau kampanye massal, tetapkan max_time_hours di bawah [deep_scan] dalam konfigurasi pemindaian mendalam.

Cara kerja batas biaya pemindaian

Tetapkan batas estimasi biaya dalam USD sebelum memulai pemindaian:

npx @openai/codex-security scan . --max-cost 5

Batas ini merupakan estimasi, bukan batas pengeluaran mutlak. Permintaan yang sudah berjalan dapat selesai dengan biaya yang melampauinya. Jika pemindaian mendalam mencapai batas setelah Codex Security menggabungkan hasil worker yang telah selesai, CLI dapat menyimpan laporan yang telah selesai dengan peringatan anggaran. CLI mengembalikan 0, atau 1 jika temuan memenuhi ambang tingkat keparahan yang dikonfigurasi. Jika CLI tidak dapat menghasilkan hasil selesai yang valid, CLI mengembalikan 2 dan mempertahankan semua keluaran yang tersedia.

Untuk pemeriksaan pull request GitHub dan pemindaian repositori terjadwal, gunakan Codex Security GitHub Action. Dengan action-v0.3.0, pemindaian yang selesai berarti analisis yang dikonfigurasi menghasilkan hasil yang valid. Pengecualian cakupan dan investigasi yang ditunda tidak mengabaikan kebijakan tingkat keparahan. Tinjau coverage.json untuk menilai cakupan dan keterbatasan pemindaian. Untuk juga menolak diff kosong dan uji coba, wajibkan keluaran scan-status dari Action bernilai completed; lihat Memilih kebijakan tingkat keparahan.

Untuk penyedia lain, lihat Ringkasan CI/CD. Untuk melakukan pemeriksaan sebelum setiap commit, gunakan install-hook.