rl-scanner template for Azure DevOps Pipelines

ReversingLabs provides the official template for Azure DevOps Pipelines to enable faster and easier deployment of the rl-secure solution in CI/CD workflows.

The template provided in this repository is called rl-secure-scan-ado.yml. It uses the official reversinglabs/rl-scanner Docker image to scan a single build artifact with rl-secure, generate the analysis report, and display the analysis status. To use the rl-secure security scanning functionality, a valid site-wide deployment license from ReversingLabs is required.

This template is most suitable for experienced users who want to integrate rl-secure into their existing Azure DevOps pipelines. To successfully work with the template, you should be familiar with the basic Azure DevOps Pipelines concepts.

What is rl-secure?

rl-secure is a CLI tool that's part of the Spectra Assure platform - a new ReversingLabs solution for software supply chain protection.

With rl-secure, you can:

• Scan your software release packages on-premises and in your CI/CD pipelines to prevent threats from reaching production.
• Compare package versions to ensure no vulnerabilities are introduced in the open source libraries and third-party components you use.
• Prevent private keys, tokens, credentials and other sensitive information from leaking into production.
• Improve developer experience and ensure compliance with security best practices.
• Generate actionable analysis reports to help you prioritize and remediate issues in collaboration with your DevOps and security teams.

How this template works

This template relies on user-specified template parameters to:

• create a directory for analysis reports
• use the rl-scanner Docker image to scan a single build artifact with rl-secure inside the container
• place the analysis reports into the previously created directory and optionally publish them as pipeline artifacts
• output the scan result as a build status message (also displayed on the pipeline summary page in Azure DevOps interface)

The template is intended to be used in the test stage of a standard build-test-deploy pipeline. It expects that the build artifact is produced in a previous stage and requires specifying the location of the artifact with the BUILD_PATH parameter. The path must be relative to $(System.DefaultWorkingDirectory).

Analysis reports generated by rl-secure after scanning the artifact are saved to the location specified with the REPORT_PATH parameter. The reports are always created regardless of the scan result (pass or fail).

By default, the reports are also automatically uploaded to Azure DevOps Pipelines and displayed on the job build level in the interface (not in the Artifacts tab). To disable automatic report uploads, you must explicitly set the WITH_UPLOAD template parameter to false.

Requirements

1. An Azure DevOps Services account to create an Azure DevOps organization and use Azure Pipelines. If you're already in an Azure DevOps organization, make sure you can access the Azure DevOps project where you want to use this template.

2. An Azure Pipelines agent with the Docker capability enabled. The example pipeline in this repository runs on a Microsoft-hosted agent using the ubuntu-latest VM image.

3. A valid rl-secure site-wide deployment license. This type of license has two parts: the site key and the license file. ReversingLabs sends both parts of the license to users on request. If you don't already have a site key, follow the instructions in the official rl-secure documentation to get it from ReversingLabs. You don't need to activate the license - just save the license file and the site key for later use. To use it with the template, you must convert your license file into a Base64-encoded string.

4. Your rl-secure license file and site key added as secrets to your Azure DevOps organization.

How to use this template

The most common use-case for this template is to include it in the "test" stage of an existing pipeline, after the build artifact you want to scan has been created.

1. Copy the template file rl-secure-scan-ado.yml into the repository associated with your Azure DevOps project.

2. Make sure your rl-secure license file (RLSECURE_ENCODED_LICENSE) and site key (RLSECURE_SITE_KEY) are configured as secrets in your Azure DevOps organization. Add them as a variable group to your pipeline like in the following example:

    variables:
    - group: rl-scanner
   

3. Specify the required template parameters in the variables section of your pipeline like in the following example:

    variables:
    - group: rl-scanner
    - name: BUILD_PATH
      value: '.'
    - name: REPORT_PATH
      value: report
    - name: MY_ARTIFACT_TO_SCAN
      value my-package.rpm
   

4. Include the template into the steps section of your pipeline like in the following example:

    steps:
    # placeholder for build step
    - template: rl-secure-scan-ado.yml
      parameters:
        REPORT_PATH: ${{ variables.REPORT_PATH }}
        BUILD_PATH: ${{ variables.BUILD_PATH }}
        MY_ARTIFACT_TO_SCAN: ${{ variables.MY_ARTIFACT_TO_SCAN }}
        RLSECURE_ENCODED_LICENSE: ${{ variables.RLSECURE_ENCODED_LICENSE }}
        RLSECURE_SITE_KEY: ${{ variables.RLSECURE_SITE_KEY }}
        WITH_UPLOAD: true
        VERBOSE: true
    # placeholder for deploy step
   

5. Save and commit your changes to the repository/the Azure DevOps project.

Parameters

The following template parameters can be modified in the pipeline.

Note: All optional string parameters have a default empty string value and do not have to be specified if not used.

Parameter name	Required	Description	Type
RLSECURE_ENCODED_LICENSE	Yes	The rl-secure license file converted to a Base64-encoded string. Users must encode the contents of the license file, and provide the resulting string with this variable.	string
RLSECURE_SITE_KEY	Yes	The rl-secure license site key. The site key is a string generated by ReversingLabs and sent to users with the license file.	string
BUILD_PATH	Yes	The directory where the build artifact specified with the MY_ARTIFACT_TO_SCAN parameter is located. The path must be relative to $(System.DefaultWorkingDirectory). The default value is .	string
MY_ARTIFACT_TO_SCAN	Yes	The name of the file you want to scan. Must be relative to BUILD_PATH. The file must exist in the specified location before the scan starts.	string
REPORT_PATH	No	The directory where analysis reports will be stored after the scan is finished. The path must be relative to $(System.DefaultWorkingDirectory). The directory must be empty before the scan starts. The default value is RlReport	string
RL_WITH_UPLOAD	No	Automatically uploads analysis reports into the Azure DevOps pipeline after the scan is finished. The default value is true ; the option is enabled by default.	boolean
RL_VERBOSE	No	Includes detailed progress feedback into the pipeline output and displays the stdout and stderr messages from the rl-secure run in the Docker container. The default value is false; the option is disabled by default.	boolean
RL_STORE	No	If using a package store, use this parameter to provide the path to a directory where the package store has been initialized.	string
RL_PACKAGE_URL	No	If using a package store, use this parameter to specify the package URL (PURL) for the scanned artifact.	string
RL_DIFF_WITH	No	If using a package store, use this parameter to specify the PURL of a previously scanned version of the artifact to compare (diff) against. The previous version must exist in the same project and package as the scanned artifact.	string
RL_PROXY_SERVER	No	An optional proxy server.	string
RL_PROXY_PORT	No	An optional proxy port.	string
RL_PROXY_USER	No	An optional proxy user for authentication.	string
RL_PROXY_PASSWORD	No	An optional proxy password for authentication.	string

Examples

The azure-pipeline-example.yml file in this repository is an example of a basic Azure DevOps pipeline that uses the ReversingLabs rl-scanner template.

If you want to try out the template before integrating it into your pipelines, you can clone this repository and create an Azure DevOps project for it.

The template is already added to the azure-pipeline-example.yml file, so all you need to do is associate the pipeline with your project and configure your rl-secure licensing information as described previously in this text.

By default, the pipeline will scan this README file, and the scan should pass without any issues. The example deploy stage will be triggered, and the analysis reports will be uploaded to Azure DevOps as job artifacts.

If you want to test what happens when a scan fails:

• download the test file called eicarcom2.zip and add it to the same directory as this README file (the repository root directory). This is a test malware that is safe to use because it only contains a virus signature, but does not cause any harm to the system. For more information, check the official European Institute for Computer Anti-Virus Research (EICAR) website.

• in the azure-pipeline-example.yml file, replace the current value of the MY_ARTIFACT_TO_SCAN parameter with eicarcom2.zip

After saving your changes and running the pipeline again, the scan should fail. The example deploy stage will not be triggered, but the analysis reports will still be uploaded to Azure DevOps as job artifacts. The example pipeline also shows a meaningful output message to indicate that the scan has failed because of detected malicious components.

Notes

• The rl-html report format produced by rl-secure consists of an HTML file and its dependencies. Because this HTML file cannot be displayed in Azure DevOps Artifact Upload, the template must publish the report as a compressed file. This is done with the StoreAsTar option in the template. To show the HTML report, you have to download the TAR file and locally unpack it.

Useful resources

• The official Microsoft documentation on using templates with Azure DevOps Pipelines
• The official reversinglabs/rl-scanner Docker image on Docker Hub
• Supported file formats and language coverage for rl-secure
• Introduction to secure software release processes with ReversingLabs