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.

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.

Maintained by:

• ReversingLabs as part of the Spectra Assure platform

Where to get help:

• Official documentation
• ReversingLabs Support

Where to file issues:

• GitHub repository

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.

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.

The following environment variables can be used with this image.

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.

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.

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

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

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

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.

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>

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

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==

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>

The rl-scan helper tool supports the following parameters.

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

The rl-prune tool supports the following parameters.