reversinglabs/rl-scanner

reversinglabs/rl-scanner is the official Docker image created by ReversingLabs for users who want to deploy the rl-secure solution in ephemeral environments and integrate it with their CI/CD tools.

To optimize the developer experience, the image provides helper tools that wrap commonly used rl-secure features - scanning packages and generating analysis reports.

This image is based on Rocky Linux 9.

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

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.

Quick reference

Maintained by:

• ReversingLabs as part of the Spectra Assure platform

Where to get help:

• Official documentation
• ReversingLabs Support

Where to file issues:

• GitHub repository

Versioning and tags

Unversioned Docker image will have the tag reversinglabs/rl-scanner:latest. This tag will always point to latest published image.

Versioned tags will be structured as reversinglabs/rl-scanner:X, where X is an incrementing version number. We will increment the major version number to signify a breaking change. If changes to the image are such that no existing functionality will be broken (small bug fixes or new helper tools), we will not increment the version number.

This makes it easier for cautious customers to use versioned tag images and migrate to a new version at their own convenience.

How to use this image

The most common workflow for this Docker image is to scan a software package in a container and save the analysis report to local storage. All input and output data is transferred into or out of the container using two (2) Docker volume mounts.

The image provides helper tools that wrap the rl-secure functionality into a practical script. As a result, users don't have to chain multiple rl-secure commands in the container, as the whole workflow can be executed with a single command. The following helper tools are included:

• rl-scan - for scanning packages
• rl-prune - for cleaning up old scans

To use the provided rl-secure functionality, a valid site-wide deployment license is required. 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. Users must then encode the license file with the Base64 algorithm. The Base64-encoded license string and the site key must be provided using environment variables.

When the container starts, it will try to download and install the latest version of rl-secure. In some cases, a proxy server may be required to access the internet and connect to ReversingLabs servers. This optional proxy configuration can be provided using environment variables.

Environment variables

The following environment variables can be used with this image.

Environment variable	Description
RLSECURE_ENCODED_LICENSE	Required. The rl-secure license file as a Base64-encoded string. Users must encode the contents of your license file, and provide the resulting string with this variable.
RLSECURE_SITE_KEY	Required. The rl-secure license site key. The site key is a string generated by ReversingLabs and sent to users with the license file.
RLSECURE_VAULT_KEY	Optional. Password vault key to use for preserving and accessing passwords in a package store (rl-store).
RLSECURE_PACKAGE_PASSWORD	Optional. Password string to use for decrypting password-protected archives during the scan.
RLSECURE_PACKAGE_ENCODED_LIST	Optional. Base64-encoded password list file to use for decrypting password-protected archives during the scan.
RLSECURE_PACKAGE_PASSWORD_LIST	Optional. Path to a password list file to use for decrypting password-protected archives during the scan.
RLSECURE_PROXY_SERVER	Optional. Server URL for local proxy configuration.
RLSECURE_PROXY_PORT	Optional. Network port for local proxy configuration. Required if RLSECURE_PROXY_SERVER is used.
RLSECURE_PROXY_USER	Optional. User name for proxy authentication.
RLSECURE_PROXY_PASSWORD	Optional. Password for proxy authentication. Required if RLSECURE_PROXY_USER is used.

Prerequisites

To successfully use this Docker image, you need:

1. A working Docker installation on the system where you want to use the image. Follow the official Docker installation instructions for your platform.

2. A valid rl-secure license with site key. If you don't already have a site-wide deployment license, 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. You must convert your license file into a Base64-encoded string to use it with the Docker image.

3. One or more software packages to analyze. Your packages must be stored in a location that Docker will be able to access.

Scanning packages

Scan a file and generate analysis report

1. Prepare the file you want to scan and store it in a directory that will be mounted as your input (package source - read-only).

2. Prepare an empty directory where analysis reports will be stored after the file is scanned. That directory will be mounted as your output (reports destination - writable).

3. Start the container with input and output directories mounted as volumes and rl-secure license keys provided as environment variables.

