# Artifact Ban Maven Plugin

This is a maven plugin that allows for developers and organizations to ban Maven artifacts.  We are keenly aware of the capability in the `maven-enforcer-plugin`.  Instead of simply generating an error when a banned artifact is referenced, this plugin prevents the artifact from being downloaded as well.  This is crucial within certain organizations with strict security scans that crawl the Maven cache.

## Usage

```xml
<project>
    ...
    <build>
        ...
        <plugins>
            ...
            <plugin>
                <groupId>com.inteligr8</groupId>
                <artifactId>ban-maven-plugin</artifactId>
                <version>...</version>
                <extensions>true</extensions>
                <configuration>
                    <import>
                        <url>https://host:port/path/file.xml</url>
                        <artifact>groupId:artifactId:version</artifact>
                    </import>
                    <includes>
                        <artifact>
                            <groupId>...<groupId>
                            <artifactId>...<artifactId>
                            <version>...</version>
                        </artifact>
                        <artifact>
                            <groupIdRegex>...<groupIdRegex>
                            <artifactIdRegex>...<artifactIdRegex>
                            <version>...</version>
                        </artifact>
                        <artifact>com.inteligr8:ban-maven-plugin:[,1.0.0)</artifact>
                        <artifact>log4j:log4j</artifact>
                        <artifact>org\.springframe.+::[,4.0.0.RELEASE)</artifact>
                    </includes>
                    <excludes>
                    	   <artifact>
                    	       ....
                    	   </artifact>
                    </excludes>
                    <import>https://domain:port/path/file</import>
                </configuration>
            </plugin>
            ...
        </plugins>
        ...
    </build>
    ...
</project>
```

The `extensions` elements is critical.  Without it, the plugin does nothing.  With it, the plugin is able to detected ban artifacts before they are downloaded.

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 `groupId` is not provided, it is ignored in the matching process.  So it will match all artifact group IDs and the constraint will be for `artifactId` and `version` only.  The same is true for `artifactId` and `version`.  This means that `<includes><artifact></artifact></includes>` will ban every artifact.

If `groupId` and `groupIdRegex` are both provided, only `groupId` is used.  The same is true for `artifactId` and `artifactIdRegex`.  The `*Regex` values use standard Java regular expressions.  If using regular expressions, remember to escape the dots (`\.`) in group IDs.

The `version` element supports the standard Maven specification.  You can match a specific version like `1.0.0`.  Or you can match all versions before `1.2.17` like `[,1.2.17)`.  You can match all future versions after `1.2.17` (inclusive) with `[1.2.17,)`.

There is nothing stopping you from specifying two `artifact` elements with the exact same values.  So you can ban multiple version ranges of the same artifact by using multiple `artifact` elements.

If you *include* all versions by omitting the `version` element, you can still *exclude* (unban) certain versions, like `[1.2.17,)`.

The `import` URL and artifact are to be XML files that conform to the same `configuration` element as described here.  In fact, the root elmenet of that XML should be `configuration`.  You can create a Maven `pom` packaging type project that deploys the XML to your Maven repository.  Importing the configuration allows you to change banned dependencies without making changes to each individual project.  Just like with the `include` and `exclude` notation, the `import/artifact` version may be a range.  This way the latest banned dependencies can be side-loaded into all projects.  This means previously functioning builds may eventually start failing.  That is by design in this scenario.