Skip to main content

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:

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.

Policy configuration fields

Suppressing secrets uses the following policy configuration objects and their fields:

  • leak_threshold
  • processing.filter.policies
  • processing.filter.secrets

Consult the policy configuration schema for details on all supported options.

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

  • In the SAFE report, select Secrets from the left sidebar.
  • Use Filter by Service to find the secrets by type. If the list of displayed secrets is too long, use Filter by Secret Status > Suppressed to reduce it.
  • Confirm that the secrets are suppressed according to the configured threshold by looking at the Exposure column.

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

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

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

  • In the SAFE 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 SAFE 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.

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

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

  • In the SAFE 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.

Detecting placeholder credentials​

By default, common network protocol credentials in the format schema://user:pass@domain.tld are automatically suppressed and do not raise any policy violations. They are assigned the uri-placeholder-known tag.

However, it is possible to manually declare specific network credentials as secrets and override the default behavior. To do this, you can create a networking filter in your policy configuration files. The credentials you declared will be assigned the uri-placeholder tag and trigger the SQ34301 policy.