Codex Security CLI referansı

Desteklenen codex-security komutlarını, bayrakları, çıktı biçimlerini ve çıkış davranışını kontrol etmek için bu referansı kullanın. Yönlendirmeli bir ilk tarama için CLI hızlı başlangıcı ile başlayın.

Yayımlanan paketi projenize yükleyin:

npm install @openai/codex-security

Yüklü paketi npx @openai/codex-security olarak çağırın. Yürütülebilir dosya PATH üzerinde kullanılabiliyorsa codex-security komutunu doğrudan kullanabilirsiniz.

Komutlara genel bakış

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

CLI şu komutları sağlar:

CLI ayrıca şu entegrasyon komutlarını sağlar:

Kullanılabilir tüm komutları listeleyin:

npx @openai/codex-security --help

Bağımsız değişkenlerini ve seçeneklerini incelemek için bir komuta --help ekleyin:

npx @openai/codex-security scan --help

codex-security --version yüklü sürümü yazdırıp çıkar. codex-security info --json SDK ve paketlenmiş eklenti sürümlerini bildirir. İki komut da Python gerektirmez.

Komutları keşfetme ve ajanları bağlama

Ajan tarafından okunabilir komut bildirimini yazdırın:

npx @openai/codex-security --llms

Tarama bağımsız değişkeni şemasını JSON olarak inceleyin:

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

Bash için kabuk tamamlamaları oluşturun:

npx @openai/codex-security completions bash

Bu kabuklar için bash değerini zsh veya fish ile değiştirin.

Tarama sonuçları --format toon|json|yaml|jsonl ve --full-output biçimlerini destekler. Bu çerçeve düzeyindeki --format, tamamlanmış bir taramadan dışa aktarılan yapıtın biçimini seçen --export-format değerinden ayrıdır. Genel komut yardımı md değerini de listeler ancak tarama sonuçları Markdown çıktısını desteklemez.

CLI'ı bir MCP sunucusu olarak kaydedin:

npx @openai/codex-security mcp add

Codex Security becerilerini ajanlarınızla eşitleyin:

npx @openai/codex-security skills add

MCP yalnızca salt okunur info meta veri komutunu sunar. Taramalar, dışa aktarmalar, kimlik doğrulama, doğrulama ve yama uygulama yalnızca CLI üzerinden yapılabilir.

codex-security scan

Bir depoya, seçilen yollara, kaydedilmiş değişikliklere veya çalışma ağacına karşı tarama çalıştırın.

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 varsayılan olarak geçerli dizindir.

Tarama kimlik doğrulamasını seçme

Kimlik bilgilerini otomatik olarak seçmek için varsayılan değer olan --auth auto kullanın. Hem ChatGPT oturumu hem de OPENAI_API_KEY veya CODEX_API_KEY mevcut olduğunda, metin çıktılı etkileşimli taramalar hangi kimlik bilgisinin kullanılacağını sorar. CI, JSON ve JSONL taramaları ile etkileşimli terminali olmayan diğer taramalar ortam API key'ini kullanır. Deneme çalıştırmaları istem göstermez veya kimlik bilgilerini yüklemez.

Saklanan kimlik bilgilerinizi kullanmak için --auth chatgpt geçirin:

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

Bir ortam API key'i kullanmak için --auth api-key geçirin:

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

Saklanan kimlik bilgilerini otomatik varsayılan yapmak için unset OPENAI_API_KEY CODEX_API_KEY komutunu çalıştırın.

Amazon Bedrock kullanma

--provider amazon-bedrock ile Amazon Bedrock'ı seçin ve --model ile açık bir Bedrock modeli belirtin:

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

AWS_REGION değerini ayarlayın ve AWS_BEARER_TOKEN_BEDROCK, standart AWS erişim anahtarları, bir AWS profili, web kimliği, kapsayıcı kimlik bilgileri veya varsayılan AWS kimlik bilgisi zinciriyle kimlik doğrulayın. Bedrock taramaları --auth, ChatGPT oturumu veya OpenAI API key yerine AWS kimlik bilgilerini kullanır. Hem scan hem de bulk-scan --provider değerini destekler.

