Skip to main content

Get started with rl-secure

This quick start guide is for users who want to try the ReversingLabs Spectra Assure CLI (rl-secure) in less than 10 minutes.

In this guide, you will learn how to scan your first software package and display analysis results. To learn about all supported features and functionalities, refer to the Supported rl-secure commands section in our documentation.

Prerequisites​

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

  • Install rl-secure locally. Follow the instructions in the installation guide.

  • Prepare a test file to work with. 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. It's recommended to place the package into a directory with a short, handy name.

1. Initialize a package store​

In this step, you will create a local package store. This is a special directory where rl-secure keeps your projects, scanned software packages, and analysis results.

You can initialize the package store anywhere on your system. In this example, we're showing how to initialize it on a Linux-based system in the user's home directory.

  1. In your terminal, navigate to the directory where you want to create the package store.

  2. Run the rl-secure init command followed by an optional custom name for your package store.

rl-secure init --rl-store=/home/armando/my-repository/

You should now be able to browse the contents of your newly initialized package store. By default, it contains only hidden configuration files and folders.

2. Scan a new software package​

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 analysis results for your software package. If you check the contents of your package store, you will notice a new subdirectory called projects containing your newly added package.

3. Display analysis results​

In this step, you will request an overview of analysis results for your package and then filter the results to find specific details.

  1. In your terminal, navigate to the package store where you previously added a package. 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 status command followed by the package URL of your package.

rl-secure status pkg:rl/my-project/my-package@v1

By default, this command returns a condensed version of the analysis results, with indicators for the overall CI status at the configured level (LX:PASS or LX:FAIL) and the total count of issues by severity (high, medium, low). The priority indicator (P0-P4) shows the highest priority across all issues (for example, if only one of the issues is P0, the indicator will show P0).

To get more information about all types of issues detected in your package, you need to use the rl-secure inspect command. This command supports different options that can be combined to filter out the detailed analysis results.

In this example, we're requesting more details about issues with the CI fail status.

rl-secure inspect pkg:rl/my-project/my-package@v1 --show-issues --fail-only

The full analysis report contains rich, detailed information about every single component in your package file. To make the full analysis report easier to inspect, share, and store, you can export it.

4. Save the analysis report​

In this final step, you will save the full analysis report as a standalone file in one of the supported report formats. The rl-secure report command supports different report formats, including CycloneDX, SARIF, SPDX, and special ReversingLabs reports.

  1. In your terminal, navigate to the package store that contains your analyzed package. 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 report command followed by the desired report format and the package URL of your software package. In this example, we're requesting the rl-html format (the ReversingLabs SAFE report), and using the --output-path option to save the report to the current directory.

rl-secure report rl-html pkg:rl/my-project/my-package@v1 --output-path .
  1. To work with the saved report, access the location where you exported it. By default, the report file is named sdlc.html and placed into the automatically created rl-html directory. The __deps subdirectory contains all assets required to display the SAFE report.
Congratulations!

You have successfully completed a basic workflow with ReversingLabs Spectra Assure CLI.

Explore the resources on this documentation website to learn how you can secure your software with rl-secure.

Next steps​