Suppress secrets

The Spectra Assure platform detects a wide range of sensitive information that may be present in your software packages.

In some cases, secrets detected in your software packages are not actually dangerous. For example, they may be placeholder values used for testing, or they can be included on purpose as canary tokens.

To prevent CI/CD failures in such cases, you can modify the policy configuration to suppress secrets.

Policy configuration files support several approaches for suppressing secrets:

• By excluding network placeholders
• By exposure time
• By policy ID
• By exact secret string

The approach you'll choose primarily depends on the secret type and your use-case.

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.

Exclude network 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. Because the default rl-secure policy configuration reports those credentials as "false positives", we need to create an exception on the package store level. The goal is to exclude those placeholder values from the list of actual sensitive information leaks.

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

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, 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.
• In userinfo, list the credentials either as standalone items or as pairs ("username" "password").

Example networking filter

policies 
{
    profile "repository_profile" 
    {
        inherit_rules "sdlc_default"
  
        networking
        {
            protocol "http*,ftp"
            {
                enabled true

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

                        author    "armando@secure.software"
                        reason    "Filtering all placeholder networking credentials"
                        timestamp "2023-01-01T12:00:00+00:00"

                        userinfo
                        {
                            "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 HTML analysis report for details about filtered network credentials.

• In the HTML 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 and http://test:test@my.domain.com.

Configure secrets exposure time

In this example, our project called armando-client uses some commonly shared SSH keys for testing. The default rl-secure configuration detects those keys as sensitive information leaks, which results in the CI:FAIL status. Because we know the origin and purpose of those keys in our project, it's safe to suppress them in analysis reports.

To do this, we're modifying the policy configuration file for the project. When applied, our changes will affect all packages and package versions in the project.

Specifically, we're changing the leak_threshold option to suppress all secrets older than a year, which covers the keys used in our project. Sensitive information age is counted starting from the date when the secret was first recorded in the ReversingLabs cloud.

As a result of this change, all secrets older than the configured amount of days will be displayed as 'Suppressed' and treated as commonly shared in the analysis reports. Their presence in the software package will not cause a CI/CD failing condition.

1. Modify project policy settings

1) In the rl-secure package store, navigate to the policy configuration file for the project 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/armando-client/.project_policy.info.

2) In the .project_policy.info file, find or add the leak_threshold option and set it to 365.

Set leak threshold

policies
{
    profile "project_profile"
    {
        inherit_rules  "repository_profile"
        leak_threshold  365
    }
}

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/armando-client/production-package@1.0.1 --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 suppressed secrets.

Check the CLI output

Use the find command to look up sensitive information by type and confirm that it's still detected, but reported as suppressed in the project for which the configuration was modified.

rl-secure find secrets --service=SSH --purl=pkg:rl/armando-client --evidence

The output should be similar to the following example. It indicates the policy that was triggered and the details about the secret, including exposure information. Because of the configuration change, the secret is now reported as suppressed.

Example output

[ MATCHED ] armando-client/production-package@1.0.1
[ SECRETS ] [ CI:PASS ] <P2> / PEM OpenSSH SSH Encrypted Private Key / SQ34105 (x1)
            Detected presence of embedded encrypted private SSH keys.
Detections ---------------------------------------------------------------------
         1) fc0f38b258c1594f319415fd45c880fb6ce27489/embedded_secret/1
              Exposure: about 1 year ago (Suppressed)
              ------------------------------------------------------------------
              Liveness: UNSUPPORTED - about 19 hours ago
              Evidence: { #01 / Offset: 0x00001745 (EMBEDDED FILE) }

Check the HTML report

Choose one of the following pages to access the exposure information on detected secrets:

Secrets page

• In the HTML report, select Secrets from the left sidebar.
• Use Filter by Service to find the secret.
• Confirm that the secret is suppressed according to the configured threshold by looking at the Exposure column.

Issues page

• In the HTML report, select Issues from the left sidebar and expand the Sensitive Information section.
• Find the relevant policies in the list and select the Found N files button to show files with the issue.
• You can expand every file in the list to show more information, and select the Secrets tab for each file to confirm that the secret is suppressed according to the configured exposure threshold.

Exclude a sensitive information policy

In this example, our package called armando-test-tool contains an embedded private key in all versions.

The default rl-secure configuration detects the key as a sensitive information leak, which results in the CI:FAIL status. Because we use this private key only for testing, we want to create an exception for it.

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 sensitive information policy from setting the CI/CD status to 'FAIL'.

We need to identify which policy is reporting the issue with our private key. This information is usually obtained from the rl-secure CLI output or from the analysis reports.

We can also look up the key in the list of supported secrets. In the list, we find "DER PKCS8 Private Key" under "Embedded private keys". Searching the list of sensitive information policies, we find that SQ34109 is the policy that detects embedded private keys. This is the policy we need to customize in our filter.

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/testing-tools/packages/armando-test-tool/.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 "file" and pattern set to a specific file name, the filter will target only the file(s) with that file name across all analyzed package versions.
• Because blocker for the policy ID is set to pass, the policy violation will be included in the report, but it 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
                matches "file"
                pattern "armando.exe"

                author "Spectra Assure"
                timestamp "2022-06-02T15:00:00+0000"
                reason "Approving the use of internal testing key"
                
                policies
                {
                    SQ34109
                    {
                        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/testing-tools/armando-test-tool@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 suppressed secrets.

Check the CLI output

Use the find command to look up sensitive information by type and confirm that it's still detected, but reported as suppressed in package versions for which the configuration was modified.

rl-secure find secrets --service=DER --purl=pkg:rl/testing-tools/armando-test-tool --evidence

The output should be similar to the following example. It indicates the policy that was triggered and the details about the secret, including exposure information.

Because of the configuration change, the CI status is set to PASS even if the secret is still considered exposed.

Example output

[ MATCHED ] testing-tools/armando-test-tool@1.0
[ SECRETS ] [ CI:PASS ] <P0> / DER PKCS8 Private Key / SQ34109 (x1)
            Detected presence of embedded private keys.
Detections ---------------------------------------------------------------------
         1) $PLUGINSDIR/app-64.7z/armando.exe
              Exposure: 5 months ago (Exposed)
              ------------------------------------------------------------------
              Liveness: UNSUPPORTED - 1 minute ago
              Evidence: { #01 / Offset: 0x08986040 (EMBEDDED FILE) }
--------------------------------------------------------------------------------

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, C4:PASS).

Check the HTML report

Choose one of the following pages to access the audit information on detected secrets:

Secrets page

• In the HTML report, select Secrets from the left sidebar.
• Use Filter by Service to find the secret in the list.
• Confirm the CI/CD status for the secret is set to PASS. Depending on your RL-Levels settings, the status indicator may also show that you are using a Custom Level and/or that the policy is disabled on the currently configured level.

Issues page

• In the HTML report, select Issues from the left sidebar and expand the Sensitive Information section.
• Find the relevant policy in the list and confirm the CI/CD status for the policy is set to PASS. Depending on your RL-Levels settings, the status indicator may also show that you are using a Custom Level and/or that the policy is disabled on the currently configured level.
• Select the Found N files button to show files with the issue. You can then expand every file and view the Secrets tab for it to confirm the CI/CD status for the secret is set to PASS.

Filter canary tokens

Canary tokens are sensitive information that has been intentionally placed into the code or configuration files of a software project to track external credential (ab)use. Because of their specific purpose, it's important to be able to distinguish canary tokens from other types of secrets, and not treat them as release blockers for a software project.

To do this, we're modifying the policy configuration file for the project. When applied, our changes will affect all packages and package versions in the project. Specifically, we're creating a filter that will target a file containing our canary tokens and identify them as such.

As a result of this change, the secrets we specified in the filter will be displayed as canary tokens in the analysis reports. Their presence in the software package will not cause a CI/CD failing condition.

1. Modify project policy settings

1) In the rl-secure package store, navigate to the policy configuration file for the project 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/.project_policy.info.

2) In the .project_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 "file" and pattern set to a specific file name, the filter will target only the file(s) with that file name across package versions. We're using this because our canary tokens are always saved in that specific file.
• In the secrets section, we're specifying which strings found in the pattern file should be marked as canary tokens. Every canary token can be specified as a literal string (the whole token value) or as a SHA256 hash of the token value (prepended by rl-sha256). Keep in mind that you can only specify the secret strings if the pattern file is plain text (unencrypted, human-readable file). For improved privacy and security, SHA256 hashes are recommended.

Example processing filter

policies
{
    profile "project_profile"
    {
        inherit_rules  "repository_profile"
        
        processing
        {
            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:df3e6b0bb..."  ; SHA256 of token1
                }
            }
        }
    }
}

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 configured canary tokens.

