ChatGPT Belgeleri
Türkçe
İletişim goolvyouyou@gmail.com

Codex Security CLI hızlı başlangıç kılavuzu

Codex Security'yi kurun, yerel bir tarama çalıştırın; raporu, bulguları ve kapsamı inceleyin.

Codex Security, güvenlik ve mühendislik ekiplerinin güvenlik açıklarını bulmasına, doğrulamasına ve gidermesine yardımcı olur. Sahibi olduğunuz veya değerlendirme izniniz bulunan depoları taramak, bulguları zaman içinde incelemek ve değişiklikleri birleştirilmeden önce denetlemek için komut satırı arayüzünü (CLI) kullanın.

Ön koşulları denetleme

CLI için Node.js 22 (22.13.0 veya sonrası), 24 ya da 26 gerekir. Taramalar, toplu taramalar, dışa aktarımlar, tarama geçmişi ve kaydedilmiş bulgular için ayrıca Python 3.10 veya sonrası gerekir. Ayrıntılı bilgi için Kimlik doğrulama ve ön koşullar bölümüne bakın.

CLI'ı kurma ve doğrulama

CLI'ı npx ile çalıştırın ve sürümünü denetleyin:

npx @openai/codex-security --version

Hem paket sürümünü hem de paketle birlikte gelen eklentinin sürümünü görmek için şunu çalıştırın:

npx @openai/codex-security info --json

Paket değişiklikleri için CLI ve SDK sürümlerine bakın.

Kullanılabilir komutları listeleyin:

npx @openai/codex-security --help

Ayrıca CLI başvurusuna bakın.

Oturum açma

Yerel kullanım için ChatGPT hesabınızla oturum açın:

npx @openai/codex-security login

Uzak veya ekranı olmayan bir makinede cihaz kimlik doğrulamasını kullanın:

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

CI ve diğer otomatik iş akışları için bir OpenAI API key ayarlayın:

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

AWS kimlik bilgileri için Amazon Bedrock kurulumuna bakın. OpenRouter veya Fireworks için sağlayıcının API key'ini ayarlayın ve --provider ile --model kullanarak bir model seçin.

Bir API key de ayarlanmışken ChatGPT oturumunuzu kullanmak için bunu açıkça seçin:

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

Ortam API key'ini zorunlu tutmak için API key kimlik doğrulamasını seçin:

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

Hesabınıza ve deponuza bağlı olarak tam depo taramaları için ayrıca Trusted Access for Cyber gerekebilir.

Taramayı hazırlama

Güvendiğiniz ve değerlendirme izniniz bulunan bir depo seçin. Taramalar yerel işletim sistemi izinlarınızı kullanır ve onay için duraklamaz. Tarama işlemleri ortamınızı devralabilir; bu nedenle başlamadan önce ilgisiz kimlik bilgilerini kaldırın. Yerel tarama izinleri bölümüne bakın.

Tarama sonuçları için deponun dışında bir dizin seçin:

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

--output-dir seçeneğini atlarsanız Codex Security sonuçları kendi kalıcı durum dizinine kaydeder. Sonuçlar kaynak alıntıları ve güvenlik açığı ayrıntıları içerebilir; bu nedenle özel bir konum ve uygun bir saklama politikası seçin.

Varsayılan durum dizini yazılabilir değilse taranan deponun dışında yazılabilir bir dizin seçin:

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

Taramayı başlatmadan önce depoyu, hedefi ve çıktı dizinini denetleyin:

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

Deneme çalıştırması; Codex'i başlatmadan, kimlik bilgilerini yüklemeden veya eklentinin Python yorumlayıcısını yoklamadan, tüm --knowledge-base yolları dahil olmak üzere yerel girdileri denetler.

İlk taramanızı çalıştırma

Standart bir tarama çalıştırın ve sonuçlarını seçilen dizinde tutun:

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

Etkileşimli terminaller canlı bir tarama panosu gösterir. Bunun yerine düz ilerleme satırları göstermek için --headless ekleyin. CI ve etkileşimli oturumu olmayan terminaller düz ilerleme görünümünü otomatik olarak kullanır.

Pano, canlı oturum ayrıntılarını da gösterir. Bunlar kaynak kodu veya kimlik bilgileri içerebilir; bu nedenle paylaşmadan önce inceleyin.

CLI varsayılan olarak tarama ilerlemesini ve tamamlanma özetini stderr'e yazar. Tarama sonucunun tamamını stdout'a yazdırmaz. Tamamlanan bir tarama şuna benzer bir özet yazdırır:

  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

Kullanılabilir olduğunda token kullanımı ve tahmini maliyet gösterilir. Sonucun tamamını makine tarafından okunabilir JSON biçiminde yazdırmak için yapılandırılmış çıktıyı açıkça isteyin:

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

