Codex Security TypeScript SDK

Codex Security TypeScript SDK を使うと、アプリケーションや開発ツールからリポジトリやコードの変更を対象にセキュリティスキャンを実行できます。SDK は、型情報を持つ検出結果、スキャンのマニフェスト、保存したレポートのパスを返します。

SDK は ECMAScript モジュール（ESM）を使用し、サーバー側で動作します。対応バージョンは Node.js 24、26、および 22 系の 22.13.0 以降です。スキャンには Python 3.10 以降も必要です。Python 3.10 を使う場合は、さらに tomli パッケージが必要です。

圧縮された Codex セッション（.jsonl.zst）を読み込むか再開するには、Node.js 22 系の 22.15.0 以降、または Node.js 24、26 を使用してください。非圧縮の .jsonl セッションは、サポート対象のすべての Node.js バージョンで利用できます。

SDK のセットアップ

SDK をインストールします。

npm install @openai/codex-security

スキャンを開始する前に、OPENAI_API_KEY または CODEX_API_KEY を設定するか、ファイルに保存済みの Codex サインイン情報を使用するか、別のプロバイダーを設定してください。Amazon Bedrock は AWS の認証情報を使用します。OpenRouter と Fireworks は、それぞれのプロバイダー専用の API キーと設定を使用します。

サイバーセキュリティに関する一部のリクエストや、保護された検出結果へのアクセスには、ChatGPT アカウントまたは API 組織で Trusted Access for Cyber を取得する必要があります。

スキャンの実行

SDK はローカル OS 上のユーザー権限で動作し、承認待ちで一時停止することはありません。スキャンプロセスは環境変数を引き継ぐことがあるため、開始前に無関係な認証情報を環境から取り除いてください。ローカルスキャンの権限を参照してください。

次の例を scan.mjs として保存し、リポジトリのパスと結果ディレクトリのパスをこの順にコマンドライン引数で渡します。標準のリポジトリスキャンを実行し、処理が完了したらクライアントを閉じます。outputDir には、対象を含む Git Worktree の外にある非公開の結果ディレクトリを指定してください。

outputDir を省略すると、Codex Security は自身の状態を永続化するディレクトリに結果を保存します。結果にはソースコードの抜粋や脆弱性の詳細が含まれることがあります。閲覧権限と保存期間を設定してください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19import { CodexSecurity } from "@openai/codex-security";

const [repository, outputDir] = process.argv.slice(2);
if (!repository || !outputDir) {
  throw new Error("Usage: node scan.mjs <repository> <results-directory>");
}
const security = new CodexSecurity();

try {
  const result = await security.run(repository, {
    outputDir,
  });

  console.log(result.reportPath);
  console.log(result.manifest.scan.status);
  console.log(result.findings.findings.length);
} finally {
  await security.close();
}

Node.js で実行します。

node scan.mjs /path/to/repository /path/outside/repository/results

この例では、レポートのパス、スキャンのステータス、検出件数が出力されます。レポートを開いて検出の根拠を確認してください。

run は保存された成果物を検証し、ScanResult を返します。結果が返るのは result.manifest.scan.status が "completed" の場合です。指定した対象は result.manifest.scan.scope で、警告の有無と内容は result.manifest.scan.warnings で確認できます。完了ステータスだけでは、どのファイルがレビューされたかは分かりません。ランタイムや入力に問題がある場合や、結果の整合性を確認できない場合は、エラーがスローされることがあります。

以降の例では、開いた状態の security クライアントを再利用します。ランタイムを解放できるように、close() は finally 内で呼び出してください。追加のインポートは scan.mjs の先頭に記述します。

プリフライトによる入力の確認

preflight を使うと、スキャンを開始する前に、リポジトリ、対象、モード、ナレッジベースのドキュメント、出力先、Codex の設定を確認できます。次の例では、リポジトリのルートにある security.md を読み込みます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { join } from "node:path";

const knowledgeBase = join(repository, "security.md");

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

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

プリフライトではローカルの入力を確認します。Codex の起動、認証情報の読み込み、Python やプラグインが利用可能かどうかの確認は行いません。プリフライトが成功しても、スキャンの認証や起動が成功するとは限りません。

既存の結果ディレクトリのアーカイブ先をプレビューするには、archiveExisting: true を設定します。

1
2
3
4
5
6const plan = await security.preflight(repository, {
  outputDir: outputDir,
  archiveExisting: true,
});

console.log(plan.archiveDir);

返される archiveDir で、アーカイブ先にどのような名前が付くかを確認できます。run は実行時に一意の保存先を生成するため、最終的なパスは異なる場合があります。実際のアーカイブ先は onOutputArchived で取得できます。

1
2
3
4
5
6
7
8
9
10
11try {
  await security.run(repository, {
    outputDir: outputDir,
    archiveExisting: true,
    onOutputArchived(archiveDir) {
      console.log("Archived results:", archiveDir);
    },
  });
} finally {
  await security.close();
}

以前の結果がアーカイブされ、出力ディレクトリが空の状態でスキャンが始まります。

スキャン対象の選択

SDK は、リポジトリ、指定したパス、コミット間の差分、作業ツリーを対象にスキャンできます。デフォルトの対象はリポジトリ全体です。

指定したパスのスキャン

リポジトリ内のパスを配列で渡します。

1
2
3
4
5
6
7try {
  const result = await security.run(repository, {
    target: ["services/billing", "packages/auth"],
  });
} finally {
  await security.close();
}

パスにはファイルまたはディレクトリを指定できます。SDK はリポジトリ内で各パスを解決し、重複を取り除きます。

コミット済みの変更のスキャン

DiffTarget.refs を使うと、ローカルで利用できる 2 つの Git リビジョン間のコミット済みの変更をスキャンできます。

1
2
3
4
5
6
7
8
9
10
11
12import { DiffTarget } from "@openai/codex-security";

const target = DiffTarget.refs({
  base: "HEAD~1",
  head: "HEAD",
});

try {
  const result = await security.run(repository, { target });
} finally {
  await security.close();
}

比較先のデフォルトは HEAD です。リポジトリには Git Worktree のルートを渡し、スキャン前に比較先のリビジョンをチェックアウトしてください。

作業ツリーのスキャン

DiffTarget.workingTree を使うと、ステージ済みの変更と未ステージの変更をベースリビジョンと比較してスキャンできます。

1
2
3
4
5
6
7import { DiffTarget } from "@openai/codex-security";
const target = DiffTarget.workingTree({ base: "HEAD" });
try {
  const result = await security.run(repository, { target });
} finally {
  await security.close();
}

ベースリビジョンのデフォルトは HEAD です。差分または作業ツリーのスキャンを開始する前に、選択したリビジョンをフェッチしてください。

詳細モードの選択

リポジトリまたは指定したパスをより広範にレビューするには、mode: "deep" を設定します。

1
2
3
4
5
6
7
8
9
10
11
12
13try {
  const result = await security.run(repository, {
    target: ["services/billing"],
    mode: "deep",
    workers: 2,
    subagents: 0,
    stopAfterNoNew: 3,
    maxDiscoveryRuns: 10,
    maxTimeMinutes: 90,
  });
} finally {
  await security.close();
}

詳細モードはリポジトリと指定したパスを対象にできます。差分と作業ツリーのスキャンには標準モードを使用してください。詳細モードでは、workers で同時に実行するスキャンワーカー数の上限を、subagents でワーカーあたりのサブエージェント数を設定します。stopAfterNoNew に指定した回数だけ、新たな検出のないワーカー実行が連続すると探索を終了します。maxDiscoveryRuns はワーカーの合計実行回数の上限です。

maxTimeMinutes で詳細モードの探索時間を制限できます。デフォルト値と最大値はいずれも 5,760 分（96 時間）です。期限に達すると探索が終了し、SDK は完了したワーカーの結果を統合します。標準スキャンでは maxTimeMinutes は調査時間の目安です。レポート作成はその後に完了する場合があります。カスタム検証とスキャン後の指示の実行時間は、この時間に含まれません。

セキュリティナレッジベースの追加

アーキテクチャに関するドキュメント、脅威モデル、セキュリティポリシーは knowledgeBasePaths で渡します。

1
2
3
4
5
6
7
8
9
10
11import { join } from "node:path";

const knowledgeBase = join(repository, "security.md");

try {
  const result = await security.run(repository, {
    knowledgeBasePaths: [knowledgeBase],
  });
} finally {
  await security.close();
}

SDK はファイルとディレクトリを受け付け、ディレクトリを再帰的に検索します。対応形式には、UTF-8 テキスト（JSON と SARIF を含む）、PDF、DOCX があります。入力パス自体がリンクの場合は拒否し、ディレクトリ内のリンクはスキップします。

SDK はドキュメントから抽出したテキストを、スキャン成果物と同じ場所にある非公開ファイル .scan-knowledge.json に保存します。このファイルはスキャンディレクトリと一緒に保管してください。中断した詳細スキャンを再開すると、codex-security scans resume は元のドキュメントが変更または削除されていても、保存済みのテキストを使用します。正式なレポートにはドキュメントのテキストは埋め込まれません。

スキャン時とスキャン後の指示の追加

scanPrompt でスキャンの重点項目を指定し、postScanPrompt でスキャン後の追加作業を依頼できます。

1
2
3
4
5
6
7
8try {
  const result = await security.run(repository, {
    scanPrompt: "Focus on tenant isolation and authorization checks.",
    postScanPrompt: "Write confirmed findings to post-scan-summary.md.",
  });
} finally {
  await security.close();
}

追加作業に失敗した場合、SDK は完了済みのスキャン結果を保持し、onWarning でエラーを通知します。追加作業で変更された完了済みスキャンの成果物は元に戻します。追加作業はスキャンのコスト追跡が終了してから実行され、maxCostUsd の対象外です。

自分の環境での検出結果の検証

validationPrompt を渡すと、独自のテスト手順で検出候補を検証できます。たとえば、チェックアウト先の外で自分が管理しているスクリプトをプロンプトで指定し、ローカルのテストサーバーに対して実行できます。リポジトリと結果ディレクトリの引数に続けて、検証スクリプトのパスとサーバーの URL をこの順に渡してください。

1
2
3
4
5
6
7const [validationScript, validationUrl] = process.argv.slice(4);
if (!validationScript || !validationUrl)
  throw new Error("Pass a validation script path and service URL.");
const result = await security.run(repository, {
  outputDir,
  validationPrompt: `Run ${validationScript} against ${validationUrl} and report which findings reproduce.`,
});

node scan.mjs /path/to/repository /path/outside/repository/results /path/to/validate.sh http://localhost:3000

validationPrompt は、リポジトリ、指定したパス、コミット間の差分、作業ツリーを対象とする標準スキャンで使用できます。コンポーネントごとの標準スキャンに同じ検証手順を適用するには、scanOptions.validationPrompt を runComponentScans に渡します。詳細スキャンではカスタム検証を指定できません。

スキャン予算の設定

maxCostUsd を設定すると、モデルの推定利用コストが上限を超えたときにスキャンが停止します。onCost で実行中のコストを追跡し、estimatedUsdRange を出力できます。

1
2
3
4
5
6
7
8
9
10
11
12try {
  const result = await security.run(repository, {
    maxCostUsd: 5,
    onCost(cost) {
      console.log(cost.estimatedUsdRange);
    },
  });

  console.log(result.cost?.estimatedUsdRange);
} finally {
  await security.close();
}

上限の判定には、短いコンテキストの料金を基準にした estimatedUsd を使用します。すでに進行中のリクエストによって、推定額が上限を超えることがあります。長いコンテキストの料金が適用されると、estimatedUsdRange も上限を超える場合があります。この設定で実際の請求額を制限することはできません。

詳細スキャンで Codex Security が完了済みワーカーの結果を集計した後に上限に達した場合、run は manifest.scan.status が "completed" の結果を返し、onWarning で予算に関する警告を通知することがあります。

有効な完了結果を生成できない場合、run は ScanCostLimitExceededError をスローし、その時点で得られている出力を保持します。

プロジェクトのコンポーネントのスキャン

runComponentScans を使うと、サービスやパッケージを並列でスキャンし、検出結果を統合できます。各コンポーネントに名前を付け、リポジトリを基準とする相対パスを 1 つ以上指定します。出力先には、対象を含む Git Worktree の外にある新規または空のディレクトリを指定してください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17import { runComponentScans } from "@openai/codex-security";

const result = await runComponentScans({
  repository: repository,
  outputDir: outputDir,
  components: [
    { name: "API", paths: ["services/api", "packages/auth"] },
    { name: "Web", paths: ["services/billing"] },
  ],
  workers: 2,
  onProgress: ({ name, status }) => console.log(name, status),
});

console.log(result.reportPath);
if (result.failed > 0) {
  throw new Error(`${result.failed} component scans failed.`);
}

workers で同時にスキャンするコンポーネント数を指定します。デフォルトは 4 です。

Codex にコンポーネントを提案させるには、auto: true を指定し、components は省略します。planOnly: true を追加すると、スキャンを実行せずに計画を components.json に保存できます。

1
2
3
4
5
6
7
8
9
10import { runComponentScans } from "@openai/codex-security";

const plan = await runComponentScans({
  repository: repository,
  outputDir: outputDir,
  auto: true,
  planOnly: true,
});

console.log(plan.planPath);

スキャンに失敗したコンポーネントがある場合は、result.retryPlanPath が指す JSON ファイルを読み込みます。そのファイルの components 配列を runComponentScans に渡し、新しい outputDir を指定してください。再実行のレポートには、再実行したコンポーネントの結果だけが含まれます。初回と再実行の両方のレポートを確認してください。

スキャン結果の利用

ScanResult から、構造化ドキュメント、スキャンのメタデータ、成果物のパスを取得できます。

後続のスキャンで同じバージョンのプラグインを必須にするには、expectedPluginVersion: result.pluginVersion を渡します。インストールされているプラグインのバージョンが異なる場合、SDK はスキャンを拒否します。

各検出結果の重大度と、最初に記録されたソースコード上の位置は、次のように取得できます。

1
2
3
4
5
6
7
8
9
10for (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
  );
}

検出結果には、任意のフィールドとして codeEvidence、rootCause、validation、attackPath、remediationTests、preventiveControls が含まれる場合があります。

リポジトリ全体の検出結果では、confirmedInLatestScan を使って、最新のスキャンで確認された項目と、以前のスキャンで検出され未解決のままの項目を区別できます。

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

result.toJSON() を使うと、マニフェスト、検出結果、記録されたレビュー除外項目、成果物のパス、ターンのメタデータをシリアライズできます。

保存済みの脅威モデルの読み込み

threatModel と threatModelPath を使用する前に、それぞれが null でないことを確認してください。Codex Security が Markdown ファイルを書き込めなかった場合でも、保存済みのモデルはエクスポートできます。ファイル名を決め打ちせず、エクスポートで返されたパスを使用してください。

保存済みの成果物のエクスポート

Codex の起動、認証情報の読み込み、モデルの呼び出しを行わずに、保存済みの結果をエクスポートできます。次の例は、保存済みの脅威モデルを標準出力に書き出します。既存のスキャン結果ディレクトリのパスを最初のコマンドライン引数として渡してください。

1
2
3
4
5
6
7
8
9
10
11
12
13
14import { exportArtifact } from "@openai/codex-security";

const directory = process.argv[2];
if (!directory) {
  throw new Error(
    "Pass an existing scan results directory as the first argument."
  );
}

await exportArtifact({
  source: { directory },
  artifact: "threat-model",
  output: "-",
});

保存済みのスキャンを ID で選ぶには、代わりに source: { scanId: "SCAN_ID" } を指定します。output に出力先のパスを指定すると、成果物をファイルに保存できます。

脅威モデルは Markdown 形式でエクスポートされます。対象のスキャンに保存済みの脅威モデルがない場合は、エラーが返ります。検出結果をエクスポートするには、artifact: "findings" を設定します。出力形式は format: "sarif"（デフォルト）、"json"、"csv"、"servicenow-avit" から選択できます。

結果には出力先の path が含まれます。脅威モデルをファイルにエクスポートした場合は、同じ保存済みの結果に由来する provenance も含まれます。両フィールドが null になるのは、output: "-" で標準出力に書き出す場合です。エクスポートには Python 3.10 以降が必要です。

ServiceNow Manual AVIT Ingestion を使用する場合は、artifact: "findings" と format: "servicenow-avit" を設定します。アプリケーションテンプレートを準備し、そのパスを avitTemplate に指定してください。output には、リポジトリ外の非公開の場所に保存する CSV ファイルのパスを指定します。source.directory で既存のスキャン結果ディレクトリを指定してください。

既存の検出結果の検証

validate を使うと、別のツールやワークフローで得られた検出結果をソースコードと照合できます。新たなスキャンの開始、アプリケーションの起動、テストの実行は行いません。実行時の挙動を裏付ける証拠が必要な場合は、別途、再現手順を実行してください。

1
2
3
4
5
6
7
8
9
10const validation = await security.validate({
  repositoryPath: repository,
  finding: {
    title: "Possible SQL injection",
    location: "src/index.js:1",
  },
});

console.log(validation.disposition);
console.log(validation.report);

検出結果は、空でないテキストまたは JSON オブジェクトとして渡します。ファイルに保存されている場合は、ファイルを読み込んでその内容を渡してください。

disposition には、検出結果の判定として reportable（報告対象）、suppressed（報告を抑制）、not_applicable（該当なし）、deferred（保留）のいずれかが入ります。validation.report の Markdown には、判定の根拠と確認できていない点が記載されます。レポートファイルが必要な場合は、この文字列を保存してください。

スキャンの進捗確認とキャンセル

ScanOptions のコールバックを渡すと、スキャンの開始、ワーカーの進捗、接続の再試行を通知できます。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27try {
  const result = await security.run(repository, {
    outputDir: outputDir,
    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);
} finally {
  await security.close();
}

リクエストまたはジョブコントローラーから AbortSignal を渡すと、スキャンをキャンセルできます。次の例では、30 分後もスキャンが実行中であれば中断し、それまでの出力の保存先ディレクトリを表示します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import { ScanInterruptedError } from "@openai/codex-security";

try {
  await security.run(repository, {
    outputDir: outputDir,
    signal: AbortSignal.timeout(30 * 60 * 1000),
  });
} catch (error) {
  if (error instanceof ScanInterruptedError) {
    console.error(error.scanDir);
  } else {
    throw error;
  }
} finally {
  await security.close();
}

スキャンを中断すると、scanDir に途中までの出力が残る場合があります。結果を調査する必要がある場合は、そのディレクトリを保管してください。

スキャンの準備状況を表示するアプリケーションでは、ScanOptions のライフサイクルコールバックも利用できます。

Trusted Access のステータスは granted、not_granted、unknown のいずれかです。アクセス権がない場合や不明な場合は、onWarning も呼び出されます。

onSessionEvent が受け取るイベントでは機密情報がマスクされておらず、ソースコードや認証情報が含まれる可能性があります。共有ログや他のサービスに送信する前にフィルタリングしてください。

ランタイムと認証情報の設定

特定のプラグイン、インタープリター、Codex の設定を使用する場合は、ランタイム設定を渡します。自分のアカウントで利用できるモデルを選択してください。

1
2
3
4
5
6
7
8const security = new CodexSecurity({
  // To override the bundled plugin, add pluginPath: "/path/to/plugin".
  pythonPath: "python3",
  codexOverrides: {
    model: "gpt-6.1-sol",
    model_reasoning_effort: "medium",
  },
});

pluginPath にプラグインのディレクトリまたは ZIP ファイルを指定すると、同梱のプラグインに代えてそのプラグインを使用できます。pythonPath はプラグインが使用するインタープリターを指定します。codexOverrides は、サポート対象の設定値を隔離された Codex 環境の設定に統合します。Amazon Bedrock を使用するには、model_provider と model を codexOverrides で設定します。

codexOverrides.approval_policy を "never" に設定すると、権限リクエストが拒否されます。それ以外の場合、スキャンでは承認リクエストの自動レビューが使用されます。ファイルシステムへのアクセスと引き継がれる認証情報については、ローカルスキャンの権限を参照してください。

OpenRouter または Fireworks を使用する場合は、対応する API キーも用意し、codexOverrides でプロバイダーの設定をすべて指定してください。OpenRouter の場合は OPENROUTER_API_KEY を設定し、利用可能な OpenRouter のモデル ID を次の TypeScript 関数に渡します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16function createOpenRouterClient(model: string) {
  return new CodexSecurity({
    codexOverrides: {
      model,
      model_provider: "openrouter",
      model_providers: {
        openrouter: {
          name: "OpenRouter",
          base_url: "https://openrouter.ai/api/v1",
          env_key: "OPENROUTER_API_KEY",
          wire_api: "responses",
        },
      },
    },
  });
}

Fireworks の場合は、2 か所の openrouter キーを fireworks に変更します。name には Fireworks AI、env_key には FIREWORKS_API_KEY を設定します。https://api.fireworks.ai/inference/v1 を base_url に指定し、Fireworks のモデルを選択してください。

クライアントには、認証用のメソッドも用意されています。

ログインハンドルは waitForInstructions、authUrl、verificationUrl、userCode、wait、cancel を提供します。アプリケーションはこれらを使って、選択したサインインフローをユーザーに案内し、完了させることができます。SDK はファイルに保存された Codex サインイン情報を再利用できます。CI やサーバー側の自動化には API キーを使用してください。

API キーと保存済みのサインイン情報の両方がある場合、SDK はデフォルトで API キーを使用します。代わりに ChatGPT のサインイン情報を使うには、スキャン時に次のように指定します。

1
2
3const result = await security.run(repository, {
  auth: "chatgpt",
});

auth: "api-key" を設定すると、環境変数の API キーが必須になります。preflight でも同じ auth オプションを指定できます。

スキャンエラーへの対処

アプリケーションで実行できる対処に応じて、SDK がエクスポートする次のエラークラスを捕捉してください。

続いて、CLI クイックスタート、CI ガイド、または CLI リファレンスを参照してください。