Create custom 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 are 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.Processing filters are 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.
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.
Workflow overview:
- Scan your software with
rl-secure
and generate the SAFE report. - Examine the SAFE report and identify areas of concern you want to address with custom policy configuration.
- Create the appropriate filter type at the desired policy configuration level (the whole package store, a project, or a package).
- Scan your software again to apply the filters and recreate the SAFE report to verify the filters are working properly.
Networking filtersโ
With networking filters, you can:
- Explicitly tag networking placeholder credentials
- Mark specific URIs as restricted
- Add network services to the SBOM โ
Networking filters use the following policy configuration objects and their fields:
networking.protocol.filter.address
networking.protocol.block.address
Consult the policy configuration schema for details on all supported options.
Declare networking placeholdersโ
In this example, all projects in a package store use some placeholder network credentials for testing purposes.
The credentials are in the schema://user:pass@domain.tld
format.
By default, rl-secure
recognizes those credentials as networking placeholders.
They are assigned the uri-placeholder-known
tag and automatically suppressed in the analysis report.
This means the presence of those credentials in your software does not violate any policies and is not treated as a sensitive information leak.
However, in some cases you may want to explicitly raise an issue when a networking placeholder is detected for visibility or for auditing purposes. To do this, you need to override the default behavior with a networking filter that declares a set of credentials as a networking placeholder.
In this example, we're modifying the policy configuration file for the whole package store. Specifically, we're creating a networking filter that will look for a pattern and declare all URIs matching that pattern as placeholders.
Those placeholder values will be assigned the uri-placeholder
tag and trigger the SQ34301 policy.
You can use either of those data points to check that the placeholders are correctly identified and reported.
With this change, the presence of configured placeholder values in the software package will not cause a CI/CD failing condition because the triggered policy is not a blocking policy.
1. Modify package store policy settingsโ
1) In the rl-secure
package store, navigate to the policy configuration file in the root directory and open it in a text editor. In this example, the full path to the file we're editing is /home/armando/my-repository/.repository_policy.info
.
2) In the .repository_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
, andftp
will all be matched. - To ensure that the filter is applied when analyzing files, set
enabled
totrue
. - In
address
, you must specify at least thehost
value. - In
userinfo
, list the credentials either as standalone items or as pairs ("username" "password"
). - Add the
declare
option to theuserinfo
object to indicate that you want to declare the credentials as placeholders.
policies
{
profile "repository_profile"
{
inherit_rules "sdlc_default"
networking
{
protocol "http*,ftp"
{
enabled true
filter
{
address
{
host "*.domain.com"
author "armando@secure.software"
reason "Declaring placeholder networking credentials"
timestamp "2023-01-01T12:00:00+00:00"
userinfo declare
{
"test" "test"
"user" "pass"
"username"
}
}
}
}
}
}
}
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.
This action may take a long time if the entire package store needs to be synchronized.
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 SAFE report (rl-html
) for details about filtered network credentials.
- In the SAFE report, select Networking from the left sidebar.
- In the Show All Tags dropdown, select Filtered by uri-placeholder.
- The list of networking strings will be filtered, and at least one of the items in the list should match the pattern defined in the policy configuration. In this example, some of the items could be
https://user:pass@example.domain.com
andhttp://test:test@my.domain.com
.
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 software package (the .package_policy.info
file).
When changes are synchronized, the configuration will apply to all versions in that package.
Specifically, we're creating a networking filter that will look for the pattern we define and restrict all URIs matching that pattern. Consequently, those URIs will be reported as policy violations. 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
, andftp
will all be matched. - To ensure that the filter is applied when analyzing files, set
enabled
totrue
. - In
address
, you must specify at least thehost
value.
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.
[ 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:
- Issues page
- Networking page
- 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.
- In the SAFE report, select Networking from the left sidebar.
- In the Show All Tags dropdown, select Filtered by uri-restricted.
- The list of networking strings will be filtered, and at least one of the items in the list should match the pattern defined in the policy configuration. In this example, some of the items could be
http://www.test-domain.net:990
orsuspicious.test-domain.net:990
.
Processing filtersโ
With processing filters, you can:
- Control the criteria for triggering policies
- Modify SBOM contents โ
- Suppress secrets โ
- Manually triage CVEs โ
- Block unusual or unwanted software behaviors โ
Processing filters use the following policy configuration objects and their fields:
processing.filter.policies
processing.filter.triaged
processing.filter.secrets
processing.filter.hunting.categories
processing.filter.hunting.behaviors
processing.filter.identity.component
processing.filter.identity.dependency
processing.filter.identity.model_card
Consult the policy configuration schema for details on all supported options.
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 software package (the .package_policy.info
file).
When changes are synchronized, the configuration will apply to all versions in that package.
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
totrue
. - With
matches
set to"root"
andpattern
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 haveSQ141
as the first five characters. - Because
blocker
for the policy ID is set topass
, the policy violations will be included in the report, but will not cause a CI/CD failing condition for any of the package versions.
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'.
[ 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.