Pull Request Checks

github

Part of StackHawk’s official GitHub App integration.

Overview

StackHawk with GitHub helps teams understand the state of their DAST scans at a glance, directly in their pull requests or from commit statuses. View a high level summary of your latest HawkScan in your pull request, and see HawkScan statuses tied to commits.

Features

HawkScan can be tied to commits so that scan statuses can be associated with specific commits.
Pull requests can be decorated with summaries of your latest HawkScans, based on the commit. View high level scan details directly in the pull request while reviewing the code.

Requirements

You must have the official StackHawk GitHub app installed, with a GitHub repo mapped to the StackHawk application you are trying to get PR comments and commit statuses on. For detailed installation and configuration docs, check out the main GitHub App page.

Usage

Once the GitHub Integration is installed and a StackHawk Application is connected to a GitHub repository, you must make a few updates to your stackhawk.yml to start seeing commit statuses and PR comments.

This feature makes use of the open scan tags beta, by specifying a reserved tag that tells the StackHawk platform which commit the given scan is associated with.

It is recommended to use HawkScan’s environment variable resolution for the values of these tags, so that the environment variables can be injected by your CI/CD pipeline.

stackhawk.yml

app:
  applicationId: xXXxxXXx-xXXx-XxxX-xXxX-xXXXxxXXXxXx
  env: pull_request
  host: http://localhost:8080
tags:
  - name: _STACKHAWK_GIT_COMMIT_SHA
    value: ${ENV_VAR_FOR_COMMIT_SHA}
  - name: _STACKHAWK_GIT_BRANCH
    value: ${ENV_VAR_FOR_BRANCH}
hawk:
  # Add this if you want pull request comments to specifically call out findings at or above a failure threshold.
  failureThreshold: high

Only the commit SHA is required for pull request checks; however, including the Git branch will show additional information about where a scan came from.

If you want the commit SHA and branch name to default to blank when not set, you can set a blank fallback value: value: ${ENV_VAR:}. This configuration is useful if you use the same stackhawk.yml locally and in CI/CD.

Examples of Scan Tags Values

Reading the variables specified from your CI/CD provider will vary by provider. In the provided stackhawk.yml snippet, the environment variable containing the commit SHA and branch name must be passed to the appropriate scan tag. Some CI/CD providers directly provide these values as environment variables in your build. Others do not (Looking at you, GitHub Actions…).

Here are a few direct examples of configuring some popular CI/CD providers to work with this feature.

GitHub Actions

As referenced above, GitHub Actions does not provide the commit SHA or branch as an environment variable, but instead these values are provided to their workflow syntax.

For this CI/CD provider, use the following 2-step approach to enabling PR Comments:

Their workflow syntax will need to be used to extract the variable value and inject it as an environment variable.
This environment variable can be used in the stackhawk.yml so that the scanner can correctly read the commit SHA and branch under scan.

Relevant parts of the GitHub Actions workflow file:

github-actions.yml

name: GitHub Actions YAML
on:
  # To get Pull Request Comments, you need to be scanning *on Pull Request*
  pull_request:

jobs:
  example-build:
    name: Example Action
    runs-on: ubuntu-latest
    steps:
        # Ensure we have the project & stackhawk.yml checked out.
      - name: Checkout code
        uses: actions/checkout@v3
      - name: Build Your App
        run: echo "Build Your App First"
      - name: Run Your App in the Background
        # The '&' at the end of this command is one way to push a process to the background.
        run: echo "Run your app in the background" &
      - name: HawkScan
        uses: stackhawk/hawkscan-action@v2
        with:
          # Provide this as a GitHub Actions Secret
          apiKey: ${{ secrets.HAWK_API_KEY }}
        env:
          # Use GitHub Actions workflow variables to populate these environment variables
          COMMIT_SHA: ${{ github.event.pull_request.head.sha }}
          BRANCH_NAME: ${{ github.head_ref }}

Now the scanner will have access to these exact same environment variables we just populated. We can use these variables directly in our stackhawk.yml for those tag values.

stackhawk.yml

# Reuse the ENV vars we just populated from GitHub workflow variables
tags:
  - name: _STACKHAWK_GIT_COMMIT_SHA
    value: ${COMMIT_SHA}
  - name: _STACKHAWK_GIT_BRANCH
    value: ${BRANCH_NAME}

