Maven Distribution Verifier Plugin

Introduction

The Maven Distribution Verifier Plugin allows verification of .jar, .war, .ear and .zip files. The content is checked against a defined whitelist. This ensures that only the expected artifacts with the respective fingerprint are included in your application distribution.

If there are any discrepancies in the defined hash values or files that are not defined during the verification process, a report is generated. In this way, the software artifact is additionally hardened in the quality assurance process.

Features

• Verify distribution files against a whitelist

• Support for JAR, WAR, EAR, and ZIP files

• MD5 checksum validation

• Generate detailed verification reports

• JUnit report format support

• Maven integration

Requirements

• Java 11 or higher

• Maven 3.6.0 or higher

Quick Start

Add the plugin to your Maven pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>com.dataliquid.maven</groupId>
      <artifactId>distribution-verifier-maven-plugin</artifactId>
      <version>1.0.3</version>
      <configuration>
        <distributionFile>${project.build.directory}/${project.build.finalName}.zip</distributionFile>
        <whitelistFile>${project.basedir}/src/main/resources/whitelist.xml</whitelistFile>
        <reportFile>${project.build.directory}/distribution-verifier-report.xml</reportFile>
      </configuration>
      <executions>
        <execution>
          <goals>
            <goal>verify</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Goals

The plugin provides two main goals:

verify

Verifies a distribution file against a whitelist.

Parameters:

Parameter	Type	Required	Description
distributionFile	File	Yes	The distribution file to verify (JAR, WAR, EAR, or ZIP)
whitelistFile	File	Yes	The whitelist XML file containing expected entries
reportFile	File	No	Output report file (default: target/distribution-verifier-report.xml)
reportFormat	String	No	Report format: "xml" or "junit" (default: "xml")
failOnError	boolean	No	Fail the build if verification errors are found (default: true)

Usage:

mvn distribution-verifier:verify

generate

Generates a whitelist from an existing distribution file.

Parameters:

Parameter	Type	Required	Description
distributionFile	File	Yes	The distribution file to analyze
whitelistFile	File	Yes	Output whitelist file location

Usage:

mvn distribution-verifier:generate

Whitelist

The whitelist file whitelist.xml contains file name, path and the MD5 fingerprint.

Attribute	Description
path	File path within the Zip file
md5	File expects md5 hash. The attribute is optional. If missing, only checks whether the file exists.

<whitelist>
  <entry path="/Sample.md" />
  <entry md5="193fa5e788a1800a760d1108051c2363" path="/Sample.txt" />
</whitelist>

Report

After verification, all results are summarized in a report. The file report.xml contains information on both successful and faulty checks.

Each file is shown with a status and message.

The status can have the following values:

• SUCCESS

• FAILED

<report>
 <entry md5="4114b3e750902c5404ffe4864b3e11b8" path="/Sample.md">
    <result message="Validation passed successfully" status="SUCCESS" />
 </entry>
 <entry md5="193fa5e788a1800a760d1108051c4711" path="/Sample.txt">
    <result message="File found but with a different MD5 Checksum 193fa5e788a1800a760d1108051c2363"
            status="FAILED" />
 </entry>
 <entry md5="193fa5e788a1800a760d1108051c7778" path="/Sample.adoc">
    <result message="Defined file not found" status="FAILED" />
 </entry>
 <entry md5="0430eba9643b5e60e49c055eb16cbf7a" path="/Sample.adoc">
    <result status="FAILED" message="File is not defined in whitelist" />
 </entry>
</report>

Tools

Creating an initial whitelist, the commands find and md5sum can be combined on linux systems. Listing all files with path and MD5 hash in the whitelist structure, use this command:

cd path/to/your/directory
find * -type f -exec md5sum {} \; | awk '{printf "<entry path=\"/%s\" md5=\"%s\" />%s", $2, $1, "\n"}'

The <entry> elements are displayed on the console after the processing has been completed. These can then be transferred to your own whitelist.

<entry path="/Sample.md"   md5="4114b3e750902c5404ffe4864b3e11b8" />
<entry path="/Sample.text" md5="193fa5e788a1800a760d1108051c2363" />

Examples

Basic Verification

Verify a distribution file with default settings:

<plugin>
  <groupId>com.dataliquid.maven</groupId>
  <artifactId>distribution-verifier-maven-plugin</artifactId>
  <version>1.0.3</version>
  <executions>
    <execution>
      <phase>verify</phase>
      <goals>
        <goal>verify</goal>
      </goals>
      <configuration>
        <distributionFile>${project.build.directory}/${project.build.finalName}.zip</distributionFile>
        <whitelistFile>src/main/resources/whitelist.xml</whitelistFile>
      </configuration>
    </execution>
  </executions>
</plugin>

Generate Whitelist from Existing Distribution

mvn distribution-verifier:generate \
  -DdistributionFile=target/myapp.zip \
  -DwhitelistFile=src/main/resources/whitelist.xml

JUnit Report Format

Generate reports in JUnit format for CI/CD integration:

<configuration>
  <distributionFile>${project.build.directory}/${project.build.finalName}.war</distributionFile>
  <whitelistFile>src/main/resources/whitelist.xml</whitelistFile>
  <reportFile>${project.build.directory}/surefire-reports/distribution-verifier.xml</reportFile>
  <reportFormat>junit</reportFormat>
</configuration>

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.