Taramalar varsayılan olarak yalnızca rapor üretir; dolayısıyla bulgular yerel inceleme için kullanılabilir kalır. CI'da tarama çalıştırmaya hazır olduğunuzda bir önem derecesi eşiği eklemek isteyebilirsiniz.

Model ve akıl yürütme düzeyi seçme

Taramalar varsayılan olarak xhigh akıl yürütme düzeyiyle gpt-5.6-sol kullanır. Görev gerektirdiğinde farklı bir model ve düzey seçin:

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

Desteklenen düzeyler minimal, low, medium, high, xhigh ve max şeklindedir.

Sonuçları inceleme

Okunabilir sonucu görmek için report.md dosyasını açın. Tarama dizini ayrıca otomasyonun kullandığı yapılandırılmış dosyaları içerir:

codex-security-results/
├── scan-manifest.json
├── findings.json
├── coverage.json
├── report.md
├── artifacts/
└── exports/
    └── results.sarif       # when produced
  • scan-manifest.json hedefi, kapsamı, üreticiyi ve mühürlenmiş yapıtları kaydeder.
  • findings.json her bulgunun önem derecesini, güven düzeyini, konumlarını, kanıtlarını ve düzeltmesini kaydeder.
  • coverage.json incelenen yüzeyleri, hariç tutulanları, ertelenen işleri, açık soruları ve kapsamın eksiksizliğini kaydeder.

Kapsam complete, partial veya unknown olabilir. Taramayı inceleme kanıtı olarak kabul etmeden önce ertelenen alanları veya açık soruları okuyun. CLI başvurusu, yapıt ve çıktı sözleşmesinin tamamını açıklar.

Bulguları inceleme ve düzeltme

Bulgular içeren eksiksiz bir etkileşimli taramadan sonra CLI bir bulgu tarayıcısı sunar. Kanıtları inceleyin ve hangi bulguların düzeltileceğini seçin. Kaydedilen görevleri Codex masaüstü uygulamasında bulabilirsiniz.

Yüksek ve kritik önem dereceli bulguları tarayıcı olmadan düzeltmek için:

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

Doğrulanmış yamaları commit etmek ve bir GitHub pull request açmak için --create-pr ekleyin.

Kaydedilmiş bulguları da düzeltebilir veya Linear sorunlarını içe aktarabilirsiniz. validate ve patch başvurusuna bakın.

Sonraki taramayı seçme

Bir depo ayrı hizmetler veya paketler içeriyorsa yol taraması kullanın:

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

Temel revizyon ile HEAD arasındaki commit edilmiş değişiklikleri inceleyin:

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

Hazırlanmış ve hazırlanmamış değişiklikleri HEAD ile karşılaştırarak inceleyin:

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

Fark ve çalışma ağacı taramalarında depo bağımsız değişkeninin Git çalışma ağacının kökü olması beklenir. Fark taraması başlatmadan önce seçilen revizyonları fetch edin.

Bir depo veya yolun daha geniş kapsamlı incelenmesi gerektiğinde derin modu kullanın:

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

Çalışanları, alt ajanları ve taramanın ne zaman duracağını denetlemek için:

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

Bu seçenekler, fark veya çalışma ağacı taramalarını değil depo ve yol hedeflerini destekleyen derin modu gerektirir. Burada --workers, tek bir taramadaki bağımsız standart tarama çalışanlarını; bulk-scan --workers ise eşzamanlı depo taramalarını denetler. --max-time-hours, kesirli saatler dahil olmak üzere 96 değerine kadar pozitif bir sayı kabul eder. Sınıra ulaşıldığında tarama tamamlanmamış çalışanları durdurur, tamamlanan tarama sonuçlarını korur ve bunları nihai raporda birleştirir.

Mimari ve güvenlik bağlamı ekleme

Mimari belgelerini, tehdit modellerini veya güvenlik politikalarını tarama bağlamı olarak sağlayın. Bu, Codex Security'nin bulguları sisteminizin gerçekte nasıl çalıştığına göre değerlendirmesine yardımcı olur:

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

Özel tarama talimatları ekleme

Taramayı güvenlik önceliklerinize odaklayan talimatlar ekleyin. Takip talimatları için ikinci bir dosya kullanın:

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

Takip işlemi, başarılı taramaların ve kapsamı eksik ya da hatalı taramaların ardından aynı kimliği doğrulanmış oturumda çalışır. Takip işlemi başarısız olursa CLI bir uyarı bildirir ve tamamlanmış taramayı korur. İptalden veya maliyet sınırına ulaşan bir taramadan sonra çalışmaz. Her iki seçenek de bulk-scan ile çalışır; CSV'deki bir prompt sütunu depoya özgü talimatlar ekler.

Tarama bütçesi belirleme

