Codex Security TypeScript SDK

Uygulamanızdan veya geliştirici aracınızdan depolarda ve kod değişikliklerinde güvenlik taramaları çalıştırmak için Codex Security TypeScript SDK'yı kullanın. SDK, türü belirlenmiş bulgular, kapsam ayrıntıları ve tarama yapıtlarının yollarını döndürür. Daha uzun taramalar için ön kontrol, maliyet sınırları, ilerleme geri çağrıları ve iptal desteği sunar.

SDK, ECMAScript modüllerini (ESM) kullanır ve sunucu tarafında Node.js 24 veya 26 ya da 22.13.0 sürümünden itibaren Node.js 22 ile çalışır. Tarama için ayrıca Python 3.10 veya üzeri gerekir. Python 3.10 için tomli paketi de gerekir.

SDK'yı kurma

SDK'yı yükleyin:

npm install @openai/codex-security

Bir tarama başlatmadan önce OPENAI_API_KEY veya CODEX_API_KEY ayarlayın, dosya tabanlı mevcut bir Codex oturum açma işlemini kullanın ya da başka bir sağlayıcı yapılandırın. Amazon Bedrock, AWS kimlik bilgilerini; OpenRouter ve Fireworks ise sağlayıcıya özgü API key'leri ve yapılandırmayı kullanır.

En iyi sonuçlar için Trusted Access for Cyber kapsamında doğrulanmış bir hesap kullanın. Oturum açmak veya API key sağlamak Trusted Access erişimi vermez.

Tarama çalıştırma

SDK, yerel işletim sistemi izinlerinizle çalışır ve onay almak için duraklamaz. Tarama süreçleri ortamınızı devralabilir; bu nedenle başlamadan önce ilgisiz kimlik bilgilerini kaldırın. Yerel tarama izinlerine bakın.

Bu örneği scan.mjs olarak kaydedin. Yolları değiştirin, standart bir depo taraması çalıştırın ve iş tamamlandığında istemciyi kapatın. İçinde bulunduğu Git worktree'sinin dışında özel bir sonuç dizini seçmek için outputDir parametresini iletin.

outputDir parametresini belirtmezseniz Codex Security, sonuçları kendi kalıcı durum dizinine kaydeder. Sonuçlar, kaynak kod alıntıları ve güvenlik açığı ayrıntıları içerebilir. Bunları kimlerin okuyabileceğini ve ne kadar süre saklanacaklarını belirleyin.

const security = new CodexSecurity();

try {
  const result = await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
  });

  console.log(result.reportPath);
  console.log(result.manifest.scan.status);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

Node.js ile çalıştırın:

node scan.mjs

Örnek, rapor yolunu, tarama durumunu ve bulgu sayısını yazdırır. Kanıtları incelemek için raporu açın. Sayı, depoya ve taramaya göre değişir; bu nedenle entegrasyonun çalışıp çalışmadığını kontrol etmek için beklenen bir sayı kullanmayın.

run, kaydedilen çıktı dosyalarını doğrular ve result.manifest.scan.status değeri "completed" olduğunda bir ScanResult döndürür. İncelenen alanlar, hariç tutulan öğeler ve ertelenen işler için result.coverage değerini kontrol edin. Tamamlanmış bir taramada yine de kapsam boşlukları olabilir. Çalışma zamanı, girdi veya sonuç bütünlüğü sorunları bir hata fırlatılmasına neden olabilir.

Sonraki örneklerde açık security istemcisini yeniden kullanın ve çalışma zamanını serbest bırakmak için close() çağrısını finally içinde tutun. Ek içe aktarma ifadelerini scan.mjs dosyasının başına ekleyin.

Girdileri ön kontrolle denetleme

Bir taramayı başlatmadan önce depo, hedef, mod, bilgi tabanı belgeleri, çıktı konumu ve Codex yapılandırmasını denetlemek için preflight kullanın:

const plan = await security.preflight("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
  knowledgeBasePaths: ["/path/to/architecture.md"],
  outputDir: "/path/outside/repository/results",
});

console.log(plan.repository);
console.log(plan.target.kind);
console.log(plan.mode);
console.log(plan.outputDir);

Ön kontrol, Codex'i başlatmadan, kimlik bilgilerini yüklemeden veya Python ve eklenti kullanılabilirliğini denetlemeden yerel girdileri kontrol eder. Başarılı bir ön kontrol, taramanın kimlik doğrulayabileceğini veya başlayabileceğini kanıtlamaz.

Mevcut bir sonuç dizininin arşivlenmesini önizlemek için archiveExisting: true değerini ayarlayın:

const plan = await security.preflight("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
});

console.log(plan.archiveDir);

Döndürülen archiveDir, arşiv adlandırmasını önizler. run kendi benzersiz hedefini oluşturduğundan nihai yol farklı olabilir. Gerçek arşiv yolunu onOutputArchived ile yakalayın:

await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  archiveExisting: true,
  onOutputArchived(archiveDir) {
    console.log("Archived results:", archiveDir);
  },
});

Tarama önceki sonuçları arşivler ve boş bir çıktı diziniyle başlar.

Tarama hedefi seçme

SDK; depo, yol, kaydedilmiş fark ve çalışma ağacı hedeflerini destekler. Varsayılan hedef deponun tamamıdır.

Seçili yolları tarama

Depo içindeki yolları içeren bir dizi iletin:

const result = await security.run("/path/to/repository", {
  target: ["services/billing", "packages/auth"],
});

Yollar dosyaları veya dizinleri belirtebilir. SDK her yolu depo içinde çözümler ve yinelenenleri kaldırır.

Kaydedilmiş değişiklikleri tarama

Yerel olarak kullanılabilen iki Git revizyonu arasındaki kaydedilmiş değişiklikleri taramak için DiffTarget.refs kullanın:

const target = DiffTarget.refs({
  base: "origin/main",
  head: "HEAD",
});

const result = await security.run("/path/to/repository", { target });

Head varsayılan olarak HEAD değerini alır. Fark hedefleri, depo bağımsız değişkeninin Git worktree kökü olmasını gerektirir.

Çalışma ağacını tarama

Hazırlanmış ve hazırlanmamış değişiklikleri bir base revizyonuna göre taramak için DiffTarget.workingTree kullanın:

const target = DiffTarget.workingTree({ base: "HEAD" });
const result = await security.run("/path/to/repository", { target });

Base varsayılan olarak HEAD değerini alır. Bir fark veya çalışma ağacı taraması başlatmadan önce seçili revizyonları getirin.

Derin modu seçme

Daha kapsamlı inceleme gerektiren bir depo veya yol taraması için mode: "deep" ayarlayın:

const result = await security.run("/path/to/repository", {
  target: ["services/billing"],
  mode: "deep",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
  maxTimeHours: 1.5,
});

Derin mod, depo ve yol hedeflerini destekler. Fark ve çalışma ağacı taramalarında standart modu kullanın. İsteğe bağlı ayarlar; eşzamanlı ve bağımsız standart tarama çalışanlarını, çalışan başına alt ajanları, yeni bulgu olmadan art arda tamamlanan çalışan taramalarını ve çalışan çalıştırmalarının toplam sayısı ile süresini denetler. Bunlar mode: "deep" gerektirir.

maxTimeHours varsayılan olarak 96 değerini kullanır ve 96 değerine kadar pozitif sayıları, kesirli saatler dahil kabul eder. Süre dolduğunda Codex Security, tamamlanmamış çalışanları durdurur, tamamlanan tarama sonuçlarını korur ve bunları nihai raporda birleştirir. Ertelenen işler ve açık sorular için result.coverage içeriğini inceleyin.

Güvenlik bilgi tabanı ekleme

Mimari belgeleri, tehdit modellerini veya güvenlik politikalarını knowledgeBasePaths üzerinden iletin:

const result = await security.run("/path/to/repository", {
  knowledgeBasePaths: [
    "/path/to/architecture.md",
    "/path/to/security-policies",
  ],
});

SDK dosyaları veya dizinleri kabul eder ve dizinleri özyinelemeli olarak arar. Desteklenen belge biçimleri .md, .markdown, .txt, .pdf ve .docx biçimleridir. SDK, bağlantılı giriş yollarını reddeder, bağlantılı dizin girdilerini atlar ve ayıklanan belge içeriğini kaydedilmiş tarama sonuçlarının dışında tutar.

Tarama ve takip talimatları ekleme

Taramaya odak kazandırmak için scanPrompt, bir takip istemek için postScanPrompt kullanın:

const result = await security.run("/path/to/repository", {
  scanPrompt: "Focus on tenant isolation and authorization checks.",
  postScanPrompt: "Write confirmed findings to post-scan-summary.md.",
});

Takip başarısız olursa SDK tamamlanmış taramayı korur ve hatayı onWarning üzerinden bildirir. Takibin değiştirdiği tamamlanmış tarama yapıtlarını geri yükler.

Tarama bütçesi belirleme

Tahmini model maliyeti bir sınırı aştığında taramayı durdurmak için maxCostUsd ayarlayın. Tarama sürerken maliyeti izlemek için onCost kullanın:

const result = await security.run("/path/to/repository", {
  maxCostUsd: 5,
  onCost(cost) {
    console.log(cost.estimatedUsd);
  },
});

console.log(result.cost?.estimatedUsd);

Sınır, harcamayı tahmin eder ancak kesin bir üst sınır değildir; bu nedenle devam eden istekler tamamlandığında sınır biraz aşılabilir. Derin tarama, Codex Security tamamlanan çalışan sonuçlarını birleştirdikten sonra sınıra ulaşırsa run, bir sonuç döndürüp manifest.scan.status alanını "completed" olarak ayarlayabilir ve bütçe uyarısını onWarning üzerinden bildirebilir. Tamamlanmamış işler için result.coverage içeriğini kontrol edin.

Tarama, geçerli ve tamamlanmış bir sonuç üretemezse run, ScanCostLimitExceededError hatasını fırlatır ve mevcut tüm çıktıları korur.

Tarama sonuçlarıyla çalışma

ScanResult; yapılandırılmış belgeleri, tarama meta verilerini ve yapıt yollarını sunar:

Sonraki bir taramada aynı eklentiyi zorunlu kılmak için expectedPluginVersion: result.pluginVersion iletin. Yüklü eklenti sürümü farklıysa SDK taramayı reddeder.

Yapılandırılmış bulguları ve kapsamı doğrudan kullanın:

for (const finding of result.findings.findings) {
  const location = finding.locations[0];
  if (location === undefined) continue;

  console.log(
    finding.severity.level,
    `${location.path}:${location.startLine}`,
    finding.title
  );
}

for (const deferred of result.coverage.deferred) {
  console.log(deferred.id, deferred.reason);
}

Bulgular isteğe bağlı codeEvidence, rootCause, validation, attackPath, remediationTests ve preventiveControls alanlarını içerebilir.

Depo genelindeki bulgular için confirmedInLatestScan, en son taramada görülen bulguları açık kalmaya devam eden önceki bulgulardan ayırır:

for (const finding of result.repositoryFindings ?? []) {
  console.log(finding.title, finding.confirmedInLatestScan);
}

Yeni sonuçlar coverage.completeness içermez. Yürütme durumu için manifest.scan.status kullanın ve taramanın neleri incelediğini anlamak için ertelenen alanları, hariç tutulanları ve açık soruları coverage içinde inceleyin.

result.toJSON(); bildirimi, depo ve mevcut tarama bulgularını, kapsamı, tarama ve thread tanımlayıcılarını, reportPath, artifactsDir, sarifPath, maliyet ve tur meta verilerini JSON'a hazır tek bir nesnede döndürür.

Taramayı izleme veya iptal etme

Taramanın başlatılmasını, çalışan ilerlemesini ve bağlantı yeniden denemelerini bildirmek için ScanOptions geri çağrılarını iletin:

const result = await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  onScanStarted() {
    console.log("Scan started");
  },
  onProgress(progress) {
    console.log(progress.phase, progress.filesCompleted, progress.filesTotal);
  },
  onWorkerStatus(status) {
    console.log(status.kind, status);
  },
  onSessionEvent(session) {
    console.log(session.threadId, session.worker, session.event["type"]);
  },
  onReconnect(attempt, maxAttempts) {
    console.log(`Reconnect attempt ${attempt} of ${maxAttempts}`);
  },
  onObserverError(observer, error) {
    console.error(`${observer} failed`, error);
  },
});

console.log(result.reportPath);

Bir taramayı iptal etmek için istek veya iş denetleyicinizden bir AbortSignal iletin. Tarama 30 dakika sonra hâlâ çalışıyorsa bu örnek taramayı kesintiye uğratır ve kaydedilmiş çıktıları içeren dizini yazdırır:

try {
  await security.run("/path/to/repository", {
    outputDir: "/path/outside/repository/results",
    signal: AbortSignal.timeout(30 * 60 * 1000),
  });
} catch (error) {
  if (error instanceof ScanInterruptedError) {
    console.error(error.scanDir);
  } else {
    throw error;
  }
}

Kesintiye uğrayan bir tarama scanDir içinde kısmi çıktı bırakabilir. Sonucun incelenmesi gerekiyorsa bu dizini koruyun.

Tarama kurulum ilerlemesini gösteren uygulamalar, ScanOptions yaşam döngüsü geri çağrılarını da kullanabilir:

Trusted Access durumu granted, not_granted veya unknown değeridir. Eksik veya bilinmeyen erişim de onWarning tetikler.

onSessionEvent, hassas bilgileri gizlenmemiş ve kaynak kodu veya kimlik bilgileri içerebilen olayları alır. Bunları paylaşılan günlüklere veya diğer hizmetlere göndermeden önce filtreleyin.

Çalışma zamanını ve kimlik bilgilerini yapılandırma

Belirli bir eklentiye, yorumlayıcıya veya Codex ayarına ihtiyacınız olduğunda çalışma zamanı yapılandırmasını iletin. Kimlik bilgilerinizle erişebildiğiniz bir model seçin. ChatGPT ile oturum açıyorsanız bu örneği kullanmadan önce GPT-6.1 Sol kullanılabilirliğini kontrol edin:

const security = new CodexSecurity({
  pluginPath: "/path/to/codex-security-plugin",
  pythonPath: "/path/to/python",
  codexOverrides: {
    model: "gpt-6.1-sol",
    model_reasoning_effort: "medium",
  },
});

pluginPath bir eklenti dizinini veya ZIP dosyasını kabul eder. pythonPath eklenti yorumlayıcısını seçer. codexOverrides, desteklenen değerleri yalıtılmış Codex yapılandırmasıyla birleştirir. Taramalar varsayılan olarak çok yüksek akıl yürütme düzeyiyle gpt-5.6-sol kullanır. Farklı bir model veya akıl yürütme düzeyi kullanmak için codexOverrides içinde model ve model_reasoning_effort ayarlayın. Amazon Bedrock kullanmak için codexOverrides içinde model_provider ve model ayarlayın.

codexOverrides, taramanın dosya sistemi erişimini kısıtlayamaz veya onay politikasını değiştiremez. Yerel tarama izinleri bölümüne bakın.

OpenRouter veya Fireworks için eşleşen API key'i ve eksiksiz bir sağlayıcı yapılandırmasını codexOverrides içinde de sağlayın. Örneğin OPENROUTER_API_KEY ayarlayın ve OpenRouter'ı yapılandırın:

const security = new CodexSecurity({
  codexOverrides: {
    model: "anthropic/claude-sonnet-4.5",
    model_provider: "openrouter",
    model_providers: {
      openrouter: {
        name: "OpenRouter",
        base_url: "https://openrouter.ai/api/v1",
        env_key: "OPENROUTER_API_KEY",
        wire_api: "responses",
      },
    },
  },
});

Fireworks için her iki openrouter anahtarını fireworks olarak değiştirin, name değerini Fireworks AI olarak, env_key değerini FIREWORKS_API_KEY olarak ayarlayın, https://api.fireworks.ai/inference/v1 değerini base_url olarak kullanın ve bir Fireworks modeli seçin.

İstemci, desteklenen kimlik doğrulama yöntemlerini de sunar:

Oturum açma tanıtıcısı waitForInstructions, authUrl, verificationUrl, userCode, wait ve cancel sağlar; böylece bir uygulama seçilen oturum açma akışını sunabilir ve tamamlayabilir. SDK, dosyada saklanan bir Codex oturumunu yeniden kullanabilir. API key kullanımı, CI ve sunucu tarafı otomasyon için uygundur.

Hem bir API key hem de saklanan bir oturum açma işlemi varsa SDK varsayılan olarak API key'i kullanır. Bunun yerine ChatGPT oturumunuzu kullanmak için tarama kapsamında bunu seçin:

const result = await security.run("/path/to/repository", {
  auth: "chatgpt",
});

Bir ortam API key'ini zorunlu kılmak için auth: "api-key" ayarlayın. preflight aynı auth seçeneğini kabul eder.

Tarama hatalarını işleme

Uygulamanızın gerçekleştirebileceği eylemle eşleşen dışa aktarılmış hata sınıfını yakalayın:

CLI hızlı başlangıç kılavuzu, CI kılavuzu veya CLI referansı ile devam edin.