Referensi Codex Security CLI

Gunakan referensi ini untuk memeriksa perintah codex-security yang didukung, flag, format keluaran, dan perilaku keluar. Untuk panduan pemindaian pertama, mulailah dengan panduan mulai cepat CLI.

Instal paket yang telah dipublikasikan di proyek Anda:

npm install @openai/codex-security

Jalankan paket yang terinstal sebagai npx @openai/codex-security. Anda dapat menggunakan codex-security secara langsung jika berkas executable tersedia di PATH Anda.

Ringkasan perintah

usage: codex-security [--version] <command> [options]

CLI menyediakan perintah berikut:

CLI juga menyediakan perintah integrasi berikut:

Tampilkan semua perintah yang tersedia:

npx @openai/codex-security --help

Tambahkan --help ke perintah untuk memeriksa argumen dan opsinya:

npx @openai/codex-security scan --help

codex-security --version mencetak versi yang terinstal lalu keluar. codex-security info --json melaporkan versi SDK dan plugin bawaan. Kedua perintah tersebut tidak memerlukan Python.

Temukan perintah dan hubungkan agen

Cetak manifes perintah yang dapat dibaca agen:

npx @openai/codex-security --llms

Periksa skema argumen pemindaian sebagai JSON:

npx @openai/codex-security scan --schema --format json

Buat pelengkapan shell untuk Bash:

npx @openai/codex-security completions bash

Ganti bash dengan zsh atau fish untuk shell tersebut.

Hasil pemindaian mendukung --format toon|json|yaml|jsonl dan --full-output. --format pada tingkat kerangka kerja ini berbeda dari --export-format, yang memilih format artefak yang diekspor dari pemindaian selesai. Bantuan perintah global juga mencantumkan md, tetapi hasil pemindaian tidak mendukung keluaran Markdown.

Daftarkan CLI sebagai server MCP:

npx @openai/codex-security mcp add

Sinkronkan skill Codex Security ke agen Anda:

npx @openai/codex-security skills add

MCP hanya mengekspos perintah metadata hanya-baca info. Pemindaian, ekspor, autentikasi, validasi, dan pembuatan patch tetap hanya tersedia melalui CLI.

codex-security scan

Jalankan pemindaian terhadap repositori, jalur yang dipilih, perubahan yang telah di-commit, atau working tree.

