Files
codex-security/docker
..

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.

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.

  1. 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.io
    

    Use a personal access token (classic) with write:packages, authorized for SSO if required; never commit it or pass it into the build.

  2. In the package's settings, link openai/codex-security, set visibility to Public, and grant the repository Write under Manage Actions access. The workflow uses GITHUB_TOKEN and refuses missing, private, or unreadable packages. Verify docker pull works after logging out of GHCR.

  3. Configure the protected npm environment with release reviewers authorized for both npm and GHCR and limit it to npm-v* tags. For image backfills and standalone Wolfi OS updates, protect the container environment with required reviewers and deployment rules for main and approved container-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.