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 22 (22.13.0 veya sonrası), 24 ya da 26 ile çalışır. Tarama için ayrıca Python 3.10 veya sonrası 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 vermez.

Tarama çalıştırma

Yalnızca güvendiğiniz ve değerlendirme izniniz olan depoları tarayın. SDK, yerel işletim sistemi izinlerinizle çalışır ve onay için hiçbir zaman 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.

Tek bir CodexSecurity istemcisi oluşturun, standart bir depo taraması çalıştırın ve iş tamamlandığında istemciyi kapatın. Kapsayıcı Git çalışma ağacının dışında özel bir sonuç dizini seçmek için outputDir iletin.

outputDir değerini belirtmezseniz 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 uygun izinleri ve saklama politikalarını seçin.

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.coverage.completeness);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

run taramayı başlatır, tamamlanmasını bekler, mühürlenmiş yapıtları doğrular ve bir ScanResult döndürür. close yalıtılmış çalışma zamanını serbest bırakır ve yinelenen çağrıları destekler.

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 çalışma zamanına ve kimlik bilgilerine dokunmaz. Eklenti ve Python keşfini de taramanın kendisine bırakır. Bu sayede ön kontrol, uzun süren veya kimlik bilgisi kullanan bir işlemden önce kullanıcı girdisini denetlemek için kullanışlıdır.

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 çalışma ağacının 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 alır ve kesirli saatler dâhil 96 değerine kadar pozitif bir sayıyı kabul eder. Son tarihte Codex Security tamamlanmamış çalışanları durdurur, tamamlanmış tarama sonuçlarını korur ve bunları nihai raporda birleştirir. Süreyle sınırlandırılmış bir taramayı tam kapsam kanıtı olarak kabul etmeden önce result.coverage.completeness değerini 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 katı bir üst sınır değildir; bu nedenle devam eden istekler sınırın biraz üzerinde tamamlanabilir. Codex Security tamamlanmış çalışan sonuçlarını birleştirdikten sonra derin tarama sınıra ulaşırsa run, coverage.completeness değeri "partial" olarak ayarlanmış bir sonuç döndürür ve bütçe uyarısını onWarning üzerinden bildirir.

Tarama tamamlanmış bir kısmi sonuç üretemezse run, ScanCostLimitExceededError oluşturur ve kullanılabilir 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);
}

Kapsam eksiksizliği complete, partial veya unknown değeridir. Bir taramayı güvenlik kararı için kanıt olarak kullanmadan önce ertelenmiş yüzeyleri, hariç tutmaları ve açık soruları inceleyin.

result.toJSON(); bildirimi, depo ve mevcut tarama bulgularını, kapsamı, tarama ve iş parçacığı 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);

İptal bir istekten, iş denetleyicisinden veya zaman aşımından kaynaklanıyorsa bir AbortSignal iletin:

const controller = new AbortController();

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

  controller.abort();
  await scan;
} 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, sansürlenmemiş 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:

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

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 ekstra yüksek akıl yürütme çabasıyla gpt-5.6-sol kullanır. Farklı bir model veya akıl yürütme çabası 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:

Bir oturum açma tanıtıcısı; uygulamanın seçili oturum açma akışını sunup tamamlayabilmesi için waitForInstructions, authUrl, verificationUrl, userCode, wait ve cancel sağlar. SDK, dosya tabanlı bir Codex oturum açma işlemini yeniden kullanabilir. API key'ler CI ve sunucu tarafı otomasyonu 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.