# Checkmarx

SureCloud connects to Checkmarx One (and Checkmarx SAST) to retrieve static application security testing (SAST) and software composition analysis (SCA) scan results, vulnerability findings, and project configuration. This allows SureCloud to verify that security scanning is being performed on your codebases, that identified vulnerabilities are tracked by severity, and that the scanning programme is running at the required cadence — providing evidence for secure development lifecycle controls.

## Authentication and setup

Checkmarx One authenticates API requests using OAuth 2.0 with client credentials. SureCloud uses a dedicated API client registered within your Checkmarx One tenant.

{% tabs %}
{% tab title="Checkmarx One (cloud)" %}
{% stepper %}
{% step %}
**Create an API client in Checkmarx One**

Log in to the Checkmarx One console. Navigate to **Access Management → API Keys** and click **Generate API Key**. Assign the **Viewer** role. Copy the **Client ID**, **Client Secret**, and note your **Tenant Name**. Also copy the IAM URL for your region (e.g. `https://iam.checkmarx.net`).
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Checkmarx → Connect (One)**. Enter the IAM URL, Tenant Name, Client ID, and Client Secret. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Checkmarx SAST (on-premises)" %}
{% stepper %}
{% step %}
**Create a service account in Checkmarx SAST**

Log in to the Checkmarx SAST portal. Create a user account (e.g. `surecloud-api`) with the **SAST Viewer** role, which provides read-only access to scan results and project data.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Checkmarx → Connect (SAST)**. Enter your Checkmarx SAST server URL, the username, and the password. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store credentials securely. SureCloud encrypts them at rest. Rotate them every 90 days and update in **SureCloud → Integrations → Checkmarx → Edit Connection**.
{% endhint %}
{% endtab %}
{% endtabs %}

## Endpoints

**Checkmarx One:**

| API Call                               | Use Case                                                              |
| -------------------------------------- | --------------------------------------------------------------------- |
| `GET /api/projects`                    | Enumerate projects and their scan configuration                       |
| `GET /api/scans`                       | Retrieve scan history including status, type, and completion time     |
| `GET /api/results`                     | Retrieve vulnerability findings per scan including severity and state |
| `GET /api/sca/riskmanagement/packages` | Retrieve SCA package risk findings and vulnerable dependency evidence |

**Checkmarx SAST:**

| API Call                               | Use Case                                            |
| -------------------------------------- | --------------------------------------------------- |
| `GET /cxrestapi/projects`              | Enumerate SAST projects                             |
| `GET /cxrestapi/sast/scans`            | Retrieve scan history and results                   |
| `GET /cxrestapi/sast/results/{scanId}` | Retrieve vulnerability findings for a specific scan |

## Pagination

`GET /api/projects` and `GET /api/results` use offset-based pagination. SureCloud increments `offset` by the page size until all records are retrieved.

```json
GET /api/results?offset=100&limit=100
```

## Required permissions

SureCloud requires read-only access to projects, scans, and results. No scan-trigger, triage, or project-management permissions are required.

## Polling frequency

| Data Type                  | Interval       |
| -------------------------- | -------------- |
| Project and scan inventory | Every 24 hours |
| Vulnerability findings     | Every 24 hours |
| SCA package risk findings  | Every 24 hours |

## Troubleshooting

<details>

<summary>Authentication fails with "invalid_client"</summary>

The Client ID, Client Secret, or Tenant Name is incorrect. Confirm all three values in **Checkmarx One → Access Management → API Keys** and update them in **SureCloud → Integrations → Checkmarx → Edit Connection**.

</details>

<details>

<summary>Scan results are empty despite completed scans</summary>

Results are only available after a scan has completed successfully. In-progress or failed scans will not have results. Confirm scan completion status in the Checkmarx console and trigger a manual SureCloud refresh after scans complete.

</details>

<details>

<summary>On-premises SAST server is unreachable</summary>

Checkmarx SAST is deployed on-premises. Confirm the server URL is accessible from the SureCloud collector network over HTTPS. Contact SureCloud Support for firewall requirements.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/checkmarx.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.