See GitHub’s docs for why github.event.pull_request.head.sha and not github.sha for builds on pull_request. The TL;DR is that StackHawk requires the HEAD commit of the pull request branch, and this variable is the only place that commit SHA lives for pull request builds in GitHub actions.

For more information see GitHub Actions variable documentation.

Jenkins

If you are using the Jenkins Git Plugin, environment variables with these Git details will be set directly on your pipeline.

See the complete list of environment variables.

The commit SHA is provided by this plugin as GIT_COMMIT. For the branch, there are a few options, but to exclude the remote in the branch name, the best option is GIT_LOCAL_BRANCH.

Since these are set as environment variables, we are able to use them directly in our stackhawk.yml.

stackhawk.yml

# Directly use the environment variables set by the Jenkins Git plugin.
tags:
  - name: _STACKHAWK_GIT_COMMIT_SHA
    value: ${GIT_COMMIT}
  - name: _STACKHAWK_GIT_BRANCH
    value: ${GIT_LOCAL_BRANCH}

CircleCI

CircleCI also includes built-in environment variables that fit our needs. You can see the complete list.

CircleCI provides the commit SHA with CIRCLE_SHA1, and the branch with CIRCLE_BRANCH.

Again, since the environment variables are set directly in the build, we can use them directly in our stackhawk.yml.

stackhawk.yml

# Directly use the environment variables set by the Jenkins Git plugin.
tags:
  - name: _STACKHAWK_GIT_COMMIT_SHA
    value: ${CIRCLE_SHA1}
  - name: _STACKHAWK_GIT_BRANCH
    value: ${CIRCLE_BRANCH}

Other CI/CD Providers

As you can see from above, CI/CD providers fall into one of two possibilities.

Those that set the variables you need as environment variables.
Those that do not set the variables you need as environment variables.

In all cases, you must use environment variables with the Git commit SHA and branch name in your stackhawk.yml. Sometimes, you’ll need to go through extra steps from your CI/CD provider to extract the Git values you need and set them as environment variables on your HawkScan runtime.

Commit Statuses

Once a commit sha has been provided on a StackHawk application linked to a GitHub repo, StackHawk will post commit statuses to that commit sha so that GitHub can provide a link to the last scan associated to that commit, and also provide a quick glance as to the overall result (success or failure) of that scan.

Successful commit status:

Unsuccessful commit status:

Pull Request Comments

Once a commit sha has been provided on a StackHawk application linked to a GitHub repo, if there is an open pull request where that commit sha is the last commit, StackHawk will post a PR comment when the scan has completed with an overview of the scan along with a link to the scan details.

Example of a successful pull request comment:

HawkScan allows the configuration of a threshold check via hawk.failureThreshold to cause scans to error if there are findings at or above the threshold. This same threshold is taken into account for these PR checks. In the event that there is a finding at or above the configured threshold, the HawkScan commit status will be marked as a failure, and the comment will highlight the findings at or above the configured failure threshold.

Example of a threshold failure pull request comment: Failure threshold pull request comment

If for any reason the scan fails, a brief error message will be posted to the PR, along with a link to the failed scan.

Example of an error pull request comment: Unsuccessful pull request comment

Blocking Pull Request Merges

Because this integration has the ability to create commit statuses, you have the option to configure HawkScan as a required check after your first successful scan with commit statuses. Then GitHub can enforce not allowing the merge of Pull Requests without a successful HawkScan. The default behavior is to show commit statuses as Pull Request checks, but not require successful completion of these checks before merging. For more information, check out this GitHub article on required checks.

Commit SHA and Branch in the StackHawk Platform

When these 2 reserved tags are provided, they will show up on specific scan details in the StackHawk platform as an easy way to see where a given scan came from.

Commit Sha and Branch in Platform

Hovering over these fields will reveal the entire value. The commit box shows the value of the _STACKHAWK_GIT_COMMIT_SHA tag, and the branch box shows the value of the _STACKHAWK_GIT_BRANCH tag.

Troubleshooting

No commit statuses or Pull Request comments? Verify that the commit sha shown in the StackHawk platform for the scan matches the last commit sha shown in the pull request or commit tree. CI providers can have various ways of exposing these commit shas, and some providers can have multiple variables that provide different things.

Feedback

Have any suggestions, feature requests, or feedback to share? Contact StackHawk Support .