Skip to main content

Codex CLI Plugin

Developer Assist for Codex CLI intercepts file writes and package installations performed by Codex CLI, runs security scans on the targeted content, and returns findings directly to the agent — enabling it to automatically remediate issues and retry the operation before the action is allowed to proceed. Remediation occurs automatically upon risk detection, with no need for user action to initiate it. The plugin is installed directly from the marketplace. The Checkmarx CLI is installed automatically as part of the process — the only requirement is authenticating with Checkmarx One. Once in place, the plugin runs automatically on all code generation performed by Codex CLI.

Realtime Scanners

This plugin currently runs the following scanners:

Prerequisites

  • A Checkmarx One account with a Checkmarx One Assist license. Also, Dev Assist must be activated for your tenant account in the Checkmarx One UI under Global Settings > Plugins page. This must be done by an account admin.

    Users will need to provide:

    • an API Key (see Generating an API Key), OR

    • login credentials (Base URL, Tenant name, Username and Password)

  • The IaC Realtime scanner requires having either Podman or Docker installed.

    Warning

    If both are installed, this will cause an error.

  • The plugin is based on the Checkmarx CLI which it installs automatically. However, it relies on host-provided dependencies that must be installed beforehand. The following table explains these requirements.

Requirement

Why it's needed

Windows

macOS

Linux

POSIX shell ( sh )

Runs the check script. On Windows this is Git Bash.

Git for Windows - mandatory

Warning

If this prerequisite is missing, the installation proceeds without error. But the Checkmarx tools aren't activated.

Tip

The following path must be set as an environment variable for the installation C:\Program Files\Git\bin.

Built in

Built in

Python 3 or above

Runs the readiness logic.

Install from python.org — not the Microsoft Store stub.

xcode-select --install or brew install python3

apt / dnf / apk install python3

curl or wget

Downloads the Cx CLI during install.

Bundled with Git for Windows

Built-in curl

Usually present; minimal images may need it

Connectivity Requirements

The following network connections must be available:

  • GitHub - https://github.com/Checkmarx/ast-cli This is needed specifically during download and version updates.

  • Checkmarx tenant URL - required for authentication, scanning, remediation etc.

  • Identity/sign-in host (IdP/auth URL) - for sign in, when using OAuth

Notice

If your environment requires an HTTP proxy for outbound network access, configure it using the http_proxy or CX_HTTP_PROXY environment variable.

Installation and Initial Setup

  1. Start running the Codex CLI terminal or Codex CLI TUI.

  2. Add the Developer Assist plugin in marketplace, using the following command:

    codex plugin marketplace add https://github.com/Checkmarx/cx-agentic-ai

  3. Verify that the the plugin was added, using the following command:

    codex plugin marketplace list

  4. Install the plugin using the following command:

    codex plugin add cx-devassist@cx-devassist-marketplace

    Notice

    During the installation, the plugin verifies that the minimum required version of the Checkmarx One CLI is installed. If it isn't already installed then it installs automatically.

  5. Restart the Codex CLI session so it re-reads config.toml and loads the plugin's hooks and skills. When prompted, trust the hooks.

  6. Confirm the plugin itself is installed: run /plugins in the Codex CLI TUI and select Checkmarx DevAssist for Codex — it should show as Installed under cx-devassist-marketplace, with its skills and hooks listed.

  7. Reload the plugin by running:

    /reload-plugins

  8. It is recommended to explicitly run the cx-cli-setup skill to initiate authentication. Otherwise, once you enter a prompt to generate code, the plugin runs automatically and prompts you to authenticate with Checkmarx. The prompt asks you to choose an Auth method. Options are API Key or Browser sign-in (OAuth).

    • For API Key (recommended), enter a Checkmarx One API Key. To generate an API Key, see Creating an API Key for Checkmarx One Integrations.

    • For OAuth, you will be redirected to browser-based login. You will need to specify your CxOne base url, tenant name, username and password.

      Notice

      If an MDM admin has configured a properties file for your tenant, then you won't be required to enter the base url and tenant name.

  9. Quit the Codex CLI session using /exit and relaunch it. You can use codex resume --last to continue the conversation. You do not need to register the MCP server manually, the agent registers it automatically first time a remediation tool is needed.

Optional Configuration

You can optionally customize the plugin functonality by adjusting the values of these variables. If not configured, sensible defaults are applied.

Variable

Purpose

CX_BINARY

Absolute path to cx when it is not available on PATH. The specified file must be a valid, recent, capable, and authenticated cx executable.

CX_GATE_ALL_FILES=1

Gate every file write, not just types the Checkmarx engines can scan — restores pre-scoping behavior.

CX_LOG_DIR

Overrides the log directory. The default directory is ~/.checkmarx/agent-logs/codex/.

CX_ALLOW_UNLICENSED=1

Allow writes to proceed (with a logged warning) when cx is authenticated but has no AI-scanning license, instead of denying — accepts that those writes are unscanned.

CX_LOG_DISABLE=1

Disables structured logging entirely.

CX_ASSISTANT

Specifies the assistant label used in logs. The hooks-hooks.json file sets this value to codex.

CX_REQUIRE_CHECKSUM=1

You can set cx-bootstrap.sh refuse to install an asset it can't checksum-verify.

CX_ALLOW_UNSCANNED=1

Enables an audited emergency bypass that runs the action without scanning and records the action in the audit log.

Updating the Plugin Version

You can update to the latest version of the plugin to make sure you have access to all of the latest improvements.

  1. Update the marketplace listing to pick up newly published plugin versions:

    codex plugin marketplace upgrade cx-devassist-marketplace

  2. Update the plugin to the latest version published on the marketplace:

    codex plugin remove cx-devassist@cx-devassist-marketplace

  3. Reload to activate the changes:

    /reload-plugins

