secret-scanning-review-action

Action to provide feedback annotations to the developer when a Secret Scanning alert is initially detected in a PR commit.

The action is intended for private repositories that have GitHub Advanced Security licensed.

Adds a Warning annotation alert to any PR file that has introduced a secret (based on the secret scanning alert initial commit)

Workflow FailOnAlert configuration to turn those Warnings into Errors!

Allowing you additional secret scanning trust->but->verify control in your branch protection rules

Summary of all secrets from the PR in the Secret Scanning Review workflow job summary

Comments on the Pull Request

Overview

This action is used to enhance the Advanced Security Secret Scanning experience with:

• Increased Alert Visibility
  • Secret Scanning alerts are only sent to the commiter / Admin role dependent on proper repo watch notification configurations. Alerts can also be configured to be async via email and may not be viewed in immediately.
• Additional Alerting Scope
  • Increase visibility for secrets that are detected with advanced security but are not supported via push protection
• Trust but Verify
  • Secrets that are initially prevented but have been forced into the Pull Request via push protection bypass can now be audited via Branch Protection / Required Checks.

Security Model Changes

• To be clear, this will make Secret Scanning Alerts visible to anyone with Read access to a repo following the View code scanning alerts on pull requests via the workflow annotation access model. This security control level is consistent with the access needed to see any raw secrets already commited to git history!

• If you do wish to give broader access to Secret Scanning Alerts in the GitHub Advanced Security platform 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 to any of the base roles with no default alert permissions: Read,Triage or the roles that only see alerts on secrets they have commited: Write,Maintain. The View secret scanning results permission would allow those roles to then be able to view the deep link to the Security Alert column - which is disclosed in the summary.

Configuration Options

token

REQUIRED A GitHub Access Token

• Classic Tokens
  • repo scope or security_events scope. For public repositories, you may instead use the public_repo scope.
• 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".

Outputs

N/A

Example usage

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

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.

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

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
• 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

FAQ

Why Powershell

A few reasons

1. I was challanged by a coworker during a Python v PowerShell discussion
2. To demonstrate GitHub Actions flexibility (pwsh is installed by default on the runners!)
3. Find current pitfalls and work with platform team to improve!
4. Powershell is cross-platform automation platform with the power of .NET!