From b1a1876368c01ec55373bc25dcd76982371e32ea Mon Sep 17 00:00:00 2001 From: Jonathan Leitschuh Date: Tue, 7 Jan 2020 13:01:20 -0500 Subject: [PATCH] Add an explanation to the README --- CONTRIBUTING.md | 12 ++++++++++++ README.md | 37 +++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..24cdc3f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,12 @@ +## Project Goals + +We aim to keep the scope of this project limited so that it is easy for maintainers to apply and forget about. + +### Goals + +To verify that all the gradle-wrapper.jar(s) in a given GitHub repository or pull request against that repo is an official Gradle Wrapper release. + +### Non-Goals + +It is not the goal of this action to verify that the gradle-wrapper.jar matches a specific version of Gradle, +nor that the version declared in the build.gradle or gradle-wrapper.properties file matches. diff --git a/README.md b/README.md index 1db5411..c652e25 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,34 @@ This action validates the checksums of [Gradle Wrapper](https://docs.gradle.org/current/userguide/gradle_wrapper.html) 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](https://github.com/search?l=&q=filename%3Agradle-wrapper.jar&type=Code). + +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. + +![Screen Shot 2020-01-07 at 12 26 07 PM](https://user-images.githubusercontent.com/1323708/71915219-477d7780-3149-11ea-9254-90c80dbffb0a.png) + +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 **before** running any Gradle build: @@ -13,3 +41,12 @@ Simply add this action to your workflow **before** running any Gradle build: ```yaml uses: eskatos/gradle-wrapper-check@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](mailto: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](https://try.diffoscope.org/). +Regardless of what you find, we still kindly request that you reach out to us and let us know about any issues you encountered.