Codex Security TypeScript SDK

Sử dụng Codex Security TypeScript SDK để chạy quét bảo mật trên các kho lưu trữ và thay đổi mã nguồn từ ứng dụng hoặc công cụ dành cho nhà phát triển của bạn. SDK trả về các phát hiện có kiểu, chi tiết phạm vi bao phủ và đường dẫn tới artifact quét. Đối với các lượt quét dài hơn, SDK hỗ trợ kiểm tra trước, giới hạn chi phí, callback tiến trình và hủy bỏ.

SDK sử dụng mô-đun ECMAScript (ESM) và chạy phía máy chủ với Node.js 22 (22.13.0 trở lên), 24 hoặc 26. Việc quét cũng yêu cầu Python 3.10 trở lên. Python 3.10 còn yêu cầu gói tomli.

Thiết lập SDK

Cài đặt SDK:

npm install @openai/codex-security

Trước khi bắt đầu quét, hãy đặt OPENAI_API_KEY hoặc CODEX_API_KEY, sử dụng một phiên đăng nhập Codex hiện có được lưu trong tệp hoặc cấu hình một nhà cung cấp khác. Amazon Bedrock sử dụng thông tin xác thực AWS; OpenRouter và Fireworks sử dụng API key cùng cấu hình riêng của nhà cung cấp.

Để có kết quả tốt nhất, hãy sử dụng tài khoản đã được xác minh cho Trusted Access for Cyber. Việc đăng nhập hoặc cung cấp API key không cấp Trusted Access.

Chạy một lượt quét

Chỉ quét các kho lưu trữ mà bạn tin cậy và được phép đánh giá. SDK chạy với quyền cục bộ của hệ điều hành và không bao giờ tạm dừng để xin phê duyệt. Quy trình quét có thể kế thừa môi trường của bạn, vì vậy hãy loại bỏ thông tin xác thực không liên quan trước khi bắt đầu. Xem Quyền quét cục bộ.

Tạo một client CodexSecurity, chạy một lượt quét kho lưu trữ tiêu chuẩn rồi đóng client khi công việc hoàn tất. Truyền outputDir để chọn một thư mục kết quả riêng tư nằm bên ngoài Git worktree bao quanh.

Nếu bỏ qua outputDir, Codex Security sẽ lưu kết quả trong thư mục trạng thái lâu dài của riêng mình. Kết quả có thể bao gồm trích đoạn mã nguồn và chi tiết lỗ hổng, vì vậy hãy chọn quyền và chính sách lưu giữ phù hợp.

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 bắt đầu lượt quét, chờ hoàn tất, xác thực các artifact đã niêm phong và trả về một ScanResult. close giải phóng runtime cô lập và hỗ trợ các lần gọi lặp lại.

Kiểm tra đầu vào bằng bước kiểm tra trước

Dùng preflight để kiểm tra kho lưu trữ, mục tiêu, chế độ, tài liệu cơ sở tri thức, vị trí đầu ra và cấu hình Codex trước khi bắt đầu quét:

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

Bước kiểm tra trước không tác động đến Codex runtime và thông tin xác thực. Bước này cũng dành việc phát hiện plugin và Python cho chính lượt quét. Nhờ đó, bước kiểm tra trước hữu ích để kiểm tra dữ liệu đầu vào của người dùng trước một thao tác kéo dài hoặc sử dụng thông tin xác thực.

Để xem trước việc lưu trữ cho một thư mục kết quả hiện có, hãy đặt archiveExisting: true:

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

console.log(plan.archiveDir);

archiveDir được trả về cho biết trước cách đặt tên bản lưu trữ. Đường dẫn cuối cùng có thể khác vì run tự tạo một đích duy nhất. Thu thập đường dẫn bản lưu trữ thực tế bằng onOutputArchived:

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

Lượt quét lưu trữ kết quả trước đó và bắt đầu với một thư mục đầu ra trống.

Chọn mục tiêu quét

SDK hỗ trợ các mục tiêu là kho lưu trữ, đường dẫn, phần thay đổi đã commit và cây làm việc. Mục tiêu mặc định là toàn bộ kho lưu trữ.

Quét các đường dẫn đã chọn

Truyền một mảng đường dẫn bên trong kho lưu trữ:

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

Đường dẫn có thể xác định tệp hoặc thư mục. SDK phân giải từng đường dẫn bên trong kho lưu trữ và loại bỏ mục trùng lặp.

