Skip to main content

How to configure ReversingLabs Levels

New RL-Levels defaults

Prior to rl-secure 1.4.0, RL-Levels were an opt-in feature and had to be explicitly enabled in the policy configuration.

Starting with rl-secure 1.4.0, RL-Levels are enabled by default and set to level 5 for every newly created package store, project, and package. You can override those defaults in policy configuration files.

If you already have RL-Levels configured, your current settings will be preserved after upgrading to rl-secure 1.4.0.

Existing package stores, projects, and packages without any RL-Levels configuration will start using level 5 after upgrading to rl-secure 1.4.0. To prevent this, you should disable RL-Levels before running rl-secure sync with 1.4.0.


ReversingLabs Levels (RL-Levels) are predefined sets of policy controls that help you gradually improve your software security. Instead of having to manually modify the behavior of each individual policy, you can select a level and apply ReversingLabs-recommended settings to many policies at once. As a result, RL-Levels reduce the risk of false positives and prevent issues caused by mutually incompatible policy modifications.

RL-Levels are primarily concerned with your software build status. If your software satisfies all criteria for a specific level, it receives the PASS status on that level.

There are five RL-Levels, with L1 being the most basic security level, and L5 the most advanced. Different level settings can be used in different scenarios and for specific purposes:

  • L1 - suitable for CI/CD, as it should fail you only under the most extreme conditions (such as build compromise).
  • L3 - suitable for nightly builds in CI/CD, as it will catch the most severe issues prior to release.
  • L5 - recommended for software releases, as it is the most secure level.

RL-Levels are designed around the idea of a maturity model, where every level requires that your software satisfies the criteria on previous levels. Each RL-Level sets specific security goals and indicates which components of your software fail to attain those goals.

To improve your software quality and security, use RL-Levels as milestones for security improvement, and create a process around "leveling up". Focus on passing the configured level while continuously assessing how far you are from the next level.

To learn more about RL-Levels and how they work, read our conceptual docs.

Prerequisitesโ€‹

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

  • Install the latest rl-secure version. The RL-Levels feature was first introduced in version 1.2.0.

  • Set up a project and package(s) to work with. If you haven't yet created any projects and packages, follow the instructions in the quick start guide.

Initial RL-Levels settingsโ€‹

In rl-secure 1.4.0 and newer, RL-Levels are enabled by default. Every new package store you create automatically uses the most secure level (L5), and this setting propagates down to all projects and packages in the store.

To set a different level when creating a package store, use the --rl-level option with the rl-secure init command.

Similarly, you can use the --rl-level option with the rl-secure create command to configure the level when creating new projects and packages.

You can override those initial settings and change your RL-Levels configuration at any point in the policy configuration files.

Configure RL-Levelsโ€‹

You can configure RL-Levels:

  • globally - for all projects and packages in your package store
  • selectively - only for specific projects and packages
RL-Levels configuration inheritance

If RL-Levels are configured for the package store, all projects and packages in the store automatically inherit the configuration. Users can override those global settings in policy configuration files for every project and package in the store.

In the Spectra Assure Portal, RL-Levels are configured in the context of user management (organizations and groups), not for specific projects or packages. All groups in an organization inherit the configuration. Every group can override organization settings to use a different level.

Configure RL-Levels globallyโ€‹

Use this approach to override the default L5 setting for the package store.

  1. To configure RL-Levels for a package store, find the .repository-policy.info file in the .rl-secure directory in your store. Open the file in your preferred text editor.

  2. In the .repository-policy.info file, find the profile "repository_profile" section. Add the rl_scan_level option to this section, followed by the level number (1-5) as in the following example.

Example .repository-policy.info file
policies 
{
profile "repository_profile"
{
inherit_rules "sdlc_default"
rl_scan_level 1
; user rules come here
}
}
  1. Save your changes to the .repository-policy.info file and close it.

  2. To apply the changes, you must reprocess your packages with the rl-secure sync command. The command automatically detects which packages need to be reprocessed. Depending on the amount and the size of packages in your store, reprocessing may take a while to complete. Reprocessing packages with this command does not affect your monthly analysis capacity.

Configure RL-Levels for projects and packagesโ€‹

Use this approach to apply different RL-Levels settings to different projects and packages, and to override the package store settings.


  1. To configure levels for a project in your package store, find the .project-policy.info file in the .rl-secure/projects/my-project directory in your store. Open the file in your preferred text editor.

  2. In the .project-policy.info file, find the profile "project_profile" section. Add the rl_scan_level option to this section, followed by the level number (1-5) as in the following example.

Example .project-policy.info file
policies 
{
profile "project_profile"
{
inherit_rules "repository_profile"
rl_scan_level 2
; user rules come here
}
}
  1. Save your changes to the .project-policy.info file and close it.

  2. To apply the changes, you must reprocess the packages in the project with the rl-secure sync pkg:rl/my-project command. Reprocessing packages with this command does not affect your monthly analysis capacity.

Find the RL-Levels information in the outputโ€‹

If you have modified your RL-Levels settings, you should reprocess your packages and confirm that your settings are correctly applied.

Using rl-secure, you can check this:

Information about RL-Levels in the rl-secure output should be consistent with the information you get in the HTML report even if it's presented differently.

RL-Levels in the CLI outputโ€‹

The following rl-secure commands can display information about RL-Levels in the output:

  • rl-secure find - shows RL-Levels when searching for issues by policy IDs; can also display issues blocking the upgrade to a specific level
  • rl-secure list - shows RL-Levels in all output; includes details in the risk assessment card
  • rl-secure inspect - shows RL-Levels when displaying the package status and filtering issues in a package; can also display issues blocking the upgrade to a specific level

The main difference between rl-secure CLI output with and without RL-Levels is in the CI/CD status indicators.

When RL-Levels are disabled, CI/CD status is indicated by the CI:PASS/FAIL labels.

When RL-Levels are enabled, CI/CD status is indicated by LX:PASS/FAIL, where X corresponds to the level you configured (the level at which a package was scanned).

If you modify the policy configuration to relax RL-Levels requirements, the CI/CD status indicators change to CX:PASS/FAIL, where C shows you are using Custom Levels, and X corresponds to the level at which a package was scanned.

Compare the following examples of the rl-secure list command output.

  / 7zip
/ linux
@ [ CI:PASS ] 22.01
/ windows
@ [ CI:PASS ] 19.0
@ [ CI:PASS ] 22.01

The fastest way to confirm that RL-Levels are working is to run rl-secure list for the package store where you configured the feature.

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

The output indicates the current RL-Levels status for all packages in your store. If you configured different RL-Levels for different projects and packages, the output will reflect that.

  / 7zip
/ linux
@ [ L1:PASS ] 22
@ [ L1:PASS ] 9
/ windows
@ [ L3:PASS ] 19
@ [ L3:PASS ] 22
/ music-software
/ itunes
@ [ L1:PASS ] latest
/ spotify
@ [ L1:PASS ] latest
/ slack
/ linux
@ [ L4:PASS ] 4.25
@ [ L4:FAIL ] 4.28

As the next step, you can use other rl-secure commands to take a deeper look at issues that might be failing on the current level and/or preventing you from upgrading to a higher level.

RL-Levels in the HTML reportโ€‹

To confirm your RL-Levels configuration is correctly applied, you can generate the HTML report for a package version with the rl-secure report command.

By default, reports are saved to the package version subdirectory in your package store. You can specify a custom directory to save reports to with the --output-path option.

rl-secure report rl-html --purl=pkg:rl/my-project/my-package@1.0.1 --rl-store=/home/armando/my-repository/ --output-path=/home/armando/my-reports

When your HTML report is generated, access it and open it in your web browser. The main areas where you can notice information about RL-Levels are:

  • the top section of the report
  • the Issues page on the left-hand side of the report

The top section shows:

1 - your package CI/CD status (LX PASS or LX FAIL) for the configured RL-Level

2 - the RL-Levels status summary for the package

Levels in the top section of the HTML report

In the summary, you can see the currently configured level (Scan Level) and the path to the next level your package can attain (Best Level).

If the path is clear, Best Level is highlighted and animated.

If there are issues to resolve, this section indicates their amount and links to more details about them in the report. Scan Level can be equal to Best Level when it's the highest level your package can attain without any changes.

When Best Level is lower than Scan Level, that indicates the actual level your package was able to attain. It can't attain the currently configured level until you resolve all issues between Best Level and Scan Level.

Disable RL-Levelsโ€‹

To stop using RL-Levels altogether, you can disable the feature by setting the rl_scan_level option to zero in policy configuration files.

You can disable RL-Levels:

  • globally - for the whole package store in the .repository-policy.info file
  • selectively - only for specific projects and packages in their respective project-policy.info and package-policy.info files

In this example, we're going to disable RL-Levels only for a specific package.

When RL-Levels are disabled for a package, all package versions inherit the configuration, and rl-secure does not use RL-Levels when scanning them.

  1. To disable RL-Levels for a package in any of your projects, find the .package-policy.info file in the .rl-secure/projects/my-project/packages/my-package directory in your store. Open the file in your preferred text editor.

  2. In the .package-policy.info file, find the profile "package_profile" section. Set the rl_scan_level option to zero as in the following example.

Example .package-policy.info file
policies 
{
profile "package_profile"
{
inherit_rules "project_profile"
rl_scan_level 0
; user rules come here
}
}
  1. Save your changes to the .package-policy.info file and close it.

  2. To apply the changes, you must reprocess the package with the rl-secure sync pkg:rl/my-project/my-package command. This will reprocess all versions of the package. Reprocessing packages with this command does not affect your monthly analysis capacity.

  3. After reprocessing the package with RL-Levels disabled, check the CLI output and/or HTML report to confirm that your settings are correctly applied. RL-Levels indicators should not be present anywhere, and the CI/CD status indicators should use CI:PASS/FAIL labels.

Next stepsโ€‹