Primary navigation

Suggested

Permissions

Codex Security

Safety

API Dashboard
Try ChatGPT

Review code changes for security

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

See More

Use a security change review when you need evidence about regressions introduced by one Git-backed change set. The workflow reviews every changed source-like file and directly supporting code without turning the task into a general repository audit.

If you want to scan a full repository instead of a specific change, see Run a security scan.

Run a manual review

For uncommitted changes, send:

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. Confirm Scan type is Changes.
  2. Confirm the checked-out Codebase, Current branch, and Last 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
codex plugin add codex-security@openai-curated

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>/:

FileContents
findings.jsonFindings with stable identifiers, severity, confidence, source locations, and remediation. Use it to create pull-request comments or feed 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. Some key fields are:

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.

Here are examples of how to use Codex Security in common pipelines:

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
      pull-requests: write
    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."

      - name: Comment with findings
        if: always()
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          findings="$(find "${{ runner.temp }}/codex-security/codex-security-scans" -name findings.json -print -quit 2>/dev/null || true)"
          test -n "$findings" || exit 0
          jq -r '
            "## Codex Security findings",
            "",
            if (.findings | length) == 0 then "No findings reported."
            else .findings[] | "- **\(.severity.level | ascii_upcase)**: \(.title) (`\(.locations[0].path):\(.locations[0].startLine)`)\n  \(.summary)"
            end
          ' "$findings" | gh pr comment "$PR_NUMBER" --body-file -

      - 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, and coverage artifacts. 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.