Scanning Your Applications in the Pipeline

This document is part of the Mend Rollout Guidance.

The content is this document is intended for users who have already set up their Mend UI in preparation for scan results from the pipeline. If you have not set up the Mend UI, please see the following documents:

Mend Platform Rollout Overview
Setting Mend UI for Pipeline Scanning

The Mend CLI should be used for the following scans:

• Supported SCA languages

• SAST

• Container Image scanning

For SCA languages the CLI does not support, the Unified Agent can be leveraged. A detailed list of difference between the Mend CLI and the Unified Agent can be found here. Mend recommends defaulting to the CLI whenever possible.

The list of supported SAST languages can be found in SAST Supported Languages. Note, the Mend CLI will always run the latest engine for any detected languages. The engine does not need to be set when scanning and should only be used for testing purposes.

Mend Container support base-OS distributions can be found in Container image Supported Distribution. Supported registries and default behavior in case the image is not present locally is described in Container Image-supported Registries

Source File Matching

If neither scanner can support the language, a file system scan can be used to attempt Source File Matching.

The Mend CLI currently does not support the scanning of binaries.

Source File Matching is a best effort match and requires manual validation of the findings to ensure the best results. Due to this, it is not recommended to use Source File Matching when dependency resolution can be used. These results can currently only be maintained on the Legacy SCA UI. For instructions on how to manage Source Libraries found through Source File Matching see Identifying and Validating Source Libraries.

Building out your pipeline

This section will only cover scanning with the Mend CLI in an Linux environment as the recommended Mend scanner. If you need to use the Unified Agent, please see the example scripts provided in the Mend Toolkit repository discussed in Pipeline Examples

Prior to building out the pipeline for the Mend CLI, please review the Prerequisites of the Mend CLI. The recommended system requirements are a starting point, these will need to be adjusted based on the size of the project being built and scanned.

Required Environment Variables for Authentication

The Mend CLI requires user credentials in order to perform and upload a scan. These credentials need to be provided as environment variables in order to bypass the interactive login built into the Mend CLI. Mend recommends creating a service user for the purpose of running scans in the CI/CD pipeline.

The required environment variables for authentication with the Mend CLI are:

• MEND_URL

  • URL of your Mend Environment

• MEND_EMAIL

  • Email used to access Mend

• MEND_USER_KEY

  • Access key of the Mend User

  • Obtained by going to My Profile → User Keys

The minimum level of permission required by a user to scan with the Mend CLI is Scan Manager.

If you are not using a service user and you have multiple orgs within Mend MEND_ORGANIZATION must be set an environment variable. When the Mend CLI authenticates without an organization set, the organization will be the last accessed org of that user. Not setting this variable will make the location of your scan unpredictable.

Creating a Service User

Using a service user will ensure scans will continue to run even if someone where to leave the company and allow you to set permissions to only allow the service user to upload scans.

It is recommended to create a separate group for the service user with the Scan Manager role prior to service user creation.

For more information on roles and groups see the documentation on Access Control.

For instructions on how to create a service user see: Manage Service Users in the Mend Platform.

Pipeline steps

After setting the environment variables for authentication, it is time to start scanning your applications.

To scan SCA, SAST, and Container images, the pipeline will require the following steps:

1. Clone the repository

2. Build the application - SCA only

3. Download the Mend CLI

4. SCA Scan

5. SAST Scan

6. Container Image Scan

Clone the Repository

For the Mend CLI to scan either SCA or SAST, access to the repository needs to be cloned into the file system of the CI/CD process running the scanner. This can be done with a simple Git command and should already be in place for your build pipelines.

git clone <path to my repo>

Build the application - SCA Scans only

Applications should be scanned for open source components after the build step in the pipeline. This will ensure a clean scan by guaranteeing the application has access to any private registries or external artifacts that are pulled into the build process. Not building the application prior to scanning will lead to inaccurate results, no results, or a failed scan.

The proper build commands will vary based on the package manager being used and how complex the application is. If you are not integrating the scan into an existing build pipeline, You need to consult with your development teams about their build process so you can mirror it in your scanning pipeline. You should ensure the pipeline is able to build the application correctly before adding Mend SCA scan steps.

Download the Mend CLI

The Mend CLI is needed to perform Mend Scans. The Mend CLI is lightweight enough to be downloaded at the start of your pipelines for simplicity.

curl https://downloads.mend.io/cli/linux_amd64/mend -o /usr/local/bin/mend && chmod +x /usr/local/bin/mend

For the download location of other runtime environments see: Download the Mend CLI

If your CI/CD process has way to store the CLI and pass it into the pipeline, downloading on every run is not needed. The CLI is a wrapper for the other scanners within it and will update them whenever the scan command is executed.

SCA Scan

To scan your built application, run the following command:

mend dep --update --scope "<My Application>//<My Project>"

--update is required in order to send the results to the Mend UI. SCA scans are the only scan that do not upload the data to the UI by default.

--scope will control the application and project the data is uploaded to. For more information about this flag see: Controlling Data Upload

To perform a file system scan with the Mend CLI the flag --extended should be used. This will perform the file system scan in addition to the dependency resolution scan. File system scans are only recommended if the language is not supported by a package manager.

More SCA configurations are available in: Configure the Mend CLI for SCA

Reachability

This feature is currently in beta and only supports Java and Javascript

Reachability Analysis can be performed with your SCA scan by adding the --reachability flag. This feature will analyze whether an associated vulnerability is actually being called within your code base allowing you to prioritize vulnerabilities that can actually be exploited by your code base.

For more information on Reachability see: SCA Reachability.

For technical requirements and limitations see: SCA Reachability - Technical Requirements and Limitations.

SAST Scan

To perform a static analysis scan, run the following command:

mend code --scope "<My Application>//<My Project>"

--scope will control the application and project the data is uploaded to. For more information about this flag see: Controlling Data Upload

It is important to keep in mind that SAST scan times are dependent on a number of factors including the size of the code base being scanned. It is not uncommon for SAST scans to take a long time. To speed up scan times in your pipeline an Incremental scanning strategy can be used. The incremental scan will analyze the newly added code against a previously uploaded baseline. Incremental scanning results will include all results from the baseline plus any new findings from the changes. The baseline will need to be updated periodically for the incremental scan to stay up to date. Mend recommends updating your baseline during a nightly SAST scan aligned with your release process.

More SAST configurations are available in: Configure the Mend CLI for SAST

Container Image Scan

To perform a container image, run the following command:

mend image <image_name[:image_tag]> --scope "<My Application>//<My Project>"

--scope will control the application and project the data is uploaded to. For more information about this flag see: Controlling Data Upload

Only one container image can be scanned at a time with the CLI command. If multiple images need to be scanned, the command can be ran for each image or a list of images can be provided and looped through. An example of the looping method can be found in the Azure Devops Scan Template Example.

If bulk scanning of images is required, Mend can connect to your container registry to scan images directly from the registry. This option loses the ability to associate each image to a specific project.

Controlling Data Upload

Uploading Data to a Specific Application during a Scan

In order to control which application/project the scan is uploaded to from the CLI, specific parameters needs to be set. Setting these values are recommended in order to have the data populate in the Mend Platform and follow a structure that makes sense for your organization.

When these values are not set, a default naming scheme will be used depending on the integration. This will make it harder to effectively manage your vulnerabilities.

• SCA/SAST

  • Application: CLI

  • Project: name of directory scan was executed in

• Image

  • Application: Registry Name

  • Project: Repo name

When scanning SCA, SAST, and Containers for the same application, it is recommended to keep the scope the same for all three scans so the data is in a central location within the Mend UI. The easiest way to ensure the value is consistent between each scan type is to use a variable to store the values. This can either be passed into the pipeline, set as an environment variable, pulled from git, or a combination of these.

mend dep --update --scope "$CI_PROJECT_NAMESPACE//$PROJECT"
mend code --scope "$CI_PROJECT_NAMESPACE//$PROJECT"
mend image ubuntu:latest --scope "$CI_PROJECT_NAMESPACE//$PROJECT"

Adding an Application Label during a Scan

It is recommended to add a label during a scan to make it easier to filter the UI to specific business units and teams.

• --label-app to set the team who owns the application

  • mend code --scope "<My SAST App>\\<My Release Branch>" --label-app "Team Alpha"

Pipeline Examples

Example pipelines for scanning with Mend can be found in the Mend Toolkit/Mend-Examples repository. These examples are meant to be guides for implementing Mend in your own CI/CD pipeline. It is not recommended to use them exactly out of the box.

Next Steps

Implement Results consumption to start taking action on results: Consuming Mend Pipeline Results