English

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.

If you want to scan a full 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, identify both ends 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.

The workflow doesn't check out another branch or change 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

Run the same $codex-security:security-diff-scan skill from CI when the runner can invoke the Codex CLI without interaction. First install the CLI and plugin 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.

Then expose an OpenAI API key from your CI secret store as CODEX_SECURITY_API_KEY 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 scan writes its output to $TMPDIR/codex-security-scans/<repository>/<scan-id>/:

File Contents
report.md Primary 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.json Findings with stable identifiers, severity, confidence, source locations, and remediation. Feed approved internal security workflows or downstream tools.
scan-manifest.json Sealed scan receipt with the reviewed target, revisions, and artifact hashes.
coverage.json Reviewed and deferred surfaces, exclusions, and coverage completeness.

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

Field Type Description
documentType String Identifies the document as codex-security.findings.
schemaVersion String Identifies the findings schema version.
scanId String Identifies the scan that produced the findings.
findings Array Contains zero or more finding objects.
findings[].findingId String Stable finding identifier derived from the finding fingerprint.
findings[].occurrenceId String Identifies this occurrence of the finding in a specific scan.
findings[].ruleId String Identifies the vulnerability family.
findings[].identity Object Contains the semantic anchor and optional sibling-instance identifier.
findings[].fingerprints Object Contains the fingerprint algorithm and primary fingerprint.
findings[].title String Provides the short finding title.
findings[].summary String Summarizes the vulnerability and its impact.
findings[].severity Object Contains the severity level and optional scoring details.
findings[].confidence Object Contains the confidence level and rationale.
findings[].taxonomy Object Contains the vulnerability category and CWE identifiers.
findings[].locations Array Lists affected files, line numbers, and location roles.
findings[].remediation String Describes the recommended fix.
findings[].provenance Object Identifies 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.

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.