Skip to main content

Scanning Projects

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

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 needed to specify which branch of the project is being scanned.

You can also add tags to the scan. Tags are very useful for projects 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 (default).

  2. In the row of the project that you would like to scan, click Scans.png Scan.

    Image_942b.png

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

    Image_947.png

    Notice

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

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

    1. Scan from a zipped file:

      • With the File option selected (default), click the Select File link.

      • Select the requested zip archive file.

      Select_zip_Scan.png
      File_Uploaded.png
    2. Scan a Repository URL:

      • Click the Repository button.

      • Enter the Repository URL.

      • Click Fetch Branches button.

      Select_Repo_Scan.png
    3. Type your Personal Access Token and click Login

      For example:

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

      For example:

      3214115088.png
  4. Under 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 ???

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

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

  7. Select one or more scanners.

    Image_982.png
  8. Click Scan. The New Scan dialog closes and the scan starts.

  9. You can monitor the scan's status in the Projects tab.

    Image_948.png

Note

  • Only API Security and SAST support incremental scans. If you select additional scanners for an Incremental Scan, a full scan is performed instead.

  • 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 (SAST Scanner)

Definition

Notice

Incremental scans are relevant only for the SAST scan type.

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

If an incremental scan is run, but more than 7% of the project’s files that 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 the results of 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 incremental 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 results types are removed because they are filtered in the incremental scan and the remaining results are those that at least one of their nodes inside the changed files (A, D).

  • C – All of the result nodes are outside the closure files. These cannot be found by the incremental scan because these files are not scanned. Results from the last full scan are merged with the incremental scan results and shown as “recurrent”.

  • D – The result nodes are inside both the changed files and the closure files. New results like these 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. This kind of result cannot be found by the incremental scan because some of the result files are not scanned. Results from the last full scan are merged with the incremental scan results and shown as “recurrent”.

  • F - The result nodes are inside the changed files, inside the closure files, and also outside the closure files. This kind of result cannot be found by the incremental scan because some of the result files are not scanned. Results from the last full scan are merged with the incremental scan results and shown as “recurrent”.

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

  • 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 = [email protected]:docker-library/mongo.git
  • There is a 10M 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.

    LOC calculation is performed after filtering is applied in scans, including within the CLI. This workflow helps ensuring that scans are not prematurely terminated due to exceeding the maximum allowed LOC limit in Checkmarx One.

    LOC is calculated as a combination of SAST and IaC scanners together. The 10M limit is for the combination of both.

    For example: If a user is scanning a project using SAST (9M) + IaC (3M) within the same scan, the scan will fail.

    It also provide users the following business values:

    • Improved efficiency - More efficient scanning processes by avoiding unnecessary calculations on code that is going to be filtered out, in addition to reducing processing time and resource utilization.

    • Higher scan success rates - By preventing scans from being prematurely terminated due to exceeding LOC limits, we ensure that more scans are completed successfully. This can lead to more thorough security assessments and reduced risk of missing vulnerabilities.

    • Enhanced Security Posture - With more scans completing successfully and thoroughly the organization can maintain a stronger security posture by identifying and addressing potential vulnerabilities and security issues in the codebase.

    • Cost savings - Greater scanning efficiency can lead to cost savings by reducing the computing resources and time required for each scan. This is particularly valuable in large-scale scanning operations.

    • User satisfaction - Users, such as developers and security teams, benefit from a more streamlined and effective scanning process. Users can work more efficiently, leading to improved job satisfaction and productivity.

  • There is a 5.5M LOC 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.

  • 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.

  • 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.