# Codex Security GitHub Action Run Codex Security scans in GitHub Actions. Scan a repository or pull request, check findings against a severity threshold, and export JSON and SARIF reports. [Quick start](#quick-start) · [Pull requests](#scan-pull-requests) · [Inputs](#inputs) · [Outputs](#outputs) · [Troubleshooting](#troubleshooting) ## Quick start Use a GitHub-hosted Ubuntu 24.04 x64 runner on GitHub.com or GitHub Enterprise Cloud on `*.ghe.com`, and an OpenAI API key with access to the selected model. OpenAI is the default provider. See [Inference providers](#inference-providers) for Bedrock, OpenRouter, and Fireworks. Add your API key as a repository secret named `CODEX_SECURITY_API_KEY`, then save this workflow in `.github/workflows/codex-security.yml`. Open the [GitHub releases](https://github.com/openai/codex-security/releases) and select the `action-vX.Y.Z` release you have reviewed. Copy the **full distribution commit SHA** from its release notes into `REPLACE_WITH_REVIEWED_COMMIT`. The distribution commit contains the Action bundles and CLI dependency lock. When updating the SHA, review the new release and run the workflow manually before relying on its scheduled runs. For a fork, use its owner and release. The [repository workflow](examples/repository.yml) below uses `gpt-5.6-sol` and an estimated $5 cost limit. Change `max-cost` to adjust the budget, or remove it for no estimated cost limit. Requests already in progress can exceed the limit. Daybreak is optional; see [Daybreak access and refusals](#daybreak-access-and-refusals). ```yaml name: Codex Security repository on: workflow_dispatch: schedule: - cron: "23 7 * * 1" # Mondays at 07:23 UTC permissions: contents: read jobs: security: runs-on: ubuntu-24.04 timeout-minutes: 120 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Scan the repository id: security # Choose the distribution SHA as described at https://github.com/openai/codex-security/tree/main/github-action#quick-start uses: openai/codex-security@REPLACE_WITH_REVIEWED_COMMIT with: scope: repository model: gpt-5.6-sol effort: high max-cost: "5" fail-on-severity: none env: OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }} ``` The workflow runs weekly on Mondays at 07:23 UTC. To run it manually, use **Actions → Codex Security repository → Run workflow**. Findings are report-only by default. Set `fail-on-severity` to fail on reported findings at or above a selected severity. Scanner and required reporting errors also fail the job. Intentional exclusions and investigation notes do not. ### Ubuntu sandbox setup The Action checks that Codex can start its sandbox before using the scan credential. If sandbox startup fails on a GitHub-hosted Ubuntu 24.04 VM and Codex can load its configuration, the Action installs `bubblewrap` and `apparmor-profiles`, loads the supplied `bwrap-userns-restrict` AppArmor profile, and checks startup again. Self-hosted runners and job containers must provide a working Codex sandbox. The Action checks sandbox startup in both, but does not install system packages or change AppArmor there. See the [sandbox documentation](https://learn.chatgpt.com/docs/sandboxing). ## Supported GitHub hosts and checkout URLs The Action supports GitHub.com and GitHub Enterprise Cloud on `*.ghe.com`. Checkout origins can use HTTPS, SCP-style SSH (`USER@HOST:OWNER/REPO.git`), or an `ssh://` URL, including an explicit port 22. Repository names and hostnames are compared without regard to case; a `.git` suffix and trailing slash are optional. On GitHub.com, `ssh://git@ssh.github.com:443/OWNER/REPO.git` is also supported. GitHub does not offer this SSH-over-443 endpoint for enterprises on `ghe.com`; see [GitHub's SSH-over-HTTPS guidance](https://docs.github.com/en/authentication/troubleshooting-ssh/using-ssh-over-the-https-port). ### GitHub Enterprise Cloud The workflows in this guide also support GitHub Enterprise Cloud with data residency at `https://SUBDOMAIN.ghe.com`. The Action reads `GITHUB_SERVER_URL` from the runner and requires the checkout origin to match that host and `GITHUB_REPOSITORY`. No additional Action input or GitHub token is needed. Use a reviewed Action commit containing this support. Keep `persist-credentials: false` and use the triggering repository and revision. HTTPS origins work with the checkout step above. For SSH origins, GitHub uses the enterprise subdomain as the username, such as `example-enterprise@example-enterprise.ghe.com:example/repo.git`. See [GitHub's SSH guidance](https://docs.github.com/en/enterprise-cloud@latest/admin/data-residency/network-details-for-ghecom#using-ssh-with-ghecom). Report artifacts use the runner's Actions artifact service. The separate `github/codeql-action/upload-sarif` step uses the enterprise's code scanning service and requires the permissions and availability described below. Enterprise policies must permit the referenced actions. For Bedrock OIDC, configure AWS trust for the enterprise issuer at `https://token.actions.SUBDOMAIN.ghe.com`; see [GitHub's feature differences](https://docs.github.com/en/enterprise-cloud@latest/admin/data-residency/feature-overview-for-github-enterprise-cloud-with-data-residency). GitHub Enterprise Server remains unsupported. The Linux x64 runtime and sandbox requirements apply on both supported GitHub Cloud hosts. ## Inference providers `provider` and `model` map to `codex-security scan --provider` and `--model`. The Action supports the four providers below and forwards credentials for the one you select. The pinned CLI configures the provider and validates the model. | `provider` | Step environment | | ------------------ | ------------------------------------------------------ | | `openai` (default) | `OPENAI_API_KEY`, or `CODEX_API_KEY` as a fallback | | `amazon-bedrock` | AWS credentials and region; see the OIDC example below | | `openrouter` | `OPENROUTER_API_KEY` | | `fireworks` | `FIREWORKS_API_KEY` | OpenAI scans in the Action require an API key in the step environment. The standalone CLI can also use a saved ChatGPT login. The Action supplies `gpt-5.6-sol` when you omit the OpenAI model. For other providers, pass a model ID your credentials can access. For example, replace the quick-start scan step with: ```yaml - name: Scan with OpenRouter uses: openai/codex-security@REPLACE_WITH_REVIEWED_COMMIT with: provider: openrouter model: ${{ vars.INFERENCE_MODEL_ID }} env: OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }} ``` Use `provider: fireworks` and `FIREWORKS_API_KEY` for Fireworks. Installation and dry runs receive no provider credentials. For providers or settings outside the Action's inputs, use the [direct CLI workflow](../examples/github-actions/README.md) and check the options in your pinned CLI's `scan --help`. ## Scan with Amazon Bedrock Set `provider: amazon-bedrock` and supply the exact Bedrock model ID your AWS identity can invoke. No OpenAI API key or Codex login is needed. This workflow uses GitHub OIDC to assume an AWS role and passes the temporary credentials only to the scan step. Configure repository variables `AWS_REGION`, `AWS_ROLE_ARN`, and `BEDROCK_MODEL_ID`. The role needs permission to invoke that model, and its OIDC trust policy must restrict access to your repository and approved branches or environments. See [AWS credentials configuration](https://github.com/aws-actions/configure-aws-credentials#oidc-configuration-details) for the role and identity-provider setup. ```yaml name: Codex Security Bedrock on: workflow_dispatch: permissions: contents: read jobs: security: runs-on: ubuntu-24.04 timeout-minutes: 60 permissions: contents: read id-token: write steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: persist-credentials: false - name: Assume the Bedrock role id: aws uses: aws-actions/configure-aws-credentials@cbe3b392738ccf3f987d68400dafcf4b0624a56c # v6.2.4 with: aws-region: ${{ vars.AWS_REGION }} role-to-assume: ${{ vars.AWS_ROLE_ARN }} role-duration-seconds: 3600 output-env-credentials: false output-credentials: true - name: Scan with Bedrock id: security uses: openai/codex-security@REPLACE_WITH_REVIEWED_COMMIT with: provider: amazon-bedrock model: ${{ vars.BEDROCK_MODEL_ID }} effort: high env: AWS_REGION: ${{ vars.AWS_REGION }} AWS_ACCESS_KEY_ID: ${{ steps.aws.outputs.aws-access-key-id }} AWS_SECRET_ACCESS_KEY: ${{ steps.aws.outputs.aws-secret-access-key }} AWS_SESSION_TOKEN: ${{ steps.aws.outputs.aws-session-token }} ``` Follow the [quick start](#quick-start) to pin the Action. By default, the job reports Bedrock findings in its summary. You can also configure a severity threshold, annotations, artifacts, and SARIF uploads. Both `mode: standard` and `mode: deep` use the selected AWS credentials. Allow enough time in the AWS role session and job timeout for the scan to finish; the Action does not renew exported temporary credentials. For PR scans, apply the same trusted-contributor restrictions as [Scan pull requests](#scan-pull-requests). You can also supply `AWS_BEARER_TOKEN_BEDROCK` and a region directly to the step. The Action forwards AWS region, profile, web-identity, and container-credential settings used by the CLI. It keeps its private home directories, so profiles must specify absolute `AWS_CONFIG_FILE` and `AWS_SHARED_CREDENTIALS_FILE` paths instead of relying on the runner's `~/.aws` files. Installation and dry runs receive no provider credentials; Bedrock scans receive no OpenAI API key. See [Bedrock setup](../docs/bedrock.md) for model access and authentication, or the [CLI workflow](../examples/github-actions/README.md) to run without the Action. ## Daybreak access and refusals Daybreak is optional. You can use the Action with a general-purpose model your credentials can access under standard safeguards. Some security tasks may trigger model refusals or API cybersecurity safety blocks. **If a refusal or safety block aborts the scan, the Action fails**, even with `fail-on-severity: none`. The findings setting does not suppress scanner errors. Check the job summary and logs for the reason. A failed scan does not mean the repository has no vulnerabilities. For authorized security work that needs reduced refusals, [request Daybreak access](https://openai.com/form/enterprise-trusted-access-for-cyber/). After organization approval, enable the required program for the API project and use a key from that project. Daybreak reduces some refusals but does not remove every safeguard or guarantee that a scan will complete. To explicitly select an approved Cyber access program, add `cyber-access-program: daybreak_blue` to the scan step's `with` settings. The input also accepts `standard` and `daybreak_red`; choose a program supported by your model and API project. Leaving it unset preserves CLI defaults. Selecting `standard` does not require Daybreak approval. Selecting a Daybreak program does not grant access; an unavailable program or incompatible model causes the scan to fail. The API-project instructions above apply to `provider: openai`. For Bedrock, use an approved model ID and AWS provisioning as described in [Bedrock setup](../docs/bedrock.md#daybreak-blue-and-red). ## Scan pull requests Use the same API-key secret and Action commit as above. The [pull-request workflow](examples/pull-request.yml) checks out the PR head with full history and requires a completed scan of the event's snapshot. For each protected target branch, require its matching **Codex Security / ** check (for example, **Codex Security / main** on `main`) from the GitHub Actions app as part of the branch's merge policy. An independent merge-time gate must require fresh scan qualification whenever the live base changes, including after this check passes. GitHub can reuse a successful head check after a base-only update, even with strict up-to-date checks when the new base is already an ancestor of the head. This example does not implement that merge-time gate: the named check alone cannot establish that the current merge diff was scanned. Require this check only for branches that do not use a merge queue. The Action does not support `merge_group` events, so this workflow cannot provide the required check for a merge queue. If branch protection requires a check named **Codex Security**, let the target-specific check run once, then replace the old requirement with **Codex Security / **. Otherwise GitHub waits for the old check before allowing a merge. The check name includes the target branch because GitHub can evaluate checks on the shared head commit when a test merge commit has no status. The workflow uses read-only pull request and Git-ref access on the triggering GitHub host to verify the event's head, target branch, and live base SHA before the scan and before accepting its result. The pull record's base SHA alone can lag the branch tip. Retargeted PRs get a new review. During a run, a changed snapshot fails verification. Each push gets its own concurrency group through `github.run_id`. A new push can therefore start a scan while the previous one finishes. A rerun of an old event cannot cancel a newer review, even if the target branch changed only in case. Run the workflow from the current PR event after retargeting. If the target has advanced since that event, update the PR branch to trigger a fresh review. See GitHub's [required-check evaluation](https://docs.github.com/en/pull-requests/how-tos/merge-and-close-pull-requests/troubleshooting-required-status-checks) and [rerun semantics](https://docs.github.com/en/actions/how-tos/manage-workflow-runs/re-run-workflows-and-jobs). When the required check must establish which workflow ran, use an [organization ruleset that requires a workflow](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#require-workflows-to-pass-before-merging) from a protected ref. Selecting the GitHub Actions app identifies the app, not a particular workflow or ref. Code owner approval for `.github/workflows/` and `CODEOWNERS`, together with dismissing stale approvals, protects edits in the PR being reviewed. It does not stop a workflow on another writable branch from creating a check with the same name and app on that PR's head, so it cannot substitute for the protected-ref workflow requirement. ```yaml # Configure branch protection and merge-time freshness before requiring this check. # https://github.com/openai/codex-security/tree/main/github-action#scan-pull-requests name: Codex Security PR on: pull_request: types: [opened, synchronize, reopened, ready_for_review, edited] permissions: contents: read pull-requests: read concurrency: # Each push gets its own group. A rerun cannot cancel a newer scan, even # when the target branch changed only in case. group: codex-security-pr-${{ github.event.pull_request.number }}-${{ github.run_id }} cancel-in-progress: true jobs: security: if: >- github.event.pull_request.head.repo.full_name == github.repository && (github.event.action != 'edited' || github.event.changes.base != null) name: Scan changes runs-on: ubuntu-24.04 timeout-minutes: 60 outputs: scan-status: ${{ steps.security.outputs.scan-status }} skip-reason: ${{ steps.security.outputs.skip-reason }} steps: - &verify-current-pr name: Verify the PR still matches this scan env: GH_TOKEN: ${{ github.token }} PR_NUMBER: ${{ github.event.pull_request.number }} PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }} PR_BASE_REF: ${{ github.event.pull_request.base.ref }} PR_BASE_SHA: ${{ github.event.pull_request.base.sha }} run: | current=$(gh api --hostname "${GITHUB_SERVER_URL#https://}" "repos/$GITHUB_REPOSITORY/pulls/$PR_NUMBER" --jq '[.head.sha, .base.ref, .base.sha] | @tsv') expected=$(printf '%s\t%s\t%s' "$PR_HEAD_SHA" "$PR_BASE_REF" "$PR_BASE_SHA") if [ "$current" != "$expected" ]; then echo 'The PR head or target changed. Run the workflow for the current PR snapshot.' >&2 exit 1 fi base_ref=$(printf '%s' "$PR_BASE_REF" | jq -sRr @uri) live_base=$(gh api --hostname "${GITHUB_SERVER_URL#https://}" "repos/$GITHUB_REPOSITORY/git/ref/heads/$base_ref" --jq '.object.sha') if [ "$live_base" != "$PR_BASE_SHA" ]; then echo 'The PR head or target changed. Run the workflow for the current PR snapshot.' >&2 exit 1 fi - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: ref: ${{ github.event.pull_request.head.sha }} fetch-depth: 0 persist-credentials: false - name: Scan PR changes id: security uses: openai/codex-security@REPLACE_WITH_REVIEWED_COMMIT with: scope: diff model: gpt-5.6-sol effort: high max-cost: "5" fail-on-severity: high env: OPENAI_API_KEY: ${{ secrets.CODEX_SECURITY_API_KEY }} required-review: name: ${{ github.event.action == 'edited' && github.event.changes.base == null && 'metadata / ' || '' }}Codex Security / ${{ github.event.pull_request.base.ref }} needs: security if: always() && (github.event.action != 'edited' || github.event.changes.base != null) runs-on: ubuntu-24.04 steps: - *verify-current-pr - name: Require a completed review or an empty diff env: SCAN_JOB_RESULT: ${{ needs.security.result }} SCAN_STATUS: ${{ needs.security.outputs.scan-status }} SKIP_REASON: ${{ needs.security.outputs.skip-reason }} run: | test "$SCAN_JOB_RESULT" = success if [ "$SCAN_STATUS" = completed ]; then exit 0 fi test "$SCAN_STATUS" = skipped test "$SKIP_REASON" = empty-diff ``` The scan job fails on high or critical findings, scanner errors, or required reporting errors. After a failure, a later step with `if: failure()` in the same job can read any validated reports through the Action outputs. Set `upload-artifacts: 'true'` to make those reports downloadable after the job ends. File and line annotations are enabled by default. The repository workflow above reruns when a PR's base branch changes, even when the head commit is unchanged. Title and body edits skip the scan and use a separate concurrency group and check name, preserving the active scan and its required **Codex Security** result. For `pull_request`, GitHub runs required ruleset workflows on `opened`, `synchronize`, and `reopened`. After retargeting a PR covered by that rule, push a new commit or close and reopen the PR to scan the new base. See [GitHub's supported ruleset triggers](https://docs.github.com/en/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#supported-event-triggers). For scan-triggering events, the separate **Codex Security** job runs even if the scan job is skipped. It passes only after a successful scan job that reports a completed scan or a verified empty diff. A dry run, cancellation, or skipped scan job fails this required check. Use PR scanning for trusted contributors with branches in the calling repository. To scan Dependabot PRs, also configure `CODEX_SECURITY_API_KEY` as a [Dependabot secret](https://docs.github.com/en/code-security/reference/supply-chain-security/troubleshoot-dependabot/dependabot-on-actions#accessing-secrets). The same workflow uses that secret for Dependabot runs and the Actions secret for other runs. Missing credentials fail with setup guidance. The scan job skips fork PRs, so the required check fails for those PRs. Repositories accepting fork contributions need an approved review process for them before using this check as a merge requirement. `pull_request_target` and `workflow_run` are not supported. The scanner uses applicable `SECURITY.md` guidance from the checked-out revision, including policy changes in the PR. Review those changes alongside the code. ## Scan settings The Action defaults to `mode: standard` for repository, selected-path, and diff scans. Keep unrelated credentials and deployment steps in separate jobs. - Set `paths` to newline-separated files or folders to scan part of a repository. Names such as `src/[slug]/page.tsx` are literal paths; glob characters are not expanded. This requires repository scope. - For diff scans outside PR events, set `diff-base`. - Set `dry-run: 'true'` with `fail-on-severity: none` to check configuration and sandbox startup without an API key or model calls. Use a separate setup job; dry-run does not assess code or verify model access. For a Deep scan of a repository or selected paths, add these inputs to the scan step: ```yaml with: mode: deep max-time-hours: "1" ``` Deep mode does not support diff scans. `max-time-hours` limits Deep discovery (the Action converts hours to CLI minutes); finalization can take additional time. It is unset by default, which uses the CLI's default of 96 hours. Set an explicit budget for Deep scans that leaves room for finalization within your job timeout. The one-hour discovery budget above leaves time for setup and finalization within the repository workflow's two-hour job timeout. ## Reports The Action lists the highest-severity findings first in the job summary and source annotations, preserving scan order within each severity level. Set `upload-artifacts: 'true'` to upload full reports and link them from the summary. Anyone signed in to GitHub with read access to the repository can download the reports, which can contain source code and vulnerability details. Set `retention-days` to change the default of seven days. When the scan records scope limitations, the job summary displays them. For example, a time-limited Deep scan can finish before any source review completes. The job summary includes the configured provider, reported input/cached/output token usage, and estimated USD cost, including a range when supplied by the CLI. Missing measurements or pricing appear as `unavailable`; measured zeros remain zero. Cost estimates are not billing totals. The Action uses the normal Actions job check. Its summary and final log message distinguish findings above the failure threshold from a scan that could not complete or a required reporting failure. With `fail-on-severity: none`, findings are report-only; scanner and required reporting failures still fail the job. A completed scan means the configured analysis produced a valid result. Scope exclusions, deferred investigations, and other coverage notes remain in the review notes, they do not create a separate scan outcome or bypass the findings policy. Completion does not certify that every vulnerability was found. The Action follows the CLI outcome consistently: | CLI exit | Action result | | ----------------------------- | ------------------------------------------------------------------------------ | | `0` | `scan-status: completed`, `policy-status: passed`; the step succeeds. | | `1` | `scan-status: completed`, `policy-status: failed`; the step fails on findings. | | `2` or an interrupted process | `scan-status: failed`, `policy-status: not-evaluated`; the step fails. | A verified empty diff succeeds with `scan-status: skipped` and `skip-reason: empty-diff`, including when a severity threshold is configured. A dry run checks local setup and requires `fail-on-severity: none`. Use the [required PR check](#scan-pull-requests) to handle skipped scan jobs as well as the Action's own results. After an execution failure, the Action returns paths to usable reports and sets `sarif-upload-ready: false`. Invalid or missing required reports, a changed checkout, and requested artifact-upload or runtime-cleanup failures also fail the step. Empty diffs and dry runs use `scan-status: skipped`. SARIF is optional. If it cannot be produced, the Action warns and sets `report-status: partial` and `sarif-upload-ready: false`. Summaries, annotations, and JSON reports remain available, and the scan outcome is preserved. This report availability status does not describe scan coverage. A requested artifact upload that fails still fails the job. ### GitHub code scanning Grant the job `security-events: write` and, for private repositories, `actions: read`, alongside `contents: read`. When extending the pull-request workflow, retain `pull-requests: read` in the job's permissions map for its snapshot checks; a job-level map replaces the workflow-level permissions. Set `id: security` on the scan step, then add this step after it: ```yaml - name: Upload security findings if: ${{ always() && steps.security.outputs.sarif-upload-ready == 'true' }} uses: github/codeql-action/upload-sarif@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4.38.0 with: sarif_file: ${{ steps.security.outputs.sarif-path }} sha: ${{ steps.security.outputs.scanned-sha }} ref: ${{ steps.security.outputs.analysis-ref }} category: codex-security-repository ``` Completed scans remain uploadable when findings exceed the severity threshold. Failed or interrupted scans, empty diffs, and dry runs are not uploadable. Use a distinct category for each scan scope, such as repository and PR scans. The Action removes the CLI scan identifier from SARIF automation details so the uploader can apply that category. See [GitHub's SARIF upload requirements](https://docs.github.com/en/code-security/how-tos/find-and-fix-code-vulnerabilities/integrate-with-existing-tools/upload-sarif-file) for code scanning availability and permissions. ## Runtime The Action installs a pinned CLI release from npm using a committed dependency lock. It runs on Linux x64 with Node 24 and Python 3.11 or later. GitHub-hosted Ubuntu 24.04 VMs supply Node and Python. Codex uses the system Bubblewrap from `PATH`; see [Ubuntu sandbox setup](#ubuntu-sandbox-setup) for VM setup and requirements for self-hosted runners and job containers. npm and Python are found on the runner's `PATH`; `actions/setup-node` and `actions/setup-python` can select installations. Python helpers preserve the selected virtual environment and library settings. The runner's process tracking marker is retained by the scan coordinator and Deep Scan workers. See [inference providers](#inference-providers) for the environment variables to pass to the scan step. Temporary runtime files are removed after the job; reports remain available to downstream steps. The Action uses the CLI’s validated JSON result for findings and scan status. If the CLI exits without a usable result, the Action reports failure and leaves report paths empty; it does not recover unvalidated files from disk. ### Request attribution The Action adds `codex_security_integration=github_action` and `codex_security_provider` (the configured provider family) through the CLI's existing `responses_api_metadata` setting. These accompany the CLI's request attribution on model requests supported by the provider. This attribution contains no repository, workflow, run, actor, credential, or finding data. Native managed configuration may override the provider selection before inference. The Action continues to set `analytics.enabled=false`. Request metadata is separate from native analytics and does not create an additional telemetry request or publish scan results to Codex Security Cloud. Requests sent to other providers do not establish OpenAI-side usage reporting. Summaries, annotations, and artifact uploads retain their existing controls. ## Troubleshooting - **Checkout or history errors:** use the triggering revision, `fetch-depth: 0` for PRs, and `persist-credentials: false`. - **Authentication errors:** for OpenAI, check the repository secret and model access. For Bedrock, check the AWS identity, session expiry, region, and permission to invoke the exact model ID. - **Sandbox startup errors:** for jobs running directly on GitHub-hosted Ubuntu 24.04 VMs, inspect the package-install and AppArmor diagnostics. On self-hosted runners and in job containers, configure the sandbox before running the Action. Installing Bubblewrap alone does not load Ubuntu's required AppArmor profile. - **Missing SARIF uploads:** inspect `scan-status`, `report-status`, and `sarif-upload-ready`. - **Failed scans:** inspect the CLI diagnostics for execution errors. Scope exclusions and deferred investigations in the review notes do not cause execution failures or bypass the severity policy. CLI diagnostics stream by default. Set `verbose: 'false'` for lifecycle and elapsed-time messages only. ## Update a pinned Action Use the [quick start](#quick-start) to choose a new distribution SHA. Keep `dry-run: 'true'` in a separate setup job with `fail-on-severity: none`. Run a manual scan with the model, cost limit, and reporting options your production workflow uses. Confirm that the summary and any expected artifacts appear before using the new pin for a required check. For GitHub-hosted Ubuntu VMs, check the sandbox instructions shipped with the release you pin. Remove a manual Bubblewrap setup step once your pin includes [automatic sandbox setup](#ubuntu-sandbox-setup). Self-hosted runners and job containers supply their own sandbox. ## Development From the repository root, use Node.js 24 to check the committed files and audit both dependency locks. ```bash npm --prefix github-action ci --ignore-scripts --no-audit --no-fund npm --prefix github-action run validate npm --prefix github-action audit --audit-level=high npm --prefix github-action/runtime audit --omit=dev --audit-level=high ``` After editing `action.yml` inputs or outputs, or workflows in `github-action/examples/`, run `npm --prefix github-action run docs` to regenerate the README. After changing bundled source or the runtime lock, run `npm --prefix github-action run build`. Review the generated README and `dist/*.cjs` changes, rerun validation, and commit them with their source changes. On Linux x64 with a working sandbox, run the published CLI integration and packaged smoke tests. ```bash npm --prefix github-action/runtime ci --ignore-scripts --no-audit --no-fund npm --prefix github-action run test:cli node github-action/scripts/linux-smoke.mjs ``` Validation checks types, tests, Action metadata, documentation, and bundle reproducibility. CI also tests the result adapter against the pinned CLI and its SARIF exporter using synthetic scans. A local inference fixture checks request attribution and the analytics opt-out with synthetic credentials. These tests run without external model calls. The `@openai/codex-security` dependency in `runtime/package.json` is the installed CLI version source. Main keeps an already published CLI baseline so its checks remain runnable while a release PR prepares the next product version. This development pin does not necessarily track the latest CLI release. To upgrade it, update it and regenerate `runtime/package-lock.json`, rebuild the bundles, and run validation. See [the release process](../RELEASING.md) for publication, verification, and recovery. The [quick start](#quick-start) explains which commit consumers pin. ## Inputs Inputs are strings. Quote booleans and use newline-separated literal paths for lists. | Input | Default | Meaning | | --- | --- | --- | | `repository` | `${{ github.workspace }}` | Checkout root. Use paths to select folders within the checkout. | | `scope` | `repository` | repository or diff. Select diff for PR changes only; repository scans the full checkout. | | `paths` | Unset | Newline-delimited literal repository-relative files or folders. Only for repository scope; no glob expansion. | | `diff-base` | Unset | Diff base revision. Defaults to the PR merge base; required outside PRs when scope is diff. | | `mode` | `standard` | standard or deep. Deep supports repository scans, including selected paths; not diff scans. | | `provider` | `openai` | Providers supported by the Action: openai, openrouter, fireworks, or amazon-bedrock. Pass the selected provider's credentials to the scan step. | | `model` | Unset | Model to scan with, passed to scan --model. Defaults to gpt-5.6-sol for OpenAI; other providers require an explicit model ID. Cost limits require CLI pricing support for the model. | | `cyber-access-program` | Unset | Optional Cyber access program: standard, daybreak_blue, or daybreak_red. Unset preserves CLI defaults. Daybreak selections require approved organization and enabled API project access; model access is checked separately. | | `effort` | `xhigh` | Reasoning effort passed to Codex; supported values depend on the model and provider. | | `max-cost` | Unset | Positive estimated USD stop threshold per invocation. In-flight requests can exceed it; unset means no cost limit. | | `max-time-hours` | Unset | Positive Deep discovery duration in hours, up to 96. Unset uses the CLI default. Finalization and job timeout are separate. | | `fail-on-severity` | `none` | none, low, medium, high, or critical. Fails on reported findings at or above the selected severity. Scanner and required reporting errors also fail. | | `verbose` | `true` | Stream CLI diagnostics to the job log. Set false for lifecycle and elapsed-time messages only. | | `dry-run` | `false` | Validate local configuration without a scan or API key. Does not verify authentication or model access. Requires fail-on-severity: none; use a separate non-required job. | | `summary` | `true` | Write a human-readable job summary. | | `annotations` | `true` | Emit up to 50 source finding annotations; complete findings remain in reports. | | `upload-artifacts` | `false` | Upload an allowlist of validated reports and link the artifact in the job summary. Reports may contain source and vulnerability details. | | `artifact-name` | `codex-security` | Report artifact name; choose distinct names for matrix jobs and multiple invocations. | | `retention-days` | `7` | Artifact retention, 1–90 days (subject to repository limits). | ## Outputs All outputs are strings. An empty cost or count means unavailable, not zero. | Output | Meaning | | --- | --- | | `sarif-path` | Absolute validated SARIF file path, or empty when unavailable or withheld. | | `json-path` | Absolute canonical findings JSON path, or empty when unavailable or withheld. | | `manifest-path` | Absolute scan manifest path, including scan status and scope, or empty when unavailable or withheld. | | `coverage-path` | Legacy coverage JSON path. Empty for current CLI results. | | `results-directory` | Runner-local reports directory; do not upload it recursively. | | `scan-status` | completed, failed, or skipped. Completed means analysis produced a valid result. Skipped is reserved for empty diffs or dry-run. | | `skip-reason` | empty-diff or dry-run when no scan ran; otherwise empty. | | `policy-status` | passed, failed, or not-evaluated. Failed or skipped scans are not-evaluated. | | `report-status` | ready, partial, or failed. Missing optional SARIF yields partial without failing the scan; required reporting failures yield failed. | | `exit-code` | CLI exit code, or empty if the CLI was not started. 0 means success, 1 means findings policy failed, and 2 means execution failed. | | `scanned-sha` | Verified checkout commit SHA. | | `analysis-ref` | GitHub ref matching the scanned revision. | | `sarif-upload-ready` | true only for validated SARIF from a completed scan with a publishable immutable revision. Remains true after severity-policy failure. | | `critical-count` | Available critical findings, or empty before results are available. | | `high-count` | Available high findings, or empty before results are available. | | `medium-count` | Available medium findings, or empty before results are available. | | `low-count` | Available low findings, or empty before results are available. | | `informational-count` | Available informational findings, or empty before results are available. | | `estimated-cost` | Estimated USD cost reported by the CLI. Empty means unavailable, not zero. |