Dokumentasi ChatGPT
Bahasa Indonesia
Hubungi kami goolvyouyou@gmail.com

Mulai cepat Codex Security CLI

Siapkan Codex Security, jalankan pemindaian lokal, lalu tinjau laporan, temuan, dan cakupannya.

Codex Security membantu tim keamanan dan rekayasa menemukan, mengonfirmasi, dan memperbaiki kerentanan. Gunakan antarmuka baris perintah (CLI) untuk memindai repositori yang Anda miliki atau boleh Anda nilai, meninjau temuan dari waktu ke waktu, dan memeriksa perubahan sebelum digabungkan.

Periksa prasyarat

CLI memerlukan Node.js 22 (22.13.0 atau yang lebih baru), 24, atau 26. Pemindaian, pemindaian massal, ekspor, riwayat pemindaian, dan temuan tersimpan juga memerlukan Python 3.10 atau yang lebih baru. Untuk detail selengkapnya, lihat Autentikasi dan prasyarat.

Siapkan dan verifikasi CLI

Jalankan CLI dengan npx dan periksa versinya:

npx @openai/codex-security --version

Untuk melihat versi paket sekaligus versi plugin yang disertakan, jalankan:

npx @openai/codex-security info --json

Lihat rilis CLI dan SDK untuk perubahan paket.

Tampilkan daftar perintah yang tersedia:

npx @openai/codex-security --help

Lihat juga referensi CLI.

Masuk

Untuk penggunaan lokal, masuk dengan akun ChatGPT Anda:

npx @openai/codex-security login

Di komputer jarak jauh atau tanpa antarmuka, gunakan autentikasi perangkat:

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

Untuk CI dan alur kerja otomatis lainnya, tetapkan OpenAI API key:

export OPENAI_API_KEY="<your-api-key>"

Untuk kredensial AWS, lihat penyiapan Amazon Bedrock. Untuk OpenRouter atau Fireworks, tetapkan API key penyedia dan pilih model dengan --provider dan --model.

Untuk menggunakan proses masuk ChatGPT Anda ketika API key juga ditetapkan, pilih secara eksplisit:

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

Untuk mewajibkan API key lingkungan, pilih autentikasi API key:

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

Bergantung pada akun dan repositori Anda, pemindaian seluruh repositori mungkin juga memerlukan Trusted Access for Cyber.

Siapkan pemindaian

Pilih repositori yang Anda percayai dan boleh Anda nilai. Pemindaian menggunakan izin sistem operasi lokal Anda dan tidak berhenti untuk meminta persetujuan. Proses pemindaian dapat mewarisi lingkungan Anda, jadi hapus kredensial yang tidak terkait sebelum memulai. Lihat Izin pemindaian lokal.

Pilih direktori di luar repositori untuk hasil pemindaian:

REPOSITORY=/path/to/repository
SCAN_DIR=/path/outside/repository/codex-security-results

Jika Anda menghilangkan --output-dir, Codex Security menyimpan hasil dalam direktori status persistennya sendiri. Hasil dapat menyertakan cuplikan sumber dan detail kerentanan, jadi pilih lokasi privat dan kebijakan retensi yang sesuai.

Jika direktori status default tidak dapat ditulis, pilih direktori yang dapat ditulis di luar repositori yang dipindai:

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

Periksa repositori, target, dan direktori output sebelum memulai pemindaian:

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

Uji coba kering memeriksa input lokal, termasuk setiap jalur --knowledge-base, tanpa memulai Codex, memuat kredensial, atau memeriksa interpreter Python plugin.

Jalankan pemindaian pertama Anda

Jalankan pemindaian standar dan simpan hasilnya di direktori yang dipilih:

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

Terminal interaktif menampilkan dasbor pemindaian langsung. Tambahkan --headless untuk menampilkan baris progres biasa. CI dan terminal tanpa sesi interaktif menggunakan progres biasa secara otomatis.

Dasbor juga menampilkan detail sesi langsung. Detail ini dapat berisi kode sumber atau kredensial, jadi tinjau sebelum membagikannya.

Secara default, CLI menulis progres pemindaian dan ringkasan penyelesaiannya ke stderr. CLI tidak mencetak hasil pemindaian lengkap ke stdout. Pemindaian yang selesai mencetak ringkasan seperti ini:

  REPORT    /path/outside/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/outside/repository/codex-security-results

Penggunaan token dan perkiraan biaya ditampilkan jika tersedia. Untuk mencetak hasil lengkap sebagai JSON yang dapat dibaca mesin, minta output terstruktur secara eksplisit:

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

