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

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

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

ReversingLabs rl-scanner task

ReversingLabs