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 SAFE report (rl-html format), 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

Save passwords for versions in the store​

Password-protected files can be scanned with the rl-scanner Docker image. However, without passwords to decrypt such files during analysis, the scanner produces incomplete analysis reports. This is why you have to provide passwords for password-protected files when scanning them.

If you are using a package store, you can save the passwords associated with scanned package versions to support more permanent password management workflows. The passwords are saved inside the package store in a secure vault and protected by a master vault key.

You can set up the vault for a package store in any of the following ways:

  • while creating the package store with the rl-secure init command
  • at any point after the package store has been created with the rl-secure vault command
  • when scanning a password-protected file with rl-scanner by providing the --vault-key parameter in the Docker command

In all cases, the vault key is an arbitrary user-provided string, meaning that you can freely choose the vault key for your package store. You can provide the key with the --vault-key parameter or with the RLSECURE_VAULT_KEY environment variable. The vault key must be provided to the Docker container together with the file password whenever you want to scan a password-protected file and save its password to the vault.

How to modify passwords saved to the vault

If you need to change the passwords previously saved to the vault, you can do that with your rl-secure installation that you used to create the package store.

Use the rl-secure vault command to modify passwords for specific package versions in the package store. The same command can be used to change the master vault key for the package store, too. Note that you will have to update the vault key value in your environment variables, scripts, and Docker commands after changing it with rl-secure.

In this example, we're scanning a password-protected archive and adding it to the package store as the package version project/package@1.0.0.

The following command will scan the new package version and use the file password provided with the --password parameter to decrypt and extract the protected file contents.

Because we're specifying the vault key with the RLSECURE_VAULT_KEY environment variable, the file password will be saved to the vault of the package store mounted to the container.

Pull the image from Docker Hub
docker pull reversinglabs/rl-scanner:latest
Docker command to scan a password-protected file
docker run --rm \
  -u $(id -u):$(id -g) \
  -v "$(pwd)/packages:/packages:ro" \
  -v "$(pwd)/rlstore:/rlstore" \
  -v "$(pwd)/report:/report" \
  -e RLSECURE_VAULT_KEY=ExampleVaultKey \
  -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 \
    --password=ExampleFilePassword123

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:

  • -e RLSECURE_VAULT_KEY=ExampleVaultKey for allowing access to the package store password vault and saving the file password to it. Alternatively, the vault key can be provided with the --vault-key parameter
  • -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
  • --password for decrypting the protected contents of the file you're analyzing. Alternatively, the file password can be provided as a path to the password list (with the --password-list parameter) or as the Base64-encoded contents of the password list (with the --encoded-password-list parameter)

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