Bring Your Own Results (BYOR)

Overview

Bring Your Own Results (BYOR) is a powerful capability that enables organizations to enhance their application security posture by incorporating external vulnerability findings into their existing security ecosystem. This feature allows organizations to import vulnerability results from third-party security tools and services, regardless of their origin, if they adhere to a specific standard format: SARIF.

SARIF (Static Analysis Results Interchange Format) is a standard file format developed by OASIS Open to allow software security tools to provide static analysis results in a standardized, consistent and easy-to-consume format. SARIF allows developers to receive more accurate and useful information about software security vulnerabilities in their projects. It allows static analysis tools to generate results in a common format that can be imported and consumed by other vulnerability management tools and systems.

By incorporating these external results into Checkmarx One, organizations can gain a comprehensive view of their application security landscape, identifying and prioritizing vulnerabilities more effectively. These imported results are integrated into the Application Risk Management feature, providing organizations with a unified view of their application risk profile and enabling them to make informed decisions to secure their end-to-end application lifecycle.

Users can import external vulnerability findings into their application security workflow via CI/CD & CLI or API.

Using the SARIF format, organizations can easily import and consolidate vulnerability results from various sources. Our platform validates SARIF files against standards to ensure data integrity and consistency. To optimize performance and resource utilization, we set thresholds for the number of results and rules per import run. These limits prevent overload and ensure efficient data processing. For additional information, refer to SARIF file Limitations.

Permissions

To use the BYOR feature, a user must have either the ast-admin role or the following combination of roles and permissions:

ast-admin - Can do everything in Checkmarx One,
manage-project (Role) + manage application (Role) + view-risk-management (Permission) + import-findings-external-platforms (Permission).

SARIF file Specifications

Only a SARIF file or a ZIP file containing multiple SARIF files are supported for import.
The supported SARIF version is 2.1.0
To import a SARIF file or a ZIP file containing multiple SARIF files, there are mandatory fields that the user must ensure are present. Otherwise, the import will fail:
- Tool - A name field inside the tool field.
- SARIF provides a property called level within the result object to indicate the severity level. Common values include error, warning, and note.
- The ruleid property within the result object can be used to specify the identifier or name of the vulnerability.
Checkmarx One also consumes several other optional fields to provide more information about each result.
- There isn't a specific property for the timestamp of when a vulnerability first appeared in the SARIF file. However, you can include a timestamp in the run object to represent when the analysis was performed.
- SARIF doesn't have a dedicated field for assigning a result to a user. However, you can use a custom property or an extension to include this information.
- The related source code location of a result can be indicated using the location property.
- If the SARIF file contains a URL link or text for remediation, the information will be presented in the result's Remediation information.
- Fix URI for each result - The fixes array contains an object describing the remediation. The artifactChanges field specifies the changes to be made in the source code file to address the issue.
- If the information exist in the SARIF file, startLine, endLine, URI, and text will be presented in Checkmarx One Result information.

SARIF file Limitations

The maximum size for a SARIF file or ZIP file containing multiple SARIF files is 10 MB. Files over this limit are rejected.
SARIF data imported is also a subject to limits. If any of these limits are exceeded, the file is rejected.
- Runs per file - 20
- Results per run - 25000. Only the top 5000 results are persisted, ordered by by risk score.
- Rules per run - 25000
- Location per result - 100

Feature Flow

Bring your own results flow is as follows:

Create a SARIF file or a ZIP file containing multiple SARIF files for the import.
Import the SARIF file or the ZIP file containing multiple SARIF files to Checkmarx One using the CLI tool or API.
A validation will be performed. If all fields match and are correct, the information is parsed and sent to Checkmarx One.
The results are displayed in Checkmarx One's Risk Management feature, among the top fifty results.
Users can drilldown into the results via Application Risk Management feature.
if you need to import more files into the same Checkmarx One Project, please take into consideration that we don't keep a history and we will present always the most updated SARIF content per tool.

Import Procedure

Importing a SARIF file or a ZIP file containing multiple SARIF files can be done using the CLI or API.

SARIF Import using CLI

To import a SARIF file using Checkmarx One CLI tool, proceed as follows:

Download Checkmarx One CLI Tool.
Open Command Prompt or Terminal on your local laptop/PC.
Navigate to the SARIF file path.
```
cd <file path>
```
Run the cx configure command.
```
<file path> ./cx configure
```

Configure your authentication parameters:

AST Base URI [https://eu.ast.checkmarx.net/]:
AST Base Auth URI (IAM) [https://eu.iam.checkmarx.net/]:
AST Tenant []:
Do you want to use API Key authentication? (Y/N): Y
AST API Key []

Run the cx utils import command using --project-name and --import-file-path flags.

<file path> ./cx utils import --project-name "<project name>" --import-file-path <file path>

SARIF Import using API

You can import a SARIF file using the POST /api/imports REST API. For the end to end workflow for importing results via API, refer to our API documentation.

Verifying Results

After the import is completed, you can assess the results inside the Application Risk Management feature.

The screenshot below reflects a scenario of an empty Project with no scan results. In this case, the SARIF file contains only four results. The Application Risk Management feature displays up to the top fifty most risky results, including those from both BYOR and Checkmarx One scanners.

Clicking on a result will open it in its own tab, displaying three sections with information retrieved from the optional fields in the SARIF file.

If some sections do not display information, it means the information is missing from the SARIF file.

For example:

In this section: