Skip to main content

How to configure SAFE Levels

SAFE 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, SAFE Levels reduce the risk of false positives and prevent issues caused by mutually incompatible policy modifications.

SAFE 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 SAFE 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.

SAFE Levels are designed around the idea of a maturity model, where every level requires that your software satisfies the criteria on previous levels. Each SAFE 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 SAFE 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 SAFE Levels and how they work, read our conceptual docs.

Prerequisites​

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

  • Install the latest rl-secure version. The SAFE 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 SAFE Levels settings​

In rl-secure 1.4.0 and newer, SAFE 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 SAFE Levels configuration at any point in the policy configuration files.

Configure SAFE Levels​

You can configure SAFE Levels:

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

If SAFE 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, SAFE 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 SAFE Levels globally​

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

  1. To configure SAFE 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 SAFE Levels for projects and packages​

Use this approach to apply different SAFE 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 SAFE Levels information in the output​

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

Using rl-secure, you can check this:

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

CLI output​

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

  • rl-secure find - shows SAFE Levels when searching for issues by policy IDs; can also display issues blocking the upgrade to a specific level
  • rl-secure list - shows SAFE Levels in all output; includes details in the SAFE assessment card
  • rl-secure inspect - shows SAFE 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 SAFE Levels is in the CI/CD status indicators.

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

When SAFE 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 SAFE 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 SAFE 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 SAFE Levels status for all packages in your store. If you configured different SAFE 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.

SAFE report​

To confirm your SAFE Levels configuration is correctly applied, you can generate the SAFE report (rl-html) 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 SAFE report is generated, access it and open it in your web browser. The main areas where you can notice information about SAFE Levels are:

  • the Summary page
  • the Issues page

The Summary page shows:

1 - the overall CI/CD status (LX PASS or LX FAIL) of your software package for the configured SAFE Level

2 - the SAFE Levels status summary for the software 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 SAFE Levels​

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

You can disable SAFE 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 SAFE Levels only for a specific package.

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

  1. To disable SAFE 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 SAFE Levels disabled, check the CLI output and/or SAFE report to confirm that your settings are correctly applied. SAFE Levels indicators should not be present anywhere, and the CI/CD status indicators should use CI:PASS/FAIL labels.

Next steps​