rl-scanner-cloud Docker image

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

The rl-scanner-cloud Docker image connects to a Portal instance and provides access to commonly used Projects workflows - uploading package versions to a project, scanning them, and generating analysis reports. You can also compare different package versions in a project, perform reproducibility checks for a package version, and save analysis reports to local storage.

All successfully analyzed files are visible in the Portal interface, and accessible by you and any other Portal users who can access your projects.

To optimize the developer experience, the image wraps the functionality of several Portal Public API endpoints into a single command with configurable parameters. This means you don't have to send multiple separate API requests, because the whole workflow can be completed in a single run.

In this guide, you will learn to use the following rl-scanner-cloud Docker image workflows:

• Upload a file for analysis to the Portal and download the reports
• Compare two package versions in a Portal project
• Run a reproducibility check for a package version

Docker volumes

All workflows described in this documentation rely on Docker volume mounts to give the container access to input data, and to optionally store analysis reports.

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.
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 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 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-cloud 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. An active Portal account and a Personal Access Token generated for it. If you don't already have a Portal account, you may need to contact the administrator of your Portal organization to invite you. Alternatively, if you're not a Spectra Assure customer yet, you can contact ReversingLabs to sign up for a Portal account. When you have an account set up, follow the instructions to generate a Personal Access Token.

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

4. Enough reserved Projects quota for the group to which you want to upload the file. You can check the analysis capacity usage at the top of the sidebar on the Projects page for your group.

Environment variables

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

Environment variable	Description
RLPORTAL_ACCESS_TOKEN	Required. A Personal Access Token for authenticating requests to the Portal. Before you can use this Docker image, you must create the token in your Portal settings. Tokens can expire and be revoked, in which case you'll have to update the value of this environment variable. It's strongly recommended to treat this token as a secret and manage it according to your organization's security best practices.
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	Returned when: - The file is successfully analyzed on the Portal with CI status PASS - The --submit-only parameter is used
1	Returned when: - The file is successfully analyzed on the Portal with CI status FAIL - The default or user-configured timeout expired - There is a problem with file scanning on the Portal

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

Configuration parameters

The rl-scanner-cloud image supports the following parameters.

Parameter	Description
--rl-portal-server	Required. Name of the Portal instance to use for the scan. The Portal instance name usually matches the subdirectory of my.secure.software in your Portal URL. For example, if your Portal URL is my.secure.software/demo, the instance name to use with this parameter is demo.
--rl-portal-org	Required. The name of a Portal organization to use for the scan. The organization must exist on the Portal instance specified with --rl-portal-server. The user account authenticated with the token must be a member of the specified organization and have the appropriate permissions to upload and scan a file. Organization names are case-sensitive.
--rl-portal-group	Required. The name of a Portal group to use for the scan. The group must exist in the Portal organization specified with --rl-portal-org. Group names are case-sensitive.
--purl	Required. The package URL used to associate the file with a project and package on the Portal. Package URLs are unique identifiers in the format [pkg:type/]<project></package><@version>. When scanning a file, you must assign a package URL to it, so that it can be placed into the specified project and package as a version. If the project and package you specified don't exist in the Portal, they will be automatically created. The pkg:type/ part of the package URL can be freely omitted, because the default value pkg:rl/ is always automatically added. To analyze a reproducible build artifact of a package version, you must append the ?build=repro parameter to the package URL of the artifact when scanning it, in the format <project></package><@version?build=repro>.
--file-path	Required. Path to the file you want to scan. The specified file must exist in the package source directory mounted to the Docker container. The file must be in any of the formats supported by Spectra Assure. The file size on disk must not exceed 10 GB.
--filename	Optional name for the file you want to scan. If omitted, defaults to the file name specified with --file-path. When the file is uploaded and analyzed on the Portal, this file name is visible in the reports.
--replace	Replace (overwrite) an already existing package version with the file you're uploading.
--force	In the Portal, a package can only have a limited amount of versions. If a package already has the maximum number of versions, you can use this optional parameter to delete the oldest version of the package and make space for the version you're uploading. This parameter is incompatible with ?build=repro and should not be used when analyzing reproducible build artifacts.
--diff-with	This optional parameter lets you specify a previous package version against which you want to compare (diff) the version you're uploading. The specified version must exist in the package. This parameter is incompatible with ?build=repro and should not be used when analyzing reproducible build artifacts.
--submit-only	By default, the Docker container runs until the uploaded file is analyzed on the Portal and returns the result in the output. This optional parameter lets you skip waiting for the analysis result. When this parameter is used, the analysis report URL is not displayed in the output.
--timeout	This optional parameter lets you specify how long the container should wait for analysis to complete before exiting (in minutes). The parameter accepts any integer from 10 to 1440. The default timeout is 20 minutes.
--message-reporter	Optional parameter that changes the format of output messages (STDOUT) for easier integration with CI tools. Supported values: text, teamcity
--report-path	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	A comma-separated list of report formats to generate. Supported values: cyclonedx, rl-checks, rl-cve, rl-json, sarif, spdx, all

Quick start guide

In this basic workflow, we're using the rl-scanner-cloud Docker image to upload a file for analysis to a Portal instance, and save analysis reports to local storage.

