rl-scanner Docker image

ReversingLabs provides the official Spectra Assure CLI Docker image for easier automation and integration with CI/CD tools. The image is called reversinglabs/rl-scanner and published on Docker Hub. It is based on Rocky Linux 9.

To optimize the developer experience, the image provides helper tools that wrap commonly used rl-secure features - scanning packages, generating reports, and comparing package versions. This means you don't need 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 in the Docker image:

rl-scan - for scanning packages
rl-prune - for package store maintenance

In this guide, you will learn to use the rl-scanner Docker image to scan a software package in a container and save the analysis report to your local storage.

Docker volumes

All workflows described in this documentation rely on Docker volume mounts to transfer files into and out of the container.

About Spectra Assure Docker images

If you're already familiar with the ReversingLabs Spectra Assure platform, you've likely noticed there are multiple official Docker images for Spectra Assure integrations. You may be wondering how they are different.

In short:

rl-scanner is primarily intended for Spectra Assure CLI users, as it closely aligns with the CLI workflows and makes it easier to deploy the CLI in various environments.
rl-scanner-cloud is mainly for Spectra Assure Portal users who want to build their own integrations on top of the Portal features.

The following table lists more detailed differences between these two Docker images that should help you choose the most appropriate image for your use-case.

	rl-scanner	rl-scanner-cloud
Endpoint access	Connects to `api.reversinglabs.com` and `data.reversinglabs.com`	Connects to a user-specified Portal instance (`my.secure.software/{server}/api`)
Scanning	Software packages are scanned inside the Docker container, on the local system where the container is running.	Software packages are scanned in the cloud, on the Portal instance to which they are uploaded.
Password management	Users can provide passwords or (Base64-encoded) password list files to allow decrypting password-protected archives during the scan and getting complete analysis reports.	Not supported at this time. The analysis reports will indicate that the file content is protected by an unknown password.
Policy controls	If a permanent package store is used with the Docker image, users can modify policies through local configuration files.	Any existing policy configuration for the user's organization and group on the Portal automatically applies.
Reports	Users can choose the report format(s) they want to generate, and automatically save the reports to local storage or as pipeline artifacts.	Users can choose the report format(s) they want to generate and save them to local storage or as pipeline artifacts. The SAFE report (rl-html format) is always generated, but it's accessible only in the Portal web interface. By default, the direct link to the SAFE report on a Portal instance is included in the Docker command output.
Accounts and licensing	A valid `rl-secure` license with site key is required to use the Docker image. The size of analyzed files is deducted from the monthly analysis capacity tied to the user's `rl-secure` account.	An active Portal account with a Personal Access Token is required to use the Docker image. The size of analyzed files is deducted from the monthly limit configured for the user's group and designated for projects.

Prerequisites

To successfully use the rl-scanner Docker image, you need:

A working Docker installation on the system where you want to use the image. Follow the official Docker installation instructions for your platform.
A valid rl-secure license with site key. You must convert your license file into a Base64-encoded string to use it with the Docker image. If you don't already have a site-wide deployment license, follow the instructions in the rl-secure licensing guide to get it from ReversingLabs.
One or more software packages to analyze. Your packages must be stored in a location that Docker will be able to access.

Environment variables

The following environment variables can be used with the rl-scanner Docker image.

