Skip to main content

Get started with RL-SAFE archives

rl-safe is a CLI tool created by ReversingLabs to enable working with RL-SAFE archives.

The RL-SAFE archive format helps users of all Spectra Assure products to exchange and store the full SAFE reports for their software packages.

What are RL-SAFE archives?​

RL-SAFE is a portable archive that contains the full SAFE report and all other supported report formats for a software package. In this context, "portable" means that the RL-SAFE archive can be freely shared and moved between different computers and viewed without access to a Spectra Assure Portal instance or CLI installation. The archive can be downloaded from the Portal UI and the Portal API, or created with the CLI.

When you create or download the RL-SAFE archive for a software package, you need the SAFE Viewer to open the archive and work with the SAFE report. The SAFE Viewer is a cross-platform, free-to-use standalone application developed by ReversingLabs that lets users open RL-SAFE archives and manage SAFE reports anytime, anywhere. From the SAFE Viewer, you can export other report formats that are included in the archive, and access diff and reproducible build reports (if they exist for that software package version).

How the RL-SAFE archive handles report formats

  • Included, can be exported with SAFE Viewer: CycloneDX, rl-cve, rl-uri, SARIF, SPDX

  • Included, cannot be exported with SAFE Viewer: rl-checks

  • Not included: rl-json

Archives from unknown or unreliable sources

Even though the SAFE Viewer processes are sandboxed to minimize damage from potentially malicious code, do not open any RL-SAFE archives from unknown or unreliable sources.

RL-SAFE archives are intended to be opened with the SAFE Viewer. However, it is possible to open them with file archiver utilities like any other compressed file. If you extract the RL-SAFE archive, you will notice that it contains engine and policy configuration files alongside raw report files. The configuration files are included in the archive so that the SAFE Viewer can accurately represent the conditions used to analyze the software package.

The contents of the RL-SAFE archive cannot be modified, and the archive cannot be repackaged. Attempting to do that can make the archive unusable and may result in irreversible data loss.

What is rl-safe?​

rl-safe is a CLI tool created by ReversingLabs to simplify the process of creating and sharing SAFE reports. It is a companion tool to rl-secure and automatically installed with rl-secure 2.5.0 and newer.

rl-safe allows for significant flexibility in sharing the complete SAFE report, as RL-SAFE archives created with the tool can be shared with anyone regardless of their access to Spectra Assure products.

It also makes SAFE reports more resilient and suitable for long-term storage, as RL-SAFE archives are immutable snapshots of a software package's security status at a specific point in time. They can be used for reference in auditing processes long after the software package itself has been reprocessed or even removed.

With rl-safe, you can:

  • Create the RL-SAFE archive for any software package previously analyzed with rl-secure.
  • Control the contents of the RL-SAFE archive by specifying which other report formats to include alongside the SAFE report.
  • Password-protect the RL-SAFE archive to further control who can access its contents.
  • Verify the integrity of RL-SAFE archives shared with you or created in other Spectra Assure products.

Supported systems and architectures

rl-safe supports the same systems and architectures as rl-secure. They are listed on the System recommendations page.

Workflow overview

To work with RL-SAFE archives in Spectra Assure CLI:

  1. Analyze a software package with rl-secure
  2. Create the RL-SAFE archive for the package with rl-safe
  3. Open and manage the RL-SAFE archive with the SAFE Viewer

Who should use rl-safe?​

This guide is for users who are already familiar with rl-secure and want to start using RL-SAFE archives.

The RL-SAFE archive format is most suitable for:

  • use-cases that require long-term storage of the SAFE report for auditing and compliance purposes
  • viewing SAFE reports for software packages very large in size
  • sharing the SAFE report with stakeholders and other parties who don't have access to Spectra Assure products

When there is a new version of rl-secure available, it includes a new version of rl-safe. If you update rl-secure (or it performs a self-update), rl-safe will also be automatically updated.

To learn more about rl-safe, refer to the Supported rl-safe commands section in our documentation.

Prerequisites​

The following tasks should be completed before you start working with rl-safe:

  • Install or update rl-secure to get the rl-safe tool. The rl-safe tool was first introduced in rl-secure version 2.5.0.

  • Set up a package store and prepare a software package to scan. You can use any software package on your system for the purposes of this guide. Make sure you have permissions to access the directory containing the package. If this is your first time working with an rl-secure package store, first read the rl-secure quick start guide before continuing.

  • Get the SAFE Viewer for your operating system. You're going to need the SAFE Viewer to open the RL-SAFE archive after you create it with rl-safe. You can download the SAFE Viewer directly from this documentation website.

1. Analyze a software package with rl-secure​

In this step, you will add a software package to the package store and scan it to get the analysis results.

By default, the package is copied from its original location into the package store and automatically assigned to a project as a new package version. This behavior is configurable, but in this example we're showing how it works without setting any specific options.

  1. In your terminal, navigate to the directory where you initialized the package store. If you skip this step, you must specify the path to the package store with the -s argument in the next step.

  2. Run the rl-secure scan command followed by the path to your package file and the package URL in the format pkg:type/project-name/package-name@package-version. This special URL serves as a unique identifier that registers your software package in the package store.

rl-secure scan /home/armando/my-package.exe pkg:rl/my-project/my-package@v1

You should now be able to view the analyzed software package in your rl-secure package store. Run rl-secure list to check that the project, package and version you scanned are included in the package store, and that the analysis results are being correctly displayed.

2. Use rl-safe to create an RL-SAFE archive​

In this step, you will create an RL-SAFE archive for the software package scanned in the previous step.

By default, the RL-SAFE archive contains the SAFE report, all other supported report formats, and various configuration files. This behavior is configurable, but in this example, we're showing how it works without setting any specific options.

  1. In your terminal, navigate to the directory where you initialized the package store. If you skip this step, you must specify the path to the package store with the -s argument in the next step.

  2. Run the rl-safe pack command followed by the formats to include in the archive and the package URL in the format pkg:type/project-name/package-name@package-version. The package URL must match the one created in the previous step.

As we don't want to exclude any report formats in this case, we're going to use the all option to add all supported formats to our RL-SAFE archive. 

rl-safe pack all pkg:rl/my-project/my-package@v1

You should now be able to access the newly created RL-SAFE archive in the directory specified in the command output. By default, the archive is placed into the package-name/versions/package-version-number/reports directory in your package store. As you get familiar with rl-safe, you may find it more convenient to save RL-SAFE archives to a custom location. You can do that with the --output-path option.

The default RL-SAFE archive file name is report.rl-safe. After it's created, you can freely copy or move the archive to a different location, or even change its file name. Make sure to keep the archive extension (.rl-safe) if you decide to rename it.

3. Open the RL-SAFE archive with SAFE Viewer​

In this step, you will open the RL-SAFE archive created in the previous step to view the SAFE report for the analyzed software package.

  1. Open the SAFE Viewer application you previously installed on your system.

  2. Drag and drop the RL-SAFE archive file into the designated spot in the SAFE Viewer, or select Choose a File in the middle of the drag-and-drop area to open the file browser and select the RL-SAFE archive file in it.

The SAFE Viewer performs integrity verification before displaying the report contents. Usually, the verification process is done instantly, but may take a while for large reports.

The SAFE report opens automatically if the integrity verification passes.

You can then freely share your RL-SAFE archive with other people in your organization or even with external stakeholders and collaborators to allow them to view the SAFE report for your software package. They will have to install the SAFE Viewer to open the archive.

Next steps​