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
exclusiveContentfor 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.xmlwith 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.jarshows 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 anchor | How it is established | What it proves | What it does not prove |
|---|---|---|---|
Namespace (groupId) on Maven Central | Central 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.bitbucket | The publisher controlled the domain or code-hosting account at registration | That they still do, or that every artifact in it is safe |
| Central Portal user token | Generated at central.sonatype.com with a display name and expiry; not retrievable after creation | The upload came from someone holding the token | That 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.edu | The file was signed by the holder of that private key | That the key belongs to the project; key names are not proof of identity |
| Repository declaration in the build | Gradle repositories and content filters; Maven settings.xml mirrors and POM repositories | Where the build will look | Anything 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.internalis 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 Mavensettings.xmlare security changes. Protect them with CODEOWNERS review by the build or security team.
Integrations, API tokens and service accounts
| Credential | Where it is usually found | Risk | Better practice |
|---|---|---|---|
| Central Portal user token | CI secrets, developers' ~/.m2/settings.xml or ~/.gradle/gradle.properties | Publish malicious versions under your namespace | Dedicated token per pipeline with an expiry, held only by the release job, regenerated on maintainer change |
| PGP private key and passphrase | CI secret variables, exported ASCII-armoured key | Sign malicious artifacts that pass verification | Signing 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 attacks | Short-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 read | Overwrite internal artifacts | Separate deploy identity, only in release pipelines, immutable releases |
| Gradle Plugin Portal keys | CI secrets | Publish a malicious build plugin that runs in every consumer build | Same controls as the Central token |
- Keep credentials out of build files: never commit tokens in
build.gradle,pom.xmlor a project-levelgradle.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
| Signal | Source | What it can indicate |
|---|---|---|
| Dependency verification failures (incorrect checksum, failed or untrusted signature) | Gradle build output and HTML report; CI logs | A tampered or substituted artifact, or a repository serving unexpected content |
| Internal group requested from a public remote | Repository manager request logs | Misconfigured build or an active dependency confusion attempt |
| New versions published to your namespace outside the release pipeline | Central Portal deployment history; monitoring of your coordinates on Central | Stolen publishing token |
Changes to gradle-wrapper.jar, verification-metadata.xml, repository blocks or settings.xml mirrors | Version control, CODEOWNERS alerts | Attempt to weaken build trust |
Builds run with --dependency-verification=off or lenient | CI logs, build scans | Verification bypass becoming routine |
| Wrapper validation failures | CI (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-levelcontent { }filters are not exclusive, so declare what every repository contains. UsemavenContent { releasesOnly() }on release repositories. - Dependency verification: generate with
./gradlew --write-verification-metadata sha256,pgp help(use--dry-runto review first), check every entry markedorigin="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() }withLockMode.STRICT, lockfiles committed, updates through--update-locksin reviewed pull requests. In Maven, pin explicit versions and avoid ranges. - Wrapper: validate
gradle-wrapper.jaragainst official checksums on every pull request (the gradle/actionssetup-gradleaction does this automatically from v4) and pindistributionSha256Sumingradle-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
- Inventory: list every repository URL in POMs, Gradle builds, init scripts and
settings.xmlfiles across the estate, and every internalgroupId. - Centralise resolution: point all builds at the repository manager; block direct egress from CI agents to public repositories so the change cannot be bypassed.
- Protect internal groups: add exclusive content rules and claim namespaces on Central.
- Verification in lenient mode: bootstrap
verification-metadata.xml, run CI with--dependency-verification=lenientfor 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. - 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
| Control | NIST SP 800-53 Rev. 5 | NIST CSF 2.0 | OWASP ASVS 5.0 | ATT&CK |
|---|---|---|---|---|
| Single repository manager, exclusive content | SR-3, CM-7 | GV.SC-05, PR.PS-01 | V15.2.4 | T1195.001 |
| Dependency verification (checksums, PGP) | SR-11, SI-7, CM-14 | PR.PS-02 | V15.2.4 | T1195.001 |
| Dependency locking and inventory | SA-10, SR-4 | ID.AM-02 | V15.1.2 | T1195.001 |
| Wrapper validation | SI-7 | PR.PS-01 | n/a | T1195.001 |
| Publishing token and signing key custody | IA-5, CM-14 | PR.PS-01 | n/a | T1552.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=offleft 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
exclusiveContentand 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.jarand pindistributionSha256Sum. - 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
- Gradle: Verifying dependencies
- Gradle: Filtering repository content
- Gradle: Locking dependency versions
- Apache Maven: Using mirrors for repositories
- Sonatype Central: GPG signing requirements
- Sonatype Central: Register a namespace
- Gradle: Wrapper validation action
- NIST: SP 800-53 Rev. 5
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