usage: codex-security scan [-h] [--auth {auto,chatgpt,api-key}]
                           [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                           [--path PATH | --diff BASE | --working-tree]
                           [--head HEAD] [--base BASE]
                           [--knowledge-base PATH]
                           [--mode {standard,deep}] [--model MODEL]
                           [--effort {minimal,low,medium,high,xhigh}]
                           [--output-dir DIR]
                           [--archive-existing]
                           [--plugin-path PATH] [--python PATH]
                           [--codex KEY=VALUE] [--fail-on-severity LEVEL]
                           [--max-cost USD] [--dry-run] [--verbose]
                           [--json] [--format {toon,json,yaml,jsonl}]
                           [--full-output] [repository]

repository secara default menggunakan direktori saat ini.

Pilih autentikasi pemindaian

Gunakan --auth auto, nilai default, untuk memilih kredensial secara otomatis. Jika sesi masuk ChatGPT dan OPENAI_API_KEY atau CODEX_API_KEY sama-sama tersedia, pemindaian interaktif dengan keluaran teks akan menanyakan kredensial yang akan digunakan. CI, pemindaian JSON dan JSONL, serta pemindaian lain tanpa terminal interaktif menggunakan API key lingkungan. Uji coba tidak menampilkan prompt atau memuat kredensial.

Untuk menggunakan kredensial tersimpan, teruskan --auth chatgpt:

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

Untuk menggunakan API key lingkungan, teruskan --auth api-key:

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

Untuk menjadikan kredensial tersimpan sebagai default otomatis, jalankan unset OPENAI_API_KEY CODEX_API_KEY.

Gunakan Amazon Bedrock

Pilih Amazon Bedrock dengan --provider amazon-bedrock dan tentukan model Bedrock secara eksplisit dengan --model:

npx @openai/codex-security scan . \
  --provider amazon-bedrock \
  --model openai.gpt-5.6-sol

Tetapkan AWS_REGION dan lakukan autentikasi dengan AWS_BEARER_TOKEN_BEDROCK, access key AWS standar, profil AWS, identitas web, kredensial kontainer, atau rantai kredensial AWS default. Pemindaian Bedrock menggunakan kredensial AWS, bukan --auth, sesi masuk ChatGPT, atau API key OpenAI. scan dan bulk-scan keduanya mendukung --provider.

Pilih target pemindaian

Pilih satu jenis target untuk setiap pemindaian.

--path, --diff, dan --working-tree saling eksklusif. --head memerlukan --diff, dan --base memerlukan --working-tree. Mode mendalam mendukung target repositori dan jalur.

Pemindaian diff dan working tree mengharuskan argumen repositori berupa root worktree Git. Ref yang dipilih harus tersedia di checkout tersebut.

Pindai seluruh repositori:

npx @openai/codex-security scan .

Pindai jalur yang dipilih:

npx @openai/codex-security scan . --path src --path tests

Pindai perubahan yang telah di-commit:

npx @openai/codex-security scan . --diff origin/main --head HEAD

Pindai perubahan yang telah dan belum di-stage:

npx @openai/codex-security scan . --working-tree --base HEAD

Jalankan peninjauan repositori yang lebih mendalam:

npx @openai/codex-security scan . --mode deep

Tambahkan konteks keamanan

Gunakan --knowledge-base PATH untuk memberikan dokumen arsitektur, model ancaman, atau kebijakan keamanan. Ulangi opsi untuk menambahkan berkas atau direktori:

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

Dokumen yang didukung mencakup berkas .md, .markdown, .txt, .pdf, dan .docx. CLI menelusuri direktori secara rekursif, menolak jalur masukan tertaut, melewati entri direktori tertaut, dan menyimpan konten dokumen yang diekstrak di luar hasil pemindaian tersimpan.

Tetapkan opsi keluaran dan kebijakan

Gunakan opsi berikut untuk menyimpan artefak, mempertahankan hasil sebelumnya, atau membuat hasil yang dapat dibaca mesin.

Batas biaya merupakan perkiraan, bukan batas pengeluaran mutlak. Permintaan yang sudah berlangsung dapat selesai di atas batas, dan hasil pemindaian parsial tetap tersedia.

Jika Anda menghilangkan --output-dir, hasil disimpan di $CODEX_HOME/state/plugins/codex-security/scans/<repository>. CODEX_HOME secara default adalah ~/.codex. Tetapkan CODEX_SECURITY_STATE_DIR untuk menyimpan hasil di $CODEX_SECURITY_STATE_DIR/scans/<repository>. Direktori ini dapat memuat cuplikan sumber dan detail kerentanan, jadi kelola izin serta retensinya dengan tepat.

Workbench menyimpan riwayat pemindaian di $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3. Menetapkan CODEX_SECURITY_STATE_DIR juga memindahkan basis data workbench.

Direktori keluaran harus berada di luar direktori yang dipindai dan setiap worktree Git yang menaunginya. Pemindaian dapat mengganti direktori hasil yang ada dengan --archive-existing.

Untuk mempertahankan hasil sebelumnya sebelum menggunakan kembali direktori keluaran:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --archive-existing

Secara default, pemindaian hanya menghasilkan laporan. Tambahkan --fail-on-severity untuk mengevaluasi kebijakan tingkat keparahan di CI:

npx @openai/codex-security scan . \
  --diff origin/main \
  --output-dir /path/outside/repository/results \
  --json \
  --fail-on-severity high \
  > /path/outside/repository/codex-security.json

Uji coba memeriksa masukan lokal tanpa memuat kredensial, memulai Codex, atau memeriksa interpreter Python milik plugin:

npx @openai/codex-security scan . \
  --output-dir /path/outside/repository/results \
  --dry-run

Konfigurasikan runtime

Gunakan opsi runtime jika Anda memerlukan model, interpreter, plugin, atau nilai konfigurasi Codex tertentu.

Untuk memilih model dan upaya penalaran lain tanpa menulis TOML:

npx @openai/codex-security scan . --model gpt-5.6-terra --effort high

Beri tanda kutip pada nilai string yang diteruskan melalui --codex agar parser TOML menerima string:

npx @openai/codex-security scan . --codex 'model="gpt-5.6-terra"'

codex-security install-hook

Instal pemeriksaan keamanan Git pre-commit untuk repositori saat ini:

npx @openai/codex-security install-hook

Pemeriksaan ini memindai perubahan yang telah dan belum di-stage sebelum setiap commit serta memblokir temuan berkeparahan tinggi atau kesalahan pemindaian. Pemeriksaan mematuhi core.hooksPath dan tidak mengganti skrip pre-commit yang sudah ada. Tetapkan ambang tingkat keparahan lain jika diperlukan:

npx @openai/codex-security install-hook . --fail-on-severity medium

codex-security bulk-scan

Temukan dan pindai repositori GitHub, atau jalankan pemindaian yang dapat dilanjutkan dari CSV repositori:

Untuk panduan lengkap tentang penemuan GitHub, inventaris CSV, hasil kampanye, dan pemindaian dalam kontainer, lihat Jalankan pemindaian keamanan massal.

usage: codex-security bulk-scan [input] [--output-dir DIR]
                                [--workers N] [--mode {standard,deep}]
                                [--provider {openai,openrouter,fireworks,amazon-bedrock}]
                                [--model MODEL]
                                [--effort {minimal,low,medium,high,xhigh}]
                                [--max-attempts N] [--plugin-path PATH]
                                [--python PATH] [--codex KEY=VALUE]

Jalankan npx @openai/codex-security bulk-scan tanpa argumen untuk memilih repositori secara interaktif. Alur ini memerlukan sesi masuk GitHub CLI.

Untuk memilih model dan upaya penalaran selama penemuan interaktif:

npx @openai/codex-security bulk-scan --model gpt-5.6-terra --effort high

Untuk daftar repositori yang telah disiapkan, berikan CSV dan --output-dir:

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

CSV memerlukan kolom id, repository, dan revision. Revisi harus berupa hash commit lengkap. Kolom opsional scope dan mode mengonfigurasi setiap repositori:

id,repository,revision,scope,mode
service,https://github.com/example/service.git,0123456789abcdef0123456789abcdef01234567,src,standard

--workers membatasi pemindaian serentak dan secara default adalah 4. --mode secara default adalah standard, dan --max-attempts secara default adalah 1. Tetapkan --max-attempts jika Anda ingin mencoba kembali repositori setelah terjadi kesalahan. Jalankan kembali perintah yang sama untuk melanjutkan pemindaian massal dari direktori keluaran yang ada. CLI hanya melewati repositori yang telah selesai jika artefak hasil tercatatnya masih tersedia.

Untuk kampanye dalam kontainer, lihat Jalankan pemindaian massal di Docker.

codex-security scans

Temukan pemindaian tersimpan

Tampilkan pemindaian tersimpan untuk direktori saat ini:

npx @openai/codex-security scans

Tampilkan pemindaian untuk repositori lain:

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

Temukan pemindaian yang disimpan di direktori keluaran tertentu:

npx @openai/codex-security scans list --scan-root /path/outside/repository/results

Periksa atau ulangi pemindaian

Tampilkan hasil dan konfigurasi pemindaian tersimpan:

npx @openai/codex-security scans show SCAN_ID

Jalankan ulang pemindaian terhadap checkout saat ini menggunakan konfigurasi aslinya:

npx @openai/codex-security scans rerun SCAN_ID

Cocokkan dan bandingkan temuan

Cocokkan temuan yang memiliki akar penyebab sama di antara dua pemindaian:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Bandingkan pemindaian yang telah dicocokkan untuk menemukan temuan baru, yang tetap ada, muncul kembali, terselesaikan, dan tidak diketahui:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Temuan dianggap tidak diketahui jika pemindaian berikutnya memiliki cakupan tidak lengkap atau tidak mencakup lokasi asli temuan. Tambahkan --force ke match jika Anda perlu menghitung ulang pencocokan yang ada.

Untuk mencocokkan semua pemindaian selesai bagi repositori saat ini, termasuk pemindaian dari checkout lain:

npx @openai/codex-security scans match --all

Hasil pemindaian dapat berbeda meskipun Anda menjalankan ulang konfigurasi yang sama. Pencocokan dan perbandingan melacak perubahan; keduanya tidak membuat hasil deterministik atau membuktikan bahwa kerentanan sudah tidak ada. Gunakan validate untuk memeriksa ulang temuan yang sangat penting bagi keamanan terhadap kode saat ini.

codex-security findings

Catat temuan yang telah ditinjau sebagai positif palsu:

usage: codex-security findings false-positive OCCURRENCE_ID
                       --reason REASON

Periksa pemindaian tersimpan untuk mengidentifikasi kemunculan temuan:

npx @openai/codex-security scans show SCAN_ID

Catat penjelasan khusus untuk positif palsu tersebut:

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

Alasan tidak boleh kosong. Codex Security menyimpan keputusan tersebut untuk repositori dan memberikannya sebagai konteks bagi pemindaian berikutnya. Setiap pemindaian secara independen memeriksa ulang sumber, kontrol, dan keterjangkauan saat ini. Keputusan sebelumnya tidak mengecualikan aturan, jalur, atau kelas kerentanan.

codex-security export

Ekspor CSV, JSON, atau SARIF dari pemindaian selesai yang telah disegel. Ekspor memvalidasi artefak pemindaian sebelum menulis keluaran serta tidak menyentuh runtime Codex dan kredensial.

usage: codex-security export [--export-format {csv,json,sarif}]
                             [--output FILE|-] [--source-root PATH]
                             [--python PATH] scan_dir

scan_dir adalah direktori pemindaian selesai.

--source-root hanya berfungsi dengan --export-format sarif. JSON mempertahankan dokumen temuan tersegel. CSV berisi kolom temuan portabel dan tidak menyertakan status triase workbench lokal.

Tanpa --output, CLI menulis SARIF ke results.sarif, JSON ke findings.json, dan CSV ke findings.csv di direktori kerja saat ini. Ekspor dapat memuat cuplikan sumber dan detail kerentanan. Jalankan perintah di luar repositori atau teruskan --output dengan jalur privat di luar checkout yang dipindai.

Tulis SARIF ke berkas:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root /path/to/repository \
  --output /path/outside/repository/exports/results.sarif

Tulis SARIF ke stdout:

npx @openai/codex-security export /path/to/scan \
  --export-format sarif \
  --source-root . \
  --output -

Ekspor temuan sebagai JSON:

npx @openai/codex-security export /path/to/scan \
  --export-format json \
  --output /path/outside/repository/exports/findings.json

Ekspor temuan sebagai CSV:

npx @openai/codex-security export /path/to/scan \
  --export-format csv \
  --output /path/outside/repository/exports/findings.csv

codex-security validate dan codex-security patch

Periksa apakah kandidat temuan valid:

npx @openai/codex-security validate findings.json \
  "Possible SQL injection in src/query.ts:42"

Buat perbaikan dengan skill remediasi bawaan:

npx @openai/codex-security patch findings.json \
  "Missing authorization check in src/routes.ts:18"

Setiap argumen dapat berisi teks literal atau merujuk ke berkas. Kedua perintah bekerja terhadap direktori saat ini. Gunakan validate untuk memeriksa ulang temuan asli secara langsung setelah perbaikan atau saat pemindaian berikutnya tidak lagi melaporkannya. Perbandingan pemindaian saja tidak membuktikan bahwa perbaikan berhasil. Alat eksternal dapat menggunakan perintah ini tanpa membangun ulang pemindai.

Gunakan --effort untuk memilih upaya penalaran bagi kedua perintah:

npx @openai/codex-security validate "Possible SQL injection" --effort high

codex-security login, logout, dan info

Masuk secara interaktif:

npx @openai/codex-security login

Gunakan autentikasi perangkat pada mesin jarak jauh atau tanpa antarmuka pengguna:

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

Periksa sesi masuk saat ini:

npx @openai/codex-security login status

Hapus sesi masuk yang tersimpan:

npx @openai/codex-security logout

Simpan API key dengan meneruskannya melalui stdin:

printenv OPENAI_API_KEY | npx @openai/codex-security login --with-api-key

Simpan token akses perusahaan:

printenv CODEX_ACCESS_TOKEN | npx @openai/codex-security login --with-access-token

Periksa metadata SDK dan plugin bawaan yang bersifat hanya-baca:

npx @openai/codex-security info --json

Saat Anda mengekspos CLI sebagai server MCP, info adalah satu-satunya perintah yang tersedia. Pemindaian, ekspor, proses masuk, validasi, dan pembuatan patch tetap hanya tersedia melalui CLI.

Baca keluaran pemindaian

Secara default, pemindaian mengirim progres, ringkasan penyelesaian, dan kesalahan ke stderr tanpa menulis hasil pemindaian lengkap ke stdout. Minta --json, --format, atau --full-output untuk mengirim hasil pemindaian terstruktur ke stdout.

Diagnostik mendetail

Tambahkan --verbose untuk mencetak diagnostik siklus hidup, autentikasi, progres, dan biaya yang telah disunting ke stderr:

npx @openai/codex-security scan . --verbose

Tetapkan CODEX_SECURITY_LOG_LEVEL=debug untuk mengaktifkan diagnostik yang sama tanpa flag. LOG_LEVEL=debug juga mengaktifkan diagnostik jika CODEX_SECURITY_LOG_LEVEL tidak ditetapkan.

Kontrol pencatatan ini hanya berlaku untuk CLI. Kredensial dan pengenal penyedia tetap disunting, dan hasil pemindaian terstruktur tetap berada di stdout.

Ringkasan penyelesaian

Pemindaian yang selesai menulis jumlah temuan, perincian tingkat keparahan, cakupan, waktu berlalu, jalur laporan, dan direktori hasil ke stderr. Ringkasan menyertakan penggunaan token dan perkiraan biaya jika tersedia:

codex-security: Findings: 4 (1 critical, 2 high, 1 informational). Coverage: complete.
codex-security: Elapsed: 1s.
codex-security: Tokens: 1,250 input, 200 cached, 30 output.
codex-security: Report: /path/to/scan/report.md
codex-security: Results: /path/to/scan

Temuan informasional dihitung dalam jumlah total ringkasan. Kebijakan tingkat keparahan hanya mengevaluasi temuan critical, high, medium, dan low.

Keluaran JSON

scan --json menulis satu dokumen JSON lengkap ke stdout. Bentuk tingkat teratasnya adalah:

manifest
findings
coverage
scanDir
threadId
reportPath
artifactsDir
sarifPath
turn
  id
  status
  durationMs
  finalResponse
  usage

Progres, ringkasan penyelesaian, pemberitahuan arsip, dan kesalahan tetap berada di stderr. Pemindaian yang selesai tetap mencetak hasil JSON lengkap jika kebijakan tingkat keparahan mengembalikan kode keluar 1 atau cakupan tidak lengkap mengembalikan kode keluar 2.

Artefak pemindaian

Pemindaian yang selesai menyimpan laporan yang mudah dibaca dan artefak terstruktur secara bersamaan:

<scan-directory>/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced

Berkas terstruktur memiliki fungsi berbeda:

Kelengkapan cakupan memiliki tiga nilai:

• complete: Pemindaian mencatat cakupan lengkap untuk lingkup yang dipilih.
• partial: Pemindaian mencatat pekerjaan yang ditunda atau batasan cakupan lainnya.
• unknown: Pemindaian melaporkan kelengkapan cakupan sebagai tidak diketahui.

Tinjau permukaan yang ditunda, pengecualian eksplisit, dan pertanyaan terbuka sebelum menggunakan cakupan sebagai bukti untuk keputusan keamanan.

Kode keluar dan sinyal

CLI menggunakan kode keluar berikut:

Setiap pemindaian dengan cakupan partial atau unknown mengembalikan 2, meskipun tanpa kebijakan tingkat keparahan. Saat Anda meminta keluaran terstruktur, pemindaian yang selesai tetap menulis hasil yang tersedia ke stdout. CLI mencetak lokasi setiap keluaran parsial setelah interupsi atau kesalahan runtime.

Autentikasi dan prasyarat

Tetapkan OPENAI_API_KEY atau CODEX_API_KEY, masuk dengan npx @openai/codex-security login, atau gunakan sesi masuk Codex berbasis berkas yang sudah ada. Untuk Amazon Bedrock, gunakan API key Bedrock atau rantai kredensial AWS standar.

Untuk pemilihan kredensial, lihat Pilih autentikasi pemindaian.

Untuk CI, batasi cakupan API key pada langkah pemindaian dan gunakan alur kerja tepercaya.

CLI memerlukan Node.js 22 atau yang lebih baru. Menjalankan pemindaian atau mengekspor temuan juga memerlukan Python 3.10 atau yang lebih baru. Python 3.10 juga memerlukan tomli. Gunakan --python atau PYTHON untuk memilih interpreter jika penemuan otomatis tidak sesuai.

Lanjutkan dengan panduan mulai cepat CLI, panduan pemindaian massal, FAQ CLI, panduan CI, atau panduan TypeScript SDK.

Alias teks biasa

• --output FILE|-