This plugin is a state-of-the-art solution that validates the integrity of a maven build.
It does this by generating a lock file that contains the checksums of all the artifacts in the repository.
The lock file can then be used to validate the integrity prior to building.
This guards the supply chain against malicious actors that might tamper with the artifacts in the repository.
We also allow to rebuild your old versions with the pinned versions from the lockfile.
We call this freeze and replace all versions in the pom with the versions from the lockfile.
Also, every transitive dependency is pinned to the version from the lockfile.
We add these dependencies to the pom and due to the transitive dependency resolution of maven, the exact versions are used.
- Generative Maven lockfiles.
- Rebuild old versions with the pinned versions from the lockfile.
- Checking Maven lockfiles against the local dependencies.
- Lockfile format in readable JSON
- Support for application, test, plugin dependencies
- One Lockfile per module
- Usage as Maven plugin and GitHub action
This plugin is available on maven central. See https://search.maven.org/artifact/io.github.chains-project/maven-lockfile for the latest version.
First, generate a lock file by running the following command in the repository that you want to validate:
mvn io.github.chains-project:maven-lockfile:generate
This should generate a lockfile.json file in each module of the repository. This file contains the checksums of all the artifacts in the repository. Also, the complete dependency tree is stored in the lock file.
Then run the following command to validate the repository:
mvn io.github.chains-project:maven-lockfile:validate
If this runs successfully, the repository is valid. All dependencies defined are still the same as when the lock file was generated.
mvn io.github.chains-project:maven-lockfile:freeze
This replaces every version in the pom with the version from the lockfile. Also, every transitive dependency is added to the pom with the version from the lockfile. If you invoke build afterward, the exact versions from the lockfile are used.
reducedwill reduce the lockfile only containing the dependencies after dependency resolution conflicts are resolved. This format is smaller, and easier to review and read. Only use this if you do not need the full dependency tree.includeMavenPluginswill include the maven plugins in the lockfile. This is useful if you want to validate the Maven plugins as well.checksumAlgorithmwill set the checksum algorithm used to generate the lockfile. The default depends on your checksum mode.checksumModewill set the checksum mode used to generate the lockfile. See Checksum Modes for more information.skipwill skip the execution of the plugin. This is useful if you would like to disable the plugin for a specific module.getConfigFromFilewill read the configuration of maven lockfile from the existing lockfile.
An example lockfile is shown below: For a full example, see the lockfile.json file in this repository.
{
"artifactID":"my-app",
"groupID":"com.mycompany.app",
"version":"1",
"lockFileVersion":1,
"dependencies":[
{
"groupId":"org.junit.platform",
"artifactId":"junit-platform-engine",
"version":"1.9.2",
"checksumAlgorithm":"SHA-256",
"checksum":"25f23dc535a091e9dc80c008faf29dcb92be902e6911f77a736fbaf019908367",
"id":"org.junit.platform:junit-platform-engine:1.9.2",
"parent":"org.junit.jupiter:junit-jupiter-engine:5.9.2",
"children":[
{
"groupId":"org.apiguardian",
"artifactId":"apiguardian-api",
"version":"1.1.2",
"checksumAlgorithm":"SHA-256",
"checksum":"b509448ac506d607319f182537f0b35d71007582ec741832a1f111e5b5b70b38",
"id":"org.apiguardian:apiguardian-api:1.1.2",
"parent":"org.junit.platform:junit-platform-engine:1.9.2",
"children":[
]
},
{
"groupId":"org.junit.platform",
"artifactId":"junit-platform-commons",
"version":"1.9.2",
"checksumAlgorithm":"SHA-256",
"checksum":"624a3d745ef1d28e955a6a67af8edba0fdfc5c9bad680a73f67a70bb950a683d",
"id":"org.junit.platform:junit-platform-commons:1.9.2",
"parent":"org.junit.platform:junit-platform-engine:1.9.2",
"children":[
{
"groupId":"org.apiguardian",
"artifactId":"apiguardian-api",
"version":"1.1.2",
"checksumAlgorithm":"SHA-256",
"checksum":"b509448ac506d607319f182537f0b35d71007582ec741832a1f111e5b5b70b38",
"id":"org.apiguardian:apiguardian-api:1.1.2",
"parent":"org.junit.platform:junit-platform-commons:1.9.2",
"children":[
]
}
]
},
{
"groupId":"org.opentest4j",
"artifactId":"opentest4j",
"version":"1.2.0",
"checksumAlgorithm":"SHA-256",
"checksum":"58812de60898d976fb81ef3b62da05c6604c18fd4a249f5044282479fc286af2",
"id":"org.opentest4j:opentest4j:1.2.0",
"parent":"org.junit.platform:junit-platform-engine:1.9.2",
"children":[
]
}
]
}
]
}This is close to the format of the lock file in the npm package-lock.json file.
We made some java-specific changes to the format, e.g., we added the groupId field.
For each artifact, we store the hashes of all transitive dependencies in the children field.
This allows us to validate the integrity of the transitive dependencies as well.
We have created a GithubAction that can be used to validate the integrity of your maven repository.
A sample workflow is shown below:
Usage:
name: Lockfile
on:
pull_request:
permissions:
contents: read
jobs:
check-lockfile:
permissions:
contents: write
runs-on: ubuntu-latest
steps:
- name: run maven-lockfile
uses: chains-project/maven-lockfile@6572b9abec75a66b669cc6d432bdaf0ec25a92e3 # v5.0.0
with:
github-token: ${{ secrets.JRELEASER_GITHUB_TOKEN }}
include-maven-plugins: true
If a pom.xml file is changed, this action will add a commit with the updated lockfile to the pull request. Otherwise, it will validate the lockfile and fail if the lockfile is incorrect. A lockfile is incorrect if any dependency has changed since the lockfile was generated. This includes versions and checksums.
Here we list some related work that we found while researching this topic.
- Maven: https://github.com/vandmo/dependency-lock-maven-plugin
- Gradle: For Gradle, there exists a built-in solution: https://docs.gradle.org/current/userguide/dependency_locking.html. This solution only works for Gradle builds and is deeply connected to the Gradle build system. The Gradle ecosystem is fast changing and so is its dependency resolution. Our lockfile is independent of the build system and can be used to validate the integrity of a maven repository.
- NPM: https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json