> For the complete documentation index, see [llms.txt](https://docs.sealsecurity.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sealsecurity.io/integrations/internal-scanners/checkmarx.md).

# Checkmarx integration

<figure><img src="/files/DEp0k44N8lsnpO5c1ICS" alt="Checkmarx" width="240"><figcaption></figcaption></figure>

The Seal CLI calls the Checkmarx API after every `seal fix` run and updates the corresponding findings in the targeted Checkmarx project. Vulnerabilities Seal has sealed are marked as remediated; vulnerabilities still open stay open.

## Before you start

* Checkmarx One credentials for the CLI: an API key, or an OAuth client (client ID and secret). The steps to create either are below. Use one or the other, not both.
* The Checkmarx project ID for the project Seal is sealing. In Checkmarx One, open the project and copy the ID from **Project Settings**, or from the project page URL.
* Your Checkmarx tenant URL. For the US hosted offering this is `https://ast.checkmarx.net`; regional tenants use their regional base URL (for example `https://eu.ast.checkmarx.net` or `https://deu.ast.checkmarx.net`). The CLI derives the matching IAM endpoint automatically.

## Creating the API key

A Checkmarx One API key has no permission settings of its own: it inherits the permissions of the user who creates it. Pick that user first, using the [permissions guidance](#which-permissions-the-key-needs) below, then create the key while signed in as that user.

1. Sign in to Checkmarx One as the user whose permissions the key should carry.
2. Go to **Settings > Identity and Access Management** (the Settings gear icon sits at the bottom of the left sidebar).

<figure><img src="/files/OODHK0O01s09A62NTSwT" alt="The Checkmarx One Settings menu with Identity and Access Management highlighted" width="220"><figcaption><p>Settings > Identity and Access Management.</p></figcaption></figure>

3. Open the **API Keys** tab and click **Create API Key**.

<figure><img src="/files/Z3HD30gLKfVgClHBT5FA" alt="The API Keys tab in Checkmarx One Identity and Access Management, with the Create API Key button at the top right"><figcaption><p>The API Keys tab under Identity and Access Management.</p></figcaption></figure>

4. Give the key a recognizable note (for example `seal-integration`) and click **Create**. The expiration period is enforced by your tenant settings.

<figure><img src="/files/isdbDFUtEKEaHuqtRULb" alt="The Create API Key panel with the Note and Expiration period fields" width="280"><figcaption><p>The Create API Key panel.</p></figcaption></figure>

5. Copy the key from the confirmation dialog immediately and store it in your secret manager. Checkmarx shows the key **only once**; if you close the dialog without copying it, you have to create a new key.

## Which permissions the key needs

Checkmarx One has over 200 permissions, from very granular to quite broad, and there is no single permission dedicated to this integration. What matters is the role of the user who creates the key:

* **Recommended**: create the key from a dedicated service user assigned the built-in **`ast-viewer`** and **`ast-scanner`** roles, plus a role that includes the state-change permission below.
* The specific action behind Seal's update is changing a finding's state to Not Exploitable, covered by the **`update-result-state-not-exploitable`** permission. Any role that includes it works.
* For enterprise setups that scope triage rights by team, use **`update-result-state-not-exploitable-if-in-group`** instead: it allows the same state change, limited to findings in the groups the service user belongs to. The broader `update-result-if-in-group` does not include the Not Exploitable state.

Admin credentials are not required. Avoid creating the key from an admin user: the key carries every permission its creating user has.

## Using an OAuth client instead of an API key

If your organization prefers service credentials over user-bound API keys, the CLI can authenticate with an OAuth client (client ID and secret) instead. This requires Seal CLI version 0.3.345 or later.

Unlike an API key, an OAuth client has its own role assignment, so its permissions do not depend on any user.

1. Go to **Settings > Identity and Access Management** and open the **OAuth Clients** tab.
2. Click **Create OAuth Client**, give it a recognizable name (for example `seal-integration`), and create it.
3. Copy the client ID and client secret from the confirmation dialog and store them in your secret manager. Checkmarx shows the secret **only once**.
4. In the client's **Role Mapping** section, assign the roles from the [permissions guidance](#which-permissions-the-key-needs) above: **`ast-viewer`**, **`ast-scanner`**, and a role that includes `update-result-state-not-exploitable`.

You also need your tenant name: the account name shown at **Settings > Identity and Access Management**, also visible in the Checkmarx One login URL after `/auth/realms/`. The API key flow reads it from the key itself, but an OAuth client carries no such information, so it must be configured explicitly.

## Configuration

Set these in your CI environment. With an API key:

```bash
export SEAL_CHECKMARX_URL=<your checkmarx tenant url>
export SEAL_CHECKMARX_TOKEN=<checkmarx api key>
export SEAL_CHECKMARX_PROJECT_ID=<checkmarx project id>
```

With an OAuth client:

```bash
export SEAL_CHECKMARX_URL=<your checkmarx tenant url>
export SEAL_CHECKMARX_CLIENT_ID=<oauth client id>
export SEAL_CHECKMARX_CLIENT_SECRET=<oauth client secret>
export SEAL_CHECKMARX_TENANT=<your checkmarx tenant name>
export SEAL_CHECKMARX_PROJECT_ID=<checkmarx project id>
```

Or in `.seal-config.yml` at the project root:

```yaml
checkmarx:
  url: <your checkmarx tenant url>
  token: <checkmarx api key>
  project-id: <checkmarx project id>
```

```yaml
checkmarx:
  url: <your checkmarx tenant url>
  client-id: <oauth client id>
  client-secret: <oauth client secret>
  tenant: <your checkmarx tenant name>
  project-id: <checkmarx project id>
```

The two credential types are mutually exclusive: set `token` or `client-id`/`client-secret`, not both. If both are set, the CLI skips the integration and logs a warning.

## Verify

After a `seal fix` run with the integration configured, open the targeted Checkmarx project's SCA results. On the **Risks** tab, every vulnerability sealed by that run is marked **Not Exploitable** and shown with a strikethrough, with a Seal-attributed comment in its Management of Risk history. Vulnerabilities that are not yet sealed, and findings from earlier runs or other projects, keep their previous state.

<figure><img src="/files/263IK5O3cxduE0ntrLvP" alt="The Checkmarx SCA Risks tab, with the vulnerabilities Seal sealed marked Not Exploitable and struck through, next to still-open To Verify findings"><figcaption><p>The Risks tab after a <code>seal fix</code> run: vulnerabilities sealed by the run are Not Exploitable and struck through; findings the run did not fix stay open.</p></figcaption></figure>

On the **Packages** tab, a package whose vulnerabilities were all sealed drops to zero aggregated risks; a partially sealed package keeps counting the vulnerabilities that are still open.

<figure><img src="/files/pP4VOY1QP6CkA7DbFvyx" alt="The Checkmarx SCA Packages tab, with a fully sealed package showing zero aggregated risks and a partially sealed package still showing one"><figcaption><p>The Packages tab: <code>netmask</code> is fully sealed (0 aggregated risks), <code>axios</code> is partially sealed (open risks still counted).</p></figcaption></figure>

Checkmarx recalculates the risk counters only on the next scan or scan recalculation, so freshly synced findings can show the strikethrough immediately while the summary counters catch up after a recalculation.

## Related

* [How CLI-driven sync works](/integrations/internal-scanners/how-cli-sync-works.md)