Tarama hedefini seçme

Her tarama için bir hedef türü seçin.

--path, --diff ve --working-tree birbirini dışlar. --head --diff gerektirir ve --base, --working-tree gerektirir. Derin mod depo ve yol hedeflerini destekler.

Fark ve çalışma ağacı taramalarında depo bağımsız değişkeni Git çalışma ağacı kökü olmalıdır. Seçilen başvurular bu çalışma kopyasında bulunmalıdır.

Tüm depoyu tarayın:

npx @openai/codex-security scan .

Seçilen yolları tarayın:

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

Kaydedilmiş değişiklikleri tarayın:

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

Hazırlanmış ve hazırlanmamış değişiklikleri tarayın:

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

Depoyu daha derinlemesine inceleyin:

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

Güvenlik bağlamı ekleme

Mimari belgeleri, tehdit modellerini veya güvenlik politikalarını sağlamak için --knowledge-base PATH kullanın. Daha fazla dosya veya dizin için seçeneği yineleyin:

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

Desteklenen belgeler arasında .md, .markdown, .txt, .pdf ve .docx dosyaları bulunur. CLI dizinlerde özyinelemeli arama yapar, bağlantılı girdi yollarını reddeder, bağlantılı dizin girdilerini atlar ve çıkarılan belge içeriğini kaydedilmiş tarama sonuçlarının dışında tutar.

Çıktı ve politika seçeneklerini ayarlama

Yapıtları tutmak, önceki sonuçları korumak veya makine tarafından okunabilir bir sonuç oluşturmak için bu seçenekleri kullanın.

Maliyet sınırı bir tahmindir, kesin harcama üst sınırı değildir. Devam eden istekler sınırın üzerinde tamamlanabilir ve kısmi tarama sonuçları kullanılabilir durumda kalır.

--output-dir belirtilmediğinde sonuçlar $CODEX_HOME/state/plugins/codex-security/scans/<repository> altında kalıcı olur. CODEX_HOME varsayılan olarak ~/.codex değeridir. Sonuçları bunun yerine $CODEX_SECURITY_STATE_DIR/scans/<repository> altında tutmak için CODEX_SECURITY_STATE_DIR ayarlayın. Bu dizinler kaynak alıntıları ve güvenlik açığı ayrıntıları içerebilir; bu nedenle izinlerini ve saklama sürelerini uygun şekilde yönetin.

Çalışma tezgâhı tarama geçmişini $CODEX_HOME/state/plugins/codex-security/workbench.sqlite3 içinde tutar. CODEX_SECURITY_STATE_DIR ayarlamak çalışma tezgâhı veritabanını da taşır.

Çıktı dizini, taranan dizinin ve onu kapsayan tüm Git çalışma ağaçlarının dışında olmalıdır. Bir tarama, mevcut sonuç dizinini --archive-existing ile değiştirebilir.

Bir çıktı dizinini yeniden kullanmadan önce önceki sonuçları korumak için:

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

Taramalar varsayılan olarak yalnızca rapor üretir. CI'da bir önem derecesi politikasını değerlendirmek için --fail-on-severity ekleyin:

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

Deneme çalıştırması; kimlik bilgilerini yüklemeden, Codex'i başlatmadan veya eklentinin Python yorumlayıcısını yoklamadan yerel girdileri kontrol eder:

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

Çalışma zamanını yapılandırma

Açık bir model, yorumlayıcı, eklenti veya Codex yapılandırma değeri gerektiğinde çalışma zamanı seçeneklerini kullanın.

TOML yazmadan farklı bir model ve akıl yürütme çabası seçmek için:

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

TOML ayrıştırıcısının bir dize alması için --codex üzerinden geçirilen dize değerlerini tırnak içine alın:

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

codex-security install-hook