Secara default, pemindaian hanya menghasilkan laporan sehingga temuan tetap tersedia untuk tinjauan lokal. Anda mungkin ingin menambahkan ambang tingkat keparahan saat siap menjalankan pemindaian dalam CI.

Pilih model dan tingkat penalaran

Secara default, pemindaian menggunakan gpt-5.6-sol dengan tingkat penalaran xhigh. Pilih model dan tingkat yang berbeda jika tugas memerlukannya:

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

Tingkat yang didukung adalah minimal, low, medium, high, xhigh, dan max.

Tinjau hasil

Buka report.md untuk melihat hasil yang mudah dibaca. Direktori pemindaian juga berisi file terstruktur yang digunakan oleh otomatisasi:

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json mencatat target, cakupan, pembuat, dan artefak tersegel.
  • findings.json mencatat tingkat keparahan, keyakinan, lokasi, bukti, dan remediasi untuk setiap temuan.
  • coverage.json mencatat area yang ditinjau, pengecualian, pekerjaan yang ditunda, pertanyaan terbuka, dan kelengkapan cakupan.

Cakupan dapat berupa complete, partial, atau unknown. Baca setiap area yang ditunda atau pertanyaan terbuka sebelum memperlakukan pemindaian sebagai bukti peninjauan. Referensi CLI menjelaskan kontrak lengkap artefak dan output.

Tinjau dan tambal temuan

Setelah pemindaian interaktif lengkap yang menghasilkan temuan, CLI menawarkan penelusur temuan. Tinjau bukti dan pilih temuan yang akan diperbaiki. Anda dapat menemukan tugas tersimpan dalam aplikasi desktop Codex.

Untuk menambal temuan tinggi dan kritis tanpa penelusur:

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

Tambahkan --create-pr untuk melakukan commit atas patch yang telah diverifikasi dan membuka pull request GitHub.

Anda juga dapat menambal temuan tersimpan atau mengimpor masalah Linear. Lihat referensi validate dan patch.

Pilih pemindaian berikutnya

Gunakan pemindaian jalur jika repositori berisi layanan atau paket terpisah:

npx @openai/codex-security scan "$REPOSITORY" \
  --path services/billing \
  --path packages/auth

Tinjau perubahan yang telah di-commit antara revisi dasar dan HEAD:

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

Tinjau perubahan staged dan unstaged terhadap HEAD:

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

Pemindaian diff dan working tree mengharuskan argumen repositori berupa root working tree Git. Ambil revisi yang dipilih sebelum memulai pemindaian diff.

Gunakan mode mendalam jika repositori atau jalur memerlukan tinjauan yang lebih luas:

npx @openai/codex-security scan "$REPOSITORY" --mode deep

Untuk mengendalikan worker, subagen, dan waktu penghentian pemindaian:

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

Opsi ini memerlukan mode mendalam, yang mendukung target repositori dan jalur, bukan pemindaian diff atau working tree. Di sini, --workers mengendalikan worker pemindaian standar independen dalam satu pemindaian; bulk-scan --workers mengendalikan pemindaian repositori serentak. --max-time-hours menerima angka positif hingga 96, termasuk pecahan jam. Saat mencapai batas, pemindaian menghentikan worker yang belum selesai, mempertahankan hasil pemindaian yang telah selesai, dan menggabungkannya ke dalam laporan akhir.

Tambahkan konteks arsitektur dan keamanan

Berikan dokumen arsitektur, model ancaman, atau kebijakan keamanan sebagai konteks pemindaian. Hal ini membantu Codex Security mengevaluasi temuan berdasarkan cara kerja sistem Anda yang sebenarnya:

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

Tambahkan petunjuk pemindaian khusus

Tambahkan petunjuk yang memfokuskan pemindaian pada prioritas keamanan Anda. Gunakan file kedua untuk petunjuk tindak lanjut:

npx @openai/codex-security scan "$REPOSITORY" \
  --scan-prompt-file /path/to/scan.md \
  --post-scan-prompt-file /path/to/follow-up.md

Tindak lanjut berjalan dalam sesi terautentikasi yang sama setelah pemindaian berhasil serta pemindaian dengan cakupan tidak lengkap atau kesalahan. Jika tindak lanjut gagal, CLI melaporkan peringatan dan mempertahankan pemindaian yang telah selesai. Tindak lanjut tidak berjalan setelah pembatalan atau pemindaian yang mencapai batas biayanya. Kedua opsi juga berfungsi dengan bulk-scan; kolom CSV prompt menambahkan petunjuk khusus repositori.

Tetapkan anggaran pemindaian

Gunakan --max-cost untuk menghentikan pemindaian saat perkiraan biaya modelnya melampaui batas dalam USD:

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

Permintaan yang sedang berlangsung dapat selesai sedikit di atas batas. Jika pemindaian mendalam mencapai batas setelah Codex Security menggabungkan hasil worker yang telah selesai, CLI menyimpan laporan yang telah selesai, menandai cakupannya sebagai partial, dan mengembalikan kode keluar 2. Jika pemindaian tidak dapat menghasilkan laporan lengkap, setiap output parsial yang tersedia tetap tersimpan di disk.

Pindai perubahan sebelum setiap commit

Instal pemeriksaan keamanan Git pre-commit untuk repositori Anda:

npx @openai/codex-security install-hook

Pemeriksaan ini memindai perubahan staged dan unstaged sebelum setiap commit. Pemeriksaan memblokir temuan berkeparahan tinggi dan kesalahan pemindaian tanpa mengganti skrip pre-commit yang sudah ada.

Pindai repositori secara massal

Masuk ke GitHub sebelum menemukan repositori:

gh auth login

Temukan dan pilih repositori dari akun atau organisasi GitHub Anda:

npx @openai/codex-security bulk-scan

Alur interaktif mengecualikan repositori yang diarsipkan dan fork. Alur ini meminta Anda mengonfirmasi repositori yang dipilih sebelum memindainya.

Untuk memindai daftar repositori yang telah disiapkan, berikan CSV dan direktori output:

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

Jalankan kembali perintah yang sama untuk melanjutkan pemindaian massal yang sudah ada. Codex Security melewati repositori yang telah selesai. Tambahkan --max-attempts 3 jika Anda ingin mencoba kembali kesalahan sementara pada repositori atau pemindaian.

Untuk penemuan GitHub, persiapan CSV, hasil kampanye, dan penyiapan Docker, lihat Jalankan pemindaian keamanan massal.

Jalankan pemindaian massal dalam Docker

Jika akses Anda mencakup image Docker Codex Security, gunakan konfigurasi Compose yang telah diperkuat dan profil keamanan yang disediakan pada host Docker Linux. Host harus mendukung pembuatan namespace pengguna tanpa hak istimewa. Sediakan CSV repositori, simpan hasil dan status masuk dalam direktori terpasang yang persisten, serta berikan kredensial melalui lingkungan atau pengelola rahasia Anda:

docker compose run --rm codex-security \
  bulk-scan /input/repositories.csv \
  --output-dir /output \
  --workers 4

Kontainer menjalankan pemindaian massal tanpa perintah interaktif. Gunakan CLI di luar Docker jika Anda ingin menemukan repositori secara interaktif. Untuk repositori privat, berikan GH_TOKEN atau GITHUB_TOKEN melalui lingkungan atau pengelola rahasia Anda. Persyaratan masuk, termasuk akses akun dan repositori, juga berlaku untuk pemindaian dalam kontainer.

Tinjau kembali pemindaian tersimpan

Tampilkan daftar pemindaian tersimpan untuk repositori Anda:

npx @openai/codex-security scans list "$REPOSITORY"

Salin ID pemindaian dari hasil untuk memeriksa temuan dan konfigurasinya:

npx @openai/codex-security scans show SCAN_ID

Untuk memeriksa peristiwa tersimpan dari pemindaian dan worker-nya:

npx @openai/codex-security scans logs SCAN_ID

Log tersimpan tidak disamarkan dan dapat berisi kode sumber atau kredensial. Tinjau sebelum membagikannya.

Tampilkan daftar temuan terbuka di seluruh pemindaian repositori:

npx @openai/codex-security findings list "$REPOSITORY"

Temuan sebelumnya tetap terbuka jika pemindaian terbaru tidak mengonfirmasinya.

Untuk menandai temuan yang telah ditinjau sebagai positif palsu, jelaskan alasan temuan tersebut tidak berlaku:

npx @openai/codex-security findings false-positive FINDING_OCCURRENCE_ID \
  --reason "The route already checks permissions"

Pemindaian berikutnya mempertimbangkan penjelasan tersebut, tetapi tetap memeriksa ulang kode saat ini.

Jalankan pemindaian yang sama terhadap checkout saat ini menggunakan konfigurasi asalnya:

npx @openai/codex-security scans rerun SCAN_ID

Bandingkan dua pemindaian untuk menemukan temuan baru, yang bertahan, dibuka kembali, terselesaikan, atau tidak diketahui:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Perbandingan secara otomatis mencocokkan temuan berdasarkan akar penyebab dan menggunakan kembali kecocokan tersimpan.

Untuk format CSV pemindaian massal, filter riwayat pemindaian, dan opsi perintah, lihat referensi CLI.

Lanjutkan dengan alur kerja yang sesuai dengan tujuan Anda: