rl-scanner extension for Azure DevOps Pipelines

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

The extension provided in this repository is called rl-scanner-task. It uses the official ReversingLabs rl-scanner Docker image to scan a single build artifact with the rl-secure CLI, generate the analysis report, and display the analysis status.

The rl-scanner-task extension is most suitable for experienced users who want to integrate the rl-secure CLI with their existing Azure DevOps pipelines.

To successfully work with the extension, you should:

• Understand the basic Azure DevOps Pipelines concepts

• 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 the extension in Azure DevOps on the Organization level, for example: https://dev.azure.com/your-Azure-organization-name/_settings/extensions

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 extension works

This extension relies on user-specified extension 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 extension 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).

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

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. Install the extension from the Azure Marketplace.

4. 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 extension, you must convert your license file into a Base64-encoded string.

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

How to use this extension

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

See the Examples section below.

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

Parameters

The following extension parameters can be modified in the pipeline.

Environment

The following secret parameters must be passed via env:

 

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

Inputs

The following secrets must be passed via inputs:

 

Parameter name	Required	Description	Type
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_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_PROXY_SERVER	No	Server name for optional proxy configuration (IP address or DNS name).	string
RL_PROXY_PORT	No	Network port on the proxy server for optional proxy configuration. Required if RL_PROXY_SERVER is used.	string
RL_PROXY_USER	No	User name for proxy authentication.	string
RL_PROXY_PASSWORD	No	Password for proxy authentication. Required if RL_PROXY_USER is used.	string

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

Examples

Basic scan

The azure-pipelines.yml file in this repository is an example of a basic Azure DevOps pipeline that uses the ReversingLabs rl-scanner-task extension to scan a build artifact.

  trigger:
    - main

  pool:
    vmImage: 'ubuntu-latest'

  variables:
  - group: rl-scanner
  - name: BUILD_PATH
    value: '.'
  - name: REPORT_PATH
    value: 'report'
  - name: MY_ARTIFACT_TO_SCAN
    value: 'README.md'

  steps:

  - task: rl-scanner-task@1
    displayName: rl-scanner-task
    inputs:
      BUILD_PATH: $(BUILD_PATH)
      REPORT_PATH: $(REPORT_PATH)
      MY_ARTIFACT_TO_SCAN: $(MY_ARTIFACT_TO_SCAN)
    env:
      RLSECURE_ENCODED_LICENSE: $(RLSECURE_ENCODED_LICENSE)
      RLSECURE_SITE_KEY: $(RLSECURE_SITE_KEY)

Scan and upload analysis reports

The azure-pipelines-with-upload.yml file in this repository is an example of an Azure DevOps pipeline that uses the ReversingLabs rl-scanner-task extension to scan a build artifact and upload the analysis reports to the pipeline.

  trigger:
    - main

  pool:
    vmImage: 'ubuntu-latest'

  variables:
  - group: rl-scanner
  - name: BUILD_PATH
    value: '.'
  - name: REPORT_PATH
    value: 'report'
  - name: MY_ARTIFACT_TO_SCAN
    value: 'README.md'

  steps:

  - task: rl-scanner-task@1
    displayName: rl-scanner-task
    inputs:
      BUILD_PATH: $(BUILD_PATH)
      REPORT_PATH: $(REPORT_PATH)
      MY_ARTIFACT_TO_SCAN: $(MY_ARTIFACT_TO_SCAN)
    env:
      RLSECURE_ENCODED_LICENSE: $(RLSECURE_ENCODED_LICENSE)
      RLSECURE_SITE_KEY: $(RLSECURE_SITE_KEY)

  - publish: $(System.DefaultWorkingDirectory)/$(REPORT_PATH)/report.cyclonedx.json
    displayName: 'Publish CycloneDX'
    artifact: 'CycloneDX-SBOM'
    condition: succeededOrFailed()

  - publish: $(System.DefaultWorkingDirectory)/$(REPORT_PATH)/report.spdx.json
    displayName: 'Publish SPDX'
    artifact: 'SPDX-SBOM'
    condition: succeededOrFailed()

  - publish: $(System.DefaultWorkingDirectory)/$(REPORT_PATH)/report.rl.json
    displayName: 'Publish RL-json'
    artifact: ReversingLabs-JSONreport
    condition: succeededOrFailed()

  - task: PublishBuildArtifacts@1
    condition: succeededOrFailed()
    inputs:
      PathtoPublish: $(System.DefaultWorkingDirectory)/$(REPORT_PATH)/rl-html
      ArtifactName: 'ReversingLabs-HTMLreport'
      StoreAsTar: true

Useful resources

• 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