Notice

The cx CLI itself updates independently. Run $cx-cli-setup if prompted, or manually upgrade via sh scripts/cx-bootstrap.sh upgrade from within the plugin directory.

Uninstalling the Plugin

If you choose to uninstall the plugin, you can either remove the entire marketplace registration, including removing the plugin using the following command:

codex plugin marketplace remove cx-devassist-marketplace/plugin marketplace remove cx-devassist-marketplace

OR, you can uninstall the plugin, but leave the marketplace registration in case you choose to reinstall it later.

codex plugin remove cx-devassist@cx-devassist-marketplace

Notice

Removing the plugin does not remove the cx CLI binary or its credentials/logs. To remove those as well, use:

:rm -rf ~/.checkmarx # Unix / macOS / WSL rmdir %LOCALAPPDATA%\Checkmarx # Windows PowerShell

Triggering Scans

Checkmarx Realtime scanners run automatically whenever Codex CLI performs an apply_patch call or uses the Checkmarx MCP tool. In addition, you can manually run the scanners by asking Codex to scan a file or check your dependencies. When you ask to scan a source code file, the ASCA scanner runs. When you ask to scan a manifest file, the OSS-Realtime scanner runs.

Notice

You can run the ASCA and OSS scanners explicitly by calling the dedicated skills $cx-devassist-asca and $cx-devassist-sca respectively.

Notice

Codex CLI's confirmed skill-discovery paths are .agents/skills (repo, user, and admin scope) — not a plugin-relative skills/ folder the way Claude Code and Copilot CLI auto-discover skills. This plugin ships skills/ for packaging/versioning, but you must symlink or copy its contents into .agents/skills for Codex to find them.

Troubleshooting

#

Error

Likely cause

Fix

1

Message says cx CLI is not installed or cannot be found.

cx is missing, or the plugin cannot resolve its path.

Run /cx-cli-setup. If cx version still shows "command not found" (exit code 127) right after, that is expected — do not re-run the installer. Proceed to use the plugin and see if the error persists.

2

Message says cx is older than the required version.

The installed cx is older than the minimum supported version for this plugin.

Run /cx-cli-setup — it detects the outdated build and upgrades automatically. Then run /reload-plugins so the remediation service picks up the new binary.

3

Message says required scanner commands are missing.

The installed cx build has the right version number but is missing the agent-security features. Re-running setup re-downloads the same build.

If you have access to an internal capable build, set CX_BINARY to its absolute path. Otherwise contact Checkmarx support.

4

Signed in but the very next action is immediately blocked (auth_pending_fresh_login).

Token propagation delay.

Wait ~30–60s and retry the SAME action. Do NOT sign in again — each sign-in cancels the previous token and restarts the wait, creating a loop.

5

Message says authentication to Checkmarx One failed.

Credential is missing, expired, or the tenant is unreachable.

Check the error text: invalid / unauthorized / 401 = credential; no such host / connection refused / timeout = network.

Credential: re-authenticate via /cx-cli-setup.

Network: check firewall, proxy, and tenant URL.

6

/mcp shows Checkmarx is not connected.

Remediation service started before cx was authenticated, or cannot reach the tenant URL.

Confirm cx sign-in is valid (cx auth validate), then run /reload-plugins followed by /mcp.

7

First file scan is slow or times out.

Scanner engine cold start — the first scan takes longer; subsequent scans are warm.

Retry the write. If it fails consistently, check tenant connectivity and proxy settings.

8

cx install fails — download error.

No route to GitHub, or proxy not applied to the install.

Set the proxy with export CX_HTTP_PROXY=<proxy-url> (or cx configure set --prop-name http_proxy), then re-run /cx-cli-setup. GitHub must be reachable for install; only the tenant URL is needed at runtime.

9

Every action is blocked with "Python 3 not found".

No usable Python 3. For Windows, may have Microsoft Store stub.

Install a real Python 3.

Windows: python.org (not the Store stub).

macOS: xcode-select --install or brew install python3.

Linux: apt / dnf / apk install python3.

10

In Windows, actions are running without any security check.

Git for Windows is not installed. The hook cannot start, and Codex CLI treats it as non-blocking — actions proceed unscanned with no warning.

Install Git for Windows. Verify by confirming Codex CLI's Bash tool works. The plugin isn't effective until this is in place.

11

Block message mentions an invalid CX_BINARY path.

The path is relative, does not exist, or is not executable.

Set CX_BINARY to a valid absolute path, or unset it to let the plugin resolve cx automatically.

12

cx version works in the terminal but actions are still blocked.

The gate uses the PATH from when Codex CLI launched, not the current terminal PATH.

Read the deny message — the reason is almost always authentication, version, or capability. Do not move binaries or edit PATH.

13

Blocked after credentials expire.

API keys expire after 30–365 days (tenant policy). OAuth tokens can also expire.

Run cx auth logout to clear the expired credential, then re-authenticate via /cx-cli-setup. No reinstall needed.

14

Actions blocked with a "pass-through" message after browser sign-in.

The scanner requires an API key credential, not a browser OAuth token.

Switch to an API key. Generate one in Checkmarx One under Settings → Identity and Access Management → API Keys (see Creating an API Key for Checkmarx One Integrations), then run /cx-cli-setup to set it.

15

Install stops with a checksum mismatch error.

The downloaded cx binary is corrupted or tampered with.

Always fatal — cannot be overridden. Re-run /cx-cli-setup to try again. If the mismatch repeats, contact Checkmarx support.

16

Remediation returns "unauthorized" right after re-signing in.

Re-signing in rotates the token; the remediation service may briefly hold the old credential.

This self-heals — the service re-reads the credential on its next call. Wait a moment and retry. No re-registration needed.

In this section: