- Checkmarx Documentation
- Checkmarx One
- Checkmarx One User Guide
- Scan Management
- SAST Query Editor
SAST Query Editor
Overview
Checkmarx Audit complements Checkmarx SAST by enabling you to easily and intuitively customize SAST’s analysis queries or configure your additional queries for:
Security
Application logic purposes.
Audit can be used to adapt SAST’s basic security functionality to non-standard code. This helps in eliminating false positives and ensuring that all real vulnerabilities are identified. Audit can also be used for expanding SAST’s functionality to include queries for supporting specific QA or application logic needs.
For more information, see Audit Overview.
Note
The queries in the Common category cannot be edited in the Query Browser.
Accessing Query Editor
The first two methods described below open the Query Editor associated with a project. The last method opens the Query Editor independent of any project.
To access Audit, perform one of the following:
From Applications and Projects
From the Applications and Projects list, navigate to the project you want to examine.
Click on the Action icon on the right end of the project row.
From the drop-down menu, click Edit Queries.
The Query Editor opens. Wait for the scan to complete.
If you prefer a dark screen, you can toggle Night Mode.
From the Project Panel
From the Applications and Projects list, navigate to the project you want to work on.
Click anywhere in the project row. The right panel appears.
In the SAST section of the panel, hover over the Actions icon, located to the left of the Overview and Results buttons.
Click on Audit Scan in the drop-down menu.
The Query Editor opens. After the Query Editor scans the project, it is ready to use.
From the Left Navigation Bar
In the left navigation bar, click on the Scan Management icon.
From the sub-menu that appears, click on Query Editor.
The Query Editor opens. It is not associated with any project.
Viewing the Project Code
To view the project code, perform the following:
In the Project area, you can drill down to see the packages contained in the project and the code snippets in the packages.
To see the code, click on the filename in the hierarchy. A tab opens, displaying the code.
Viewing the Query Code
To view the query code, perform the following:
In the lower section of the screen, on the Queries tab, you can open the list of languages relevant to the project by expanding Query Browser.
Drill down to see the individual queries relevant to the project.
To see the query source code, click on the query name in the hierarchy. A tab opens, displaying the query source code.
If there are many lines of code, use the query code scroller on the right to navigate to a particular section in the code quickly.
Running a Query
When you first open the Audit page, the Results tab is blank. It will remain blank until you run a query that returns results with vulnerabilities in the project code.
To run a query, perform the following:
Select the Queries tab, select the query from the hierarchy you want to run on the project, and click Run Query.
Wait for the query to finish running.
After the query finishes, the Results tab is displayed in one of the following modes:
If no results are found, a zero (0) is displayed after the query's name, and the No results found message is displayed in the first line of the Results sub-tab.
If results are found, the number of results is displayed after the query's name, and the line numbers where the vulnerabilities occur are displayed in the Vulnerabilities tab. In the Project pane, the vulnerable lines of code are displayed.
Creating and Running an Override Query
Default Checkmarx queries are not editable. They are listed under the Cx folder and marked in the tab with the Checkmarx logo, as shown below:
Instead, an option is available for creating override queries based on any Checkmarx queries, except for the Common queries. When you create an override query, its source code is copied from the selected Checkmarx query, which you can modify and apply to the tenant, application, or project-level scans.
When you do not want to run and apply a certain query in a project, you can override it with an override query, which will run instead. This method is useful, especially for testing purposes. Likewise, you can override tenant and application-level queries.
Overriding a query at the tenant level will also override the query for all applications and projects in that tenant.
Overriding a query at the application level will also affect the projects in that specific application. This option Override per Application will be visible when the application does not include any multi-application projects. To avoid confusion, in cases where the application includes a project associated with multiple applications, the option Override per Application will be disabled and hidden.
Overriding a query at the project level only applies to that project.
Note
As a general rule, a query applied at a lower level takes precedence over a higher level one. If you override a query at the tenant level, you can still apply a different query at the application or project level.
To create and run an override query, perform the following:
Click on the query in the Queries tab.
Right-click on the query source code, and from the pop-up menu, select the override scope, which can be either Tenant, Application, or Project.
As shown below, a new query is added to the tab panel with a pre-filled source that calls the base query. Because the queries share the same name, the Checkmarx logo is replaced with a tenant, application, or project icon.
Tenant Override:
Application Override:
Project Override:
Edit the query code in the tab.
For example, a user is increasing the maxValue to 150000, as shown:
The asterisk in front of the query name in the tab title indicates that the query has been changed but not saved.
Save the override queries by clicking . The Save modified queries panel opens. Select the modified queries and click Save or click Save all modified.
The left panel is updated with the new queries.
To check the effects of the changes, click Run Query.
When the project is re-scanned, the modified query will be used.
After modifying one or more queries, click Rescan to rescan the project with the modified queries and check the results of the changes.
Creating a New Query
New queries can be created using the Query Editor.
To create a new query, perform the following:
Select the Queries tab.
Click on the New Query button. The Properties panel opens at the right of the screen.
Enter the following information in the Properties panel.
Name of new query
Severity
Language
CWE ID (Optional)
Level
Group Name
Presets (Select one from the drop-down list of customized presets.)
Executable
Description ID (Optional)
Close the panel to save the information. The information can be edited later by opening the Properties panel with the Properties button.
Enter the new query code in the tab labeled with the name of the new query.
Test the new query and make changes if necessary.
Click to save the new query. The new query will be listed in the Query list under the language and group name that you specified in the Properties panel.
Changing the Severity of a Scan
By following these steps, you can change the severity of a new and overridden query and view the updated severity flags in the query results after running a scan.
Open the desired query: Access the queries editor or the list of queries and locate the specific query you want to modify.
Open the query in the editor: Select the query you want to change and open it in the query editor. This allows you to view and modify the query details.
Click on Properties to access the properties of the query.
Click on the Severity dropdown and select the severity that accurately represents the query.
Save the modified query: After changing the Severity value, save the modified query to apply the changes.
Exit the Queries Editor: Once the query is saved, exit the queries editor by closing the editor window.
Run a regular SAST scan: Perform a regular SAST scan using the updated query configurations.
Check the query results: After the scan is completed, review the results to see the impact of the modified query. The findings of vulnerabilities identified by the query will be flagged with the updated severity level that you assigned.
You can download the current SAST scan logs by selecting the Download Logs button on the WebAudit page. These logs assist your support engineers in troubleshooting the audit in case of an error or failure.
When the Query Editor is opened without any project, the Download Logs button (located near Rescan in the top right corner) will be disabled.
Download Logs will be enabled when the SAST scan starts running, and a ZIP file is uploaded.
During the language detection process, the Download Logs button will be enabled. However, accessing any SAST scan log will not be possible and will display an error message: Failed to get log. It's important to note that the Query Editor is directly accessed from the Project Scan page.
Once the project scan is completed, the Download Logs button will enable you to obtain the SAST scan logs in TXT format.