Secret Scanning Review Action

Overview

This Action adds more awareness, and optionally fails a pull request status check, when a secret scanning alert is introduced as part of a pull request. This makes it harder for peer reviewers to miss the alert and makes it easier to enforce that the alert is resolved before the pull request is merged (when combined with repository rulesets).

This Action is also helpful in increasing visibility for secrets that are detected with secret scanning, but are not yet supported with push protection, or where push protection has been bypassed.

Note

When running the Action with the python runtime, the Action will also provide a summary of the secrets introduced in the pull request title, description, comments, review, and review comments.

Prerequisites

For private and internal repositories, you must enable GitHub Advanced Security.

Functionality

Commit Annontations

The Action adds a Warning annotation to any file in the pull request that has introduced a secret (based on the secret scanning alert's initial commit):

Setting the workflow FailOnAlert configuration value to true will change those Warnings into Errors:

Status Check Failure

By adding Error annotations, new secret alerts will fail the workflow's status check, which provides a "trust, but verify" approach to secret scanning:

Pull Request Job Summary

The Action summarizes all secrets introduced in the pull request in the workflow run summary:

Pull Request Comments

By default, when any secrets are found the Action will also add a comment to the pull request with a summary of the secrets introduced in the pull request:

Security Model Considerations

• To be clear, this Action will surface secret scanning alerts to anyone with Read access to a repository. This level of visibility is consistent with the access needed to see any raw secrets already commited to the repository's commit history.

• By default, only users with the repository Admin role, users with the organization Security manager role, organization owners, and the committer of the secret, will be able to dismiss the alert.

• If you do wish to give broader access to secret scanning alerts in the repository you might consider a custom repository role configuration. With a custom role you can choose to grant View secret scanning results or Dismiss or reopen secret scanning results on top of any of the base repository roles.

Configuration Options

token

REQUIRED A GitHub Access Token

• Classic Tokens
  • repo scope. For public repositories, you may instead use the public_repo + security_events scopes.
• Fine-grained personal access token permissions
  • Read-Only - Secret Scanning Alerts
  • Write - Pull requests.
    • (disable-pr-comment: true) Read-Only - Pull requests. Not required for public repositories.

NOTE:

• Unfortunately we cannot currently utilize the built in Actions GITHUB_TOKEN due to ommitted permissions on the secret-scanning API. Therefore you must generate a token (PAT or GitHub App) with these permissions, add the token as a secret in your repository, and assign the secret to the workflow parameter. See Also: Granting additional permissions
• It is worth noting this token will have sensitive data access to return a list of plain text secrets that have been detected in your organization/repository. At this point, a detected secret also implies anyone with read repository access would provide the same level of access to the leaked secret and therefore should be considered compromised.

fail-on-alert

OPTIONAL If provided, will fail the action workflow via non-zero exit code if a matching secret scanning alert is found. Default 'false'.

fail-on-alert-exclude-closed

OPTIONAL If provided, will handle failure exit code / annotations as warnings if the alert is found and the alert is marked as closed (state: 'resolved'). Default 'false'.

disable-pr-comment

OPTIONAL If provided, will not put a comment on the Pull Request with a summary of detected secrets. Default 'false'.

runtime

OPTIONAL If provided, will desingate the runtime that's used to run the action. Options are 'powershell' or 'python'. Default 'powershell'.

python-http-proxy-url

OPTIONAL If provided, will set the http proxy for the python runtime. Default "". Example: "http://proxy.example.com:1234"

python-https-proxy-url

OPTIONAL If provided, will set the https proxy for the python runtime. Default "". Example: "http://proxy.example.com:5678"

python-verify-ssl

OPTIONAL If provided, will set the ssl verification option for the python runtime. Default 'true'.

Warning

Disabling SSL verification is NOT recommended for production environments. This option is provided for testing purposes only.

python-skip-closed-alerts

OPTIONAL If provided, will only process open alerts. Default 'false'.

Example usage

Note

Please keep in mind that you need a GitHub Advanced Security license if you're running this action on private repositories.

1. Add a new YAML workflow to your .github/workflows folder:

name: 'Secret Scanning Review'
on: [pull_request]

jobs:
  secret-scanning-review:
    runs-on: ubuntu-latest
    steps:
      - name: 'Secret Scanning Review Action'
        uses: advanced-security/secret-scanning-review-action@v1
        with:
          token: ${{ secrets.SECRET_SCAN_REVIEW_GITHUB_TOKEN }}
          fail-on-alert: true
          fail-on-alert-exclude-closed: true
          runtime: 'powershell' # or 'python'

Architecture

• A GitHub composite action wrapping a PowerShell script.

sequenceDiagram
    autonumber
    participant Repo as Repository
    participant PR as Pull Request
    participant Action as Action Workflow
    participant API_PR as pulls<br/><br/>REST API
    participant API_SECRET as secret-scanning<br/><br/> REST API

    Repo->>PR: Create/Update PR
    PR->>Action: invoke `pull_request` workflow
    Action->>API_PR: GET PR
    Action->>API_PR: GET PR Commits

    loop Commits
        Action->>Action: Build PR Commit SHA list
    end

    Action->>API_SECRET: GET Secret Scanning Alerts

    loop Secret Scanning Alerts
        Action->>API_SECRET: GET Secret Scanning Alert List Locations
        loop Secret Scanning Alert Locations
        Action->>Action:Build List of Alert Initial Location SHAs that are<br/>contained in the PR SHA List (Step 5)
        end
    end

    loop List of matching PR/Alerts
      loop List of Locations for matching PR/Alerts
        Action->>PR:Writes an Annotation to the message log<br/>associated with the file and line/col number.<br/>(Error/Warning based on FailOnAlert setting)
      end
    end

    Note right of PR: Annotations are visible<br/>on the PR Files changed rich diff

    Action->>PR:Writes summary to PR comment and log.<br/>Returns success/failure exit code based on FailOnAlert setting.

    Note right of PR: Fail workflow check<br/>based on FailOnAlert setting.

Loading

Environment Variables

• Implicit
  • GITHUB_REPOSITORY - The owner / repository name.
  • GITHUB_REF - PR merge branch refs/pull/:prNumber/merge
• Outputs
  • GITHUB_STEP_SUMMARY - Markdown for each job so that it will be displayed on the summary page of a workflow run (unique for each step in a job)

Dependencies

• GitHub Dependencies
  • GitHub REST APIs
• Powershell Dependencies
  • PowerShellForGitHub (Gallery / Repo) - PowerShell wrapper for GitHub API
    • by @microsoft
    • NOTE: Telemetry is collected via Application Insights
  • GitHubActions (Gallery / Repo) - PowerShell wrapper of the Github @actions/core toolkit
    • by @ebekker
• Python Dependencies
  • requests module

REST APIs

• Pulls
  • https://docs.github.com/en/enterprise-cloud@latest/rest/pulls/pulls#get-a-pull-request
  • https://docs.github.com/en/enterprise-cloud@latest/rest/pulls/pulls#list-commits-on-a-pull-request
  • https://docs.github.com/en/rest/pulls/reviews?apiVersion=2022-11-28#list-reviews-for-a-pull-request
  • https://docs.github.com/en/rest/pulls/comments?apiVersion=2022-11-28#get-a-review-comment-for-a-pull-request
• Secret Scanning
  • https://docs.github.com/en/enterprise-cloud@latest/rest/secret-scanning#list-secret-scanning-alerts-for-a-repository
  • https://docs.github.com/en/enterprise-cloud@latest/rest/secret-scanning#list-locations-for-a-secret-scanning-alert
• Comments
  • https://docs.github.com/en/rest/issues/comments?apiVersion=2022-11-28#get-an-issue-comment
  • https://docs.github.com/en/rest/issues/comments?apiVersion=2022-11-28#update-an-issue-comment
  • https://docs.github.com/en/rest/issues/comments?apiVersion=2022-11-28#create-an-issue-comment
  • https://docs.github.com/en/rest/issues/comments?apiVersion=2022-11-28#list-issue-comments

FAQ

Why are there two runtime options and what's the difference?

The primary difference is the underlying language and the dependencies that are required to be installed on the runner. The powershell runtime is the default and is the most tested. The python runtime is a newer addition for those who may not have powershell installed on their self-hosted runners.

The python runtime also includes some additional configuration options that are not available in the powershell runtime, and looks beyond just the pull request commits for secrets that were introduced in the pull request title, description, comments, review, and review comments.