SDK TypeScript Codex Security

Gunakan SDK TypeScript Codex Security untuk menjalankan pemindaian keamanan pada repositori dan perubahan kode dari aplikasi atau alat pengembang Anda. SDK mengembalikan temuan bertipe, detail cakupan, dan path menuju artefak pemindaian. Untuk pemindaian yang lebih lama, SDK mendukung pemeriksaan preflight, batas biaya, callback progres, dan pembatalan.

SDK menggunakan modul ECMAScript (ESM) dan berjalan di sisi server dengan Node.js 22 atau yang lebih baru. Pemindaian juga memerlukan Python 3.10 atau yang lebih baru.

Siapkan SDK

Instal SDK:

npm install @openai/codex-security

Sebelum memulai pemindaian, tetapkan OPENAI_API_KEY atau CODEX_API_KEY, gunakan proses masuk Codex berbasis berkas yang sudah ada, atau konfigurasikan Amazon Bedrock dengan kredensial AWS dan penggantian model_provider serta model secara eksplisit.

Untuk hasil terbaik, gunakan akun yang diverifikasi untuk Trusted Access for Cyber. Masuk atau memberikan API key tidak memberikan Trusted Access.

Jalankan pemindaian

Buat satu klien CodexSecurity, jalankan pemindaian repositori standar, lalu tutup klien setelah pekerjaan selesai. Teruskan outputDir untuk memilih direktori hasil privat di luar worktree Git yang menaunginya.

Jika Anda menghilangkan outputDir, Codex Security menyimpan hasil dalam direktori status persistennya sendiri. Hasil dapat mencakup kutipan kode sumber dan detail kerentanan, jadi pilih izin dan kebijakan retensi yang sesuai.

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 memulai pemindaian, menunggu hingga selesai, memvalidasi artefak yang disegel, dan mengembalikan ScanResult. close membebaskan runtime terisolasi dan mendukung pemanggilan berulang.

Periksa input dengan preflight

Gunakan preflight untuk memeriksa repositori, target, mode, lokasi output, dan konfigurasi Codex sebelum memulai pemindaian:

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

Preflight tidak mengubah runtime dan kredensial Codex. Preflight juga menyerahkan penemuan plugin dan Python kepada proses pemindaian itu sendiri. Dengan demikian, preflight berguna untuk memeriksa input pengguna sebelum operasi yang berjalan lama atau menggunakan kredensial.

Untuk melihat pratinjau pengarsipan bagi direktori hasil yang sudah ada, tetapkan archiveExisting: true:

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

console.log(plan.archiveDir);

archiveDir yang dikembalikan menampilkan pratinjau penamaan arsip. Path akhir dapat berbeda karena run membuat tujuannya sendiri yang unik. Rekam path arsip yang sebenarnya dengan onOutputArchived:

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

Pemindaian mengarsipkan hasil sebelumnya dan memulai dengan direktori output kosong.

Pilih target pemindaian

SDK mendukung target repositori, path, committed-diff, dan working-tree. Target default adalah seluruh repositori.

Pindai path yang dipilih

Teruskan array path di dalam repositori:

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

Path dapat mengidentifikasi berkas atau direktori. SDK menyelesaikan setiap path di dalam repositori dan menghapus duplikat.

Pindai perubahan yang telah di-commit

Gunakan DiffTarget.refs untuk memindai perubahan yang telah di-commit di antara dua revisi Git yang tersedia secara lokal:

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

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

Head menggunakan HEAD secara default. Target diff mengharuskan argumen repositori berupa root worktree Git.

Pindai working tree

Gunakan DiffTarget.workingTree untuk memindai perubahan staged dan unstaged terhadap revisi base:

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

Base menggunakan HEAD secara default. Ambil revisi yang dipilih sebelum memulai pemindaian diff atau working-tree.

Pilih mode mendalam

Tetapkan mode: "deep" untuk pemindaian repositori atau path yang memerlukan peninjauan lebih luas:

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

Mode mendalam mendukung target repositori dan path. Gunakan mode standar untuk pemindaian diff dan working-tree.