Geçerli depo için bir Git kayıt öncesi güvenlik kontrolü yükleyin:

npx @openai/codex-security install-hook

Kontrol, her kayıttan önce hazırlanmış ve hazırlanmamış değişiklikleri tarar ve yüksek önem dereceli bulguları ya da tarama hatalarını engeller. core.hooksPath değerine uyar ve mevcut bir kayıt öncesi betiğini değiştirmez. Gerektiğinde farklı bir önem derecesi eşiği ayarlayın:

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

codex-security bulk-scan

GitHub depolarını keşfedip tarayın veya bir depo CSV'sinden sürdürülebilir tarama çalıştırın:

GitHub keşfi, CSV envanterleri, kampanya sonuçları ve kapsayıcı içinde çalıştırılan taramalar hakkında eksiksiz bir kılavuz için Toplu güvenlik taramaları çalıştırma bölümüne bakın.

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]

Depoları etkileşimli olarak seçmek için npx @openai/codex-security bulk-scan komutunu bağımsız değişken olmadan çalıştırın. Bu akış için GitHub CLI oturumu gerekir.

Etkileşimli keşif sırasında bir model ve akıl yürütme çabası seçmek için:

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

Hazırlanmış bir depo listesi için bir CSV ve --output-dir sağlayın:

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

CSV için id, repository ve revision sütunları zorunludur. Revizyonlar tam kayıt karmaları olmalıdır. İsteğe bağlı scope ve mode sütunları ayrı ayrı depoları yapılandırır:

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

--workers eşzamanlı taramaları sınırlar ve varsayılan değeri 4 şeklindedir. --mode varsayılan olarak standard, --max-attempts ise 1 değeridir. Bir hatadan sonra depoyu yeniden denemek istediğinizde --max-attempts ayarlayın. Toplu taramayı mevcut çıktı dizininden sürdürmek için aynı komutu yeniden çalıştırın. CLI, tamamlanan depoları yalnızca kayıtlı sonuç yapıtları hâlâ mevcutsa atlar.

Kapsayıcı içindeki kampanyalar için Docker'da toplu taramalar çalıştırma bölümüne bakın.

codex-security scans

Kaydedilmiş taramaları bulma

Geçerli dizin için kaydedilmiş taramaları listeleyin:

npx @openai/codex-security scans

Farklı bir depo için taramaları listeleyin:

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

Belirli bir çıktı dizini altında saklanan taramaları bulun:

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

Bir taramayı inceleme veya yineleme

Kaydedilmiş bir taramanın sonuçlarını ve yapılandırmasını gösterin:

npx @openai/codex-security scans show SCAN_ID

Taramayı özgün yapılandırmasıyla geçerli çalışma kopyasında yeniden çalıştırın:

npx @openai/codex-security scans rerun SCAN_ID

Bulguları eşleştirme ve karşılaştırma

İki taramada aynı kök nedeni paylaşan bulguları eşleştirin:

npx @openai/codex-security scans match PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Yeni, devam eden, yeniden açılmış, çözülmüş ve bilinmeyen bulguları belirlemek için eşleştirilen taramaları karşılaştırın:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Sonraki taramanın kapsamı eksikse veya bulgunun özgün konumunu kapsamıyorsa bulgu bilinmeyendir. Mevcut bir eşleşmeyi yeniden hesaplamanız gerektiğinde match komutuna --force ekleyin.

Diğer çalışma kopyalarındaki taramalar da dâhil olmak üzere geçerli deponun tamamlanan tüm taramalarını eşleştirmek için:

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

Aynı yapılandırmayı yeniden çalıştırsanız bile tarama sonuçları değişebilir. Eşleştirme ve karşılaştırma değişiklikleri izler; sonuçları belirlenimci hâle getirmez veya bir güvenlik açığının artık bulunmadığını kanıtlamaz. Güvenlik açısından kritik bir bulguyu güncel koda karşı yeniden kontrol etmek için validate kullanın.

codex-security findings

İncelenmiş bir bulguyu yanlış pozitif olarak kaydedin:

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

Bulgu oluşumunu belirlemek için kaydedilmiş taramayı inceleyin:

npx @openai/codex-security scans show SCAN_ID

Yanlış pozitif için belirli bir açıklama kaydedin:

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

Gerekçe boş olmamalıdır. Codex Security kararı depo için kaydeder ve gelecekteki taramalara bağlam olarak sağlar. Her tarama güncel kaynağı, kontrolleri ve erişilebilirliği bağımsız olarak yeniden kontrol eder. Önceki bir karar bir kuralı, yolu veya güvenlik açığı sınıfını engellemez.

codex-security export

Tamamlanmış ve mühürlenmiş bir taramadan CSV, JSON veya SARIF dışa aktarın. Dışa aktarma, çıktıyı yazmadan önce tarama yapıtlarını doğrular ve Codex çalışma zamanı ile kimlik bilgilerine dokunmaz.

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

scan_dir tamamlanmış tarama dizinidir.

--source-root yalnızca --export-format sarif ile çalışır. JSON, mühürlenmiş bulgular belgesini korur. CSV taşınabilir bulgu sütunlarını içerir ve yerel çalışma tezgâhı triyaj durumunu içermez.

--output olmadan CLI, geçerli çalışma dizininde SARIF'i results.sarif, JSON'u findings.json ve CSV'yi findings.csv dosyasına yazar. Dışa aktarımlar kaynak alıntıları ve güvenlik açığı ayrıntıları içerebilir. Komutu depo dışında çalıştırın veya taranan çalışma kopyasının dışındaki özel bir yolu --output ile geçirin.

SARIF'i bir dosyaya yazın:

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

SARIF'i stdout'a yazın:

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

Bulguları JSON olarak dışa aktarın:

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

Bulguları CSV olarak dışa aktarın:

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

codex-security validate ve codex-security patch

Olası bir bulgunun geçerli olup olmadığını kontrol edin:

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

Paketlenmiş düzeltme becerisiyle bir düzeltme oluşturun:

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

Her bağımsız değişken düz metin içerebilir veya bir dosyaya işaret edebilir. Her iki komut da geçerli dizine karşı çalışır. Bir düzeltmeden sonra veya sonraki bir tarama artık bildirmediğinde özgün bulguyu doğrudan yeniden kontrol etmek için validate kullanın. Tek başına bir tarama karşılaştırması, düzeltmenin işe yaradığını kanıtlamaz. Harici araçlar tarayıcıyı yeniden oluşturmadan bu komutları kullanabilir.

Her iki komut için de akıl yürütme çabasını seçmek üzere --effort kullanın:

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

codex-security login, logout ve info

Etkileşimli olarak oturum açın:

npx @openai/codex-security login

Uzak veya ekransız bir makinede cihaz kimlik doğrulamasını kullanın:

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

Geçerli oturumu kontrol edin:

npx @openai/codex-security login status

Saklanan oturumu kaldırın:

npx @openai/codex-security logout

Bir API key'i stdin üzerinden geçirerek saklayın:

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

Kurumsal erişim token'ı saklayın:

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

Salt okunur SDK ve paketlenmiş eklenti meta verilerini inceleyin:

npx @openai/codex-security info --json

CLI'ı bir MCP sunucusu olarak sunduğunuzda kullanılabilen tek komut info olur. Taramalar, dışa aktarmalar, oturum açma, doğrulama ve yama uygulama yalnızca CLI üzerinden yapılabilir.

Tarama çıktısını okuma

Taramalar varsayılan olarak ilerlemeyi, tamamlanma özetlerini ve hataları stderr'e gönderir; tam tarama sonucunu stdout'a yazmaz. Yapılandırılmış tarama sonuçlarını stdout'a göndermek için --json, --format veya --full-output isteyin.

Ayrıntılı tanılamalar

