advanced-security / secret-scanning-review-action

Action to detect if a secret is initially detected in a PR commit

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

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

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@v0
        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 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
• Deprecated (previous inputs now supported via action workflow input parameters)
  • GITHUB_TOKEN - token used to invoke REST APIs
  • SSR_FAIL_ON_ALERT - overrides the fail-on-alert input parameter
  • SSR_FAIL_ON_ALERT_EXCLUDE_CLOSED - overrides the fail-on-alert-exclude-closed input parameter
• 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

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!