Skip to main content

Scanning Projects

Once a project is configured, you can run a scan within that project. Each time a scan is executed, the source code is uploaded as part of the scanning procedure.

There are 2 options to perform a scan:

  • Scan a “zipped file”

  • Scan a repository path - GitHub, GitLab, Bitbucket, Azure DevOps.

When a scan is executed, it is necessary to specify which branch of the project is being scanned.

You can also add tags to the scan. Tags are very useful for project filtering purposes.

Tagging has no dependencies in any other component, and it is possible to configure any required value.

Running a Scan

Notice

Initiating a scan is possible only within an existing project.

There are three options to scan a source file:

  • Scan a source file from a repository URL.

  • Scan a source file from a zipped file.

  • Scan an existing project (repository URL/zipped file).

Scan Process

When a scan is run using multiple scanners, all scanners run in parallel.

When multiple scans are run in your account, the number of concurrent scans is specified in your account's license. This info is available under Account Settings > License > License Plan Summary. When the limit is exceeded, the scans are added to a queue which runs on a "first in first out" basis.

To run a scan:

  1. On the Application and Projects home page select the Projects tab.

  2. Hover over the row of the project that you would like to scan, click on the Scan icon Scan_Management.png.

    Image_942b.png

    The New Scan window opens. By default, under Project Name, the project of the row in which you clicked the Scan iconScan_Management.png is selected.

    Image_947.png

    Notice

    If you would like to scan a different project, it is possible to select it from the drop-down menu.

  3. In the Source to Scan section, there are 2 scan options:

    • Scan from a zipped or tared file:

      • Select the File option and click the Select File link.

        Select_zip_Scan.png

      • Select the requested zip archive file.

        File_Uploaded.png

      • Branch (Optional) - Set the branch name for the scanned zip archive file, if needed.

      • Scan Tags (optional) - Add a tag to the new scan.

        Tags can be added in two different formats:

        Label: <string>

        key:value: <key string:value string>

        Tags can be used also for overriding Jira feedback app fields values. For additional information see Fields Override

        Scan_Tags_1.png

    • Scan a Repository URL:

      • Click on Repository.

      • Enter the Repository URL.

      • Click on Fetch Branches.

      Select_Repo_Scan.png

    • Type your Personal Access Token and click Login.

      Type_Token.png

    • In case that the Token is incorrect, an error will be presented while trying to connect.

      Wrong_Token.png

    • Scan Tags - Add a tag to the new scan (optional).

      Tags can be added in two different formats:

      Label: <string>

      key:value: <key string:value string>

      Tags can be used also for overriding Jira feedback app fields values. For additional information see Fields Override

      Scan_Tags_2.png

  4. Select Completed.png Incremental Scan, if you want to scan only the latest changes and not the entire project. For additional information on Incremental scans, refer to Incremental Scans (SAST Scanner).

  5. Click Next. The New Scan dialog appears and you are asked to select the scanners.

  6. Select one or more scanners.

    Image_982.png

  7. Click Scan. The New Scan dialog closes and the scan starts.

  8. You can monitor the scan's status in the Projects tab when hovering over the project.

    Image_948.png

Note

  • Only API Security and SAST support incremental scans. Selecting additional scanners will run their full scans.

  • API Security currently supports Java - Spring and AST.NET - Web API, and Python - Flask.

  • If you select API Security, SAST is selected as well because API Security utilizes the SAST code to detect APIs.

Incremental Scans

Definition

Notice

Incremental scans are relevant only for the SAST scanner.

An incremental scan is a mechanism to scan a small portion of code to deliver fast results. This mechanism scans only the code that was changed from the last full scan and any code close to it (called "closure").

If an incremental scan is run, but more than 7% of the project's files have changed since the last full scan, a full scan is run instead.

Notice

With every incremental scan, the changes from the last full scan are accumulated.

How does it work?

The results of every incremental scan are merged with its base full scan to provide a complete result set for the whole code. To understand the merge, we need to understand the different types of results. In the diagram below, only the "Changed files" and the "Closure files" are scanned by the incremental scan.

Each black line represents one result, flowing through several nodes:

6405128331.png

  • A – All of the result nodes are inside the changed files. New results like this returned from an incremental scan are "good results" that the total scan is expected to find.

  • B – All of the result nodes are inside the closure files. New results like this returned from an incremental scan are "bad results" because these files weren't changed, so there cannot be a new result here. These result types are removed because they are filtered in the incremental scan, and the remaining results are those in at least one of their nodes inside the changed files (A, D).

  • C – All of the result nodes are outside the closure files. The incremental scan cannot find these because these files are not scanned. The last full scan results are merged with the incremental scan results and shown as "recurrent.”

  • D – The result nodes are inside both the changed and closure files. New results returned from an incremental scan are "good results" that the incremental scan is expected to find.

  • E – The result nodes are both inside and outside the closure files. The incremental scan cannot find this kind of result because some result files are not scanned. The last full scan results are merged with the incremental scan results and shown as "recurrent.”

  • F - The result nodes are inside the changed files, the closure files, and the closure files. The incremental scan cannot find this kind of result because some result files are not scanned. The last full scan results are merged with the incremental scan results and shown as "recurrent.”

Running Incremental Scans

There are several ways to run an incremental scan. The following are some of the possible methods.

  • Project Settings - Go to Project Settings > Rules and create a Rule for the SAST scanner to run incremental scans. You can set whether or not this setting can be overridden when running an individual scan.

  • Running a scan - When manually initiating a scan of a Project, you can select the Checkbox for Incremental scan.

  • CLI - When running the scan create command from the CLI, you can add the flag --sast-incremental to run an incremental scan.

  • API - When running POST /scans, set the config value for sast scans as "incremental":"true".

  • IDE - When a scan is initiated from the IDE (as described here) it automatically runs as an incremental scan.

Limitations

  • Incremental scans are only relevant for the SAST scanner. All other scanners always run full scans.

  • An incremental scan can only run after an initial full scan of the Project has been run.

  • If more than 7% of the Project's files have been changed since the last full scan, then even if incremental scan is specified it will run as a full scan.

Incremental Scans in Branches

When working with branches within CX 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.

It’s recommended to meet the following before running an incremental scan:

  • Always have the base branch (master) run a full scan (preferably by every commit)

  • Before every commit made to a pull request, rebase and merge from the base branch (master) to your branch

Note: Incremental scans are most effective when the pull request source branch (master) is up-to-date with the pull request branch, and regular full scans are performed on the base branch (master) for accuracy. The existing logic prioritizes the most recent full scan in the two branches.

API

  • POST api/scans

    • in sast config payload, send a value for baseBranch (no changes needed)

      "config":[{"type":"sast","value":{"incremental":"true","baseBranch":"master"}}]

Empty Scans - SAST Scanner

Checkmarx One has Improved the accuracy and visibility for empty scans.

Checkmarx One has updated the way it handles scan status returned by SAST when no files are found to scan. When SAST identifies a scan with no files to scan, it returns a specific code that clearly indicates that the scan is empty because no files were found.

Checkmarx One treats such scans as successful. As a result, the status of each scan is represented more accurately, providing a reliable overview of the security status across all projects.

Scan Limitations

Limitation

  • There is a 22M LOC (Line of Code) limitation for repository/zip files scans. In case that the source file contains more than the limit permits we block the scan and an error message is displayed.

  • There is a 5.5M LOC (Line of Code) for IaC Security. This allows seamless integration and utilization of IaC Security LOC metrics in generating reports and applying the maximum LOC logic within both multi-tenant and single-tenant environments.

  • The IaC Security scanner does not support scanning of minified files.

  • Checkmarx One supports repositories clone using SSH and HTTPS protocols.

    • Cloning using HTTPS protocol:

      • If the repository is private a token needs to be provided.

      • If the code contains submodules, the submodules also need to use HTTPS.

      • If any of the submodules is private the same key needs to grant access to the private submodule.

      • For security reasons, no token will be sent to submodules on a different SCM.

        For example: scanning a GitHub repository with a GitLab submodule will only work if the submodule under GitLab is public.

    • Cloning using SSH protocol:

      • A key needs to be introduced to access the repository.

      • If the code contains submodules using SSH, the same SSH key needs to grant access to the submodules.

      • If the code contains submodules using HTTPS, they should be public.

  • The sub-module's address in .gitmodules file contains 1 or more info like the one bellow. The URL part can be a HTTPS or SSH.

    [submudule "src/MongoDB"]
    path = src/MongoDB
    url = git@github.com:docker-library/mongo.git

  • Max Concurrent scans per Checkmarx One environment - The system can handle up to 5000 concurrent scans simultaneously, ensuring smooth operation without failures or significant latency in scan time.

    The amount of concurrent scans appear in License Consumption

  • Queued scans - Checkmarx One restricts the number of queued scans per license. By default, 1000 queued scans are configured, and it can be upgraded to up to 2000 queued scans.

    The minimum number of queued scans that can be configured is 1. If the queue reaches its limit, a failure message will be displayed.

    The amount of queued scans appears in License Consumption

  • API Security currently supports Java - Spring 2.x and C# - ASP.NET 4.x Web API only.

Error Message

In case that the below error message appears during the scan, it usually means that the scan was triggered using HTTPS but a SSH submodule was found. So, the scan needs to use SSH protocol instead of HTTPS.

fetch-sources clone 'branch' failed, provided value:master : error creating SSH agent: "SSH agent requested but SSH_AUTH_SOCK not-specified"

Workaround

Changing the submodule's address inside .gitmodules file to HTTPS format, resolves the issue, but generally the best and accepted solution would be to use SSH.

In this section: