Copilot CLI Plugin
Developer Assist for Copilot CLI intercepts file writes and package installations performed by Copilot Code, scans the targeted content for vulnerabilities and exposed secrets, 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.
Realtime Scanners
This plugin currently runs the following scanners:
ASCA (source code) - a lightweight scanner that identifies secure coding best practice violations in individual files and code snippets, including AI-generated code.
OSS Realtime - scans dependency manifest files for vulnerable and malicious open source packages.
IaC Realtime - scans infrastructure-as-code files for configurations that could leave the resulting resources insecure.
Secrets Realtime - detects hardcoded credentials, tokens, and keys in the files Copilot writes. Secrets are checked in any file type, including
.envand.propertiesfiles.Important
The plugin never prints the secret value when it reports or fixes a finding.
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 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 ( | Runs the check script. On Windows this is Git Bash. | Git for Windows - mandatory WarningIf this prerequisite is missing, the installation proceeds without error. But the Checkmarx tools aren't activated. TipThe following path must be set as an environment variable for the installation | Built in | Built in |
Python 3 or above | Runs the readiness logic. | Install from python.org — not the Microsoft Store stub. |
|
|
| Downloads the Cx CLI during install. | Bundled with Git for Windows | Built-in | Usually present; minimal images may need it |
Connectivity Requirements
The following network connections must be available:
GitHub -
https://github.com/Checkmarx/ast-cliThis 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
Start running the Copilot CLI.
Add the Developer Assist plugin in marketplace, using the following command:
/plugin marketplace add https://github.com/Checkmarx/cx-agentic-ai
Install the plugin using the following command:
/plugin install 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.
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).
Restart the plugin by running:
/restart
It is recommended to confirm the installation by running:
/plugin list
It is recommended to explicitly run the
cx-cli-setupskill 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 anAuth method. Options areAPI KeyorBrowser 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, you won’t be required to enter the base URL and tenant name. You can also set these values yourself. See Pre-Configuring Base URL and Tenant.
Verify that the Checkmarx MCP is connected by running
/mcpand 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.
Pre-Configuring Base URL and Tenant
When you sign in with your browser (OAuth), the plugin needs your Checkmarx One base URL and tenant name. If you set them in cx-onboarding.properties, you are not asked for them at sign-in. API key sign-in does not use these settings.
The file is the same one described in Scanner Settings. Add the following lines to it:
cx_base_auth_uri=https://eu.ast.checkmarx.net cx_tenant=your-tenant
cx_base_auth_uri: the URL of your region's Checkmarx One environment. It must start withhttps://and contain only the host, with no path (for examplehttps://eu.ast.checkmarx.net, nothttps://eu.ast.checkmarx.net/auth).cx_tenant: your tenant (account) name. It must start with a letter or digit, contain only letters, digits,.,_and-, and be at most 64 characters. To find it, open Checkmarx One and go to Settings → Identity and Access Management → General Settings (shown as "Display Name"), or see the "Account name (Tenant name)" line in your Checkmarx One welcome email.
Use the base URL for your region:
If a value is missing or invalid, the plugin ignores it and asks you at sign-in as usual. If your administrator has pre-configured these values for your tenant, they are used automatically, and a value you set in your own file takes priority.
Optional Configuration
You can optionally customize the plugin functionality by adjusting the values of these variables. If not configured, sensible defaults are applied.
Variable | Purpose |
|---|---|
| Absolute path to |
| Overrides the log directory. The default directory is |
| Disables structured logging entirely. |
| Specifies the assistant label used in logs. The |
| Configures |
| 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.
Update the marketplace listing to pick up newly published plugin versions:
/plugin marketplace update cx-devassist-marketplace
Update the plugin to the latest version published on the marketplace:
/plugin update cx-devassist@cx-devassist-marketplace
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 cx-devassist-marketplace
OR, you can uninstall the plugin, but leave the marketplace registration in case you choose to reinstall it later.
/plugin uninstall cx-devassist@cx-devassist-marketplace
Warning
For Windows systems, uninstall 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.
Scanner Settings
You can turn individual scanners off, or raise the minimum severity the plugin acts on, by editing cx-onboarding.properties in the .checkmarx folder in your home directory:
macOS and Linux:
~/.checkmarx/cx-onboarding.propertiesWindows:
%USERPROFILE%\.checkmarx\cx-onboarding.properties
The plugin creates this file the first time it runs after installation. It is never overwritten, so your changes are kept when you update the plugin. To restore the defaults, delete the file and the plugin recreates it.
Setting | Default | Description |
|---|---|---|
|
| Turns the ASCA scanner (source code) on or off. |
|
| Turns the OSS Realtime scanner (dependency manifests) on or off. |
|
| Turns the IaC Realtime scanner (infrastructure-as-code files) on or off. |
|
| Turns the Secrets Realtime scanner (hardcoded secrets) on or off. |
|
| Lowest severity at which the plugin blocks an action and reports findings. Valid values: |
Set a scanner setting to false to turn it off. Every scanner is on by default. Any value other than true or false is treated as true, so a misspelled value never turns scanning off.
Notes:
When the secrets scanner is off, files that only it would scan (for example
app.env) are no longer held until a scan runs.To skip a disabled scanner in the Checkmarx CLI's own pre-write scan as well, use a current version of the Checkmarx CLI. Older versions ignore these settings.
Notice
The same file can also pre-fill your sign-in details. See Pre-Configuring Base URL and Tenant.
Triggering Scans
Checkmarx Realtime scanners run automatically on new code generated by Copilot CLI. In addition, you can manually run the scanners by asking Copilot to scan a file or check your dependencies. The scanner that runs depends on the file type: ASCA for source code files, OSS-Realtime for manifest files, IaC Realtime for IaC files, and Secrets Realtime for any other file.
You can also enter specific natural language prompts. For example, to scan for hardcoded secrets, ask Copilot to "scan for secrets" or "check .env".
Notice
You can run the ASCA, OSS, IaC and Secrets scanners explicitly by calling the dedicated skills $cx-devassist-asca, $cx-devassist-sca, $cx-devassist-kics and $cx-devassist-secrets respectively.
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 |
2 | Message says cx is older than the required version. | The installed cx is older than the minimum supported version for this plugin. | Run |
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 |
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 Network: check firewall, proxy, and tenant URL. |
6 |
| Remediation service started before cx was authenticated, or cannot reach the tenant URL. | Confirm cx sign-in is valid ( |
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 |
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: Linux: |
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. Secrets scanning is also skipped while actions proceed unscanned. | 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 | The path is relative, does not exist, or is not executable. | Set |
12 |
| 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 |
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 |
15 | Install stops with a checksum mismatch error. | The downloaded cx binary is corrupted or tampered with. | Always fatal — cannot be overridden. Re-run |
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. |
17 | A scanner does not run. | The scanner may be turned off. | Check that its |
18 | Low-severity findings are not reported. |
| Lower it to see them. |
19 | You are still asked for the base URL and tenant at sign-in. |
| Check both values in |
20 | Changes to | Edit the file in your |