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
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 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.
gradle-wrapper.jar could execute, download, or install arbitrary code while otherwise behaving like a completely normal
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.
Additionally, the action will find and SHA-256 hash all
variants of files named
for example a file named
gradlе-wrapper.jar (which uses a Cyrillic
е instead of
The goal is to prevent homoglyph attacks which may be very difficult to spot in a GitHub diff.
Add to an existing Workflow
Simply add this action to your workflow after having checked out your source tree and before running any Gradle build:
Add a new dedicated Workflow
Here's a sample complete workflow you can add to your repositories:
name: "Validate Gradle Wrapper" on: [push, pull_request] jobs: validation: name: "Validation" runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: gradle/wrapper-validation-action@v1
Contributing to an external GitHub Repository
Since GitHub Actions are completely free for open source projects and are automatically enabled on almost all projects, adding this check to a project's build is as simple as contributing a PR. Enabling the check requires no overhead on behalf of the project maintainer beyond merging the action.
You can add this action to your favorite Gradle based project without checking out their source locally via the GitHub Web UI thanks to the 'Create new file' button.
Simply add a new file named
.github/workflows/gradle-wrapper-validation.yml with the contents mentioned above.
We recommend the message commit contents of:
Official Gradle Wrapper Validation Action
- Body (at minimum):
From there, you can easily follow the rest of the prompts to create a Pull Request against the project.
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 email@example.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.
Note: When initially applying this action to your project,
gradle-wrapper.jar was generated by Gradle 3.3 to 4.0, the check will fail.
This is because these
gradle-wrapper.jar versions were dynamically generated by Gradle in a non-reproducible manner.
As such, it's not possible to verify the
gradle-wrapper.jar for those versions are legitimate using a hash comparison.
If the Gradle version in use is out of this range it is possible that your Wrapper JAR is out of sync.
To fix this run
./gradlew wrapper. If the Gradle version in use is in the problematic range, you should consider upgrading.
To learn more about verifying the Gradle Wrapper JAR locally, see our guide on the topic.