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 denetimleri, maliyet sınırlarını, ilerleme geri çağırmalarını ve iptali destekler.

SDK, ECMAScript modüllerini (ESM) kullanır ve Node.js 22 veya üzeriyle sunucu tarafında çalışır. Tarama için ayrıca Python 3.10 veya üzeri gerekir.

SDK'yı ayarlama

SDK'yı yükleyin:

npm install @openai/codex-security

Bir tarama başlatmadan önce OPENAI_API_KEY veya CODEX_API_KEY ayarlayın, dosya destekli mevcut bir Codex oturumu kullanın ya da AWS kimlik bilgileriyle ve açık model_provider ile model geçersiz kılmalarıyla Amazon Bedrock'ı yapılandırın.

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

Tek bir CodexSecurity istemcisi oluşturun, standart bir depo taraması çalıştırın ve iş tamamlandığında istemciyi kapatın. Kapsayan Git worktree'nin 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 denetimle kontrol etme

Taramayı başlatmadan önce bir depoyu, hedefi, modu, çıktı konumunu ve Codex yapılandırmasını kontrol etmek için preflight kullanın:

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

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

Ön denetim, Codex çalışma zamanına ve kimlik bilgilerine dokunmaz. Eklenti ve Python keşfini de taramanın kendisine bırakır. Bu sayede ön denetim, uzun süren veya kimlik bilgisi gerektiren bir işlemden önce kullanıcı girdisini kontrol etmek için kullanışlıdır.

Mevcut bir sonuç dizininin arşivlenmesini önizlemek için archiveExisting: true 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 son 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, commit edilmiş fark ve çalışma ağacı hedeflerini destekler. Varsayılan hedef deponun tamamıdır.

Seçili yolları tarama

Depo içindeki yolları bir dizi olarak 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.

Commit edilmiş değişiklikleri tarama

Yerel olarak kullanılabilen iki Git revizyonu arasındaki commit edilmiş 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

Bir base revizyona göre staged ve unstaged değişiklikleri 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. Fark veya çalışma ağacı taraması başlatmadan önce seçili revizyonları fetch edin.

Derin modu seçme

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

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

Derin mod, depo ve yol hedeflerini destekler. Fark ve çalışma ağacı taramaları için standart modu kullanın.

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ı girdi 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 bütçesi belirleme

Tahmini model maliyeti bir sınırı aştığında taramayı durdurmak için maxCostUsd ayarlayın. Tarama çalışırken 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 bir tahmindir, kesin bir harcama üst sınırı değildir. Devam eden istekler sınırın üzerinde tamamlanabilir. Tarama sınırı aşarsa SDK ScanCostLimitExceededError fırlatır ve mevcut sonuçları korur.

Tarama sonuçlarıyla çalışma

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

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);
}

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

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

Taramayı izleme veya iptal etme

Taramanın başlamasını, çalışan ilerlemesini ve bağlantı yeniden denemelerini bildirmek için ScanOptions geri çağırmalarını iletin:

const result = await security.run("/path/to/repository", {
  outputDir: "/path/outside/repository/results",
  onScanStarted() {
    console.log("Scan started");
  },
  onWorkerStatus(status) {
    console.log(status.kind, status);
  },
  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 kaynaklandığında 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;
  }
}

Yarıda kesilen bir tarama, scanDir içinde kısmi çıktı bırakabilir. Sonucun incelenmesi gerektiğinde bu dizini koruyun.

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

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

Belirli bir eklentiye, yorumlayıcıya veya Codex ayarına ihtiyaç duyduğunuzda ç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'i 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 extra-high 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.

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

Bir oturum açma tanıtıcısı waitForInstructions, authUrl, verificationUrl, userCode, wait ve cancel sağlar; böylece uygulama seçili oturum açma akışını sunup tamamlayabilir. SDK, dosya destekli bir Codex oturumunu yeniden kullanabilir. API key'ler CI ve sunucu tarafı otomasyonu için uygundur.

Hem API key hem de saklanmış bir oturum mevcut olduğunda SDK varsayılan olarak API key'i kullanır. Bunun yerine ChatGPT oturumunuzu kullanmak için taramada onu seçin:

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

Ortam API key'i gerektirmek 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 eyleme karşılık gelen 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.