- Checkmarx Documentation
- Checkmarx One
- Checkmarx One User Guide
- Managing Projects
- Configuring Projects Using Config as Code Files
Configuring Projects Using Config as Code Files
Config as Code provides an additional level of scan configuration beyond Global Account Settings and Project Rules by enabling configuration through code-based files.
Before scanning, you can define scan behavior by placing a Config as Code file directly within the repository or ZIP file being scanned. These settings take precedence over the corresponding settings defined in Global Account Settings and Project Rules and apply only to the specific repository or ZIP scan that contains the configuration file.
Configuration Rules
The Config as Code
config.ymlfile supports the same parameters available in Global Account Settings and Project Rules. For the full list of parameters, see below.By default, Allow Override is enabled for all supported parameters across all configuration levels.
If Allow Override is disabled for a specific parameter in the Global Account Settings or the Project Rules, configuring that same parameter in the Config as Code
.ymlfile will have no effect.A parameter cannot be assigned multiple values within the same configuration level.
Parameters configured directly at scan runtime override the corresponding settings defined in the Config as Code file.
Configuring Repository Scans
In the target repository, create a
.checkmarxfolder.Inside the
.checkmarxfolder, create aconfig.ymlfile using the template below.Configure the required scanner parameters according to the Scanner Parameter Configuration Options tables below.
Save the file before running the scan.
Configuring ZIP File Scans
Create the ZIP file to be scanned.
Create a
.checkmarxfolder.Inside the
.checkmarxfolder, create aconfig.ymlfile using the template below.Configure the required scanner parameters according to the Scanner Parameter Configuration Options tables below.
Save the file.
Place the
.checkmarxfolder in the root directory of the ZIP file. If the folder is not located in the root directory, the Config as Code configuration will not be applied during the scan.
Creating ZIP Files from Repositories
Download the repository as a ZIP file. The repository must not already contain a
.checkmarxfolder.Follow the steps in Configuring ZIP File Scans above.
config.yml Template
Use the following template as the basis for your config.yml file:
version: 1
# checkmarx-specific related configuration
# every value in this section is optional
checkmarx:
scan:
configs:
sast:
presetName: 'ASA Premium'
fastScanMode: 'false'
incremental: 'false'
incrementalChangeThreshold: "10"
lightQueries: "false"
baseBranch: "main"
languageMode: 'multi'
filter: '!*.java,!*.cpp'
engineVerbose: 'true'
incrementalInBranch: "true"
recommendedExclusions: "true"
defaultConfigId: ""
sca:
filter: '!*.cpp'
vulnerabilityComparisonMode: "Branch-Based"
exploitablePath: 'true'
lastSastScanTime: '10'
javaLanguageVersion: "25"
pythonLanguageVersion: "3.13"
kics:
filter: '*.java'
platforms: 'Ansible,CloudFormation,Dockerfile'
presetId: '047be3a8-c9d6-4c02-90d5-c243418c7abc'
containers:
imagesFilter: ""
filesFilter: "!node_modules,!dist,!build"
packagesFilter: ""
nonFinalStagesFilter: "false"
apisec:
swaggerFilter: ''
microengines:
gitCommitHistory: "true"Scanners Parameters Configuration Options
SAST Scanner Parameters
The table below presents all the optional parameters for the SAST scanner and their optional values.
Notice
There is an additional configuration option for filtering, which compliance results to show. This can currently only be configured via REST API. See API documentation.
Notice
CLI flags are submitted on the scan level with the scan create command. API configs can be configured on the account or project level using the Configuration API or on the scan level as part of the request body of the POST /scans API. When using the POST /scans API the scan.config.sast prefix is left out.
Parameter | Values | Notes | CLI | API | Config as Code |
|---|---|---|---|---|---|
PresetName | All the available SAST Presets that exist in the system |
|
|
{
"key": "scan.config.sast.presetName",
"value": "ASA Premium",
"allowOverride": true
} |
|
Fast scan mode | true / false | By default, the Fast Scan mode is set to true. For more information, refer to Fast Scan Mode. |
|
{
"key": "scan.config.sast.fastScanMode",
"value": "true",
"allowOverride": true
} |
|
Light queries | true/false | Determines whether the scan should be performed using light queries or standard queries. Light Queries are simplified versions of standard queries focusing on the most urgent vulnerabilities, helping you spot threats faster. For more information, refer to Light Queries.
|
|
{
"key": "scan.config.sast.lightQueries",
"value": "true",
"allowOverride": true
} |
|
incremental | true / false | Determines whether the scan should be performed incrementally or as a full scan.
|
|
{
"key": "scan.config.sast.incremental",
"value": "true",
"allowOverride": true
} |
|
Recommended exclusions | true / false | Determines whether the system should automatically exclude certain files and folders from the scan. Enabled by default. By default, recommended exclusions is set to true.
| --sast-recommended-exclusions |
{
"key": "scan.config.sast.recomendedExclusions",
"value": "true",
"allowOverride": true
} |
|
LanguageMode | primary / multi | For more information, see: Specifying a Code Language for Scanning Supported Code Languages and Frameworks:
NoteBy default, the languageMode is Multi. |
{
"key": "scan.config.sast.languageMode",
"value": "primary",
"allowOverride": true
} |
| |
Folder/file filter | Allow users to select specific folders or files to include or exclude from the code scanning process. |
|
|
{
"key": "scan.config.sast.filter",
"value": "*.java",
"allowOverride": true
} |
|
EngineVerbose | true / false |
|
{
"key": "scan.config.sast.engineVerbose",
"value": "true",
"allowOverride": true
} |
| |
Results scope level | Project / Application | When you triage SAST results (change state, severity, comments), by default the adjustment applies only to identical results within that Project. You can adjust this setting to apply changes to all identical results in the entire Application. | |||
Threshold for Incremental Scans (%) | 0.5 - 10 (intervals of .5) | When running an incremental scan, if the changes from the previous scan exceed the threshold, a full scan is run. By default the threshold is 7%. Use this configuration to set a custom threshold. For more information, see Adjusting the Incremental Scan Threshold. |
{
"key": "scan.config.sast.incrementalChangeThreshold",
"value": "1",
"allowOverride": true
} |
| |
Incremental in branch (API) | true / false | When working with branches within Checkmarx GitHub Integration, if you open a pull request to merge into the master branch, you could run a faster incremental scan instead of a longer full scan. This capability is activated by configuring this setting to true. By default, it is false, so that only scans of the main branch are run as incremental. For more information, see Result Sco. |
{
"key": "scan.config.sast.incrementalInBranch",
"value": "true",
"allowOverride": true
} |
|
ASA Premium Preset
ASA Premium Preset is a part of the SAST collection of presets.
This Preset is available only for Checkmarx One. Its usage is described in the table below.
Preset | Usage | Includes vulnerability queries for.... |
|---|---|---|
ASA Premium | The ASA Premium preset contains a subset of vulnerabilities that Checkmarx AppSec Accelerator team considers to be the starting point of the Checkmarx AppSec program. The preset might change in future versions. The AppSec Accelerator team will remove old/deprecated queries or include new and improved queries in a continuously manner. | Apex, ASP, CPP, CSharp, Go, Groovy, Java, JavaScript, Kotlin (non-mobile only), Perl, PHP, PLSQL, Python, Ruby, Scala, VB6, VbNet, Cobol, RPG and VbScript coding languages. |
ASA Mobile Premium | The ASA Mobile Premium preset is a dedicated preset designed for mobile apps. The ASA Premium Mobile preset contains a subset of vulnerabilities that Checkmarx AppSec Accelerator team considers to be the starting point of the Checkmarx AppSec program. The preset might change in future versions. The AppSec Accelerator team will remove old/deprecated queries or include new and improved queries in a continuously manner. | Apex, ASP, CPP, CSharp, Go, Groovy, Java, JavaScript, Kotlin (non-mobile only), Perl, PHP, PLSQL, Python, Ruby, Scala, VB6, VbNet, Cobol, RPG and VbScript coding languages. |
Fast Scan Configuration
Fast Scan configuration aims to find the perfect balance between thorough security tests and the need for quick and actionable results. There’s no need to choose between speed and security.
Fast Scan mode decreases the scanning time of projects up to 90%, making it faster to identify relevant vulnerabilities and enable continuous deployment while ensuring that security standards are followed. This will help developers tackle the most relevant vulnerabilities.
While the Fast Scan configuration identifies the most significant and relevant vulnerabilities, the In-Depth scan mode offers deeper coverage. For the most critical projects with a zero-vulnerability policy, it is advised also to use our In-Depth scan mode.
Fast Scan mode is activated by default. It can be deactivated manually on the Tenant (Account), Project or Scan level.
Warning
To expedite the results retrieval, the scanning process has been optimized to reduce the number of stages and flows involved in the scan. With this enhancement, the queries related to ASPM are not executed and results won’t be generated when utilizing this mode.
You may also notice impact on the API Security scanner results.
Fast Scan limitations
Fast Scan is not advised for CPP, JS and Kotlin.
Faster scans are achieved at the expense of comprehensive results.
Differences in scan results are expected due to the methodology used by Fast Scan. It explores fewer flows compared to the "in-depth" mode, which may result in some vulnerabilities being missed or unique findings that differ from the standard scan.
When fast scan mode is enabled, the language mode always runs as Primary, and any SAST rule that sets languageMode to multi is ignored until fast scan mode is turned off.
Light Queries
Light Queries are simplified versions of existing queries that focus on the most exploitable vulnerabilities. They help you prioritize threats while filtering out uncommon edge cases for clearer analysis. Light Queries are not intended to replace the more robust standard queries but offer an alternative form of analyzing code by focusing on the most immediate threats and readily exploitable weaknesses as quickly as possible. These queries offer a more straightforward way to analyze code, giving you key findings without the complexity. The Light Queries have a more restrictive subset of results regarding inputs and sinks and a broader one regarding sanitizers.
Important
Consider the following when Light Queries are enabled:
The Similarity ID, source, and sync remain unchanged whether or not Light Queries are enabled.
When Light Queries are enabled, the scan results are a subset of those from a standard query (i.e., when Light Queries are disabled).
When scanning with Light Queries enabled, the scan will likely get fewer results.
Supported Languages and Detected Vulnerabilities
Light Queries support the following languages:
Java
JavaScript
Client_DOM_XSS
Client_DOM_Stored_XSS
Client_DOM_Code_Injection
Client_DOM_Stored_Code_Injection
Client_DOM_Code_Injection_from_AJAX
Client_DOM_XSS_from_Ajax
C#
The following vulnerabilities are detected in all the above languages when Light Queries are enabled:
SQL Injection
Reflected XSS
Enabling Light Queries
Enable Light Queries under the Account Settings page by setting its value to true. By default, Light Queries are set to false (disabled), and the Allow Override option is enabled.

