Skip to main content

Work with a package store

Software packages and releases are often managed in a central repository. This aligns with the concept of the rl-secure package store, which is a special directory that keeps all your projects, packages, package versions and their analysis results.

A package store can be initialized in a shared location and used to keep all CI/CD scan results in one place. This is a more practical solution for preserving the data between CI/CD scans. A permanent, externally managed package store makes it possible to deploy the rl-scanner Docker image in more advanced workflows.

Specifically, working with a package store lets you:

Keep in mind that the storage space used by a package store increases with every new scan. At some point, it may become necessary to clean up old scan reports and free up storage space. You can do this with the rl-prune helper tool provided with the rl-scanner Docker image.

Customizing the scan configuration

Custom configuration is generally recommended only in advanced use-cases, as it may result in unwanted consequences.

If you decide to modify the .info policy configuration files in your package store, first make sure to understand how policy controls work in the Spectra Assure CLI.

Prerequisites​

To successfully use the rl-scanner Docker image with a package store, 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 licensing guide to get it from ReversingLabs.

  3. A package store to work with. Use the rl-secure init command to set up the package store. The package store should contain at least one project with at least one package version. The package store must be external to the Docker container, and must be in a location that Docker can access. It needs to be mounted to the Docker container as a volume with write permissions so that the analysis results and any other relevant metadata can be saved.

Scan a package in the store​

In this example, we're going to scan a package in the previously initialized rl-secure package store.

The following command will use the rlstore directory located in the current working directory as the default package store, and add a package version to the store with the project/package@1.0.0 package URL.

After the scan, the package version 1.0.0 and its analysis results remain in the store, and can be used in the future (for example, to compare against a newer package version).

Pull the image from Docker Hub
docker pull reversinglabs/rl-scanner:latest
Docker command to scan a file
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/package@1.0.0 \
    --package-path=/packages/project-1.0.0.tgz \
    --report-path=/report \
    --report-format=rl-html

The Docker options used in this command are similar to the basic workflow options.

The difference is in the additional parameters you must provide in package store workflows:

  • -v "$(pwd)/rlstore:/rlstore" for mounting the package store as a volume to the Docker container
  • --rl-store for the path to the package store
  • --purl for the package URL to assign to the scanned file

Create a diff for versions in the store​

Package versions can be compared to create a diff, which can be useful for tracking changes across software releases and recognizing if your software has been tampered with.

In this example, we're going to scan a new version of a package that exists in the previously initialized rl-secure package store. The new version is 1.1.0 and the existing version in the store is 1.0.0. Both versions must be associated with the same project and package.

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

The analysis report for the new version will contain the Diff page with all the differences between the two versions. That information can only be displayed in the rl-html report, so make sure to set the --report-format parameter to either rl-html or all.

Pull the image from Docker Hub
docker pull reversinglabs/rl-scanner:latest
Docker command to compare package versions
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/package@1.1.0 \
    --package-path=/packages/project-1.1.0.tgz \
    --report-path=/report \
    --report-format=rl-html \
    --diff-with=1.0.0

The Docker options used in this command are similar to the basic workflow options.

The difference is in the additional parameters you must provide in permanent package store workflows:

  • -v "$(pwd)/rlstore:/rlstore" for mounting the package store as a volume to the Docker container
  • --rl-store for the path to the package store
  • --purl for the package URL to assign to the new package version
  • --diff-with for the previously analyzed package version to compare against

Perform a reproducibility check​

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.

This workflow requires a previously initialized package store and a build artifact that has already been scanned and added to the store as a package version. For that package version, you can perform a reproducibility check by associating another build artifact with it. To do this, scan a new artifact with the ?build=repro parameter appended to the package URL of the same version. The previously scanned artifact is used as the reference against which the new build artifact we're scanning will be compared.

In this example, we're working with the package version project/package@1.1.0. We're scanning another build artifact for the same package version and appending the build=repro qualifier to the package URL: project/package@1.1.0?build=repro. This qualifier indicates our intention to perform a reproducibility check, and tells the scanner to treat the newly scanned file as a reproducible build artifact of an existing package version, not as a separate version in the store.

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 can 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 project/package@1.1.0.

Pull the image from Docker Hub
docker pull reversinglabs/rl-scanner:latest
Docker command to scan a reproducible build artifact
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/package@1.1.0?build=repro \
    --package-path=/packages/project-1.1.0-build-2.tgz \
    --report-path=/report \
    --report-format=rl-html

The Docker options used in this command are similar to the basic workflow options.

The difference is in additional parameters you must provide in package store workflows:

  • -v "$(pwd)/rlstore:/rlstore" for mounting the package store as a volume to the Docker container
  • --rl-store for the path to the package store
  • --purl for the package URL of the previously analyzed package version
  • ?build=repro qualifier added to the package URL for the reproducibility check

Clean up old package versions in the store​

The rl-prune helper tool supports different parameters for specifying the package store cleanup criteria.

In this example, we're going to remove all versions of a project that were scanned more than 15 days ago.

Pull the image from Docker Hub
docker pull reversinglabs/rl-scanner:latest
Docker command to prune package versions from the store
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