Skip to main content

Create policy filters

Filters are the most versatile feature in rl-secure policy configuration. They allow you to customize the default policy behavior to make Spectra Assure analysis reports more focused and tailored to your use-case.

The following filter types are supported in policy configuration files:

  • Networking filters or URI filters, defined in the networking.protocol section of the policy configuration file. These filters are primarily used to work with URIs extracted from a software package during the analysis. Networking filters do not support per-policy configuration. Consult the policy configuration schema for details on all supported filter options.

  • Processing filters, defined in the processing section of the policy configuration file. These filters are primarily used to control the policy scope and impact on CI/CD status when analyzing software packages. Processing filters support per-policy configuration, which means a filter can target a single policy or a range of policies. Consult the policy configuration schema for details on all supported filter options.

In this guide, we're showing how to create both types of filters for common use-cases.

Examples in this guide show how to modify the policy configuration for existing projects and packages in a previously created package store. If you haven't yet created any projects and packages, follow the instructions in the quick start guide.

Restrict URIs​

In this example, our package called my-package contains a large number of URIs in all versions. The detected URIs, specifically those pointing to certain ports, are considered undesirable in the software package code. Because the default rl-secure policy configuration does not necessarily report all those URIs as suspicious strings, we want to explicitly mark them as restricted on the package level.

To do this, we're modifying the policy configuration file for the package. Specifically, we're creating a networking filter that will look for a specific pattern and restrict all URIs matching that pattern. Consequently, those URIs will be reported as policy violations and their presence in the software package will cause a CI/CD failing condition.

1. Modify package policy settings​

1) In the rl-secure package store, navigate to the policy configuration file for the package and open it in a text editor. In this example, the full path to the file we're editing is /home/armando/my-repository/.rl-secure/projects/my-project/packages/my-package/.package_policy.info.

2) In the .package_policy.info file, add a new networking filter.

  • In protocol, specify one or more protocols that the filter should target. Wildcard matching is supported with the * character. In this example, http, https, and ftp will all be matched.
  • To ensure that the filter is applied when analyzing files, set enabled to true.
  • In address, you must specify at least the host value.
Example networking filter
policies 
{
    profile "package_profile"
    {
        inherit_rules  "project_profile"
  
        networking
        {
            protocol "http*,ftp"
            {
                enabled true

                block
                {
                    address
                    {
                        host      "*.test-domain.net"
                        port      "port-number"
                        author    "Spectra Assure"
                        reason    "Restrict selected networking references"
                        timestamp "2023-01-01T12:00:00+00:00"
                    }
                }
            }
        }        
    }
}

3) Save changes to the file and close it.

2. Apply and verify configuration changes​

1) To apply your policy configuration changes, run the following command in your package store:

rl-secure sync

The command automatically detects which packages in the package store require synchronization. Using the sync command does not count towards the monthly analysis capacity.

2) To make sure the new policy configuration is reflected in analysis reports, you have to regenerate them for all applicable package versions:

rl-secure report all --purl=pkg:rl/my-project/my-package@1.0 --bundle=report.zip

3) To confirm that the policy configuration change has been successfully applied, check the rl-secure output or the HTML analysis report for details about modified policies.

Check the CLI output

Use the find command to see whether the expected TH policies were triggered. The output should confirm that the policy violation is detected in the package for which the configuration was modified.

rl-secure find TH17101 --purl=pkg:rl/my-project/my-package@1.0

The output should be similar to the following example. It indicates the policy triggered due to the configuration change and shows the details on the restricted URIs.

Example output
[ MATCHED ] my-project/my-package@1.0
[ TH17101 ] [ L5:FAIL ] <P0> / [H] Severity [H] Effort / (x7)
            Detected presence of files containing URLs that were explicitly
            restricted.
Root Cause --------------------------------------------------------------------------
            ( COMPLEX ) Threat hunting policy was triggered by a heuristic signature
Violations --------------------------------------------------------------------------
     1) <Submitted package>

Check the HTML report

Choose one of the following pages to access the information on restricted URIs:

  • In the HTML report, select Issues from the left sidebar and expand the Threat Hunting section.
  • If the configuration change has been successfully applied, you will find the relevant policy in the list - more precisely, TH17101.
  • Select the Found N files button to show files with explicitly restricted URIs. You can then expand every file in the list to show more information. Select the Issues tab for each file to verify that the analysis triggered the relevant policy and that the detected URIs are restricted.

Suppress alerts on specific files​

In this example, our software package called armando-app is a packed executable file. We want to suppress all application hardening alerts in the analysis reports for this software package.

To do this, we're modifying the policy configuration file for the package. When applied, our changes will affect all package versions. Specifically, we're creating a filter that will prevent a range of security mitigations policies from setting the CI/CD build status to 'FAIL'.

1. Modify package policy settings​

1) In the rl-secure package store, navigate to the policy configuration file for the package and open it in a text editor. In this example, the full path to the file we're editing is /home/armando/my-repository/.rl-secure/projects/my-project/packages/armando-app/.package_policy.info.

2) In the .package_policy.info file, add a new processing filter.

  • To ensure that the filter is applied when analyzing files, set enabled to true.
  • With matches set to "root" and pattern set to "*", the filter will target the software package itself (the root or top-level file that is analyzed; sometimes referred to as the container file).
  • In policies, we're targeting multiple policy IDs at once by using a wildcard character *. This particular configuration change will affect all policies with IDs that have SQ141 as the first five characters.
  • Because blocker for the policy ID is set to pass, the policy violations will be included in the report, but will not cause a CI/CD failing condition for any of the package versions.
Example processing filter
policies
{
    profile "package_profile"
    {
        inherit_rules  "project_profile"
        
        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
                    }
                }
            }
        }
    }
}

3) Save changes to the file and close it.

2. Apply and verify configuration changes​

1) To apply your policy configuration changes, run the following command in your package store:

rl-secure sync

The command automatically detects which packages in the package store require synchronization. Using the sync command does not count towards the monthly analysis capacity.

2) To make sure the new policy configuration is reflected in analysis reports, you have to regenerate them for all applicable package versions:

rl-secure report all --purl=pkg:rl/my-project/armando-app@1.0 --bundle=report.zip

3) To confirm that the policy configuration change has been successfully applied, check the rl-secure output or the HTML analysis report for details about modified policies.

Check the CLI output

Use the find command to look up any of the modified policies by ID. The output should confirm that the policy violations are still detected, but the CI/CD status is set to 'PASS' in package versions for which the configuration was modified.

rl-secure find SQ141* --purl=pkg:rl/my-project/armando-app

The output should be similar to the following example. It indicates the policy that was triggered and the details about the detected issue. Because of the configuration change, the CI status is set to 'PASS'.

Example output
[ MATCHED ] my-project/armando-app@1.0
[ SQ14140 ] [ CI:PASS ] <P1> / [M] Severity [H] Effort / (x1)
            Detected Windows executable files compiled without following the
            SDL best practices while using banned string functions.
Violations ---------------------------------------------------------------------
     1) <Submitted package>

Depending on your RL-Levels settings, this type of configuration change may cause the CI:PASS indicator to switch to a Custom Level indicator (for example, C2:PASS).

Check the HTML report

  • In the HTML report, select Issues from the left sidebar and expand the Application Hardening section.
  • Find the relevant policies in the list and confirm that they all show 'PASS' in the CI/CD column.

Depending on your RL-Levels settings, the CI/CD status indicators may also show that you are using a Custom Level.