Redakte edilmiş yaşam döngüsü, kimlik doğrulama, ilerleme ve maliyet tanılamalarını stderr'e yazdırmak için --verbose ekleyin:

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

Bayrak olmadan aynı tanılamaları etkinleştirmek için CODEX_SECURITY_LOG_LEVEL=debug ayarlayın. CODEX_SECURITY_LOG_LEVEL ayarlanmamışsa LOG_LEVEL=debug de tanılamaları etkinleştirir.

Bu günlük kaydı denetimleri yalnızca CLI için geçerlidir. Kimlik bilgileri ve sağlayıcı tanımlayıcıları redakte edilmiş olarak kalır; yapılandırılmış tarama sonuçları stdout'ta kalır.

Tamamlanma özeti

Tamamlanan bir tarama bulgu sayısını, önem derecesi dağılımını, kapsamı, geçen süreyi, rapor yolunu ve sonuç dizinini stderr'e yazar. Mevcut olduğunda token kullanımını ve tahmini maliyeti içerir:

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

Bilgilendirme amaçlı bulgular özet toplamına dâhil edilir. Önem derecesi politikaları yalnızca critical, high, medium ve low bulgularını değerlendirir.

JSON çıktısı

scan --json stdout'a tek bir eksiksiz JSON belgesi yazar. Üst düzey yapısı şöyledir:

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

İlerleme, tamamlanma özetleri, arşiv bildirimleri ve hatalar stderr'de kalır. Bir önem derecesi politikası 1 çıkışını veya eksik kapsam 2 çıkışını döndürdüğünde bile tamamlanmış tarama tam JSON sonucunu yazdırır.

Tarama yapıtları

Tamamlanmış bir tarama okunabilir raporu ve yapılandırılmış yapıtları birlikte tutar:

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

Yapılandırılmış dosyalar farklı amaçlara hizmet eder:

Kapsamın eksiksizliğinin üç değeri vardır:

• complete: Tarama, seçilen kapsam için tam kapsam kaydeder.
• partial: Tarama, ertelenen işleri veya diğer kapsam sınırlarını kaydeder.
• unknown: Tarama, kapsamın eksiksizliğini bilinmeyen olarak bildirir.

Kapsamı bir güvenlik kararı için kanıt olarak kullanmadan önce ertelenen yüzeyleri, açıkça hariç tutulanları ve açık soruları inceleyin.

Çıkış kodları ve sinyaller

CLI şu çıkış kodlarını kullanır:

partial veya unknown kapsamına sahip tüm taramalar, önem derecesi politikası olmasa bile 2 döndürür. Yapılandırılmış çıktı istediğinizde tamamlanan taramalar mevcut sonuçları yine de stdout'a yazar. CLI, kesinti veya çalışma zamanı hatasından sonra tüm kısmi çıktıların konumunu yazdırır.

Kimlik doğrulama ve ön koşullar

OPENAI_API_KEY veya CODEX_API_KEY ayarlayın, npx @openai/codex-security login ile oturum açın ya da mevcut dosya tabanlı bir Codex oturumunu kullanın. Amazon Bedrock için bunun yerine bir Bedrock API key veya standart AWS kimlik bilgisi zincirini kullanın.

Kimlik bilgisi seçimi için Tarama kimlik doğrulamasını seçme bölümüne bakın.

CI için API key'i tarama adımıyla sınırlı tutun ve güvenilir bir iş akışı kullanın.

CLI için Node.js 22 veya sonraki bir sürümü gerekir. Tarama çalıştırmak veya bulguları dışa aktarmak için ayrıca Python 3.10 veya sonraki bir sürümü gerekir. Python 3.10 ayrıca tomli gerektirir. Otomatik keşif uygun değilse bir yorumlayıcı seçmek için --python veya PYTHON kullanın.

CLI hızlı başlangıcı, toplu tarama kılavuzu, CLI SSS, CI kılavuzu veya TypeScript SDK kılavuzu ile devam edin.

Düz metin diğer adları

• --output FILE|-