Codex Security TypeScript SDK

Gunakan Codex Security TypeScript SDK 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 (22.13.0 atau yang lebih baru), 24, atau 26. Pemindaian juga memerlukan Python 3.10 atau yang lebih baru. Python 3.10 juga memerlukan paket tomli.

Menyiapkan SDK

Instal SDK:

npm install @openai/codex-security

Sebelum memulai pemindaian, tetapkan OPENAI_API_KEY atau CODEX_API_KEY, gunakan login Codex berbasis file yang sudah ada, atau konfigurasikan penyedia lain. Amazon Bedrock menggunakan kredensial AWS; OpenRouter dan Fireworks menggunakan API key serta konfigurasi khusus penyedia.

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

Menjalankan pemindaian

Pindai hanya repositori yang Anda percayai dan boleh Anda nilai. SDK berjalan dengan izin sistem operasi lokal Anda dan tidak pernah berhenti untuk meminta persetujuan. Proses pemindaian dapat mewarisi lingkungan Anda, jadi hapus kredensial yang tidak terkait sebelum memulai. Lihat Izin pemindaian lokal.

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 tersegel, dan mengembalikan ScanResult. close melepaskan runtime terisolasi dan mendukung pemanggilan berulang.

Memeriksa input dengan preflight

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

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

Preflight tidak mengubah runtime Codex maupun kredensial. Preflight juga menyerahkan penemuan plugin dan Python kepada pemindaian itu sendiri. Hal ini membuat 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 menghasilkan tujuannya sendiri yang unik. Rekam path arsip aktual 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.

Memilih target pemindaian

SDK mendukung target repositori, path, diff yang telah di-commit, dan working tree. Target default adalah seluruh repositori.

Memindai 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 file atau direktori. SDK me-resolve setiap path di dalam repositori dan menghapus duplikat.

Memindai 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 secara default adalah HEAD. Target diff mengharuskan argumen repositori berupa root worktree Git.

Memindai 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 secara default adalah HEAD. Ambil revisi yang dipilih sebelum memulai pemindaian diff atau working tree.

Memilih 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",
  workers: 2,
  subagents: 0,
  stopAfterNoNew: 3,
  maxDiscoveryRuns: 10,
  maxTimeHours: 1.5,
});

Mode mendalam mendukung target repositori dan path. Gunakan mode standar untuk pemindaian diff dan working tree. Pengaturan opsional mengontrol worker pemindaian standar independen yang berjalan bersamaan, subagen per worker, jumlah pemindaian worker selesai berturut-turut tanpa temuan baru, serta jumlah total dan durasi proses worker. Pengaturan tersebut memerlukan mode: "deep".

maxTimeHours secara default adalah 96 dan menerima angka positif hingga 96, termasuk pecahan jam. Saat tenggat tercapai, Codex Security menghentikan worker yang belum selesai, mempertahankan hasil pemindaian yang telah selesai, dan mengagregasikannya ke dalam laporan akhir. Tinjau result.coverage.completeness sebelum menganggap pemindaian dengan batas waktu sebagai bukti cakupan penuh.

Menambahkan 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 file 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 tersimpan.

Menambahkan instruksi pemindaian dan tindak lanjut

Gunakan scanPrompt untuk memfokuskan pemindaian dan postScanPrompt untuk meminta tindak lanjut:

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.",
});

Jika tindak lanjut gagal, SDK mempertahankan pemindaian yang telah selesai dan melaporkan kesalahan melalui onWarning. SDK memulihkan setiap artefak pemindaian selesai yang diubah oleh tindak lanjut.

Menetapkan 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 memperkirakan pengeluaran, tetapi bukan batas mutlak, sehingga permintaan yang sudah berjalan dapat selesai sedikit di atasnya. Jika pemindaian mendalam mencapai batas setelah Codex Security mengagregasikan hasil worker yang selesai, run mengembalikan hasil dengan coverage.completeness ditetapkan ke "partial" dan melaporkan peringatan anggaran melalui onWarning.

Jika pemindaian tidak dapat menghasilkan hasil parsial yang selesai, run melempar ScanCostLimitExceededError dan mempertahankan semua output yang tersedia.

Menggunakan hasil pemindaian

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

Untuk mewajibkan plugin yang sama bagi pemindaian berikutnya, teruskan expectedPluginVersion: result.pluginVersion. SDK menolak pemindaian jika versi plugin yang terinstal berbeda.

Gunakan temuan terstruktur dan cakupan 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);
}

Temuan dapat menyertakan bidang opsional codeEvidence, rootCause, validation, attackPath, remediationTests, dan preventiveControls.

Untuk temuan di seluruh repositori, confirmedInLatestScan membedakan temuan yang terlihat dalam pemindaian terbaru dari temuan sebelumnya yang masih terbuka:

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

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 repositori dan pemindaian saat ini, cakupan, pengidentifikasi pemindaian dan thread, reportPath, artifactsDir, sarifPath, biaya, serta metadata giliran dalam satu objek yang siap untuk JSON.

Melacak atau membatalkan pemindaian

Teruskan callback ScanOptions untuk melaporkan dimulainya 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");
  },
  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);

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

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 diinterupsi dapat meninggalkan output parsial di scanDir. Pertahankan direktori tersebut jika hasilnya perlu diselidiki.

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

Status Trusted Access adalah granted, not_granted, atau unknown. Akses yang tidak ada atau tidak diketahui juga memicu onWarning.

onSessionEvent menerima peristiwa yang tidak disunting dan dapat berisi kode sumber atau kredensial. Filter peristiwa tersebut sebelum mengirimkannya ke log bersama atau layanan lain.

Mengonfigurasi runtime dan kredensial

Teruskan konfigurasi runtime saat 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 plugin atau ZIP. pythonPath memilih interpreter plugin. codexOverrides menggabungkan nilai yang didukung ke dalam konfigurasi Codex 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.

codexOverrides tidak dapat membatasi akses sistem file pemindaian atau mengubah kebijakan persetujuannya. Lihat Izin pemindaian lokal.

Untuk OpenRouter atau Fireworks, berikan juga API key yang sesuai dan konfigurasi penyedia lengkap dalam codexOverrides. Misalnya, tetapkan OPENROUTER_API_KEY dan konfigurasikan OpenRouter:

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

Untuk Fireworks, ubah kedua key openrouter menjadi fireworks, tetapkan name ke Fireworks AI, tetapkan env_key ke FIREWORKS_API_KEY, gunakan https://api.fireworks.ai/inference/v1 sebagai base_url, dan pilih model Fireworks.

Klien juga mengekspos metode autentikasi yang didukung:

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

Jika API key dan login tersimpan sama-sama tersedia, SDK menggunakan API key secara default. Untuk menggunakan login ChatGPT Anda, pilih login 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.

Menangani 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.