Commit 80068ef2 authored by Brian Long's avatar Brian Long
Browse files

Merge branch 'develop' into stable

parents 034b3191 a7480c3d

README.md

+55 −5
Original line number Diff line number Diff line
@@ -5,7 +5,9 @@ This is a maven plugin that allows for developers and organizations to ban Maven 


## Usage



Here is an example of the primary reason why this plugin is useful.

### Prevent Banned Artifacts



Here is a pseudo-code example of all the options this plugin provides.



```xml

<project>
@@ -21,6 +23,7 @@ Here is an example of the primary reason why this plugin is useful. 
                <extensions>true</extensions>

                <configuration>

                    <import>

                        <file>project-file.xml</file>

                        <url>https://host:port/path/file.xml</url>

                        <artifact>groupId:artifactId:version</artifact>

                    </import>
@@ -54,9 +57,11 @@ Here is an example of the primary reason why this plugin is useful. 
</project>

```



The `extensions` elements is critical.  Without it, the plugin does nothing for banning artifacts/dependencies.  With it, the plugin is able to not only detect ban artifacts, but do it before they are downloaded.  This keeps libraries from even reaching your local Maven repository cache.

The `extensions` elements is critical.  Without it, the plugin does nothing as far as banning artifacts/dependencies.  With it, the plugin is able to not only detect banned artifacts, but do it before they are downloaded.  This works with both dependencies and plugins.  This keeps libraries from even reaching your local Maven repository cache.



### Purge Banned Artifacts



Here is an example of the non-extension use case for the plugin:

Here is an example of the non-extension use case for the plugin.  You could use the same plugin for both preventing banned artifacts and cleaning up previously downloaded ones.  Just set `extensions` to `true` in those cases, as highlighted in the previous section.



```xml

<project>
@@ -69,7 +74,6 @@ Here is an example of the non-extension use case for the plugin: 
                <groupId>com.inteligr8</groupId>

                <artifactId>ban-maven-plugin</artifactId>

                <version>...</version>

                <extensions>true</extensions>

                <configuration>

                    ...

                </configuration>
@@ -91,11 +95,25 @@ Here is an example of the non-extension use case for the plugin: 


The `purge-repo` goal will remove all banned artifacts from your local Maven cache.  It does not support `groupIdRegex` or blank `groupId` specifications.  So any of those will not be purged/removed.



For instance, you can use the following and expect it to work for preventing and purging banned dependencies and plugins:



```xml

<include>

    <artifact>

        <groupId>...<groupId>

        <artifactId>...<artifactId>

        <version>...</version>

    </artifact>

    <artifact>com.inteligr8:ban-maven-plugin:[,1.0.0)</artifact>

    <artifact>log4j:log4j</artifact>

</include>

```



## Configuration



If no `includes` are provided, then no artifacts will be banned.  An *included* artifact is a banned artifact.  An *excluded* artifact is not banned.  It is the opposite of what you may think.  If no `excludes` are provided, then no banned artifacts are granted an exception.



The `artifact` element supports the descriptive `groupId`/`artifactId`/`version` elements or the abbreviated colon-based notation.  When using the colon-based notation, the group ID and artifact ID are treated as `groupIdRegex` and `artifactIdRegex` (see below).

The `artifact` element supports the descriptive `groupId`/`artifactId`/`version` elements or the abbreviated colon-based notation.  When using the colon-based notation, the group ID and artifact ID may be treated as `groupIdRegex` and `artifactIdRegex` (see below).  If you only use acceptable `groupId` and `artifactId` characters (letters/numbers/dashes/underscores/dots), it will not.  But if you include any other characters, like `\.` or `*`, then it will be treated as regex.  How it is treated will impact the functionality of `purge-repo` goal, if you are using it.



If `groupId` or `artifactId` or `version` are not provided, they are ignored in the matching process.  So it will match all applicable artifacts and the constraint will be only for what was specified.  This means that `<includes><artifact>:</artifact></includes>` will ban every artifact and all their versions.
@@ -118,3 +136,35 @@ You can create a Maven `pom` packaging type project that deploys a configuration 
The `import` elements supports multiple `url` or `artifact` declarations.  All imported and directly specified include specifications are processed before all exclude specifications.  You cannot change an include when importing, but you can add new ones, that may cover more versions; and you can exclude versions that may have been included by the import.



The `excludes` element is a way to provide project-by-project exceptions to imported banned artifacts where warranted.



## Examples



The recommended us of this plugin is for its use across whole organizations.  First, you will want a simple Maven project that is referenced by all other Maven projects.  That simple project will declare the banned artifacts and potentially purge existing ones.  See the `examples/ban-config` project for a full example.



```xml

<configuration>

    <includes>

        <!-- CVE-2019-17571 -->

        <artifact>org.apache.logging.log4j::[,2.17.1)</artifact>

        <artifact>log4j:log4j</artifact>

    </includes>

</configuration>

```



Deploying that project will result in the publication of the `ban-config.xml` to your Maven repository.  That is where it can be picked up by all other projects so they can enforce the ban.  If you do not have a local Maven repository, then you will have to upload the `ban-config.xml` to some other URL-accessible location by some other means.



Once you have that in place, you will want to add the following to every single Maven project that should be governed by the aforementioned `ban-config`.  See the `examples/governed-artifact` project for a full example.



```xml

<plugin>

    <groupId>com.inteligr8</groupId>

    <artifactId>ban-maven-plugin</artifactId>

    <version>1.3.6</version>

    <extensions>true</extensions>

    <configuration>

        <import>

            <artifact>com.inteligr8:ban-config:[2025.03,)</artifact>

        </import>

    </configuration>

</plugin>

```

examples/ban-config/ban-config.xml

0 → 100644
+8 −0
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="utf-8" ?>

<configuration>

    <includes>

        <!-- CVE-2019-17571 -->

        <artifact>org.apache.logging.log4j::[,2.17.1)</artifact>

        <artifact>log4j:log4j</artifact>

    </includes>

</configuration>

examples/ban-config/pom.xml

0 → 100644
+39 −0
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8"?>



<project xmlns="http://maven.apache.org/POM/4.0.0"

		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

		xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

	<modelVersion>4.0.0</modelVersion>



	<groupId>com.inteligr8</groupId>

	<artifactId>ban-config</artifactId>

	<packaging>pom</packaging>



    <!-- A monthly cadence is reasonable at most organizations -->

	<version>2025.03</version>



	<name>Banned Artifact Configuration</name>

	

	<build>

		<plugins>

			<plugin>

				<groupId>com.inteligr8</groupId>

				<artifactId>ban-maven-plugin</artifactId>

				<version>1.3.6</version>

                <executions>

                    <execution>

                        <id>purge-maven-repo</id>

                        <phase>clean</phase>

                        <goals><goal>purge-repo</goal></goals>

                        <configuration>

                            <import>

                                <file>ban-config.xml</file>

                            </import>

                        </configuration>

                    </execution>

                </executions>

			</plugin>

		</plugins>

	</build>



</project>

examples/governed-artifact/pom.xml

0 → 100644
+31 −0
Original line number Diff line number Diff line 
<?xml version="1.0" encoding="UTF-8"?>



<project xmlns="http://maven.apache.org/POM/4.0.0"

		xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

		xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">

	<modelVersion>4.0.0</modelVersion>



	<groupId>com.inteligr8</groupId>

	<artifactId>governed-artifact</artifactId>

	<version>1.0-SNAPSHOT</version>

	<packaging>jar</packaging>



	<name>Any Governed Artifact</name>

	

	<build>

		<plugins>

			<plugin>

				<groupId>com.inteligr8</groupId>

				<artifactId>ban-maven-plugin</artifactId>

				<version>1.3.6</version>

				<extensions>true</extensions>

				<configuration>

					<import>

						<artifact>com.inteligr8:ban-config:[2025.03,)</artifact>

					</import>

				</configuration>

			</plugin>

		</plugins>

	</build>



</project>

pom.xml

+19 −10
Original line number Diff line number Diff line
@@ -7,7 +7,7 @@ 


	<groupId>com.inteligr8</groupId>

	<artifactId>ban-maven-plugin</artifactId>

	<version>1.3.6</version>

	<version>1.4.0</version>

	<packaging>maven-plugin</packaging>



	<name>Ban Dependencies Maven Plugin</name>
@@ -43,14 +43,14 @@ 
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>

		<maven.compiler.source>1.8</maven.compiler.source>

		<maven.compiler.target>1.8</maven.compiler.target>

		<maven.version>3.9.0</maven.version>

		<maven.version>3.9.9</maven.version>

	</properties>



	<dependencies>

		<dependency>

			<groupId>org.apache.commons</groupId>

			<artifactId>commons-lang3</artifactId>

			<version>3.4</version>

			<version>3.17.0</version>

		</dependency>

		<dependency>

			<groupId>org.apache.maven.shared</groupId>
@@ -66,7 +66,7 @@ 
		<dependency>

			<groupId>org.apache.maven.plugin-tools</groupId>

			<artifactId>maven-plugin-annotations</artifactId>

			<version>3.7.1</version>

			<version>3.15.1</version>

			<scope>provided</scope>

		</dependency>

		<dependency>
@@ -90,16 +90,27 @@ 
		<dependency>

			<groupId>junit</groupId>

			<artifactId>junit</artifactId>

			<version>4.12</version>

			<version>4.13.2</version>

			<scope>test</scope>

		</dependency>

	</dependencies>

	

	<build>

		<pluginManagement>

			<plugins>

				<plugin>

					<artifactId>maven-plugin-plugin</artifactId>

					<version>3.15.1</version>

				</plugin>

				<plugin>

					<artifactId>maven-invoker-plugin</artifactId>

					<version>3.9.0</version>

				</plugin>

			</plugins>

		</pluginManagement>

		<plugins>

			<plugin>

				<artifactId>maven-plugin-plugin</artifactId>

				<version>3.7.1</version>

				<executions>

					<execution>

						<id>default-descriptor</id>
@@ -134,7 +145,7 @@ 
			<plugin>

				<groupId>org.codehaus.plexus</groupId>

				<artifactId>plexus-component-metadata</artifactId>

				<version>2.1.1</version>

				<version>2.2.0</version>

				<executions>

					<execution>

						<goals>
@@ -145,7 +156,6 @@ 
			</plugin>

			<plugin>

				<artifactId>maven-invoker-plugin</artifactId>

				<version>3.4.0</version>

				<configuration>

					<projectsDirectory>${basedir}/src/it</projectsDirectory>

					<cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
@@ -181,7 +191,6 @@ 
				<plugins>

					<plugin>

						<artifactId>maven-invoker-plugin</artifactId>

						<version>3.2.2</version>

						<executions>

							<execution>

								<id>run-its</id>
@@ -240,7 +249,7 @@ 
					<plugin>

						<groupId>org.sonatype.plugins</groupId>

						<artifactId>nexus-staging-maven-plugin</artifactId>

						<version>1.6.13</version>

						<version>1.7.0</version>

						<extensions>true</extensions>

						<configuration>

							<serverId>ossrh</serverId>