This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Detect secret leaks

Detect and triage leaked secrets and credentials.

Secrets are access credentials that provide access to key resources and services, such as passwords, API keys, and personal access tokens. Attackers can target vulnerabilities in places where secret information is readily accessible to many users, with the goal of gaining unauthorized entry to the services that these secrets unlock.

The exploitation of secrets can lead to various detrimental outcomes, including:

  • Data breaches through the theft of stolen secrets and credentials.
  • Unauthorized access to data and resources.
  • Financial losses due to fraudulent activities.
  • Privacy violations due to compromised credentials.
  • Legal implications and regulatory consequences.

Secret scanning helps organizations proactively identify and remediate potential security threats before they can be exploited. It is important to scan for secrets in code as developers can sometimes hard-code sensitive data such as personal access tokens or API keys directly into the code.

The following sections describe how you can scan for secrets with Endor Labs:

Benefits

Endor Labs scans your source code repositories for secrets so that your teams can proactively manage the potential exposure of secrets to a broader audience than their intended recipients.

Users can:

  • View findings for secrets exposed in the code and take corrective action.
  • Detect valid secrets in their code repositories so that teams can take immediate corrective action.
  • Perform regular scans to audit and get visibility into secrets that may represent security exposures in their environment.
  • Detect and view invalid secrets as a proactive security approach to audit your codebase and segregate findings that you do not need to focus on.
  • Use Git pre-commit hooks to detect secrets before being committed.

Secrets deduplication

Duplicate secrets increase the attack surface and the risk of unauthorized access. Managing multiple duplicate secrets can be complex and error-prone. Endor Labs intelligently categorizes instances of identical secrets found within your application components and repositories, helping an organization achieve:

  • Efficient prioritization: Simplifies the prioritization of widely dispersed secrets, as more occurrences signify increased exposure and risk.
  • Comprehensive visibility: Ensures that you have a comprehensive view of all instances associated with a specific secret, facilitating effective management when the secret is discovered or undergoes changes.
  • Optimize issue handling: Generate a single finding for multiple secrets with details, simplifying the task of managing and addressing multiple secret-related issues simultaneously.

1 - Manage secret rules

Use secret rules to scan and detect secrets

You can use the following rules to scan your codebase and detect secrets:

  • System rules: Endor Labs provides out-of-the-box rules for secret patterns for many public services like GitHub, GitLab, AWS, Bitbucket, Dropbox, and more.

  • Custom rules: If you are using a service that is not included in the out-of-the-box list of secret patterns provided by Endor Labs, you can build your own custom rule to scan and detect the secrets for any service.

The following table lists the most important fields of the rule definition.

Field name Description
meta.name The name of the rule.
spec.rule_id The rule identifier must be unique across all rules, both the system and the ones created in your namespace.
spec.regex The secret detection rule contains the pattern that the scanner will try to match.
spec.keywords The keywords are used for an initial check of a pattern before the full regex expression gets evaluated.
spec.validation The details about how to validate a secret.
spec.entropy The minimum shannon entropy a regex group must have to be considered.
spec.disabled Set to false for system rules.

Create a secret rule

  1. Select Manage > Policies & Rules from the left sidebar.

  2. Select Secret Rules.

  3. Click Create Secret Rules.

    Create secret rules

  4. Enter the unique Rule Identifier and Rule Name.

  5. Enter the Description of the secret rule.

  6. Enter the regex for the secret rule in Detection Rule.

  7. Enter keywords for pre-regex check filtering as comma separated values in Keywords.

  8. Optionally, enter the minimum shannon entropy a regex group must have to be considered in Entropy.

  9. Optionally, add validation details to validate the secret:

    • Validation URL: Enter the URL for validation.
    • Validation Method: Choose between GET and POST methods.
    • Success Response Codes: Enter valid response codes (For example, 200 for HTTP Status OK)
    • Failure Response Codes: Enter invalid response codes (For example, 401 for HTTP Status Unauthorized)
    • Authorization Details: You can choose between Authorization Header, Bearer Token, and Basic Authentication.
  10. Select Propagate this rule to all child namespaces to apply the secret rule to all child namespaces.

  11. Click Add Rule.

Create secret rules from the command line

For example, consider a token “demo_value123” can be described using a regular expression. Here is an example of the rule specification:

"meta": {
    "name": "Demo Token"
},
"spec": {
    "disabled": false,
    "keywords": [
        "demo_"
    ],
    "regex": "demo_[0-9a-zA-Z]{20}",
    "rule_id": "demo-rule"
}

Use the following command from the CLI to create this custom rule.

$ endorctl api create -r SecretRule -n demo  \
> --data '{
> "meta": {
>     "name": "Demo Token"
> },
> "spec": {
>     "disabled": false,
>     "keywords": [
>         "demo_"
>     ],
>     "regex": "demo_[0-9a-zA-Z]{20}",
>     "rule_id": "demo-rule"
> }
> }'
INFO: Initiating host-check ...
INFO: Host-check complete
{
  "meta": {
    "create_time": "2023-09-27T17:08:18.436936Z",
    "kind": "SecretRule",
    "name": "Demo Token",
    "update_time": "2023-09-27T17:08:18.436936Z",
    "upsert_time": "2023-09-27T17:08:18.436936Z",
    "version": "v1"
  },
  "spec": {
    "disabled": false,
    "keywords": [
      "demo_"
    ],
    "regex": "demo_[0-9a-zA-Z]{20}",
    "rule_id": "demo-rule"
  },
  "tenant_meta": {
    "namespace": "demo"
  },
  "uuid": "65146182aaeeffbaf5b6b553"
}

After the rule is created, the system uses this rule to detect this category of secrets.

If you can validate the secret using an HTTP request, then you can also add validation to this rule. See the following example for creating a validation rule for a demo_test123 token.

curl -H "Authorization: Bearer "demo_test123" https://api.testserver.com/user

Then the validation specification can be:

"validation": {
    "name": "Demo secrets validator",
    "http_request": {
        "header": [
            {
                "key": "Bearer",
                "value": "{{.AuthzValue}}",
                "authz": true
            }
        ],
        "method": "GET",
        "uri": "https://api.testserver.com/user"
    },
    "http_response": {
        "failed_auth_codes": [
            401
        ],
        "successful_auth_codes": [
            200
        ]
    }
}

Validator

You can use a validator to check if a discovered secret is valid or not. The Endor Labs system rules for secrets include the necessary validator. When you validate a secret, the finding for that secret is categorized as critical, ensuring it receives higher priority compared to others.

When defining a custom rule, you can add your own validator from the command line or from the user interface. The system uses this information to send an HTTP request such as a GET or POST to the address specified by the public service for the detected secret.

For example, when a GitHub Personal Access Token named “ghp_endor123” is detected, the system sends the following HTTP request to GitHub’s address:

curl -H "Authorization: Token "ghp_endor123" https://api.github.com/user

The authentication codes defined by the service are used to mark the secrets as valid or invalid.

The validation portion of the secret rule contains the following fields:

Field Description
name The name of the validator
http_request.uri The address where the HTTP request should be sent
http_request.method The HTTP method to be used (GET or POST)
http_request.header.(key, val) A set of key/value pairs that are added to the HTTP header. See HTTP Request Header
http_response.successful_auth_codes The set of HTTP response codes that should be used to tag a secret as valid. For example, http.StatusOK (200)
http_response.failed_auth_codes The set of HTTP response codes that should be used to tag a secret as invalid. For example, http.StatusUnauthorized (401)

HTTP request header

HTTP request header is a set of key-value pairs that should be added to the header.

{
    "key": "Content-Type",
    "value": "application/json"
}

There are cases where one needs to use a value on runtime and substitute a pattern. For example, the secret itself that needs to be substituted is one such case. This is achieved by declaring a value using the {{.Value}} pattern.

For the HTTP header section that includes the secret, the block looks like the following snippet.

{
    "key": "Token",
    "value": "{{.AuthzValue}}",
    "authz": true,
}

