reversinglabs/rl-scanner-cloud repository overview

⁠reversinglabs/rl-scanner-cloud

reversinglabs/rl-scanner-cloud is the official Docker image created by ReversingLabs for users who want to automate their workflows on the Spectra Assure Portal and integrate it with CI/CD tools.

The rl-scanner-cloud Docker image provides access to commonly used Portal 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.

This Docker image is based on Rocky Linux 10.

⁠What is the Spectra Assure Portal?

The Spectra Assure Portal is a SaaS solution that's part of the Spectra Assure platform - a ReversingLabs solution for software supply chain security. More specifically, the Portal is a web-based application for improving and managing the security of your software releases and verifying third-party software used in your organization.

With the Spectra Assure Portal, you can:

• Scan your software packages to detect potential risks before release.
• Improve your SDLC by applying actionable advice from security scan reports to all phases of software development.
• Organize your software projects and automatically compare package versions to detect potentially dangerous behavior changes in the code.
• Manage software quality policies on the fly to ensure compliance and achieve maturity in your software releases.

⁠Difference between rl-scanner and rl-scanner-cloud

If you're already familiar with the ReversingLabs Spectra Assure platform, you've likely come across another official Docker image: rl-scanner⁠. You may be wondering how that Docker image is different from rl-scanner-cloud.

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.

⁠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

The tag reversinglabs/rl-scanner-cloud:latest always points to the latest published image.

Versioned images are tagged reversinglabs/rl-scanner-cloud:vX.Y.Z, following semantic versioning⁠:

• X (major) is increased for a breaking change, for example a parameter, environment variable or return code that changes meaning or is removed.
• Y (minor) is increased for new functionality that keeps existing use working.
• Z (patch) is increased for bug fixes and small changes.

Using a versioned tag makes it easier for cautious customers to control when they move to a new version. The changes in each version are listed in changes.md⁠.

⁠How to use this image

The most common workflow for this Docker image is to upload a file for analysis to a Spectra Assure Portal instance, where it is added as a package version to a new or an existing project and package. Portal users can then view the analysis report and manage the analyzed file⁠ like any other package version.

The image wraps the functionality of several Portal public API endpoints into a single command with configurable parameters⁠. As a result, users don't have to send multiple separate API requests, because the whole workflow can be completed in a single run.

To use the provided Portal functionality, an active account on a Portal instance is required, together with a Personal Access Token for API authentication. Before you start using the image, make sure all prerequisites⁠ are satisfied.

Access to input data (files you want to scan) and the reports destination directory (to optionally save analysis reports) is provided by using Docker volume mounts⁠.

To prevent issues with file ownership and access, the -u option is used to provide current user identification to the container. The line -u $(id -u):$(id -g) \ can be removed for platforms where docker runs as the current user like on Windows.

When the container starts, it will try to connect to a Spectra Assure 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.

The standard proxy environment variables HTTPS_PROXY, HTTP_PROXY and NO_PROXY are also honoured when you pass them to the container (for example -e HTTPS_PROXY=http://proxy:3128). When RLSECURE_PROXY_SERVER is set, it takes precedence for all requests, and NO_PROXY does not apply to it.

⁠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. An active Spectra Assure 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.

⁠Environment variables

The following environment variables can be used with this image.

⁠Commands

The rl-scanner-cloud image supports the following commands:

• rl-scan: scan a file using --file-path
• rl-scan-url: scan a url using --import-url
• rl-scan-filestream: scan a file using --file-path into the Portal File Stream⁠
• rl-scan-url-filestream: scan a url using --import-url into the Portal File Stream⁠

⁠Configuration parameters rl-scan

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

⁠Configuration parameters rl-scan-url

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

⁠Configuration parameters rl-scan-filestream and rl-scan-url-filestream

These commands scan into the Portal File Stream instead of a project and package; see Scanning into the File Stream⁠.

• rl-scan-filestream supports the same parameters as rl-scan, and rl-scan-url-filestream the same as rl-scan-url, except for the package version parameters --purl, --replace, --force, --repro and --diff-with, which do not exist in the File Stream.
• The environment variables and return codes are the same.

⁠Return codes

The Docker container can exit with the following return codes.

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

⁠Portal throttling

When the Portal limits the request rate, it answers with HTTP status 429. The container then waits and sends the same request again (uploads included), up to 5 attempts in total.

• The wait is taken from the Retry-After header, or else from the Portal message (... available in N seconds), or else it is 60 seconds.
• Waiting never goes past --timeout, counted from the start of the run.
• Each wait is shown in the output, for example Portal throttle (429) on <url>: attempt 1 of 5, waiting 13s; <Portal message>.
• If the Portal still answers 429 after the last attempt, or when the timeout is reached, the container exits with code 101.

When a report or the RL-SAFE archive is not ready yet (HTTP 202), the container asks again every 30 seconds, also never past --timeout. If it i