Skip to main content

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:

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-scannerrl-scanner-cloud
Endpoint accessConnects to api.reversinglabs.com and data.reversinglabs.comConnects to a user-specified Portal instance (my.secure.software/{server}/api)
ScanningSoftware 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.
Policy controlsIf 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.
ReportsUsers 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 HTML report (rl-html format) is always generated, but it's accessible only in the Portal web interface. By default, the direct link to the HTML report on a Portal instance is included in the Docker command output.
Accounts and licensingA 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:

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

  3. 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 variableDescription
RLSECURE_ENCODED_LICENSERequired. 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_KEYRequired. The rl-secure license site key. The site key is a string generated by ReversingLabs and sent to users with the license file.
RLSECURE_PROXY_SERVERServer name for proxy configuration (IP address or DNS name).
RLSECURE_PROXY_PORTNetwork port on the proxy server for proxy configuration. Required if RLSECURE_PROXY_SERVER is used.
RLSECURE_PROXY_USERUser name for proxy authentication.
RLSECURE_PROXY_PASSWORDPassword for proxy authentication. Required if RLSECURE_PROXY_USER is used.

Return codesโ€‹

The Docker container can exit with the following return codes.

CodeDescription
0The file is successfully analyzed with CI status PASS
Non-zeroThe 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.

ParameterDescription
--package-pathRequired. 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-pathRequired. 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-formatRequired. A comma-separated list of report formats to generate. Supported values: cyclonedx, rl-checks, rl-cve, rl-html, rl-json, sarif, spdx, all
--rl-levelSet an RL-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 RL-Level 5). With the default setting, any detected P0 issue causes the FAIL status. Read more on how to use the RL-Levels feature.

This parameter cannot be used with an existing package store (--rl-store must be omitted).
--streamName of the release stream from which to pull the rl-secure package.
--message-reporterUse 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.

ParameterDescription
--rl-storeThe 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.
--purlThe 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-withUse 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.
--replaceReplace (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.

rl-pruneโ€‹

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

ParameterDescription
--rl-storeRequired. 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.
--purlRequired. 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-dateRemove everything matching the --purl and scanned before the specified timestamp (in ISO-8601).
--after-dateRemove everything matching the --purl and scanned after the specified timestamp (ISO-8601).
--days-olderRemove everything matching the --purl with the last scan date older than the specified number of days.
--hours-olderRemove everything matching the --purl with the last scan date older than the specified number of hours.
--message-reporterUse 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 HTML report 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.

OptionDescription
--rmCloses 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โ€‹

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

Optional proxy configurationโ€‹

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โ€‹