To prevent issues with file ownership and access to analysis reports, the -u option is used to provide current user identification to the container.

The following command runs the rl-scan helper tool inside the container and scans a file from the mounted input directory. The file must exist in the mounted input directory. The tool will generate a report in the specified format (in this example, it's an HTML report) and save it to the mounted output directory.

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -v "$(pwd)/report:/report" \
  -e RLSECURE_ENCODED_LICENSE=<base64 encoded license file> \
  -e RLSECURE_SITE_KEY=<site key> \
  reversinglabs/rl-scanner \
  rl-scan \
    --package-path=/packages/deployment_pkg.tgz \
    --report-path=/report \
    --report-format=rl-html

4. When the scan is complete, the container exits automatically. To confirm the file was successfully scanned, access the output directory (reports destination) and check if the analysis report is present.

Scan a file using an existing rl-store

When an externally managed rl-secure package store is used, it opens up the possibility of advanced use cases for the scan process. Namely, you can generate a report that shows the difference between two package versions, and customize the scan configuration.

To use an external store for the scan, you must provide two additional parameters: the path to an external rl-store and the project URL to be used during the scan process.

The following command will use the rlstore directory located in the current working directory as the default rl-store, and will scan the package using the project URL project/[email protected]. After the scan, the scanned package information for version 1.0.0 will remain inside the store and can be used in the future.

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -v "$(pwd)/rlstore:/rlstore" \
  -v "$(pwd)/report:/report" \
  -e RLSECURE_ENCODED_LICENSE=<base64 encoded license file> \
  -e RLSECURE_SITE_KEY=<site key> \
  reversinglabs/rl-scanner \
  rl-scan \
    --rl-store=/rlstore \
    --purl=project/[email protected] \
    --package-path=/packages/project-1.0.0.tgz \
    --report-path=/report \
    --report-format=rl-html

Compare package versions

To scan the new version of the package (1.1.0) and generate a report that contains a section with all the differences between this new package version and the previously scanned version 1.0.0, you can use the --diff-with argument.

The following command will scan the new package version and generate a report with difference information against the previous package version.

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -v "$(pwd)/rlstore:/rlstore" \
  -v "$(pwd)/report:/report" \
  -e RLSECURE_ENCODED_LICENSE=<base64 encoded license file> \
  -e RLSECURE_SITE_KEY=<site key> \
  reversinglabs/rl-scanner \
  rl-scan \
    --rl-store=/rlstore \
    --purl=project/[email protected] \
    --package-path=/packages/project-1.1.0.tgz \
    --diff-with=1.0.0 \
    --report-path=/report \
    --report-format=rl-html

Perform build reproducibility checks

To perform a build reproducibility check, we need two build artifacts of a package version.

Assuming there is already an existing package store with a previously scanned package version project/[email protected], we perform a reproducibility check by scanning another build artifact of the same package version with the specially crafted project URL project/[email protected]?build=repro.

The previously scanned artifact for the package version is used as the reference against which the artifact we're scanning will be compared. The build=repro qualifier indicates our intention to perform a reproducibility build check.

The following command will scan the new artifact and perform a build reproducibility check for the version project/[email protected].

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -v "$(pwd)/rlstore:/rlstore" \
  -v "$(pwd)/report:/report" \
  -e RLSECURE_ENCODED_LICENSE=<base64 encoded license file> \
  -e RLSECURE_SITE_KEY=<site key> \
  reversinglabs/rl-scanner \
  rl-scan \
    --rl-store=/rlstore \
    --purl=project/[email protected]?build=repro \
    --package-path=/packages/project-1.1.0-build-2.tgz \
    --report-path=/report \
    --report-format=rl-html

Scanning password-protected archives

If the package you want to scan contains password-protected archives, you have to provide one or more passwords that will be used to decrypt the archives during the scanning process. Without passwords, such archives cannot be decrypted and their contents won't be fully extracted, which produces incomplete analysis results.

You can provide the passwords in any of the following formats:

• as a plain-text single password
• as a password list file
• as a Base64-encoded password list

If needed, you can provide the passwords in different formats simultaneously (for example, use both the plain text and the password list options in your Docker command).

Note that decrypting password-protected archives is supported only for a limited set of file formats. The list of supported formats in the Spectra Assure documentation indicates them with a checkmark in the "Password Support" column.

Plain text single password

To specify a single literal password string, you can use the --password argument or the RLSECURE_PACKAGE_PASSWORD environment variable. If multiple passwords are required, you can use the --password argument multiple times.

The following command will scan a package version using a single password provided with the --password command-line argument.

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -v "$(pwd)/report:/report" \
  -e RLSECURE_ENCODED_LICENSE=<base64 encoded license file> \
  -e RLSECURE_SITE_KEY=<site key> \
  reversinglabs/rl-scanner \
  rl-scan \
    --package-path=/packages/deployment_pkg.tgz \
    --report-path=/report \
    --report-format=rl-html \
    --password=<password>

Password list file

To avoid providing password information directly on the command line, you can save one or more passwords to a password list file. The password list file should be a plain text file containing one password per line.

Then you can use the --password-list argument or the RLSECURE_PACKAGE_PASSWORD_LIST environment variable to specify the path to the previously created password list file. The password list file will be read by the scan process, and passwords inside it will be used to decrypt password-protected archives.

The following command will use the password.list file as a source for passwords during the scan process.

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -v "$(pwd)/report:/report" \
  -v "$(pwd)/password.list:/password.list:ro" \
  -e RLSECURE_ENCODED_LICENSE=<base64 encoded license file> \
  -e RLSECURE_SITE_KEY=<site key> \
  reversinglabs/rl-scanner \
  rl-scan \
    --package-path=/packages/deployment_pkg.tgz \
    --report-path=/report \
    --report-format=rl-html \
    --password-list=/password.list

Base64 encoded password list

Instead of providing the path to the password list file, you can encode its contents using the Base64 algorithm. Then you can use the --encoded-password-list argument or the RLSECURE_PACKAGE_PASSWORD_LIST environment variable to provide the Base64-encoded password list contents as a string.

The following command will scan a package version with the password list file encoded as a Base64 string.

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -v "$(pwd)/report:/report" \
  -v "$(pwd)/password.list:/password.list:ro" \
  -e RLSECURE_ENCODED_LICENSE=<base64 encoded license file> \
  -e RLSECURE_SITE_KEY=<site key> \
  reversinglabs/rl-scanner \
  rl-scan \
    --package-path=/packages/deployment_pkg.tgz \
    --report-path=/report \
    --report-format=rl-html \
    --encoded-password-list=c2VjcmV0MQpzZWNyZXQyCg==

Scanning password-protected files using an existing rl-store

If an existing rl-secure package store (rl-store) is used for the scan process, password management needs to be permanent to support re-scanning package versions. Because of this, all provided passwords are saved inside the rl-store in a secure vault protected by a master vault key. This means that the vault key needs to be provided whenever you want to scan password-protected files. You can provide the key with the --vault-key argument or the RLSECURE_VAULT_KEY environment variable.

The following command will use an existing rl-store with a dedicated vault to scan a password-protected file. The password provided with the --password argument will be saved to the vault and associated with the scanned package version in the rl-store.

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -v "$(pwd)/rlstore:/rlstore" \
  -v "$(pwd)/report:/report" \
  -e RLSECURE_VAULT_KEY=<vault key> \
  -e RLSECURE_ENCODED_LICENSE=<base64 encoded license file> \
  -e RLSECURE_SITE_KEY=<site key> \
  reversinglabs/rl-scanner \
  rl-scan \
    --rl-store=/rlstore \
    --purl=project/[email protected] \
    --package-path=/packages/project-1.0.0.tgz \
    --report-path=/report \
    --report-format=rl-html \
    --password=<password>

Configuration parameters for rl-scan

The rl-scan helper tool supports the following parameters.

Parameter	Description
--package-path	Required. Path to the software package (the file you want to scan). The specified file must exist in the package source directory mounted to the container.
--report-path	Required. Path to the location where you want to store analysis reports. The specified path must exist in the reports destination directory mounted to the container.
--report-format	Required. A comma-separated list of report formats to generate. Supported values: cyclonedx, rl-checks, rl-cve, rl-html, rl-json, rl-uri, sarif, spdx, all.
--rl-level	Optional. Scan level used for report generation. Can't be used with an existing rl-store. Read more on how to use the RL-Levels feature.
--password	Optional. Literal password string to use for decrypting password-protected files when scanning a package version. Multiple invocations are possible.
--password-list	Optional. Path to a password list file to use for decrypting password-protected files when scanning a package version. Multiple invocations are possible.
--encoded-password-list	Optional. Base64-encoded contents of a password list file to use for decrypting password-protected files when scanning a package version. Multiple invocations are possible.
--message-reporter	Optional. Use it to change the format of output messages (STDOUT) for easier integration with CI tools. Supported values: text, teamcity

Package store configuration parameters

The following rl-scan parameters are applicable only when working with a package store.

Parameter	Description
--rl-store	Required when using a package store. Path to an existing rl-secure package store that will be used for the scan. Use this parameter when you already have a package store and want to scan the existing package versions inside it or add new package versions to it. The package store directory must be mounted to the container as a part of the Docker command.
--purl	Required when using a package store. Package URL used for the scan (must be in the format [pkg:namespace/]<project></package><@version>). Package URLs are unique identifiers used to associate the scanned package version with a project and a package in the rl-store. This parameter must be used together with --rl-store. To use the reproducibility checks feature and analyze a reproducible build artifact of a package version, append ?build=repro to the package URL of the artifact when scanning it: --purl=project/[email protected]?build=repro.
--diff-with	Optional. Use this parameter to compare (diff) the package version you're scanning against a previous version. The parameter accepts a package version number as the value. The version selected for diffing must exist in the same project and package as the version you're scanning. The package store must be specified with the --rl-store parameter. This parameter is ignored when analyzing reproducible build artifacts.
--replace	Optional. Replace (overwrite) a package version (specified with --purl) that already exists in the package store with the file you're scanning. The package store must be specified with the --rl-store parameter.
--vault-key	Optional. The "master" vault key used to protect saved passwords for an existing rl-store. When using a package store and scanning password-protected package versions, this key must be provided together with the password(s) in the scan command to allow saving the password(s) to the vault.

Cleaning up old scans

When an existing package store is used to persist the data between scans, storage usage grows with each new scan. To clean up old scan reports and free up used storage space, use the rl-prune helper tool.

The following command will clean all versions of a project defined by the project URL project/package that were scanned more than 15 days ago.

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/rlstore:/rlstore" \
  -e RLSECURE_ENCODED_LICENSE=<base64 encoded license file> \
  -e RLSECURE_SITE_KEY=<site key> \
  reversinglabs/rl-scanner \
  rl-prune \
    --rl-store=/rlstore \
    --purl=project/package \
    --days-older=15

Configuration parameters for rl-prune

The rl-prune tool supports the following parameters.

Parameter	Description
--rl-store	Required. Path to an existing rl-secure store in which you want to prune the data.
--purl	Required. Package URL to prune, in the format [pkg:namespace/]<project>[</package>[<@version>]].
--before-date	Optional. Remove all versions scanned before the timestamp specified in ISO-8601 format.
--after-date	Optional. Remove all versions scanned after the timestamp specified in ISO-8601 format.
--days-older	Optional. Remove all versions with the last scan date older than the specified number of days.
--hours-older	Optional. Remove all versions with the last scan date older than the specified number of hours.
--message-reporter	Optional. Use it to change the format of output messages (STDOUT) for easier integration with CI tools. Supported values: text, teamcity