# Best Practices for Security

version 9.3.0

## Validate the Gradle Distribution SHA-256 Checksum

Set `distributionSha256Sum` in `gradle-wrapper.properties` to verify the integrity of the downloaded Gradle distribution.

### Explanation

Always set the `distributionSha256Sum` property in your `gradle-wrapper.properties` file to verify the integrity of the downloaded Gradle distribution. This ensures the `gradle-X.X-bin.zip` file matches the official SHA-256 checksum published by Gradle, protecting your build from corruption or tampering.

    distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
    distributionSha256Sum=2b3f4...sha256-here...f4511

This validation step enhances security by preventing the execution of compromised or incomplete Gradle distributions.

The official SHA-256 checksums can be found on the Gradle releases page.

### References

- Gradle Releases with Checksums

- Gradle Wrapper Reference

### Tags

`#properties`, `#wrapper`

## Validate the Gradle Wrapper on every Upgrade

The Gradle Wrapper runs before your build logic and can deeply affect your build. You should treat any change to the Wrapper as security-sensitive.

Validate the Wrapper JAR and distribution settings every time you upgrade Gradle.

### Explanation

When you update Gradle, two Wrapper files typically change:

- `gradle/wrapper/gradle-wrapper.jar`

- `gradle/wrapper/gradle-wrapper.properties` (`distributionUrl` and optionally `distributionSha256Sum`)

You should verify that:

- The Wrapper JAR is the official binary published by Gradle (not tampered with).

- The Wrapper JAR checksum matches one of the values published at gradle.org/release-checksums.

- The distribution URL points to the expected Gradle release.

- The distribution checksum (if configured via `distributionSha256Sum`) matches the release you intend to use (also listed on gradle.org/release-checksums).

Running an unverified Wrapper risks executing untrusted code before any of your build’s safeguards run.

#### Do this

If you use GitHub Actions, you can use the Gradle Wrapper validation action.

This action validates the checksum of every `gradle-wrapper.jar` in your repository and fails the build if it finds any unknown JAR:

github/workflows/gradle-wrapper-validation.yml

    name: Validate Gradle Wrapper
    on:
      pull_request:
        paths:
          - 'gradlew'
          - 'gradlew.bat'
          - 'gradle/wrapper/**'

    jobs:
      wrapper-validation:
        runs-on: ubuntu-latest
        steps:
          - uses: actions/checkout@v4
          # Recommended action (new namespace)
          - name: Verify Gradle Wrapper
            uses: gradle/actions/wrapper-validation@v3

### References

- Gradle Wrapper checksum verification

- Gradle release checksums

### Tags

`#wrapper`