Skip to main content

Check secret liveness

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

These secrets can be active or inactive, which is also referred to as their liveness status. This status is determined during the live secret validation. For example, if a secret is validated as inactive it will be declared as such. Since inactive secrets have the lowest priority and can't fail the build, this process of validation helps you reduce the noise while triaging secrets.

This validation process is also known as the liveness check. As part of the liveness check, Spectra Assure associates every secret with the service where it can be used for authentication. It then connects to the least-privilege APIs exposed by the service to verify if the secret is a valid credential. The liveness check results in one of the following states:

  • Active - the service accepted the secret as live, which means it is at risk of abuse. The presence of an active secret in your software is a P0 issue that produces a failing CI status.
  • Inactive - the service refused the secret as unusable or could not verify it as live. This usually indicates the secret has expired or has been rotated out of use.
  • Skipped - liveness check is not supported for that type of secret or the secret has been defined as a canary in your policy configuration.

In Spectra Assure products, the live secret validation feature is enabled by default for supported services. Every time you run a scan with rl-secure, the information on secret liveness is included in your reports. Since the liveness check affects the CI/CD status, it is an important part of the analysis that you should always keep enabled.

However, you can modify policy configuration files to do the following:

  • Check the liveness status of detected secrets on your custom endpoint for any of the supported services
  • Disable services or endpoints that are either enabled by default or by users

This guide shows 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.

Modify endpoints for live secret validation​

In this example, our package called my-package contains some API tokens. These tokens are found on various endpoints, each of which is enabled by default and returns its own liveness status for that secret. But what if we want to see whether the detected secret is active on our custom endpoint, as well?

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 doing the following:

  • adding a custom, private endpoint where the live secret validation will also be carried out for that specific service
  • disabling one of the default endpoints for live secret validation

As a result of this change, the final Liveness status for the service takes into account the live status of secrets both from the custom and the default endpoints.

The disabled endpoint will not be checked or included in the CLI output/report.

Custom endpoint certificates

To make sure the verification is done on your custom endpoint, first save its certificate in the .cacerts folder of your package store. Check the guide on managing endpoint certificates for detailed instructions.

For security purposes, secrets are only sent to the server that passes certificate validation.

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) Find or add the liveness section and specify custom endpoints for one or more supported service verifiers.

  • The verifier values are predetermined and can be found in the Supported services table.
  • To ensure the verification for the whole service is on, set enabled to true.
  • In the endpoint section, set any custom label for the endpoint (for example, Private GitHub) and enter your custom endpoint under location. Make sure it contains the protocol https and points to the expected API.
  • To check liveness on that specific endpoint, set enabled to true.

3) In the same liveness section, disable one of the default endpoints. In this example, we're disabling the "Public GitHub" endpoint.

  • In the endpoint section, set any custom label for the endpoint and enter the default endpoint URL under location. Make sure it matches the root endpoint for that service from the Supported services table.
  • To skip the liveness check on the endpoint, set enabled to false.
Example liveness configuration
policies
{
    profile "project_profile"
    {
        inherit_rules  "repository_profile"

        liveness 
        {
            verifier "github-v3" 
            {
                enabled true 

                endpoint "Public Github" 
                {
                    enabled  false
                    location "https://api.github.com"
                }

                endpoint "Private GitHub" 
                {
                    enabled  true
                    location "https://github.priv/api/v3"
                    timeout  60 
                    retries  0 
                }
            }
        }
    }
}

4) 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 the liveness details on each secret.

Check the CLI output

Use either the find or the status command to get the summary for each detected secret found on a specific supported service. For each checked endpoint, the command shows the secret status which serves as the basis for the final secret Liveness verdict for that service. Note that canary tokens will not be checked for liveness.

rl-secure find secrets --service="Github PAT" --with-evidence --with-endpoints pkg:rl/my-project

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

Because of the configuration change, the live secret verification was also done on our custom endpoint (Private GitHub), but was skipped for the default (Public Github) endpoint.

[ MATCHED ] my-project/my-package@1.0
[ SECRETS ] [ CI:PASS ] <P4> / Github PAT / SQ34253 (x1)
            Detected presence of inactive web service access tokens.
Detections ---------------------------------------------------------------------
         1) tokens.txt
              Exposure: UNKNOWN
              ------------------------------------------------------------------
              Liveness: INACTIVE - (less than a minute ago)
              Evidence: { #01 / Line: ...........1 (ghp_R4kszb***) }
                        (    [o] INACTIVE on: Private GitHub       )

Check the HTML report

Use the Secrets or the Issues page in the report to access the liveness check information on detected secrets.

  • The Secrets page displays the list of all detected secrets in your software, and the information is primarily organized around secrets.

  • The Issues page displays the list of all detected issues in your software, and the information is primarily organized around files.

Secrets page

  • In the HTML report, select Secrets from the left sidebar.
  • All detected secrets are listed and can be filtered by Liveness or Exposure, Service, Endpoint, and the policy status (Status - pass or fail).
  • Expand any secret in the list to view its Liveness details and more information on the file where it was detected. The information includes the time when the liveness check for that secret was last performed.

Issues page

  • In the HTML report, select Issues from the left sidebar and expand the Sensitive Information section.
  • For the desired policy violation, select the button to show files with the issue.
  • Expand the desired file and select the Secrets tab. Each secret found in that file can be filtered by its Liveness or Exposure, Service, Endpoint, and the policy status (Status - pass or fail).
  • For each secret in the list, expand it to view its Liveness details, including the time when the liveness check for that secret was last performed.
Disabled endpoints

If you disable one of multiple endpoints of a service, only the results for the enabled endpoints are included in the report.

If you disable the whole service or its only endpoint, the report states that No endpoints have been found for that specific service.