Skip to main content

Supported rl-safe commands

Learn more about supported rl-safe commands.

Generally, the commands produce detailed, actionable output with recommendations for next steps.

You can always access inline help in your terminal with rl-safe help, or with rl-safe command-name --help for specific commands.

pack​

Description​

Generates the RL-SAFE archive for a software package previously analyzed with rl-secure.

By default, the RL-SAFE archive is named report.rl-safe and created in the package-name/versions/package-version-number/reports directory in the package store.

The archive does not depend on the rl-secure report command and it is not related to its output. You can create the archive immediately after scanning a software package with rl-secure scan.

RL-SAFE archive contents​

When using the rl-safe pack command, you must always specify which report formats to include in the RL-SAFE archive alongside the SAFE report. Only the specified report formats can later be exported from the SAFE Viewer.

The all option includes all supported report formats. The rl-checks report is always automatically included, but cannot be controlled with the rl-safe pack command. The rl-json report format is not supported.

RL-SAFE archives never contain the binary (the software package itself) - only the reports and configuration files. If needed, configuration files can also be excluded from the archive.

RL-SAFE archives created with rl-safe pack can contain multiple diffs for a package version. Archives exported from the Spectra Assure Portal can contain only one diff per package version. To include multiple diffs into an RL-SAFE archive, run the rl-safe pack command with the --diff-with option multiple times, each time specifying a different version.

If a package version has a reproducible build artifact, it is possible to create the RL-SAFE archive for it by appending the ?build=repro option to the package URL in the rl-safe pack command.

Protected RL-SAFE archives​

When creating the RL-SAFE archive, it is possible to protect it with a password. This password is not related to passwords used to protect the software package and/or saved to the package store vault. The password set with rl-safe pack only protects the RL-SAFE archive and has no impact on the software package itself.

Usage​

rl-safe pack <csv-format-list> <purl> [<options>]

Options​

OptionDescription
--formatRequired. A comma-separated list of one or more report formats to include in the RL-SAFE archive alongside the SAFE report. If the parameter name (--format) is omitted, the list of formats must be specified immediately after the pack command. Supported values: cyclonedx, rl-cve, rl-uri, sarif, spdx, and all. The all option includes all supported formats. Note that the rl-checks report is always automatically included and cannot be controlled with this command.
-p, --purlRequired. Package URL of the scanned file for which you want to generate the RL-SAFE archive. Must be in the format [pkg:type/]<project></package><@version>. The specified package URL must exist in the package store.
-s, --rl-storePath to an initialized package store containing the package URL. If you don't specify the path, the current directory is used.
--output-pathPath to a directory where the RL-SAFE archive should be saved. If not provided, the archive is saved to the specified version's subdirectory in the package store. The default RL-SAFE archive file name is report.rl-safe
--diff-withUsed for creating diffs (comparisons) between two package versions (the version for which you're generating the archive and another, usually preceding version). Both package versions must be in the same project and package. Specify a previously analyzed package version to include diff information in the RL-SAFE archive. Only the version part of the package URL needs to be specified. To include multiple diffs in the RL-SAFE archive, run this command multiple consecutive times, each time with another version specified.
?build=reproGenerate the RL-SAFE archive for a previously analyzed reproducible build artifact of the specified package version. This option must be appended to the package URL of the selected package version, in the format [pkg:type/]<project></package><@version?build=repro>. If you don't specify this option and the selected package version has a reproducible build artifact, the RL-SAFE archive will be generated only for the main artifact.
--password, --pack-passwordSpecify a password to protect the generated RL-SAFE archive. When the archive is password-protected, its contents cannot be viewed without providing the password. If you plan to share a password-protected RL-SAFE archive with others, make sure to send them the correct password.
--no-repo-configDo not include package store configuration files in the RL-SAFE archive. By default, configuration files are included. They cannot be viewed in the SAFE Viewer, but if you open the RL-SAFE archive with a file archiver utility, these configuration files are visible in the configs/rl-secure directory.
--no-base-configDo not include base analysis engine configuration files in the RL-SAFE archive. By default, configuration files are included. They cannot be viewed in the SAFE Viewer, but if you open the RL-SAFE archive with a file archiver utility, these configuration files are visible in the configs/rl-engine directory.
--no-trackingDon't display progress bars.
-h, --helpDisplay usage information and exit.

Examples​

Exclude specific formats and configuration files​

In this example, we're creating a lightweight RL-SAFE archive for a software package we previously analyzed with rl-secure and added to our package store.

Instead of including all supported report formats, we only want the rl-cve format. Additionally, we want to exclude all configuration files from the archive.

The command expects the package store to exist in the current directory. Use the -s or --rl-store options to provide an alternative path to the package store.

The command output indicates that the rl-checks report was automatically included in the RL-SAFE archive.

When you open this archive with the SAFE Viewer, the Export menu will only contain the rl-cve report. If you open the archive with a file archiver utility, you will notice it does not contain the configs directory.

rl-safe pack rl-cve pkg:rl/my-project/my-package@1.0 --no-repo-config --no-base-config

Create a password-protected RL-SAFE archive​

In this example, we're creating a password-protected RL-SAFE archive for a software package we previously analyzed with rl-secure and added to our package store.

We're specifying the password with the --password option in the command. For the analysis report formats, we're using the all option to include all supported reports in the archive.

When the archive is created, it will not be possible to view its contents without providing the correct password. The SAFE Viewer will detect that the archive is password-protected and will prompt the user for the password. The rl-safe verify command will also require providing the password for this archive. If the archive is opened with a file archiver utility, it will not be possible to extract it without the password.

The command expects the package store to exist in the current directory. Use the -s or --rl-store options to provide an alternative path to the package store.

rl-safe pack all pkg:rl/my-project/my-secret-package@v1 --password VerySecureSoftware!

verify​

Description​

Performs integrity verification of an RL-SAFE archive previously created with rl-safe pack or exported from the Spectra Assure Portal (UI or API).

The SAFE report and any other report formats contained in the RL-SAFE archive can only be accessed if the archive passes integrity verification.

If the RL-SAFE archive you want to verify has been password-protected, you must specify the correct password with the --password option.

caution

Users should treat RL-SAFE archives as read-only files and not attempt to modify them. Trying to modify or repackage the RL-SAFE archive can make it unusable and may result in irreversible data loss.

Usage​

rl-safe verify <path> [<options>]

Options​

OptionDescription
-p, --pathRequired. Path to an existing RL-SAFE archive you want to verify. The parameter name may be omitted, but then the path must be specified immediately after the verify command.
--password, --pack-passwordIf the RL-SAFE archive you want to verify is password-protected, use this option to specify the password. Without the correct password, it will not be possible to verify the archive.
-h, --helpDisplay usage information and exit.

Examples​

Verify an RL-SAFE archive​

In this example, we have received an RL-SAFE archive called myreport.rl-safe from another Spectra Assure user. We want to verify the integrity of this RL-SAFE archive before working with it or sharing it with others.

Because RL-SAFE archives are independent of any package store, the rl-safe verify command can be executed anywhere, as long as you specify the correct path to the RL-SAFE archive you want to verify.

In this example, we're going to run the command in the same location where we placed the RL-SAFE archive. The command output shows us the software package version and indicates if the RL-SAFE archive contains any other report formats or diffs alongside the SAFE report.

rl-safe verify myreport.rl-safe