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. These filters are sometimes referred to as file-based policy overrides because you can use them to control policies at the level of an individual file or path within a software package. 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 SAFE report (rl-html) 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 SAFE report​

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

  • In the SAFE report, select Issues from the left sidebar and use the Add Filter button to find the relevant policy (Filter by: Issue > Operator: is > Value: TH17101).
  • Expand the Info dropdown for the issue to view files with explicitly restricted URIs.
  • Select a file you're interested in to show more information about it. The Networking tab on the file details page should display the restricted URIs. The Issues tab should confirm that the analysis triggered the relevant policy on the file.

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 SAFE report (rl-html) 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 SAFE 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 SAFE report​

  • In the SAFE report, select Issues from the left sidebar.
  • Use the Add Filter button to find the relevant policies - either by specific policy IDs (Filter by Issue) or by category (Filter by: Issue Category > Operator: is > Value: Application Hardening).
  • Confirm that the policies show 'PASS' in the CI/CD column.

Depending on your SAFE Levels settings, the CI/CD status indicators may also show that you are using a Custom Level and that the policy is suppressed. The Summary page of the SAFE report will indicate this in the SAFE Levels (Customized) section. If the policy is suppressed on the current level, the Suppressed button in the Issues section of the Summary page will indicate this. You can select it to confirm that it shows the exact policy that you modified in the configuration file.