The uploaded file is added to the specified organization and group, and assigned as a version to the specified project and package on the Portal. If the project or package don't exist on the Portal, they are automatically created.

To download analysis reports to local storage, we're using the --report-path and --report-format parameters. These parameters are optional, but they must be used together.

• --report-path specifies the destination directory for the reports. This destination directory is added as a volume that Docker can write into. It must be created empty before starting the container.

• --report-format accepts any of the supported report formats (cyclonedx, rl-checks, rl-cve, rl-json, sarif, spdx). To request multiple formats at once, specify them as a comma-separated list. The special value all will download all supported report formats.

1. Pull the image from Docker Hub

docker pull reversinglabs/rl-scanner-cloud:latest

2. Start the container

In a single Docker command, you will:

• mount your package source and reports destination directories as volumes,
• provide your Personal Access Token,
• upload the software package to a Portal instance for analysis,
• download analysis reports to 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 to scan a file and download reports

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -v "$(pwd)/reports:/reports" \
  -e RLPORTAL_ACCESS_TOKEN=exampletoken \
  reversinglabs/rl-scanner-cloud \
  rl-scan \
    --rl-portal-server demo \
    --rl-portal-org ExampleOrg \
    --rl-portal-group demo-group \
    --purl my-project/my-package@1.0 \
    --file-path /packages/demo-packages/MyPackage_1_0.exe \
    --report-path /reports \
    --report-format all

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. This is optional, but recommended.
-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 container to access the packages and upload them to the Portal.
-v "$(pwd)/reports:/reports"	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 RLPORTAL_ACCESS_TOKEN=exampletoken	This environment variable is required. Provides your Personal Access Token to the container for authenticating requests to the Portal. Replace the exampletoken part with the token you generated for your Portal account. Outside of this example, you will likely follow your organization's secret management practices instead of providing the token directly in the Docker command.

Optional proxy configuration

When the container starts, it will try to connect to a Portal instance. 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 uploaded a file to a Portal instance from the container.

After the file is uploaded to the Portal, it's visible in the web interface while the analysis is pending.

When the analysis is complete, the command output displays the direct link to the analysis report as Report URL.

The container then exits automatically. You can access the analysis report and continue to work with the package version you just uploaded in the Portal web interface.

To confirm that your analysis reports were successfully downloaded, access the reports destination directory you specified in the previous step, and check if analysis reports in all requested formats are present.

Examples

Compare package versions

Package versions can be compared to show differences between them, which can be useful for tracking changes across software releases and recognizing if your software has been tampered with.

To compare a new version of a package against a previously scanned version, you can use the --diff-with parameter when scanning the new version. Both versions must be in the same Portal project and package.

The following command will scan a new package version (1.1) and generate a report with differences between the new and the previously analyzed package version (1.0).

Pull the image from Docker Hub

docker pull reversinglabs/rl-scanner-cloud:latest

Docker command to compare package versions

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -e RLPORTAL_ACCESS_TOKEN=exampletoken \
  reversinglabs/rl-scanner-cloud \
  rl-scan \
    --rl-portal-server demo \
    --rl-portal-org ExampleOrg \
    --rl-portal-group demo-group \
    --purl my-project/my-package@1.1 \
    --file-path /packages/demo-packages/MyPackage_1_1.exe \
    --diff-with=1.0

The HTML analysis report for the new version will contain the Diff page with all the differences between the two versions.

In the Portal web interface, the new version will be marked as "Derived" from the previous version.

Perform reproducibility checks

Reproducibility checks are an optional step in the Spectra Assure analysis for detecting and preventing software compromise and build system tampering. To perform a reproducibility check, you need two build artifacts of the same package version.

If there is a previously scanned package version (for example, my-project/my-package@1.0), you can perform a reproducibility check by associating another build artifact with that version. To do this, scan a new file with the ?build=repro parameter appended to the package URL of the same version (for example, my-project/my-package@1.0?build=repro). The previously scanned file is used as the reference against which the new build artifact we're scanning will be compared.

Every package version can have only one reproducible build artifact at a time. If a version already has a reproducible build artifact and you want to scan another one, you must first remove the existing reproducible build artifact, or use the --replace parameter when scanning the new artifact.

The following command will scan the new artifact and perform a reproducibility check for the version my-project/my-package@1.0.

Pull the image from Docker Hub

docker pull reversinglabs/rl-scanner-cloud:latest

Docker command to scan a reproducible build artifact

docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -e RLPORTAL_ACCESS_TOKEN=exampletoken \
  reversinglabs/rl-scanner-cloud \
  rl-scan \
    --rl-portal-server demo \
    --rl-portal-org ExampleOrg \
    --rl-portal-group demo-group \
    --purl my-project/my-package@1.0?build=repro \
    --file-path /packages/demo-packages/MyPackage_1_0-build1.exe

The HTML analysis report will contain the Reproducibility page with the reproducibility check status and a summary of differences between the reproducible build artifact and the main artifact ("Reference Version" in the report).

In the Portal web interface, you can expand the package version details to find the Reproducible build check in the summary of checks and select Details to open the report.