Codex Security TypeScript SDK

Sử dụng Codex Security TypeScript SDK để chạy các lượt quét bảo mật trên kho lưu trữ và các thay đổi mã 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 đã định kiểu, thông tin chi tiết về phạm vi bao phủ và đường dẫn đến artifact quét. Đối với các lượt quét dài hơn, SDK hỗ trợ kiểm tra preflight, giới hạn chi phí, callback tiến trình và hủy bỏ.

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

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 Amazon Bedrock bằng thông tin xác thực AWS và các giá trị ghi đè model_provider và model rõ ràng.

Để 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

Tạo một client CodexSecurity, chạy lượt quét kho lưu trữ tiêu chuẩn và đó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ư bên ngoài Git worktree bao quanh.

Nếu bạn 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 đoạn trích mã nguồn và chi tiết về 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 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 môi trường chạy cô lập và hỗ trợ các lần gọi lặp lại.

Kiểm tra đầu vào bằng preflight

Sử dụng preflight để kiểm tra kho lưu trữ, mục tiêu, chế độ, 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"],
  outputDir: "/path/outside/repository/results",
});

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

Preflight không thay đổi môi trường chạy Codex và thông tin xác thực. Nó cũng để việc phát hiện plugin và Python cho chính quá trình quét thực hiện. Điều này khiến preflight hữu ích để kiểm tra đầu vào của người dùng trước một thao tác kéo dài hoặc cần thông tin xác thực.

Để xem trước việc lưu trữ đối với 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ạo đích duy nhất của riêng nó. Ghi lại đườ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);
  },
});

Quá trình quét lưu trữ các 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ợ mục tiêu là kho lưu trữ, đường dẫn, diff đã 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ỏ các mục trùng lặp.

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

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

Phần đầu mặc định là HEAD. Mục tiêu diff 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

Sử 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 gốc:

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

Phần gốc mặc định là HEAD. Hãy tải các bản sửa đổi đã chọn trước khi bắt đầu quét diff hoặc cây làm việc.

Chọn chế độ chuyên 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",
});

Chế độ chuyên sâu hỗ trợ mục tiêu là kho lưu trữ và đường dẫn. Sử dụng chế độ tiêu chuẩn cho các lượt quét diff và cây làm việc.

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 thông 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 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 các đườ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.

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

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

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 là một ước tính, không phải mức trần chi tiêu tuyệt đối. Các yêu cầu đang được xử lý có thể hoàn tất với chi phí cao hơn. Nếu lượt quét vượt giới hạn, SDK sẽ ném ScanCostLimitExceededError và lưu giữ các kết quả 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:

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

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

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

result.toJSON() trả về manifest, các phát hiện, phạm vi bao phủ, mã định danh lượt quét và luồng, reportPath, artifactsDir, sarifPath cùng 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 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");
  },
  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);

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ể sử dụng các callback vòng đời ScanOptions:

Cấu hình môi trường chạy và thông tin xác thực

Truyền cấu hình môi trường chạy khi bạn cần một plugin, trình thông dịch hoặc thiết lập 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 cực cao. Đặt model và model_reasoning_effort trong codexOverrides để sử dụng một mô hình hoặc mức nỗ lực suy luận khác. Để sử dụng Amazon Bedrock, hãy đặt model_provider và model trong codexOverrides.

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 cho CI và tự động hóa phía máy chủ.

Khi cả API key lẫn phiên đăng nhập đã lưu đều có sẵn, SDK mặc định sử dụng API key. Để sử dụng phiên đăng nhập ChatGPT của bạn, 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" để bắt buộc dùng 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ề CLI, hướng dẫn CI hoặc tài liệu tham chiếu CLI.