Tahmini model maliyeti USD cinsinden bir sınırı aştığında taramayı durdurmak için --max-cost kullanın:

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

Devam eden istekler sınırın biraz üzerinde tamamlanabilir. Derin bir tarama, Codex Security tamamlanan çalışan sonuçlarını birleştirdikten sonra sınıra ulaşırsa CLI tamamlanan raporu kaydeder, kapsamını partial olarak işaretler ve 2 çıkış kodunu döndürür. Tarama tamamlanmış bir rapor üretemezse mevcut tüm kısmi çıktılar diskte kalır.

Her commit'ten önce değişiklikleri tarama

Deponuz için bir Git pre-commit güvenlik denetimi yükleyin:

npx @openai/codex-security install-hook

Denetim, her commit'ten önce hazırlanmış ve hazırlanmamış değişiklikleri tarar. Mevcut bir pre-commit betiğini değiştirmeden yüksek önem dereceli bulguları ve tarama hatalarını engeller.

Depoları toplu olarak tarama

Depoları keşfetmeden önce GitHub'da oturum açın:

gh auth login

GitHub hesabınızdaki veya kuruluşunuzdaki depoları keşfedip seçin:

npx @openai/codex-security bulk-scan

Etkileşimli akış, arşivlenmiş depoları ve fork'ları hariç tutar. Taramadan önce seçilen depoları doğrulamanızı ister.

Hazırlanmış bir depo listesini taramak için bir CSV ve çıktı dizini sağlayın:

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

Mevcut bir toplu taramayı sürdürmek için aynı komutu yeniden çalıştırın. Codex Security tamamlanan depoları atlar. Geçici depo veya tarama hatalarını yeniden denemek istediğinizde --max-attempts 3 ekleyin.

GitHub keşfi, CSV hazırlığı, kampanya sonuçları ve Docker kurulumu için Toplu güvenlik taramaları çalıştırma bölümüne bakın.

Docker'da toplu taramalar çalıştırma

Erişiminiz Codex Security Docker görüntüsünü içeriyorsa sağlanan güçlendirilmiş Compose yapılandırmasını ve güvenlik profilini bir Linux Docker ana bilgisayarında kullanın. Ana bilgisayar ayrıcalıksız kullanıcı ad alanı oluşturmayı desteklemelidir. Bir depo CSV'si sağlayın, sonuçları ve oturum açma durumunu kalıcı bağlanan dizinlerde tutun ve kimlik bilgilerini ortamınız veya bir gizli bilgi yöneticisi üzerinden sağlayın:

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

Kapsayıcı, toplu taramaları etkileşimli istemler olmadan çalıştırır. Depoları etkileşimli olarak keşfetmek istediğinizde CLI'ı Docker dışında kullanın. Özel depolar için ortamınız veya gizli bilgi yöneticiniz üzerinden GH_TOKEN ya da GITHUB_TOKEN sağlayın. Hesap ve depo erişimi dahil olmak üzere oturum açma gereksinimleri, kapsayıcı ortamındaki taramalar için de geçerlidir.

Kaydedilmiş bir taramayı yeniden inceleme

Deponuz için kaydedilmiş taramaları listeleyin:

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

Bulgularını ve yapılandırmasını incelemek için sonuçlardan bir tarama kimliği kopyalayın:

npx @openai/codex-security scans show SCAN_ID

Bir taramanın ve çalışanlarının kaydedilmiş olaylarını incelemek için:

npx @openai/codex-security scans logs SCAN_ID

Kaydedilmiş günlükler sansürlenmez ve kaynak kodu veya kimlik bilgileri içerebilir. Paylaşmadan önce bunları inceleyin.

Deponun taramalarındaki açık bulguları listeleyin:

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

Son tarama doğrulamadığında önceki bir bulgu açık kalır.

İncelenmiş bir bulguyu yanlış pozitif olarak işaretlemek için bulgunun neden geçerli olmadığını açıklayın:

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

Sonraki taramalar bu açıklamayı dikkate alır ancak mevcut kodu yine de yeniden denetler.

Aynı taramayı özgün yapılandırmasını kullanarak mevcut checkout üzerinde çalıştırın:

npx @openai/codex-security scans rerun SCAN_ID

Yeni, devam eden, yeniden açılan, çözümlenen veya bilinmeyen bulguları belirlemek için iki taramayı karşılaştırın:

npx @openai/codex-security scans compare PREVIOUS_SCAN_ID CURRENT_SCAN_ID

Karşılaştırma, bulguları temel nedenlerine göre otomatik olarak eşleştirir ve kaydedilmiş eşleşmeleri yeniden kullanır.

Toplu tarama CSV biçimi, tarama geçmişi filtreleri ve komut seçenekleri için CLI başvurusuna bakın.

Hedefinize uygun iş akışıyla devam edin: