Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

5.1 KB
Raw Blame

Import GitHub code scanning findings

Use the JSON array from codex-security import github. It includes each alert and the instance GitHub returned for the selected ref.

Quick start

In the matching checkout, set the repository and source key. For GitHub Enterprise, export GH_HOST with your hostname first. For a repeat import, use the exact source key from your previous preview, including case.

repo=OWNER/REPO
source_key="${GH_HOST:-github.com}/$repo/code-scanning"

Saved report. Set report=/private/path/alerts.json if you already have the collector's complete JSON array. Continue with Preview the report.

Export from GitHub

Sign in to the selected host with gh auth login. A fine-grained token needs Code scanning alerts: read. A classic token needs security_events, or public_repo for a public repository. GitHub API permissions

The command below selects open alerts on the default branch. For a different branch, add --github-ref refs/heads/BRANCH to the collector command. To include fixed and dismissed alerts, add --github-state all. For exact alerts across states, repeat --github-alert NUMBER and omit --github-state. Save the complete array without output filters, token limits or --full-output. Use a private temporary directory outside the checkout.

report=
out=$(mktemp -d) &&
  codex-security import github "$repo" --format json > "$out/alerts.json" &&
  report="$out/alerts.json"

Preview the report

codex-security publish findings "$report" --to local --repository . \
  --provider github --source-key "$source_key" --dry-run --format json

Save and verify

Check the repository, ref and alert numbers against your selection. The alert repository must match a comparable local Git remote when available, or the selected Cloud repository. If the preview matches, save locally or publish to Cloud and verify the result.

Identity and evidence

The host, repository, alert number and ref identify a finding. The same alert on two refs keeps separate evidence. The finding URL opens the GitHub alert. The file, line and commit come from the selected instance. Severity comes from the rule’s security rating. A SARIF level such as error leaves a missing security rating unknown.

A GitHub dismissal applies to the entire alert, even when a selected ref's instance is open or fixed. A GitHub connection in Codex can select records. The CLI collector authenticates separately with gh.

Use the SDK

To collect with the SDK, use credentials from gh or supply githubHost and a githubToken issued for that host. This example previews a Cloud import.

import {
  importGitHubCodeScanningAlerts,
  normalizeGitHubCodeScanningAlerts,
  prepareNormalizedExternalPublication,
} from "@openai/codex-security";

const alerts = await importGitHubCodeScanningAlerts({
  repository: "example/project",
});
const prepared = await prepareNormalizedExternalPublication(
  normalizeGitHubCodeScanningAlerts(alerts, "cloud"),
  {
    provider: "github",
    repository: "https://github.com/example/project",
    sourceKey: "github.com/example/project/code-scanning",
  },
);
console.log(prepared.preview);

After reviewing the Cloud preview, call await prepared.publish() to confirm. If you supply normalized evidence that keeps the collector record in source_data, imports check its original repository against the destination.

For local storage, call normalizeGitHubCodeScanningAlerts(alerts, "local") on the original alerts to retain evidence that exceeds Cloud limits. Pass the result to prepareNormalizedLocalImport() with repository: "/path/to/project", inspect its preview, and call import(). Alternatively, pass the saved alert file directly to prepareLocalExternalImport(). Read records with listLocalExternalFindings({ repository }).

Validate the selected alerts

To get a disposition per alert, validate the collected records against the matching checkout.

import {
  CodexSecurity,
  importGitHubCodeScanningAlerts,
} from "@openai/codex-security";

const findings = await importGitHubCodeScanningAlerts({
  repository: "example/repository",
  alertNumbers: [12, 18], // Omit for all open alerts on the default branch.
  githubHost: "github.com",
  githubToken: process.env["GH_TOKEN"],
});

const security = new CodexSecurity();
try {
  for (const finding of findings) {
    const result = await security.validate({
      repositoryPath: "/path/to/repository",
      finding,
    });
    console.log(finding.url, result.disposition, result.outputDir);
  }
} finally {
  await security.close();
}

SDK options include state (default "open"), ref, and signal. Without gh, pass a githubToken issued for the selected githubHost. If you omit the token, the SDK asks the GitHub CLI for credentials, including its supported token environment variables. githubHost defaults to GH_HOST or github.com. The token needs code-scanning read access; access failures reject the import.