Environment variable	Description
`RLSECURE_ENCODED_LICENSE`	Required. The `rl-secure` license file as a Base64-encoded string. Users must encode the contents of their 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_PACKAGE_PASSWORD`	Password string to use for decrypting password-protected archives during the scan.
`RLSECURE_PACKAGE_ENCODED_LIST`	Base64-encoded contents of the password list file to use for decrypting password-protected archives during the scan.
`RLSECURE_PACKAGE_PASSWORD_LIST`	Path to a password list file to use for decrypting password-protected archives during the scan.
`RLSECURE_VAULT_KEY`	Password vault key to use for preserving and accessing passwords in a package store (rl-store). Only compatible with package store workflows.
`RLSECURE_PROXY_SERVER`	Server name for proxy configuration (IP address or DNS name).
`RLSECURE_PROXY_PORT`	Network port on the proxy server for proxy configuration. Required if `RLSECURE_PROXY_SERVER` is used.
`RLSECURE_PROXY_USER`	User name for proxy authentication.
`RLSECURE_PROXY_PASSWORD`	Password for proxy authentication. Required if `RLSECURE_PROXY_USER` is used.

Return codes

The Docker container can exit with the following return codes.

Code	Description
0	The file is successfully analyzed with CI status `PASS`
Non-zero	The file is successfully analyzed with CI status `FAIL` or a problem has occurred during analysis

You may also encounter any of the standard chroot exit codes in case of Docker-specific problems.

Helper tools

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. The file must be in any of the formats supported by Spectra Assure.
`--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`	Set a SAFE Level to use when scanning the package. Accepts an integer from 1 to 5. When this parameter is not specified, the default scanning setting is used (corresponds to SAFE Level 5). With the default setting, any detected P0 issue causes the `FAIL` status. Read more on how to use the SAFE Levels feature. This parameter cannot be used with an existing package store (`--rl-store` must be omitted).
`--password`	Literal password string to use for decrypting password-protected files when scanning a package version. The parameter can be used multiple times in the same command to provide more than one password.
`--password-list`	Path to a password list file to use for decrypting password-protected files when scanning a package version. The parameter can be used multiple times in the same command.
`--encoded-password-list`	Base64-encoded contents of a password list file to use for decrypting password-protected files when scanning a package version. The parameter can be used multiple times in the same command.
`--stream`	Name of the release stream from which to pull the `rl-secure` package. The default stream is used implicitly (without specifying this parameter) and is suitable for most use-cases.
`--message-reporter`	Use this parameter to change the format of output messages (STDOUT) for easier integration with CI tools. Supported values: `text`, `teamcity`

Package store parameters

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

Parameter	Description
`--rl-store`	The 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 files inside it or add new files to it. The package store directory must be mounted to the container as a part of the Docker command.
`--purl`	The package URL used to associate the file with a project and package in the package store. Package URLs are unique identifiers in the format `[pkg:type/]<project></package><@version>`. Use this parameter to add the file you want to scan to the package store as a package version. 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/package@1.0.0?build=repro`.
`--diff-with`	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`	Replace (overwrite) an already existing package version (specified with `--purl`) with the file you're scanning. The package store must be specified with the `--rl-store` parameter.
`--vault-key`	The "master" vault key used to save user-provided passwords for package versions in a package store (rl-store). When using an rl-store and scanning password-protected package versions, this key must be provided together with the password(s) in the command to allow saving them to the vault.

rl-prune

The rl-prune helper tool supports the following parameters. They are applicable only when working with a permanent package store.

Parameter	Description
`--rl-store`	Required. Path to an existing `rl-secure` package store in which you want to prune the data. The package store directory must be mounted to the container as part of the Docker command.
`--purl`	Required. Package URL to prune. Must be in the format `[pkg:type/]<project>[/<package>[@<version>]]`. You must at least specify the project. Depending on what you specify in the package URL, the `rl-prune` helper tool will remove a single package version, all versions in a package, or all versions across all packages in a project.
`--before-date`	Remove everything matching the `--purl` and scanned before the specified timestamp (in ISO-8601).
`--after-date`	Remove everything matching the `--purl` and scanned after the specified timestamp (ISO-8601).
`--days-older`	Remove everything matching the `--purl` with the last scan date older than the specified number of days.
`--hours-older`	Remove everything matching the `--purl` with the last scan date older than the specified number of hours.
`--message-reporter`	Use this parameter to change the format of output messages (STDOUT) for easier integration with CI tools. Supported values: `text`, `teamcity`

Quick start guide

In this basic workflow, we're using the rl-scan helper tool to scan a software package in the container and generate analysis reports.

1. Pull the image from Docker Hub

docker pull reversinglabs/rl-scanner:latest

2. Start the container

In a single Docker command, you will:

mount your package source and reports destination directories as volumes,
provide your rl-secure license keys as environment variables,
run the rl-scan helper tool inside the container,
save the SAFE report (rl-html) into the reports destination directory.

Important

The reports destination directory must be empty before starting the container. If it's not empty, you will get an error.

Docker command
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

Docker options

We use the following options with Docker to run the container.

Option	Description
`--rm`	Closes the container automatically after the scan is done.
`-u $(id -u):$(id -g)`	Provides the user identification to the container. This prevents ownership and access permission issues with files that the container needs to work with (software packages and analysis reports).
`-v "$(pwd)/packages:/packages:ro"`	Specifies the package source. Mounts the directory that contains your software packages as read-only. This allows the helper tool to access and scan the packages.
`-v "$(pwd)/report:/report"`	Specifies the reports destination. Mounts the directory where analysis reports will be saved. The directory is mounted as writable so the reports can be added to it.
`-e RLSECURE_ENCODED_LICENSE=<base64 encoded license file>`	This environment variable is required. Provides your `rl-secure` license file as a Base64-encoded string to the helper tool. Convert your license file to a Base64-encoded string, then replace the `<base64 encoded license file>` part with your string.
`-e RLSECURE_SITE_KEY=<site key>`	This environment variable is required. Provides your `rl-secure` license site key as a string to the helper tool. Replace the `<site key>` part with the site key string you received from ReversingLabs.

Choose a release stream Optional

ReversingLabs publishes different versions of the rl-secure CLI tool and makes them available in separate release streams. The default stream is used implicitly; without any special configuration. If necessary, you can specify which release stream to use when scanning your files with the rl-scanner Docker image.

To do this, use the --stream command-line parameter.

The following command will scan a file using the preview stream.

Docker command with specified stream
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 \
    --stream=preview
    --package-path=/packages/deployment_pkg.tgz \
    --report-path=/report \
    --report-format=rl-html

Proxy configuration Optional

When the container starts, it will try to download and install the latest version of rl-secure. Depending on your network settings, it may be required to access the internet through a proxy server.

To add proxy configuration to the Docker command, use the environment variables RLSECURE_PROXY_* listed in the Environment variables section.

3. Check the analysis report

In the previous step, we started the container and executed the rl-scan helper tool inside it.

The helper tool completed the following actions:

installed rl-secure
initialized a package store (rl-store) inside the container
added the specified package to the package store and scanned it
generated analysis reports in the specified formats and saved them to the specified location
sent the analysis result as a PASS or FAIL status to the output
cleaned up temporary files and removed the package store

The container then automatically shut down.

To confirm that your package was successfully scanned, access the reports destination directory you specified in the previous step, and check if analysis reports are present.

Next steps

View the instructions for scanning password-protected files
Learn how to use the rl-scanner Docker image with a permanent package store

rl-scanner Docker image

About Spectra Assure Docker images​

Prerequisites​

Environment variables​

Return codes​

Helper tools​

rl-scan​

Package store parameters​

rl-prune​

Quick start guide​

1. Pull the image from Docker Hub​

2. Start the container​

Docker options​

Choose a release stream Optional​

Proxy configuration Optional​

3. Check the analysis report​

Next steps​