# Best Practices for Security

version 9.7.0-20260618112146+0000

## 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 the `setup-gradle` action (version v4 or newer) for GitHub Actions, Wrapper validation will be performed automatically. The action validates the checksum of every `gradle-wrapper.jar` in your repository and fails the build if it finds any unknown Wrapper JAR.

If you use a different GitHub Actions setup, you can use the dedicated Gradle Wrapper validation action instead.

### References

- Gradle Wrapper checksum verification

- Gradle release checksums

### Tags

`#wrapper`

## Do not Run `./gradlew` on Untrusted Projects

When working with an untrusted project, you should exercise caution before running `./gradlew`.

### Explanation

The `gradlew` (Gradle Wrapper) script is an executable that downloads and runs a specific version of Gradle. It should be generated by running the Wrapper task with a trusted Gradle installation, but there is no guarantee that a project’s authors have done this. The script or `gradle-wrapper.jar` could have been modified. The only way to verify this is through checksum verification.

Running an unverified wrapper is similar to running any other untrusted script from the internet. Build scripts (`build.gradle`, `settings.gradle`, etc.) can also execute arbitrary code during the configuration phase.

An unreviewed wrapper or build script could potentially access or modify files on your system, install malicious software, or compromise your environment (e.g., stealing environment variables like `GITHUB_TOKEN` or `AWS_SECRET_KEY`).

| Opening an untrusted project in an IDE such as IntelliJ IDEA or Android Studio will typically trigger a Gradle sync automatically, which executes build logic. Review the project’s wrapper and build scripts before opening it in your IDE.

#### Do this

##### 1. Review the Build Scripts

- Inspect Build Files: Look at `build.gradle(.kts)`, `settings.gradle(.kts)`, and `gradle.properties` for suspicious dependencies, plugins, custom `exec` tasks, or obfuscated code.

##### 2. Verify the Gradle Wrapper Files

- Checksum Verification: Use checksum validation to ensure `gradle-wrapper.jar` hasn’t been tampered with.

- Check the URL: Open `gradle/wrapper/gradle-wrapper.properties` and ensure the `distributionUrl` points strictly to the official site: `https://services.gradle.org/`.

- Regenerate the Wrapper: If you have a trusted Gradle installation, delete the project’s `gradlew`, `gradlew.bat`, and `gradle/wrapper/gradle-wrapper.jar`, then run `gradle wrapper` (not `./gradlew`). Compare the regenerated files against the originals, any differences indicate the project’s wrapper may have been modified.

##### 3. Work in an Isolated Environment

You can optionally run the project in a Docker container or a Virtual Machine (VM). This ensures that even if a malicious script runs, it cannot access your files.

### References

- Gradle Wrapper Reference

### Tags

`#wrapper`