Skip to main content

Copilot Plugin

Developer Assist for Copilot intercepts file writes and package installations performed by Copilot Code, 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 Copilot Code.

Prerequisites

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

    Checkmarx One users will need to provide:

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

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

  • 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 Setup

  1. Start running the Copilot CLI.

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

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

  3. Install the plugin using the following command:

    /plugin install checkmarx-devassist@checkmarx-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.

  4. You are prompted to specify the installation scope. Options are, user scope (the individual user), project scope (all collaborators) or local scope (only a specific repo).

  5. Restart the plugin by running:

    /restart

  6. It is recommended to confirm the installation by running:

    /plugin list

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

  8. Verify that the Checkmarx MCP is connected by running /mcp and checking the status of the Checkmarx MCP.

    Notice

    The MCP should start automatically by running a local proxy process (cx mcp bridge) that reads the customer's credential from the cx config, figures out the correct tenant-specific URL, and forwards remediation requests to Checkmarx over HTTPS with the credential sent only in the Authorization header. If the URL can't be derived automatically (some dev/on-prem hosts), set it explicitly with CX_MCP_URL or the --mcp-url argument.

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_LOG_DIR

Overrides the log directory. The default directory is ~/.checkmarx/agent-logs/<assistant>/.

CX_LOG_DISABLE=1

Disables structured logging entirely.

CX_ASSISTANT

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

CX_REQUIRE_CHECKSUM=0

Configures cx-bootstrap.sh to issue a warning and continue when it cannot verify a download checksum. Checksum verification is required by default. Disabling it is not recommended.

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:

    /plugin marketplace update checkmarx-devassist-marketplace

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

    /plugin update checkmarx-devassist@checkmarx-devassist-marketplace

  3. Reload to activate the changes:

    /restart

    Warning

    For Windows systems, updates can only be performed when Copilot is not running in any of your applications. If the process fails (os error 5), verify that you don't have any IDEs or other applications open that are using Copilot and then retry the command.

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:

/plugin marketplace remove checkmarx-devassist-marketplace

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

/plugin uninstall checkmarx-devassist@checkmarx-devassist-marketplace

Warning

For Windows systems, updates can only be performed when Copilot is not running in any of your applications. If the process fails (os error 5), verify that you don't have any IDEs or other applications open that are using Copilot, and then retry the command.

Triggering Scans

Checkmarx Realtime scanners run automatically on new code generated by Copilot. In addition, you can manually run the scanners by asking Copilot 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.

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 Copilot Code treats it as non-blocking — actions proceed unscanned with no warning.

Install Git for Windows. Verify by confirming Copilot Code'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 Copilot Code 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: