Skip to main content

Configure rl-secure policies

In the context of rl-secure, policies are built-in rules that prescribe how software should behave in order to be considered secure. During analysis, rl-secure may detect that your software package breaks those rules. If that happens, the analysis report warns you about policy violations and presents them in the list of detected issues. You can then take the appropriate measures to resolve the issues.

By default, rl-secure is optimized and ready to use right after installation without requiring any policy configuration.

However, some use-cases may require modifying default policy settings. This is done through policy configuration files that allow you to control the behavior of rl-secure.

More specifically, you can:

  • Create or adjust the criteria for evaluating rl-secure policies
  • Change how policies impact the final verdict for your software build status
  • Define secrets specific to your organization and make exceptions for them if necessary
  • Disable policies to suppress issues in the analysis report
  • Block or require specific behavior to enforce best practices in your organization

In this guide, you will learn the basics of working with rl-secure policy configuration files.

What about the rl-secure config command?

The config command lets you control some of the rl-secure settings, but it is not used for policy configuration.

The only way to configure built-in policies for rl-secure is through configuration files described in this guide.

Prerequisites​

To successfully work with rl-secure policy configuration, you should:

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

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

  • Familiarize yourself with rl-secure commands and features. If you haven't previously analyzed any software with rl-secure, we strongly recommend you learn more about using rl-secure commands.

    Specifically, you should learn how to use the scan, report, and sync commands. They are essential for the basic workflow - analyzing software packages, generating analysis reports, and refreshing the package store after modifying policy settings, respectively.

Policy configuration files​

After you install rl-secure and initialize a package store, policy configuration files are generated automatically in every level of the package store. Those files are human-readable and can be modified in any text editor.

To change the policy configuration for your rl-secure installation, you don't need to create any new configuration files. All custom configuration is done by modifying the contents of the default configuration files.

File naming and location​

Every rl-secure package store contains three types of policy configuration files - repository, project, and package.

There is only one repository configuration file per package store, and it is located in the root directory. Every project in the package store has its own project configuration file. Likewise, there is a configuration file for every package in the package store.

The following example visualizes the structure of a rl-secure package store with configuration files highlighted and numbered:

/home/armando/my-repository/
└── .rl-secure/
    ├── .yara/
    ├── .cacerts/
    ├── .repository-policy.info  1️⃣
    └── projects/
        └── my-project/
            ├── .yara/
            ├── .project-policy.info  2️⃣
            └── packages/
                └── my-first-package/
                    ├── .yara/
                    └── .package-policy.info  3️⃣   
                └── my-second-package/
                    ├── .yara/
                    └── .package-policy.info  3️⃣
        └── external-project/
            ├── .yara/
            ├── .project-policy.info  2️⃣
            └── packages/
                └── external-project-package/
                    ├── .yara/
                    └── .package-policy.info  3️⃣

The scope of each configuration file is reflected in its file name. Policy configuration files are automatically created with the following names:

  • 1️⃣ .repository_policy.info - in the root directory of the package store. Settings defined in this file apply to all contents of the package store unless specifically overridden in other configuration files.
  • 2️⃣ .project_policy.info - in every projects/project-name subdirectory in the package store. Settings defined in this file apply to all packages and versions in the project unless specifically overridden in other configuration files.
  • 3️⃣ .package_policy.info - in every projects/project-name/packages/package-name subdirectory in the package store. Settings defined in this file apply to all package versions associated with the package-name.

Policy configuration files must use these default file names. Custom file names for policy configuration files are not supported.

The file names must start with the . character and end with the .info file extension. Depending on your operating system, such files may be treated as "hidden" and may not be visible by default when you try to browse the contents of your rl-secure package store. Graphical file managers usually have a setting to display hidden files. You can also access the package store from the command-line interface and use the appropriate commands to show all files in the package store.

Policy configuration files must be located on the appropriate level of the package store where they were created by default. Alternative locations for policy configuration files are not supported. It is not possible to use an external policy configuration file (a file kept outside of the package store).

File format, syntax, and structure​

Recover from syntax errors

If analysis fails because of syntax errors in configuration files, you must run rl-secure clean to repair the package store.

This command is required even if you already corrected your configuration files.

Policy configuration files use the Boost INFO file format where configuration options are represented as a property tree.

Every policy configuration file has multiple sections (nodes) with key-value pairs. A section can have one or more sub-sections (subnodes). The indentation of sections is important, as it reflects their nesting level and hierarchy.

Every section starts with { and ends with }. If a section is included in the configuration file as empty (without any sub-sections or options), rl-secure will just ignore it.

In the key-value pairs, the key represents the configuration option name. To modify a configuration option, you have to change the value assigned to it.

To separate a key from its value, you can use spaces or tabs. Every key-value pair should be in its own line in the configuration file. A value can be empty, in which case rl-secure treats it as unset and applies the value from the default configuration, or from another configuration file (if it exists).

Policy configuration files support the following data types as values:

  • boolean - set as true or false
  • number (integer)
  • string - set enclosed within quotation marks like "example". The \ is used as the escape character when " is part of the value.

Custom comments are supported in policy configuration files, and must be prepended by a semicolon ;. In the following example, comments are used on highlighted lines (6, 7, 10).

Example policy configuration file with comments
policies 
{
    profile "project_profile"
    {
        inherit_rules  "repository_profile"
        rl_scan_level   1 ; For testing purposes only           
        leak_threshold  ""  ; Example empty value
        test_liveness   true 

        tracking  ; Excluding information from the diff we do not need for testing
        {
            entropy 7.0
        }
    }
}

Every policy configuration file has the policies section at the top (or root) level of the property tree. All settings are stored in the profile sub-section of policies.

A profile is essentially a named collection of settings. Profile names are reserved by rl-secure and must not be changed by users. The following default profiles are used in policy configuration files:

  • repository_profile - automatically assigned to the .repository_policy.info file
  • project_profile - automatically assigned to every .project_policy.info file
  • package_profile - automatically assigned to every .package_policy.info file

The default profiles are automatically configured for configuration inheritance on every level of the package store.

Custom profiles are not supported. You should not attempt to remove or rename the default profiles, or add new profiles to configuration files. The inherit_rules option that controls configuration inheritance must not be changed in any of the configuration files.

Configuration precedence and resolution​

Policy configuration is hierarchical within each rl-secure package store, and settings can be inherited from higher levels of the package store hierarchy.

The rl-secure CLI automatically discovers policy configuration files within the package store, so you don't need to specify which configuration file to use when working with CLI commands. When executed, rl-secure scans the file tree starting from the user's current location until it finds a valid configuration file.

The .repository_policy.info is the root configuration file that controls the policy configuration for the whole package store. It is sometimes referred to as the global configuration. When they are created, all projects and packages in the store automatically inherit the default profile from this global configuration. You can override the global configuration in as many .project_policy.info and .package_policy.info files as needed.

Similarly, any configuration defined in the default profile of a .project_policy.info file is automatically inherited by all packages and versions associated with that project. You can override the default project configuration in as many .package_policy.info files as needed by modifying their default profiles.

Configuration defined in a .package_policy.info file applies to all versions associated with the package. It is not possible to have version-specific policy configuration files.

As a general rule, specific settings override global settings in case of a conflict. If the same setting is modified by multiple configuration files, rl-secure uses the value from the most specific file. In other words, if a configuration option has different values set in .repository_policy.info, .project_policy.info, and .package_policy.info at the same time, only the value from the .package_policy.info will apply.

Policy IDs and ranges are parsed as they appear in the configuration file. A policy ID should only be set once per configuration file. If there are multiple settings for the same policy ID in a configuration file (for example, in multiple different filters), rl-secure will apply the last value listed in the file.

Policy configuration schema​

This section describes the policy configuration schema and all supported options.

In every policy configuration file, the profile property tree is always nested one level under policies (the root level). You can view the example configuration file to better understand the expected structure.

How to read the schema?​

Expandable items in the schema have an arrow indicator > next to their name. Click the arrow to expand the item and view its contents. To make the schema easier to read, you can hide the navigation sidebar by selecting the << button at the bottom left of the page.

required
object

The profile section is the main container for configuration options and values in policy configuration files. By default, it is assigned a name that corresponds to the scope and location of the configuration file. Supported profile names are repository_profile, project_profile, and package_profile. Users must not change the profile name when editing policy configuration files.

{
  • "profile": {
    }
}

Example policy configuration file​

This section shows the full example of a policy configuration file with all supported options included.

Warning

This example is for illustrative purposes only. Do not use it on business-critical systems as it may produce errors or unwanted analysis results.

Example .project-policy.info file
policies
{
    profile "project_profile"
    {
        inherit_rules  "repository_profile"
        rl_scan_level   4
        leak_threshold  90
        test_liveness   true
        license_level   "weak-copyleft" 

        tracking
        {
            entropy 7.0
        }

        networking
        {
            maximum_uris 250000
            
            protocol "http*,ftp"
            {
                enabled true

                filter
                {
                    address
                    {
                        host      "*.domain.com"

                        author    "Spectra Assure"
                        reason    "Filtering all placeholder networking credentials"
                        timestamp "2023-01-01T12:00:00+00:00"

                        userinfo
                        {
                            "test" "test"
                            "user" "pass"
                            "username"
                        }         
                    }
                }

                block 
                {
                    address 
                    {
                        host      "*.domain.com"

                        author    "Spectra Assure"
                        reason    "Restricting all suspicious networking references"
                        timestamp "2023-01-01T12:00:00+00:00"

                        userinfo
                        {
                            "test" "test"
                            "user" "pass"
                            "username"
                        }  
                    }
                }

            }
        }

        liveness
        {
            verifier "github-v3" 
            {
                enabled true 

                endpoint "Private GitHub API V3" 
                {
                    enabled  true
                    location "https://github.priv/api/v3"
                    timeout  60 
                    retries  0 
                }
            }
        }

        licenses
        {
            license "OLDAP-1.*"
            {
                present   warning 
                static    fail 
                dynamic   pass 
                package   pass 

                author    "Spectra Assure"
                timestamp "2023-01-01T12:00:00+00:00"
                reason    "Explicitly restricting static linking to OLDAP 1.x license"
            }
        }

        overrides
        {
            SQ34109
            {
                enabled   false

                author    "Spectra Assure"
                timestamp "2023-01-01T12:00:00+00:00"
                reason    "Relaxing the default scanning policy"
            }
        }
        
        processing
        {
            filter
            {
                enabled   true
                
                format    "PE*/*"
                matches   "root"
                pattern   "*"
                refined   "(installer AND arch-x86) OR packed"
                
                author    "Spectra Assure"
                timestamp "2023-01-01T12:00:00+00:00"
                reason    "Explicitly allowing packed installer to ignore mitigations"
                              
                policies
                {
                    SQ141*
                    {
                        blocker pass
                    }
                }
            }

            filter
            {
                enabled   true
                
                matches   "file"
                pattern   "AWS-production-keys.txt"
                
                author    "Spectra Assure"
                timestamp "2023-01-01T12:00:00+00:00"
                reason    "Explicitly declaring secret as a canary token"
                              
                secrets
                {
                    "AKIAIOSFODNN4EXAMPLE"
                    "rl-sha256:df3e6b0bb66ceaadca4f84cbc371fd66e04d20fe51fc414da8d1b84d31d178de"
                }
            }

            filter
            {
                enabled   true
                
                matches   "path"
                pattern   "third-party/*"
                
                author    "Spectra Assure"
                timestamp "2023-01-01T12:00:00+00:00"
                reason    "Explicitly triaging third-party vulnerabilities"
                              
                triaged
                {
                    Log4Shell      mitigation-exists
                    CVE-2023-27533 vulnerable-code-unused
                }
            }

            filter
            {
                enabled   true
                
                matches   "path"
                pattern   "*"
                
                author    "Spectra Assure"
                timestamp "2023-01-01T12:00:00+00:00"
                reason    "Explicitly target specific behaviors"

                hunting
                {
                    categories
                    {
                        network   fail
                        evasion   warning
                    }

                    behaviors
                    { 
                        BH15245   fail 
                        BH16123   warning
                    }
                }
            }
        }  
    }
}

Next steps​

Follow these tutorials to modify rl-secure policy configuration for specific use-cases: