Documentation
  1. Socket Alerts
  2. Ecosystem Support

Gradle setup instructions (for Java, Kotlin, and Scala)

The recommended way to use Socket with a Gradle project is to generate a Socket facts file with the Socket CLI. socket manifest gradle resolves your full dependency graph locally and writes a single .socket.facts.json file — the preferred SBOM format for Socket. The committed-file options (gradle.lockfile and libs.versions.toml) remain supported if you prefer not to run the CLI.

Generate a manifest with the CLI (recommended)

The recommended approach is to generate a Socket facts file from your local Gradle setup. By default socket manifest gradle emits a single Socket facts file (.socket.facts.json) describing the resolved dependency graph of the whole build.

socket manifest gradle

You can use socket manifest gradle --help to get more information on how to run Gradle more directly. This will work for Gradle, Kotlin, and Scala projects that use Gradle (not sbt, see Scala setup instructions for working with Scala's sbt files).

After generating the manifest files you can use socket scan create to create a report.

CycloneDX

Alternatively you can use the open source CycloneDX Gradle plugin to generate and commit an SBOM which Socket will scan. You can run socket cdxgen --help for details.

To setup a single CycloneDX file that can be checked in you can run:

socket cdxgen -t gradle -o socket-gradle.cdx.json --install-deps --lifecycle build

gradle.lockfile

If you'd rather commit a file to source control than run the CLI, committing a gradle.lockfile is the simplest option. If you haven't already, enable lockfiles in gradle , and then commit the generated gradle.lockfile to source control. No extra setup is required!

Add dependency locking configuration to build.gradle.

  1. Add locking configuration to build.gradle:

    dependencyLocking {
    lockAllConfigurations()
}

    This tells Gradle to track locked versions for all configurations (compileClasspath, runtimeClasspath, etc.)

  2. Run the write-locks command:

    ./gradlew dependencies --write-locks

    With locking enabled, this resolves all dependencies and writes their exact versions to gradle.lockfile.

What the lockfile does

  • Pins every dependency (direct and transitive) to exact versions
  • Ensures reproducible builds across machines/CI
  • Fails the build if resolved versions differ from locked versions (unless you explicitly update)

To update locks later

./gradlew dependencies --write-locks

Or update a single dependency:

./gradlew dependencies --update-locks org.slf4j:slf4j-api

libs.versions.toml

Socket can also build an SBOM from Gradle version catalog files (libs.versions.toml). If your project already uses a version catalog, Socket will automatically detect and parse it — no extra setup is required.

⚠️

Limitations: The libs.versions.toml file is a declaration of available dependencies and versions — it does not reflect which dependencies are actually applied in your build.gradle files. This means:

  • Dependencies added directly in build.gradle or build.gradle.kts (outside the version catalog) will not be included in the generated SBOM.
  • Dependencies declared in libs.versions.toml but not referenced in any build.gradle file will still appear in the SBOM.

For the most accurate results, generate a Socket facts file with socket manifest gradle (recommended) or commit a gradle.lockfile.