Check the CLI output

Use the find command to look up sensitive information by type and confirm that it's still detected, but reported as canary in the project for which the configuration was modified.

rl-secure find secrets --service=AWS --purl=pkg:rl/my-project --evidence

The output should be similar to the following example. It indicates the policy that was triggered and the details about the secret, including exposure information. Note that canary tokens are never checked for liveness.

Because of the configuration change, the secret is now reported as a self-declared canary token.

Example output

[ MATCHED ] my-project/my-package@1.0
[ SECRETS ] [ CI:PASS ] <P4> / AWS credentials / SQ34252 (x1)
            Detected presence of self-declared canary tokens.
Suppressed ---------------------------------------------------------------------
    Author: Spectra Assure
      Date: 2023-01-01T12:00:00+00:00 (about 1 year ago)
    Reason: Explicitly declaring secret as a canary token
         1) AWS-production-keys.txt (EXPOSED CANARY)
              ------------------------------------------------------------------
              Evidence: { #01 Line: ........12 (AKIAIOSFOD***) }

Check the HTML report

Choose one of the following pages to access the information on the configured canary tokens:

Secrets page

• In the HTML report, select Secrets from the left sidebar.
• Use Filter by Service to find the secret in the list.
• The secret added to the policy configuration file will display 'Yes' in the Canary column.
• Expand the secret to show more information and view the Audit details.

Issues page

• In the HTML report, select Issues from the left sidebar.
• Use the Add filter button and Filter by File Name to find the file containing the configured canary tokens.
• Expand the file to show more information and select the Secrets tab.
• The secret added to the policy configuration file will display 'Yes' in the Canary column. You can expand it to view the Audit details, which should match your author, date, and reason specified in the policy configuration file.