For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Review code changes for security

Review pull requests and local changes for security regressions manually or in CI/CD.

Run a security change review to find regressions in one Git-backed change set. Codex reviews each changed source-like file and its directly supporting code. It doesn’t expand the review into a full repository audit.

To scan an entire repository instead of a specific change, see Run a security scan.

Run a manual review

In the desktop app, open Security, select Scans, and select + Scan. Choose the repository, then select Changes. Review uncommitted changes, a single commit, or a base and head revision. Deep scan isn’t available for a changes scan.

You can also ask Codex to review uncommitted changes in a conversation:

Use $codex-security:security-diff-scan to review my current uncommitted changes for security regressions.

For a commit or branch range, specify both revisions when needed:

Use $codex-security:security-diff-scan to review the changes from origin/main to HEAD for security regressions. Focus on authentication, authorization, input handling, filesystem access, network requests, and secrets.

You can also name a pull request when its base and head revisions are available in the local checkout.

Confirm the change in setup

  1. Select Changes.
  2. Confirm the checked-out repository, current branch, and latest commit.
  3. Under Changes to review, choose:
    • Uncommitted changes for the current working tree.
    • The latest commit for a single-commit review.
    • A base and head revision for a branch or pull-request range.
  4. Confirm that the summary describes the change you intended to review.
  5. Select Start scan.

Codex doesn’t check out another branch or switch the selected working tree. If a requested revision isn’t available locally, fetch it before the review or provide a locally available base and head.

Act on findings

After reviewing the results, fix and verify an accepted finding or export and track findings.

Automate reviews in CI/CD

If you have access to the beta standalone CLI, see Run Codex Security in CI for structured JSON, a severity policy, and SARIF upload. Continue with this section to invoke the installed plugin skill through codex exec.

Run $codex-security:security-diff-scan in CI when the runner can invoke the Codex CLI without interaction. First, install the CLI without exposing the scan credential:

npm install --global @openai/codex

Install the Codex Security plugin in the CLI:

codex plugin add codex-security@openai-curated

The install command uses the public Codex CLI plugin marketplace, which can offer a different version from the hosted desktop-app catalog. Check the plugin changelog before you depend on a specific plugin version or feature in CI.

Next, provide an OpenAI API key from your CI secret store as CODEX_SECURITY_API_KEY. Expose the credential only for the scan:

CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
  --sandbox workspace-write \
  "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

The writable sandbox lets the scan create temporary artifacts. The prompt still requires Codex to leave the source checkout unchanged.

The scan writes its output to $TMPDIR/codex-security-scans/<repository>/<scan-id>/:

FileContents
report.mdPrimary readable entry point to the complete scan directory.
findings/<slug>/One detailed vulnerability report per reportable finding, with supporting proof-of-concept files when available.
hardening/Structural hardening portfolio and supporting proposals or diagrams when the scan has reportable findings.
findings.jsonFindings with stable identifiers, severity, confidence, source locations, and remediation. Feed approved internal security workflows or downstream tools.
scan-manifest.jsonSealed scan receipt with the reviewed target, revisions, and artifact hashes.
coverage.jsonReviewed and deferred surfaces, exclusions, and coverage completeness.

The findings.json schema defines the complete structure. The schema includes these fields:

FieldTypeDescription
documentTypeStringIdentifies the document as codex-security.findings.
schemaVersionStringIdentifies the findings schema version.
scanIdStringIdentifies the scan that produced the findings.
findingsArrayContains zero or more finding objects.
findings[].findingIdStringStable finding identifier derived from the finding fingerprint.
findings[].occurrenceIdStringIdentifies this occurrence of the finding in a specific scan.
findings[].ruleIdStringIdentifies the vulnerability family.
findings[].identityObjectContains the semantic anchor and optional sibling-instance identifier.
findings[].fingerprintsObjectContains the fingerprint algorithm and primary fingerprint.
findings[].titleStringProvides the short finding title.
findings[].summaryStringSummarizes the vulnerability and its impact.
findings[].severityObjectContains the severity level and optional scoring details.
findings[].confidenceObjectContains the confidence level and rationale.
findings[].taxonomyObjectContains the vulnerability category and CWE identifiers.
findings[].locationsArrayLists affected files, line numbers, and location roles.
findings[].remediationStringDescribes the recommended fix.
findings[].provenanceObjectIdentifies the source of the finding.

For example, this command prints one tab-separated row per finding:

jq -r '
  .findings[] |
  [.findingId, .severity.level, .confidence.level, .locations[0].path, .locations[0].startLine, .title] |
  @tsv
' findings.json

These examples assume a trusted Linux runner with Node.js and npm, Git, Python 3, jq, and the provider’s command-line tools. The npm global package prefix must be writable.

Choose the example for your CI provider:

Scan results can include sensitive vulnerability details. Keep artifacts private, and publish findings only after reviewing the audience, content, and required approvals.

Choose an option
name: Codex Security review

on:
  pull_request:

jobs:
  security-review:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v5
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0
          persist-credentials: false

      - name: Install Codex Security
        env:
          CODEX_HOME: ${{ runner.temp }}/codex-home
        run: |
          npm install --global @openai/codex
          codex plugin add codex-security@openai-curated

      - name: Review code changes
        env:
          CODEX_SECURITY_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }}
          CODEX_HOME: ${{ runner.temp }}/codex-home
          TMPDIR: ${{ runner.temp }}/codex-security
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_REVISION: ${{ github.event.pull_request.head.sha }}
        run: |
          BASE_REVISION="$(git merge-base "$BASE_SHA" "$HEAD_REVISION")"
          CODEX_API_KEY="$CODEX_SECURITY_API_KEY" codex exec \
            --sandbox workspace-write \
            "Use \$codex-security:security-diff-scan to review changes from $BASE_REVISION to $HEAD_REVISION for security regressions. Do not modify the checkout."

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: codex-security-review
          path: ${{ runner.temp }}/codex-security/codex-security-scans

The examples skip forked pull requests. Run credentialed jobs only from a protected pipeline definition and only for contributors trusted with the scan credential. Archive codex-security-scans to keep the structured findings, manifest, coverage artifacts, report.md, and its linked findings/ and hardening/ outputs together. Start with advisory results and review coverage and runtime before making the job a required check.

For API-key handling and sandbox controls, see Non-interactive mode. If your organization permits the Codex GitHub Action, it can install the CLI at runtime, but you must still install the plugin first and point the action’s codex-home input at the same CODEX_HOME.