Quét các thay đổi đã commit

Dùng DiffTarget.refs để quét các thay đổi đã commit giữa hai bản sửa đổi Git có sẵn cục bộ:

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

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

Head mặc định là HEAD. Mục tiêu phần thay đổi yêu cầu đối số kho lưu trữ là thư mục gốc của Git worktree.

Quét cây làm việc

Dùng DiffTarget.workingTree để quét các thay đổi đã stage và chưa stage so với một bản sửa đổi base:

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

Base mặc định là HEAD. Hãy tìm nạp các bản sửa đổi đã chọn trước khi bắt đầu quét phần thay đổi hoặc cây làm việc.

Chọn chế độ quét sâu

Đặt mode: "deep" cho một lượt quét kho lưu trữ hoặc đường dẫn cần xem xét rộng hơ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,
});

Chế độ quét sâu hỗ trợ mục tiêu kho lưu trữ và đường dẫn. Hãy dùng chế độ tiêu chuẩn cho lượt quét phần thay đổi và cây làm việc. Các cài đặt tùy chọn kiểm soát số worker quét tiêu chuẩn độc lập chạy đồng thời, số tác nhân phụ trên mỗi worker, số lượt quét worker hoàn tất liên tiếp mà không có phát hiện mới, cũng như tổng số lượng và thời lượng chạy của worker. Chúng yêu cầu mode: "deep".

maxTimeHours mặc định là 96 và chấp nhận một số dương không vượt quá 96, bao gồm số giờ dạng thập phân. Khi đến hạn, Codex Security dừng các worker chưa hoàn tất, giữ lại kết quả quét đã hoàn tất và tổng hợp chúng vào báo cáo cuối cùng. Hãy xem xét result.coverage.completeness trước khi coi một lượt quét bị giới hạn thời gian là bằng chứng về phạm vi bao phủ đầy đủ.

Thêm cơ sở tri thức bảo mật

Truyền tài liệu kiến trúc, mô hình mối đe dọa hoặc chính sách bảo mật qua knowledgeBasePaths:

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

SDK chấp nhận tệp hoặc thư mục và tìm kiếm đệ quy trong các thư mục. Các định dạng tài liệu được hỗ trợ là .md, .markdown, .txt, .pdf và .docx. SDK từ chối đường dẫn đầu vào là liên kết, bỏ qua các mục thư mục là liên kết và giữ nội dung tài liệu đã trích xuất bên ngoài kết quả quét đã lưu.

Thêm hướng dẫn quét và theo dõi

Dùng scanPrompt để định hướng lượt quét và postScanPrompt để yêu cầu một bước theo dõi:

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

Nếu bước theo dõi thất bại, SDK giữ lại lượt quét đã hoàn tất và báo cáo lỗi qua onWarning. SDK khôi phục mọi artifact quét đã hoàn tất mà bước theo dõi đã thay đổi.

Đặt ngân sách quét

Đặt maxCostUsd để dừng một lượt quét khi chi phí mô hình ước tính vượt quá giới hạn. Dùng onCost để theo dõi chi phí trong khi lượt quét đang chạy:

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

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

Giới hạn này ước tính mức chi tiêu nhưng không phải mức trần tuyệt đối, vì vậy các yêu cầu đang xử lý có thể hoàn tất với mức chi phí cao hơn một chút. Nếu lượt quét chuyên sâu đạt giới hạn sau khi Codex Security tổng hợp kết quả của các worker đã hoàn tất, run trả về một kết quả có coverage.completeness được đặt thành "partial" và báo cáo cảnh báo ngân sách qua onWarning.

Nếu lượt quét không thể tạo ra kết quả từng phần đã hoàn tất, run sẽ ném ScanCostLimitExceededError và lưu giữ mọi đầu ra hiện có.

Làm việc với kết quả quét

ScanResult cung cấp các tài liệu có cấu trúc, siêu dữ liệu quét và đường dẫn artifact:

Để yêu cầu cùng một plugin cho lượt quét sau, hãy truyền expectedPluginVersion: result.pluginVersion. SDK từ chối lượt quét nếu phiên bản plugin đã cài đặt khác đi.

Sử dụng trực tiếp các phát hiện có cấu trúc và dữ liệu phạm vi bao phủ:

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

Các phát hiện có thể bao gồm các trường tùy chọn codeEvidence, rootCause, validation, attackPath, remediationTests và preventiveControls.

Đối với các phát hiện trên toàn kho lưu trữ, confirmedInLatestScan phân biệt các phát hiện được thấy trong lượt quét mới nhất với những phát hiện trước đó vẫn còn mở:

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

Mức độ đầy đủ của phạm vi bao phủ là complete, partial hoặc unknown. Hãy xem xét các bề mặt bị hoãn, mục loại trừ và câu hỏi còn bỏ ngỏ trước khi dùng lượt quét làm bằng chứng cho một quyết định bảo mật.

result.toJSON() trả về manifest, các phát hiện của kho lưu trữ và lượt quét hiện tại, phạm vi bao phủ, mã định danh lượt quét và luồng, reportPath, artifactsDir, sarifPath, chi phí và siêu dữ liệu lượt trong một đối tượng sẵn sàng cho JSON.

Theo dõi hoặc hủy một lượt quét

Truyền các callback ScanOptions để báo cáo lúc bắt đầu quét, tiến trình worker và các lần thử kết nối lại:

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

Truyền một AbortSignal khi yêu cầu hủy đến từ một request, bộ điều khiển job hoặc thời gian chờ:

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

Một lượt quét bị gián đoạn có thể để lại đầu ra một phần trong scanDir. Hãy lưu giữ thư mục đó khi cần điều tra kết quả.

Các ứng dụng hiển thị tiến trình thiết lập quét cũng có thể dùng các callback vòng đời ScanOptions:

Trạng thái Trusted Access là granted, not_granted hoặc unknown. Quyền truy cập bị thiếu hoặc không xác định cũng kích hoạt onWarning.

onSessionEvent nhận các sự kiện chưa được che thông tin và có thể chứa mã nguồn hoặc thông tin xác thực. Hãy lọc chúng trước khi gửi tới nhật ký dùng chung hoặc dịch vụ khác.

Cấu hình runtime và thông tin xác thực

Truyền cấu hình runtime khi bạn cần một plugin, trình thông dịch hoặc cài đặt Codex cụ thể:

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 chấp nhận một thư mục plugin hoặc tệp ZIP. pythonPath chọn trình thông dịch plugin. codexOverrides hợp nhất các giá trị được hỗ trợ vào cấu hình Codex cô lập. Theo mặc định, các lượt quét sử dụng gpt-5.6-sol với mức nỗ lực suy luận extra-high. Đặt model và model_reasoning_effort trong codexOverrides để dùng mô hình hoặc mức nỗ lực suy luận khác. Để dùng Amazon Bedrock, hãy đặt model_provider và model trong codexOverrides.

codexOverrides không thể hạn chế quyền truy cập hệ thống tệp của lượt quét hoặc thay đổi chính sách phê duyệt. Xem Quyền quét cục bộ.

Đối với OpenRouter hoặc Fireworks, hãy cung cấp thêm API key tương ứng và cấu hình nhà cung cấp đầy đủ trong codexOverrides. Ví dụ, đặt OPENROUTER_API_KEY và cấu hình 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",
      },
    },
  },
});

Đối với Fireworks, hãy đổi cả hai khóa openrouter thành fireworks, đặt name thành Fireworks AI, đặt env_key thành FIREWORKS_API_KEY, dùng https://api.fireworks.ai/inference/v1 làm base_url và chọn một mô hình Fireworks.

Client cũng cung cấp các phương thức xác thực được hỗ trợ:

Một login handle cung cấp waitForInstructions, authUrl, verificationUrl, userCode, wait và cancel để ứng dụng có thể trình bày và hoàn tất luồng đăng nhập đã chọn. SDK có thể tái sử dụng một phiên đăng nhập Codex được lưu trong tệp. API key phù hợp với CI và hoạt động tự động hóa phía máy chủ.

Khi có cả API key và phiên đăng nhập đã lưu, SDK mặc định sử dụng API key. Để thay vào đó sử dụng phiên đăng nhập ChatGPT, hãy chọn phiên đó cho lượt quét:

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

Đặt auth: "api-key" để yêu cầu API key từ môi trường. preflight chấp nhận cùng tùy chọn auth.

Xử lý lỗi quét

Bắt lớp lỗi được xuất tương ứng với hành động mà ứng dụng của bạn có thể thực hiện:

Tiếp tục với hướng dẫn bắt đầu nhanh với CLI, hướng dẫn CI hoặc tài liệu tham chiếu CLI.