Skip to main content

Cursor CLI Plugin

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

Realtime Scanners

This plugin currently runs the following scanners:

Prerequisites

  • Cursor CLI is installed and available on your system.

  • 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 ( 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. From your CLI terminal, add the Developer Assist plugin to Cursor agent marketplace, using the following command:

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

  2. Open Cursor and start the agent.

  3. In the Cursor agent, run the command /plugin, and select the Marketplace tab.

  4. In the marketplace, search for Checkmarx DevAssist for Cursor and select it.

  5. You will be prompted to select the scope for the installation. Options are:

    • Install for you (user scope)

    • Install for all collaborators on this repository (project scope)

  6. Run the skill for configuring hooks and rules, using the following command:

    /cx-install-wiring

    Notice

    This step is required due to a limitation in the Cursor CLI functionality.

  7. You will be prompted to select the scope for the hooks and rules. Options are:

    • Install for you (user scope)

    • Install for all collaborators on this repository (project scope)

    Notice

    During this process, 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.

  8. You will be prompted to authenticate with Checkmarx. The prompt asks you to choose an authentication method. Options are API Key or Browser sign-in (OAuth).

    Notice

    If for some reason this doesn't run automatically, you can trigger it using the cx-cli-setup command.

    • 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. Restart the agent by running the /exit command. This reloads the plugin hooks, rules, and MCP server.

  10. Confirm the setup is complete by running /mcp list in the agent. You should see Checkmarx listed as enabled.

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

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_GATE_ALL_COMMANDS=1

Disable the read-only-command and cx version/cx utils env diagnostic carve-outs, so every Shell command is evaluated by the gate's own logic (shell commands themselves are still never blocked by this gate.).

CX_LOG_DIR

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

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. Default: cursor

CX_REQUIRE_CHECKSUM=1

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

Triggering Scans

Checkmarx Realtime scanners run automatically on new code generated by Cursor CLI. In addition, you can manually run the scanners by asking Cursor 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, and IaC Realtime for IaC files.

Notice

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

Triggering Scans

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

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

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