When creating a new project, on the project settings page, you must enable Light Queries as a rule. To add Light Queries as a rule, perform the following:
Click + Add Rule. The scanner, mode, and value dropdown options appear.
Select SAST, light queries, and true for the scanner, mode, and value dropdowns.
Select Create Project when finished.

To delete a rule, click
at the end of the rule's row.
IaC Security Scanner Parameters
When configured globally, these parameters will apply to IaC Security scans across all projects. When configured at the project level, they will apply only to IaC Security scans for that project.
The table below presents all the optional parameters and their values.
Notice
CLI flags are submitted on the scan level with the scan create command. API configs can be configured on the account or project level using the Configuration API or on the scan level as part of the request body of the POST /scans API. When using the POST /scans API the scan.config.kics prefix is left out.
Parameter | Values | Notes | CLI | API | Config as Code |
|---|---|---|---|---|---|
Folder/file filter | Allow users to select specific folders or files to include or exclude from the code-scanning process. |
|
| scan.config.kics.filter {
"key": "scan.config.kics.filter",
"value": "*.java",
"allowOverride": true
} |
|
Platforms |
| NoticeConfigure one or more platforms, separated by a comma. The parameter means you only want to run scans (queries) for those platforms. For example, Ansible, CloudFormation, Dockerfile WarningAny mistake in the platform characters will cause an error. |
| scan.config.kics.platforms {
"key": "scan.config.kics.platforms",
"value": "GRPC",
"allowOverride": true
} |
|
Preset Name | All the available IaC Security Presets that exist in the system | There are no Checkmarx Default Presets now. For more information on IaC presets, see here. WarningThe preset ID for IaC Security must be a valid UUID. Once you create one, you can copy the PresetID from the IaC Presets page. |
|
SCA Scanner Parameters
When configured globally, these parameters will apply to SCA scans across all projects. When configured at the project level, they will apply only to SCA scans for that project.
The table below presents all the optional parameters, and their values.
Notice
CLI flags are submitted on the scan level with the scan create command. API configs can be configured on the account or project level using the Configuration API or on the scan level as part of the request body of the POST /scans API. When using the POST /scans API the scan.config.sca prefix is left out.
Parameter | Values | Notes | CLI | API | Config as Code |
|---|---|---|---|---|---|
Folder/file filter | Allow users to select specific folders or files that they want to include or exclude from the code scanning process. |
|
|
{
"key": "scan.config.sca.filter",
"value": "*.java,*.js",
"allowOverride": true
} |
|
Exploitable Path | Toggle On/Off | When Exploitable Path is activated, scans that use the SCA scanner will identify whether or not there is an exploitable path from your source code to the vulnerable 3rd party package. Learn more about Exploitable Path. |
|
{
"key": "scan.config.sca.ExploitablePath",
"value": "true",
"allowOverride": true
} |
|
Exploitable Path Configuration | Radio button selection | The Exploitable Path feature uses queries in the SAST scan of your project to identify exploitable paths to vulnerable 3rd party packages. Therefore, it is always necessary to run a SAST scan on the project in order to get results for Exploitable Path. Whenever you run a Checkmarx One scan with both the SAST and SCA scanners selected, Exploitable Path uses the results of the current SAST scan for analysis. When you run a Checkmarx One scan with only the SCA scanner selected, Checkmarx One can either use results from a previous SAST scan or it can initiate a new SAST scan (using default settings) that runs the Exploitable Path queries. Select one of the following configurations:
|
|
{
"key": "scan.config.sca.LastSastScanTime",
"value": "25",
"allowOverride": true
} |
|
New Vulnerability Comparison Mode | Project-Wide (default) or Branch-Based | Determines what is used as the base-line for determining whether or not a vulnerability is a New finding in the current scan.
|
{
"key": "scan.config.sca.vulnerabilityComparisonMode",
"value": "Branch-Based",
"allowOverride": true
} |
| |
Java Language Version | 8, 11, 17, 21 (default) or 25 | Specify the Java version used for dependency resolution for gradle package manager. This version does not affect Java version used for maven resolution. If not defined, gradle scans will run with Java version 21 by default. |
{
"key": "scan.config.sca.javaLanguageVersion",
"value": "17",
"allowOverride": true
} |
| |
Python Language Version | 2.7, 3.11, 3.12, 3.13 (default) or 3.14 | Specify the Python version used for dependency resolution for pip and poetry package managers. Poetry does not support Python prior to version 3, if version 2.7 is supplied, the default version is used instead. If not defined, scans will run with Python version 3.13 by default. |
{
"key": "scan.config.sca.pythonLanguageVersion",
"value": "3.12",
"allowOverride": true
} |
|
API Security Scanner Parameters
When configured globally, these parameters will apply to API Security scans across all projects. When configured at the project level, they will apply only to API Security scans for that project.
The table below presents the optional parameters, and their optional values.
Notice
API configs can be configured on the account or project level using the Configuration API or on the scan level as part of the request body of the POST /scans API. When using the POST /scans API the scan.config.apisec prefix is left out.
Parameter | Values | Notes | CLI | API | Config as Code |
|---|---|---|---|---|---|
Swagger folder/file filter | Swagger folder path or any folder/file type. Allow users to select specific folders or files that they want to include or exclude from the code scanning process. |
|
|
|
Container Security Scanner Parameters
Checkmarx One offers robust filter settings to enhance container security by enabling users to configure their scans for precision and relevance. Below is an overview of the four available filter settings, designed to reduce noise and focus on critical vulnerabilities in your scans.
The following table provides an overview of the functionality of each filter. Additional details about the usage and syntax for these filters is available in Filter Usage Details.
Notice
CLI flags are submitted on the scan level with the scan create command. API configs can be configured on the account or project level using the Scan Configuration APIs or on the scan level as part of the request body of the POST /scans API. When using the POST /scans API the scan.config.containers prefix is left out.
Filter name | Description | Syntax | Examples | CLI | API | Config as Code |
|---|---|---|---|---|---|---|
Folder/file filter | Specify files and folders to be included (allow list) or excluded from (block list) scans. You can create complex filters that combine include and exclude patterns. |
TipYou can submit multiple items separated by a comma. |
|
| scan.config.containers.filesFilter {
"key": "scan.config.containers.filesFilter",
"value": "*.yaml,*.yml",
"allowOverride": true
} |
|
Image/tag filter | Include or exclude images by image name and/or tag. |
TipYou can use wildcard (*) at the beginning, end or both. |
|
| scan.config.containers.imagesFilter {
"key": "scan.config.containers.imagesFilter",
"value": "!*test-image*",
"allowOverride": true
} |
|
Package Regex Filter | Prevent sensitive packages from being sent to the cloud for analysis. Exclude packages by package name or file path using regex. TipExcluded packages will nonetheless appear in the scan results. However, no vulnerabilities will be identified in those packages since their info wasn't sent to the cloud for analysis. | Regex |
|
| scan.config.containers.packagesFilter {
"key": "scan.config.containers.packagesFilter",
"value": "^internal-.*",
"allowOverride": true
} |
|
Exclude non-final stages filter | Exclude all images that are not from the final stage of the build process, so that only the final deployable image is scanned. TipOnly supported for Dockerfile images. | True - apply filter False - don't apply filter |
| scan.config.containers.nonFinalStagesFilter {
"key": "scan.config.containers.nonFinalStagesFilter",
"value": "true",
"allowOverride": true
} |
|
Secret Detection Configuration Options
The following table shows the configuration options available for the Secret Detection scanner. These configuration options can be applied on the Account > Project > Scan levels. These configurations can be set via the web application (UI), CLI or API, as shown in the table below.
In addition, the Secret Detection scanner supports a Configure as Code file, which can be added directly to the repository or included in the ZIP file being scanned. For more information, see Configuring Projects Using Config as Code Files
Notice
CLI flags are submitted on the scan level with the scan create command. API configs can be configured on the account or project level using the Scan Configuration APIs or on the scan level as part of the request body of the POST /scans API. When using the POST /scans API the scan.config.microengines prefix is left out.
Parameter | Values | Notes | CLI | API | Config as Code |
|---|---|---|---|---|---|
GIT commit history | true / false | When set to When set to For more information on scanning GIT commit history, see Git commit history |
|
Example: {
"key": "scan.config.microengines.gitCommitHistory",
"value": "true",
"allowOverride": true
} |
|