Tambahkan basis pengetahuan keamanan

Teruskan dokumen arsitektur, model ancaman, atau kebijakan keamanan melalui knowledgeBasePaths:

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

SDK menerima berkas atau direktori dan menelusuri direktori secara rekursif. Format dokumen yang didukung adalah .md, .markdown, .txt, .pdf, dan .docx. SDK menolak path input tertaut, melewati entri direktori tertaut, dan menyimpan konten dokumen yang diekstrak di luar hasil pemindaian yang disimpan.

Tetapkan anggaran pemindaian

Tetapkan maxCostUsd untuk menghentikan pemindaian ketika perkiraan biaya modelnya melampaui batas. Gunakan onCost untuk melacak biaya selama pemindaian berjalan:

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

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

Batas tersebut merupakan perkiraan, bukan batas pengeluaran mutlak. Permintaan yang sudah berlangsung dapat selesai di atas batas tersebut. Jika pemindaian melampaui batas, SDK melempar ScanCostLimitExceededError dan mempertahankan hasil yang tersedia.

Gunakan hasil pemindaian

ScanResult mengekspos dokumen terstruktur, metadata pemindaian, dan path artefak:

Gunakan temuan dan cakupan terstruktur secara langsung:

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

Kelengkapan cakupan adalah complete, partial, atau unknown. Tinjau permukaan yang ditangguhkan, pengecualian, dan pertanyaan terbuka sebelum menggunakan pemindaian sebagai bukti untuk keputusan keamanan.

result.toJSON() mengembalikan manifes, temuan, cakupan, pengidentifikasi pemindaian dan thread, reportPath, artifactsDir, sarifPath, serta metadata giliran dalam satu objek yang siap digunakan sebagai JSON.

Lacak atau batalkan pemindaian

Teruskan callback ScanOptions untuk melaporkan permulaan pemindaian, progres worker, dan percobaan ulang koneksi:

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

Teruskan AbortSignal ketika pembatalan berasal dari permintaan, pengontrol job, atau timeout:

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

Pemindaian yang dihentikan dapat meninggalkan output parsial di scanDir. Pertahankan direktori tersebut ketika hasilnya perlu diselidiki.

Aplikasi yang menampilkan progres penyiapan pemindaian juga dapat menggunakan callback siklus hidup ScanOptions:

Konfigurasikan runtime dan kredensial

Teruskan konfigurasi runtime ketika Anda memerlukan plugin, interpreter, atau pengaturan Codex tertentu:

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 menerima direktori atau ZIP plugin. pythonPath memilih interpreter plugin. codexOverrides menggabungkan nilai yang didukung ke dalam konfigurasi Codex yang terisolasi. Secara default, pemindaian menggunakan gpt-5.6-sol dengan upaya penalaran extra-high. Tetapkan model dan model_reasoning_effort dalam codexOverrides untuk menggunakan model atau upaya penalaran yang berbeda. Untuk menggunakan Amazon Bedrock, tetapkan model_provider dan model dalam codexOverrides.

Klien juga mengekspos metode autentikasi yang didukung:

Handle login menyediakan waitForInstructions, authUrl, verificationUrl, userCode, wait, dan cancel agar aplikasi dapat menyajikan dan menyelesaikan alur masuk yang dipilih. SDK dapat menggunakan kembali proses masuk Codex berbasis berkas. API key cocok digunakan untuk CI dan otomatisasi sisi server.

Jika API key dan proses masuk tersimpan sama-sama tersedia, SDK menggunakan API key secara default. Untuk menggunakan proses masuk ChatGPT Anda, pilih proses tersebut untuk pemindaian:

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

Tetapkan auth: "api-key" untuk mewajibkan API key dari lingkungan. preflight menerima opsi auth yang sama.

Tangani kesalahan pemindaian

Tangkap kelas kesalahan yang diekspor dan sesuai dengan tindakan yang dapat dilakukan aplikasi Anda:

Lanjutkan dengan panduan mulai cepat CLI, panduan CI, atau referensi CLI.