Join our Newsletter — 33% off our NHI Course
Home› Guides› Maven Central and Gradle Supply Chain Security Guide:…
Guide Software & AI Supply Chain

Maven Central and Gradle Supply Chain Security Guide: Signing, Dependency Verification and Repository Order

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 27 October 2026 12 min read
On this page

Java builds trust whatever the first matching repository serves, and most organisations have never told Maven or Gradle which repository is allowed to serve which artifact. A build that lists an internal repository and Maven Central side by side can resolve an internal group from the public internet, a gradle-wrapper.jar swapped in a pull request runs on every developer machine and CI agent, and the PGP signatures that Maven Central requires on every artifact are almost never checked by consumers. This guide covers both sides of the Java supply chain: consuming safely (repository order and mirrors, Gradle repository content filtering, dependency verification and locking, wrapper validation) and publishing safely (namespace verification, Central Portal tokens, PGP signing keys). It is for build engineers, Java and Android leads and application security teams.

Key takeaways

  • Repository order is a trust decision. Gradle's documentation says that if a library is in several declared repositories, Gradle picks the first; Maven picks the first matching mirror. Route everything through one repository manager and tell the build which repository owns which group.
  • Use Gradle's exclusiveContent for internal groups. An artifact matched by an exclusive filter cannot be found in any other repository, which closes dependency confusion for that group.
  • Turn on dependency verification. gradle/verification-metadata.xml with SHA-256 checksums and PGP signatures makes the build fail when an artifact changes, but only if the generated entries are reviewed rather than trusted blindly.
  • Validate the Gradle wrapper. A malicious gradle-wrapper.jar shows up in a diff as a binary change nobody reviews; check its checksum against official Gradle releases on every pull request.
  • Publishing credentials are high-value NHIs. Central Portal user tokens and the PGP signing key can push trusted artifacts to every downstream build; scope, vault and rotate them like production secrets.

How identity and access work in Maven Central and Gradle

Trust in the Java ecosystem rests on three identities: who owns a groupId namespace, which credential publishes into it, and which key signs the files. Consumers then decide, through repository configuration, where each coordinate may come from.

Identity or trust anchorHow it is establishedWhat it provesWhat it does not prove
Namespace (groupId) on Maven CentralCentral Portal verification: a DNS TXT record with the verification key for the exact domain (reverse-domain naming), or a public repository named with the key for io.github.<user>, io.gitlab, io.gitee or io.bitbucketThe publisher controlled the domain or code-hosting account at registrationThat they still do, or that every artifact in it is safe
Central Portal user tokenGenerated at central.sonatype.com with a display name and expiry; not retrievable after creationThe upload came from someone holding the tokenThat the holder is the maintainer (tokens leak)
PGP signature (.asc)Required by Central for published files; key published to keyserver.ubuntu.com, keys.openpgp.org or pgp.mit.eduThe file was signed by the holder of that private keyThat the key belongs to the project; key names are not proof of identity
Repository declaration in the buildGradle repositories and content filters; Maven settings.xml mirrors and POM repositoriesWhere the build will lookAnything about the artifact unless verification is on
  • Consumer resolution: Gradle searches repositories in declared order and takes the first that has the module, unless content filters say otherwise. Maven applies at most one mirror per repository: an exact ID match wins, otherwise the first matching mirror in declaration order. A single mirror with <mirrorOf>*</mirrorOf> sends every request to your repository manager.
  • Dependency confusion: if an internal group such as com.example.internal is not claimed on the public side and the build can reach a public repository before or alongside the internal one, an attacker who publishes that coordinate publicly may win resolution. Claiming your own reverse-domain namespace on Central (you control the domain, so verification works) plus exclusive content rules removes both halves. See the Malicious Package and Dependency Confusion Guide.

Admin roles and privileged access

  • Namespace owners: on the Central Portal the first verified user becomes administrator of the matching organisation, and the documented permission model has a single "publisher" permission without finer project roles. Keep the set of people who can publish into your namespaces small, use organisation accounts rather than an individual's personal account, and review membership when maintainers leave.
  • Domains behind namespaces: namespace verification uses the exact domain in DNS. Whoever controls that DNS zone can prove ownership of the namespace, so registrar and DNS accounts belong in the same privileged tier as publishing. See the Registrar and Authoritative DNS Security Guide.
  • Signing key custodians: Maven and Nexus Repository Manager verify Central signatures against the primary key, so Sonatype advises signing with the primary key rather than a signing subkey. That makes the primary private key the asset to protect: hold it offline or in a hardware token or KMS-backed signing service, with a documented holder and a revocation certificate stored separately.
  • Repository manager administrators: whoever can change proxy rules, upload to hosted repositories or edit routing in Nexus, Artifactory or a cloud artifact service controls what every build receives. See the Private Package Repository and Proxy Guide.
  • Build configuration owners: changes to settings.gradle(.kts), gradle/verification-metadata.xml, gradle/wrapper/ and Maven settings.xml are security changes. Protect them with CODEOWNERS review by the build or security team.

Integrations, API tokens and service accounts

CredentialWhere it is usually foundRiskBetter practice
Central Portal user tokenCI secrets, developers' ~/.m2/settings.xml or ~/.gradle/gradle.propertiesPublish malicious versions under your namespaceDedicated token per pipeline with an expiry, held only by the release job, regenerated on maintainer change
PGP private key and passphraseCI secret variables, exported ASCII-armoured keySign malicious artifacts that pass verificationSigning in an isolated release job or signing service; never in jobs triggered by untrusted pull requests
Internal repository credentials (read)Gradle properties, Maven <servers>Exposure of internal code and coordinates for confusion attacksShort-lived tokens from the repository manager's OIDC or CI integration where supported; read-only scope
Internal repository credentials (deploy)Same files, often the same account as readOverwrite internal artifactsSeparate deploy identity, only in release pipelines, immutable releases
Gradle Plugin Portal keysCI secretsPublish a malicious build plugin that runs in every consumer buildSame controls as the Central token
  • Keep credentials out of build files: never commit tokens in build.gradle, pom.xml or a project-level gradle.properties; pass them from the CI secret store as environment variables or user-level properties. Secret scanners routinely find repository passwords in these files (ATT&CK T1552.001).
  • Isolate release jobs: the SpotBugs Token Leak 2025 began with a maintainer's personal access token placed in a CI workflow that ran on pull_request_target, where fork pull requests could reach it; the stolen token later led to the reviewdog and tj-actions compromises. Publishing and signing secrets must never be reachable from workflows that run contributor code. See the CI/CD Pipeline Identity Security Guide.
  • Plan for key exposure: in the HashiCorp GPG Key Exposure 2021, a compromised CI tool read the signing key from pipeline environment variables; HashiCorp revoked it, published a new key and re-signed releases. Rehearse that sequence for your own signing key.

Logging and detection

SignalSourceWhat it can indicate
Dependency verification failures (incorrect checksum, failed or untrusted signature)Gradle build output and HTML report; CI logsA tampered or substituted artifact, or a repository serving unexpected content
Internal group requested from a public remoteRepository manager request logsMisconfigured build or an active dependency confusion attempt
New versions published to your namespace outside the release pipelineCentral Portal deployment history; monitoring of your coordinates on CentralStolen publishing token
Changes to gradle-wrapper.jar, verification-metadata.xml, repository blocks or settings.xml mirrorsVersion control, CODEOWNERS alertsAttempt to weaken build trust
Builds run with --dependency-verification=off or lenientCI logs, build scansVerification bypass becoming routine
Wrapper validation failuresCI (setup-gradle or wrapper-validation action)Unofficial wrapper binary in a pull request

Metrics:

  • Percentage of Gradle builds with dependency verification in strict mode and reviewed entries (target 100 percent for production services).
  • Percentage of builds resolving only through the repository manager (no direct public repository URLs).
  • Number of internal groups protected by exclusive content rules or claimed on Central.
  • Age of publishing tokens and signing keys against the rotation policy.
  • Verification failures per month and median time to explain each one.

Hardening baseline

Consumers

  • One front door: in Maven, a single <mirror> with <mirrorOf>*</mirrorOf> pointing at the repository manager; in Gradle, declare repositories once in settings (dependencyResolutionManagement) and fail on project-level repositories so modules cannot add their own.
  • Exclusive content for internal and single-source groups: exclusiveContent { forRepository { maven { url = uri("https://repo.example.com/internal") } }; filter { includeGroupByRegex("com\\.example\\..*") } }. Gradle's documentation calls exclusive content filtering a best practice; repository-level content { } filters are not exclusive, so declare what every repository contains. Use mavenContent { releasesOnly() } on release repositories.
  • Dependency verification: generate with ./gradlew --write-verification-metadata sha256,pgp help (use --dry-run to review first), check every entry marked origin="Generated by Gradle", trust keys by full 40-character fingerprint scoped to the narrowest group, commit the keyring (gradle/verification-keyring.keys, via --export-keys) and disable key servers in CI for reproducibility. Remember that SNAPSHOT versions and locally built artifacts are not verified, and that verification does not detect known vulnerabilities.
  • Locking: dependencyLocking { lockAllConfigurations() } with LockMode.STRICT, lockfiles committed, updates through --update-locks in reviewed pull requests. In Maven, pin explicit versions and avoid ranges.
  • Wrapper: validate gradle-wrapper.jar against official checksums on every pull request (the gradle/actions setup-gradle action does this automatically from v4) and pin distributionSha256Sum in gradle-wrapper.properties.
  • No plain HTTP: Maven 3.8.1 and later block external HTTP repositories by default through a built-in mirror; do not override it. Gradle rejects insecure protocols unless explicitly allowed; never allow them.
  • No mavenLocal() in CI: the local repository is writable by anything that ran earlier on the agent.

Publishers

  • Claim your reverse-domain namespace on Central even if you publish nothing publicly, so it cannot be claimed by others.
  • Sign every artifact with a primary key that has an expiry (Sonatype notes keys default to two years and can be extended), publish the public key to the supported keyservers, and list the fingerprint on your project website so consumers can trust it.
  • Publish from an isolated release pipeline with an expiring Portal token; produce an SBOM and build provenance alongside the artifacts. See the SLSA and Build Provenance Guide and the SBOM Guide.

Rolling it out

  1. Inventory: list every repository URL in POMs, Gradle builds, init scripts and settings.xml files across the estate, and every internal groupId.
  2. Centralise resolution: point all builds at the repository manager; block direct egress from CI agents to public repositories so the change cannot be bypassed.
  3. Protect internal groups: add exclusive content rules and claim namespaces on Central.
  4. Verification in lenient mode: bootstrap verification-metadata.xml, run CI with --dependency-verification=lenient for two weeks, investigate every failure, then switch to strict. Roll back a broken build by reverting the metadata commit, not by turning verification off globally.
  5. Locking and wrapper validation next, then rotate publishing tokens and move signing into an isolated job.

Decision guidance: checksum-only verification is the practical start for large monorepos with thousands of dependencies; add PGP verification for high-value services once key trust is reviewed. Small teams without a repository manager still get most of the benefit from exclusiveContent, locking and wrapper validation. Organisations that publish open source should prioritise token and signing key custody, because a compromise affects every downstream user.

Framework mapping

ControlNIST SP 800-53 Rev. 5NIST CSF 2.0OWASP ASVS 5.0ATT&CK
Single repository manager, exclusive contentSR-3, CM-7GV.SC-05, PR.PS-01V15.2.4T1195.001
Dependency verification (checksums, PGP)SR-11, SI-7, CM-14PR.PS-02V15.2.4T1195.001
Dependency locking and inventorySA-10, SR-4ID.AM-02V15.1.2T1195.001
Wrapper validationSI-7PR.PS-01n/aT1195.001
Publishing token and signing key custodyIA-5, CM-14PR.PS-01n/aT1552.001

Common misconfigurations

  • Public and internal repositories side by side with no content filters, so resolution order decides where an internal coordinate comes from.
  • Verification metadata generated and committed unreviewed: it records whatever the repositories served on that day, including anything already malicious, and trusted keys are scoped to .*.
  • Verification turned off to fix a build: --dependency-verification=off left in a CI script after an incident.
  • Signing subkey in use: artifacts signed with a subkey fail Central's primary-key checks, and teams respond by disabling signing checks downstream.
  • One shared deploy account used for reading, deploying and administering the repository manager, stored on developer laptops.
  • Unreviewed wrapper updates: "Update Gradle wrapper" pull requests merged without wrapper validation.

Practitioner checklist

  • Route all Maven and Gradle resolution through one repository manager and block direct public egress from CI.
  • Declare Gradle repositories centrally in settings and forbid project-level repositories.
  • Protect internal groups with exclusiveContent and claim your namespace on Maven Central.
  • Enable Gradle dependency verification with reviewed SHA-256 and PGP entries, narrowly scoped trusted keys and a committed keyring.
  • Lock dependency versions with strict lock mode and reviewed updates.
  • Validate gradle-wrapper.jar and pin distributionSha256Sum.
  • Keep Maven's HTTP repository blocking in place and remove mavenLocal() from CI.
  • Use expiring, pipeline-specific Central Portal tokens and separate read and deploy identities for internal repositories.
  • Sign releases in an isolated job with a protected primary key and a tested revocation plan.
  • Alert on verification failures, wrapper changes and publications outside the release pipeline.

Standards and references

Related NHI Mgmt Group resources: Software Supply Chain Security Guide · Kotlin and Android Secure Coding Guide · Java and Spring Security Guide · Artifactory Tokens Security Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 27 October 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.