In this case, the scanner replaces the candidate secret that was detected and adds it to the HTTP request header in place of {{.AuthzValue}}.

The following table describes a special case where the key-value pair is marked with the authz flag and is used to craft the “Authorization” part of the header, where three options are supported.

Key Header
Basic ‘Authorization: Basic "hash{{.AuthzValue}}"’
Bearer ‘Authorization: Bearer {{.AuthzValue}}
Token ‘Authorization: Token {{.AuthzValue}}

Manage secret rules

  1. Select Manage > Policies & Rules from the left sidebar.

  2. Select Secret Rules.

    The list of all secret rules appears. Secret rules

  3. Select the rule for which you want to view the details.

    The rule details appear in the right sidebar.

    Secret rule details

Clone a secret rule

Click the three vertical dots on the right side of the rule and select Clone Rule.

The cloned rule appears in the list of secret rules and you can edit it.

Edit a secret rule

Click the three vertical dots on the right side of the rule and select Edit Rule.

You can only edit the custom rules that you created or the system rules that you cloned.

Fetch secret rules with endorctl

To fetch the Endor Labs secret scanning rules from the command line type the following commands:

endorctl api list -r SecretRule -n <your-namespace>

For example, to see the rule for the GitHub Personal Access Token, you could search by the name GitHub Personal Access Token or by the rule-id github-pat:

endorctl api get -r SecretRule -n <your-namespace> --name "GitHub Personal Access Token"
endorctl api list -r SecretRule -n <your-namespace> --filter=spec.rule_id==github-pat

2 - Scan for secrets

Scan for secrets in your source code

Run endorctl scan --secrets to scan for leaked secrets in your source code. You can also scan for secrets with monitoring scans and CI scans. Ensure that you select Secrets as a scan type when you install the Endor Labs App for your SCM to scan for secrets during monitoring scans.

The following table lists the options available with endorctl for secrets scan.

Flag Environment Variable Description
secrets ENDOR_SCAN_SECRETS Scan source code repository and generate findings for leaked secrets. See also --git-logs, --dependencies, and --pre-commit-checks.
dependencies ENDOR_SCAN_DEPENDENCIES Use the --dependencies option in secrets scan to perform a regular scan that detects potential secrets in the dependencies.
force-rescan ENDOR_SCAN_FORCE_RESCAN Force a full rescan of the historical Git logs for all branches in the repository. Must be used together with --secrets.
git-logs ENDOR_SCAN_GIT_LOGS Audit the historical Git logs of the repository for all branches in the repository. Must be used together with --secrets.
local ENDOR_SCAN_LOCAL Scan the local filesystem. Must be used together with --secrets.
start-commit ENDOR_SCAN_START_COMMIT The start commit of the Git logs of the repository to start scanning from. Must be used together with --secrets and --end-commit.
end-commit ENDOR_SCAN_END_COMMIT The end commit of the Git logs of the repository to end scanning at. Must be used together with --secrets and --start-commit.
pre-commit-checks ENDOR_SCAN_PRE_COMMIT_CHECKS Perform Git pre-commit checks on the changeset about to be committed. Must be used together with --secrets.

Scan methods

You can perform the following types of scans to detect secrets:

  • Scan a specific code reference - Scan for secrets only on a defined path in the context of a checked-out branch, commit SHA or tag to identify secrets and raise findings. This helps you to identify secrets that are leaked in the context of what you are working on right now.

  • Scan complete history - Scan for secrets in all existing branches or tags to identify if a secret has ever been leaked in the history of the project and raise findings. This helps you to identify if any secret has ever been leaked even if it was not leaked in the context of what you are working on right now.

  • Scan pre-commits - Scan for secrets in the code before committing the code to your repository during the automated pre-commit checks. This helps you identify and remove sensitive information from your code files early in the development life cycle.

Scan a specific code reference

When starting a secrets scan, this default choice utilizes specified rules to search for patterns on the files located in the path where the scan is initiated.

Run the following command in the directory of the code reference to scan for secrets.

