OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
Container releases
Each scanner release publishes two images to ghcr.io/openai/codex-security
from the same verified npm tarball and runtime dependency lock. Both run the
scanner CLI and use the runner's local SQLite database for saved-scan deduplication.
| Tag | Image | Platforms |
|---|---|---|
X.Y.Z, sha-<scanner-commit>, latest |
Debian | Linux amd64 and arm64 |
X.Y.Z-wolfi-amd64 |
Wolfi | Linux amd64 |
X.Y.Z-wolfi-amd64-rN |
Wolfi OS update for scanner X.Y.Z | Linux amd64 |
Version tags are immutable. Only the newest stable Debian release gets latest.
- Run the scanner with Compose to scan a checkout and keep its results.
- Verify a Debian image before deploying it.
- To publish images, prepare GHCR, then follow the release and backfill procedure. Wolfi also supports OS-only updates.
Image metadata and verification
Debian release images include OCI metadata in each platform's image labels and in the final multiarchitecture index: title, description, source, license, vendor, version, source commit, build timestamp, release notes, and documentation pinned to that commit. GHCR reads the multiarchitecture description from the index, not from the Dockerfile labels alone.
The workflow generates metadata once for both architectures, verifies it on the published candidate, then signs and promotes that exact digest. Metadata changes require a new digest and a new release; existing stable versions are not updated. The successful release run's summary includes the digest, supported platforms, documentation links, and commands to pull and verify the published image.
Replace VERSION with an available stable version. Resolve its index digest once
and use that reference for inspection, verification, and deployment:
image=ghcr.io/openai/codex-security
version=VERSION
digest="$(docker buildx imagetools inspect "$image:$version" --format '{{.Manifest.Digest}}')"
reference="$image@$digest"
docker buildx imagetools inspect "$reference" --raw | jq '.annotations'
gh attestation verify "oci://$reference" --repo openai/codex-security \
--cert-identity 'https://github.com/openai/codex-security/.github/workflows/container-publish.yml@refs/heads/main' \
--source-ref refs/heads/main
docker pull "$reference"
Older Debian releases were signed by container-release.yml. For those releases,
use that filename in the certificate identity. For an older image published from
a container-vVERSION tag, use refs/tags/container-vVERSION for both refs
and pass --source-digest with the release commit.
Set CODEX_SECURITY_IMAGE to the verified
reference when using Compose. The index selects the native amd64 or arm64
image. Its unknown/unknown entries contain the per-platform SBOM and build
provenance; they are not runnable platforms and should not be removed.
All labels, annotations, SBOMs, and provenance are public. Keep private URLs, scan data, and credentials out of them. BuildKit's maximum-mode provenance includes build arguments, so pass build credentials through secret mounts rather than build arguments.
Workflow runner
compose.runner.yaml runs the packaged CLI and returns
its output and exit code. Keep the results and state directories between runs
to look up saved scans and deduplicate findings.
Run these commands from the repository root after
verifying an image. Keep the verified
reference in the same shell. Create private output and state directories,
then choose the host user's UID/GID so the runner can write its bind mounts:
mkdir -p results state
chmod 700 results state
export CODEX_SECURITY_USER="$(id -u):$(id -g)"
export CODEX_SECURITY_IMAGE="$reference"
docker compose -f compose.runner.yaml pull
docker compose -f compose.runner.yaml run --rm codex-security login --device-auth
The login --device-auth command above signs the runner in with ChatGPT and
requires device auth to be enabled in your workspace. If device auth is
disabled, skip that command and export OPENAI_API_KEY or CODEX_API_KEY in
your host shell. Compose passes the key to the runner. Use API keys for
unattended runs too.
Git authentication uses GH_TOKEN/GITHUB_TOKEN and optional
CODEX_SECURITY_GIT_HOST settings. Pass only the credentials the runner needs.
Use a version or digest in CODEX_SECURITY_IMAGE for repeatable deployments.
To test an unreleased checkout, build the same scanner target locally instead
of pulling. First prepare the universal native payload:
docker build --target scanner -t codex-security:local .
export CODEX_SECURITY_IMAGE=codex-security:local
To build the Linux amd64 Wolfi image locally, see the melange and apko recipe.
CODEX_SECURITY_RESULTS and CODEX_SECURITY_STATE settings select
the host directories (default ./results and ./state):
| Container path | Durable contents |
|---|---|
/output |
Scan artifacts and any source checkouts stored here |
/output/.codex-security-state |
CLI scan history and workbench database |
/output/.codex-security-state/codex-home |
Wrapper sign-in credentials and private runtime configuration |
/state |
Ambient Codex configuration and credentials imported at setup |
Keep both host mounts across runner replacements. The results mount also holds
the wrapper's private credential directory. Keep the approved source checkout
available at the same container path for later source reviews. For example,
place a checkout under results/repository, then scan it with artifacts outside
the checkout:
docker compose -f compose.runner.yaml run --rm codex-security \
scan /output/repository --output-dir /output/scans/run-001 --headless
An existing checkout elsewhere can instead be bind-mounted with
run --volume /absolute/repository:/input/repository; repeat that mount on each
stage that needs the source. Moving a host scan's files into these directories
does not rewrite absolute paths in its saved state. Run the scan in the runner
or preserve its original paths.
Deduplication and custom endpoints
Deduplicate a saved scan against the runner's persisted local SQLite database:
docker compose -f compose.runner.yaml run --rm codex-security \
dedupe --scan SCAN_ID --json
For a compatible endpoint you operate, pass a base URL the container can reach
through --findings-url. Loopback addresses refer to the runner itself.
See the findings guide for remote
deduplication and publication.
Run docker compose -f compose.runner.yaml run --rm codex-security --help to
see which commands your image supports. Your CI system controls stage order
and retries.
Sandbox and lifecycle
The runner starts with a nonroot user, dropped capabilities,
no-new-privileges, and the project's seccomp profile. On hosts that restrict
nested user namespaces, install the AppArmor profile
and add -f compose.apparmor.yaml after -f compose.runner.yaml in the
Compose commands. Both files configure the codex-security service. Source inspection requires a host that supports
Bubblewrap and permits its user namespaces.
The bundled Compose seccomp profile allows direct socket calls for Unix sockets, IPv4, IPv6, and the route netlink sockets Bubblewrap uses to configure loopback. It blocks the legacy IPv4 packet socket type and limits direct socket pairs to Unix sockets. Normal IP networking remains available. Use a network policy to restrict outbound destinations. On amd64, 32-bit i386 programs retain a legacy socket interface whose arguments seccomp cannot filter.
The profile also blocks ptrace, process_vm_readv, and process_vm_writev.
Debuggers and other tools that rely on these calls may fail inside the container.
run --rm removes only the finished runner container. Preserve its host mounts
for later stages and retries; use the same image version and source paths.
Stop active runners before backing up the entire results and state directories,
and keep backups separately. No service ports or Docker socket are exposed by
the runner example.
GHCR administrator setup
Before bootstrapping a package with a source build, prepare the universal native payload. An organization administrator can then configure GHCR for the first release.
Allow organization package creation and, if the package is missing, bootstrap it with a reviewed image and a non-release tag:
docker build --target scanner -t ghcr.io/openai/codex-security:bootstrap . printf '%s' "$CR_PAT" | docker login ghcr.io --username YOUR_GITHUB_USER --password-stdin docker push ghcr.io/openai/codex-security:bootstrap docker logout ghcr.ioUse a personal access token (classic) with
write:packages, authorized for SSO if required; never commit it or pass it into the build.In the package's settings, link
openai/codex-security, set visibility to Public, and grant the repository Write under Manage Actions access. The workflow usesGITHUB_TOKENand refuses missing, private, or unreadable packages. Verifydocker pullworks after logging out of GHCR.Configure the protected
npmenvironment with release reviewers authorized for both npm and GHCR and limit it tonpm-v*tags. For image backfills and standalone Wolfi OS updates, protect thecontainerenvironment with required reviewers and deployment rules formainand approvedcontainer-v*tags. Allow the workflow's pinned actions, package writes, and OIDC attestations. Use the release workflow’s job names for any required branch-protection checks.
See GitHub's registry authentication and package access settings.
Publishing
After verifying the published npm tarball and installation, node-github-release
publishes the matching Action. Its immutable action-vX.Y.Z tag preserves the
runtime lock for future backfills. The workflow passes the verified archive and
lock to container-publish. Debian builds on amd64 and arm64 and Wolfi builds
on amd64, both using recipes from the scanner release commit. Approving
Publish npm and container images in the npm environment authorizes both
images for that release. Publication uses the tested digests, verifies
anonymous pulls, and attests the images before promoting their version tags.
Debian carries BuildKit SBOMs and maximum-mode provenance. Wolfi carries build
provenance and an SPDX inventory of its OS packages, installed npm packages,
and native components.
To backfill a release, dispatch node-github-release on protected main with
the original npm-vX.Y.Z tag. A manual container-release run on main
requests the coordinated release for the current package version. Pushing a
container-vX.Y.Z tag runs the container workflow at the tagged commit.
The release source determines which images are required.
Sources from 0.5.0 onward with a Dockerfile but predating coordinated Wolfi
builds use the original Debian release path. Earlier releases skip image
publication. A default backfill uses the scanner release commit's recipes.
If the Wolfi build needs updated OS pins, dispatch node-github-release with
refresh-wolfi-recipe=true to use the recipe from protected main with the
original scanner tarball and runtime lock. Review and approve the container
deployment when publishing with a different recipe commit or recovering
images for a release whose approval covered only npm. A backfill that
verifies all existing tags finishes without a deployment approval.
Promotion updates tags separately. If publication stops partway through, rerun
the failed jobs to reuse the retained artifacts. The publisher verifies existing
version tags and refuses to replace a different digest. The release status
summary lists both digests when the coordinated release finishes. For a Wolfi
OS update between scanner releases, see Wolfi-only OS updates.
The bootstrap and release-candidate-<commit> tags are for registry setup
and release validation.