wrapper-validation-action/README.md

Gradle Wrapper Validation Action

This action validates the checksums of Gradle Wrapper JAR files present in the source tree and fails if unknown Gradle Wrapper JAR files are found.

The Gradle Wrapper Problem in Open Source

The gradle-wrapper.jar is a binary blob of executable code that is checked into nearly 2.8 Million GitHub Repositories.

Searching across GitHub you can find many pull requests (PRs) with helpful titles like 'Update to Gradle xxx'. Many of these PRs are contributed by individuals outside of the organization maintaining the project.

Many maintainers are incredibly grateful for these kinds of contributions as it takes an item off of their backlog. We assume that most maintainers do not consider the security implications of accepting the Gradle Wrapper binary from an external contributors. There is a certain amount of blind trust open source maintainers have. Further compounding the issue is that maintainers are most often greeted in these PRs with a diff to the gradle-wrapper.jar that looks like this.

A fairly simple social engineering supply chain attack against open source would be contribute a helpful “Updated to Gradle xxx” PR that contains malicious code hidden inside this binary JAR. A malicious gradle-wrapper.jar could execute, download, or install arbitrary code while otherwise behaving like a completely normal gradle-wrapper.jar.

This problem is unique to open source and doesn’t normally impact companies with closed source and pre-vetted employees.

Solution

We have created a simple GitHub Action that can be applied to any GitHub repository. This GitHub Action will do one simple task: verify that any and all gradle-wrapper.jar files in the repository match the SHA-256 checksums of any of our official releases.

If any are found that do not match the SHA-256 checksums of our official releases, the action will fail.

Usage

Simply add this action to your workflow after having checked out your source tree and before running any Gradle build:

uses: gradle/wrapper-validation-action@releases/v1

Here's a sample complete workflow you can add to your repositories:

.github/workflows/gradle-wrapper-validation.yml

name: "Validate Gradle Wrapper"
on: [push]

jobs:
  validation:
    name: "Validation"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: gradle/wrapper-validation-action@releases/v1

Reporting Failures

If this GitHub action fails because a gradle-wrapper.jar doesn't match one of our published SHA-256 checksums, we highly recommend that you reach out to us at security@gradle.com.

If you're curious and want to explore what the differences are between the gradle-wrapper.jar in your possession and one of our valid release, you can compare them using this online utility: DiffScope. Regardless of what you find, we still kindly request that you reach out to us and let us know about any issues you encountered.