endorctl scan --secrets

Specify the --dependencies option in the secrets scan to perform a regular scan that also scans the dependencies.

endorctl scan --secrets --dependencies

Scan complete history

You can scan the Git logs by using the complete history scan. The repository should be present in the scanned path. Endor Labs examines the entire repository history to search for secrets.

To perform a complete scan, include the --git-logs option in the command line.

endorctl scan --secrets --git-logs

Include the --dependencies option in the secrets scan to perform a regular dependency scan along with secret scanning.

endorctl scan --secrets --git-logs --dependencies

The --git-logs option scans the repository’s Git logs using the following logic:

  • Perform a full scan if it is the first time the repository’s Git log history is scanned.
  • Perform a full rescan if a change has been detected to any of the rules in the namespace.
  • Perform an incremental scan based on the last time a scan was performed in all the other cases.

Run the following command to force a full rescan if any of the detected secrets are no longer valid, and you want to accurately reflect the state of the secrets.

endorctl scan --secrets --force-rescan

Specify the --dependencies option in the secrets scan to perform a regular scan that also scans the dependencies.

endorctl scan --secrets --force-rescan --dependencies

Scan pre-commits

You can check for secrets before committing the code to the repository as part of pre-commit hooks.

You must install and initialize endorctl before scanning the precommits.

  1. Create a .git/hooks/pre-commit file at the root of your Git repository to configure the pre-commit hook. It runs automatically when you make a commit and looks for secrets in your commit.

    cd .git/hooks
    touch pre-commit
    
  2. Edit the .git/hooks/pre-commit and include:

    #!/bin/bash
    #
    # Script invoked on git commit.
    #
    if ! endorctl scan --pre-commit-checks --secrets; then
       echo "Pre-commit checks failed"
       exit 1
    fi
    echo "No secrets found: Pre-commit checks succeeded"
    

    --pre-commit-checks performs a pre-commit scan and will scan only the current changes that you are committing to the repository.

  3. Set the file permissions to make it executable.

    chmod +x .git/hooks/pre-commit
    
  4. You can set up this hook on other systems in your organization by creating a script and running it on each system.

    sh setup-hooks.sh
    #!/bin/sh
    # Copy all hooks to .git/hooks
    cp hooks/* .git/hooks/
    chmod +x .git/hooks/*
    

Here’s an example output when no secrets are found.

No secrets

Here’s an example when secrets are detected and the commit fails.

Secrets found

Exclude false positives from secret scan

There might be cases where certain lines of code or specific patterns are mistakenly flagged as potential secrets but are safe to include such as test values or non-sensitive information.

To handle such false positives, you can annotate the non-sensitive lines in your source code with endorctl:allow.

# These are test credentials, safe to commit
username = "test_user"  # endorctl:allow
password = "test_password"  # endorctl:allow

Scan for secrets using regular expression

Endor Labs scans for secrets based on regular expressions that are designed to detect the presence of a secret. It then validates the discovered secrets against external APIs to identify if they are valid. Valid secrets actively provide access to a service or an application and can be used to gain unauthorized access.

Regular expressions are customized to match specific types of secrets, such as GitHub personal access tokens, OAuth access tokens, AWS access tokens, OpenAPI keys, Client IDs, Client Secrets, and more.

For example, you can describe a GitHub Personal Access Token with the following regular expression.

github_pat_[0-9a-zA-Z_]{82}

3 - View secret findings

View findings of a secrets scan.

You can view the findings generated out of secrets, prioritize them, and take corrective action.

  1. Sign in to Endor Labs and select Projects from the left sidebar.

  2. Select the project for which you want to view the secrets.

  3. Select Secrets under First Party Code to view secret findings.

    Findings of secrets

  4. Select a finding to view the following details:

    • Project: The name of the project where the secret is found, finding policy, categories, and attributes of the project.
    • Risk Details:
      • Indicates if the identified secret is valid or invalid.
      • Explanation of the finding.
      • Remediation recommended.

Secrets findings right sidebar 5. Click View Details to explore additional information about the secrets findings.