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