Maven Plugin

About the Plugin

The Contrast Maven Plugin is used to integrate the Contrast jar with your build. It's capable of authenticating a user to Contrast, downloading the latest Java agent and verifying your build.

Note: Maven is a build tool that utilizes pom.xml files to configure your applications. It's used to build, package and test Java applications.

This guidance refers to version 2.0 of the Contrast Maven Plugin. For information on version 1.X, refer to the documentation in Contrast's Github repository.

Access the Plugin

You can view the plugin code in Contrast's Github repository. You can also review how our two goals, install and verify, work.

Configuration

The table below shows all the parameters for the plugin. These settings are for connecting to Contrast and filtering your vulnerabilities.

Parameter Required Default Description Since
username True Username in the Contrast application
serviceKey True Service Key
apiKey True API Key
orgUuid True Organization UUID
appName True Name of the application as seen in the Contrast UI
standalone False False Set this to "true" if this is a standalone application. 2.2
appVersion False See appVersion section. The appversion to report to the Contrast application. See the appVersion section for more information.
apiUrl True API URL to your Contrast application
serverName True Name of the server you set with -Dcontrast.server
serverPath False The server context path 2.1
minSeverity False Medium Minimum severity level to verify; options are Note, Low, Medium, High or Critical
jarPath False Path to contrast.jar, if you already have one downloaded
skipArgLine False False If this is "true", the plugin will not alter the Maven argLine property in any way. 2.0

Note: Even if your build succeeds, the plugin will fail the overall build if a vulnerability with adequate severity is found.

The following configuration is an example of a profile for the Contrast Maven Plugin. To run with this profile, use mvn install -P run-with-contrast.

<profile>
    <id>run-with-contrast</id>
    <build>
        <plugins>
            <plugin>
                <groupId>com.contrastsecurity</groupId>
                <artifactId>contrast-maven-plugin</artifactId>
                <version>2.0</version>
                <executions>
                    <execution>
                        <id>install-contrast-jar</id>
                        <goals>
                            <goal>install</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>verify-with-contrast</id>
                        <phase>post-integration-test</phase>
                        <goals>
                            <goal>verify</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <username>test_user</username>
                    <apiKey>testApiKey</apiKey>
                    <serviceKey>testServiceKey</serviceKey>
                    <apiUrl>https://app.contrastsecurity.com/Contrast/api</apiUrl>
                    <orgUuid>QWER-ASDF-ZXCV-ERTY</orgUuid>
                    <appName>MyAppName</appName>
                    <serverName>MyServerName</serverName>
                    <minSeverity>High</minSeverity>
                </configuration>
            </plugin>
        </plugins>
    </build>
</profile>

Option Details

JVM arguments

The Contrast Maven Plugin will configure your JVM arguments to use the Contrast agent by appending to the argLine property from the Maven properties. If you want to prevent this in order to build your own JVM arguments, set skipArgLine to true in the plugin properties.

serverPath

Multi-module Maven builds can appear as different servers in Contrast. If you want to discourage this behavior, and prefer to see all modules appear under the same server in Contrast, set the serverPath property.

You are strongly encouraged to add a serverPath, if this build will be run in a continuous integration (CI) environment such as Travis CI or Circle CI. This will help you keep your servers tidy in the Contrast UI.

appVersion

When your application's integration tests are run, the Contrast agent can add an appVersion property to its metadata. This allows you to compare vulnerabilities between applications versions, CI builds, etc. Contrast generates the appVersion in the following order:

  • If you specify an appVersion in the properties, Contrast will use it without modification.
  • If your build is running in TravisCI, Contrast will use appName-$TRAVIS_BUILD_NUMBER.
  • If your build is running in CircleCI, Contrast will use appName-$CIRCLE_BUILD_NUM.
  • If you don't specify an appVersion, Contrast will generate one in appName-yyyyMMddHHmmss format.

Containers

Please see the following articles for specific installation instructions:

Gradle Plugin

About the Contrast Gradle Plugin

The Contrast Gradle Plugin is used to integrate the Contrast.jar with your build. It's capable of authenticating to the Contrast application, downloading the latest Java agent and verifying your build.

Note: Gradle is a build tool that utilizes build.gradle files to configure your applications. It's used to build, package, and test various types of applications.

This documentation is for the version 2.X of the plugin. For version 1.X, please refer to the documentation on Github.

Access the Plugin

The plugin code can be viewed in our Github repository. Here you can review the two tasks added by the plugin, contrastInstall and contrastVerify, and how they work.

The latest version of the plugin can be found on Gradle's plugin webpage.

Use the Plugin

Configuration

The table belows shows all the parameters for the plugin. These settings are for connecting to the Contrast application and filtering your vulnerabilities.

Parameter Description
TeamServer Username Username/email for your user in the Contrast UI
TeamServer Service Key Service Key
TeamServer API Key API Key
TeamServer API Url API URL to the Contrast application
TeamServer Organization Uuid Organization UUID
Application Name Name of application you set with -Dcontrast.appname
This is used to filter for your application
Minimum Severity Level Minimum severity level to filter for (Note, Low, Medium, High, Critical). This property is inclusive.
Server Name Name of server you set with -Dcontrast.server
Use app.contrastsecurity.com/Contrast/api if you are a SaaS customer
Jar Path Path of a local jar file if you don't want to download the agent again

Note: Even if your build succeeds, the plugin will fail the overall build if a vulnerability is found at or above the severity level set in the configuration.

JVM arguments

The plugin edits the org.gradle.jvmargs property in the gradle.properties file to launch the JVM with the Contrast agent.

appVersion

An application version is generated during the Gradle install task. The plugin generates the application version in the following order.

  • If your build is running in TravisCI, Contrast will use appName-$TRAVIS_BUILD_NUMBER.
  • If your build is running in CircleCI, Contrast will use appName-$CIRCLE_BUILD_NUM.
  • If your build is running neither in TravisCI nor in CircleCI, Contrast will generate one in the format appName-yyyyMMddHHmm.

Onboard a Sample Web Application

The easiest way to set up a project is to clone our sample Gradle-based web application. This application has been migrated from Maven to Gradle, and relies on MongoDB; you will install that and set up the database path.

git clone https://github.com/Contrast-Security-OSS/Contrast-Sample-Gradle-Application
brew install mongodb
sudo mkdir -p /data/db
brew services start mongodb
  • Now we have an application that is ready to run. Open up the Contrast-Sample-Gradle-Application/build.gradle file. Scroll to the very bottom and you find the following contrastConfiguration extension. You can find all of these values in the Contrast UI except for appName and serverName.
contrastConfiguration {
    username = "username"
    apiKey = "apiKey"
    serviceKey = "serviceKey"
    apiUrl = "apiUrl"
    orgUuid = "orgUuid"
    appName = "editLATER"
    serverName = "editLATER"
}
  • Once username, apiKey, serviceKey, apiUrl, and orgUuid have been configured we can install the Contrast jar file by calling the contrastInstall task. This will install contrast.jar within the project's build directory.
cd path/to/Contrast-Sample-Gradle-Application
gradle build -x test contrastInstall
  • The next step is to run the application with the Java agent.
cd path/to/Contrast-Sample-Gradle-Application/build
java -javaagent:contrast.jar -Dcontrast.appname=mytestapp -Dcontrast.server=mytestserver -jar libs/Contrast-Sample-Gradle-Application-0.0.1-SNAPSHOT.jar
  • After executing the above code, the server will start. At this point we want to check that the application is running at localhost:8080 and that the application shows up in TeamServer.

  • In TeamServer, verify that the application with the appname specified in the command above shows up.

  • In the Contrast-Sample-Gradle-Application project's build.gradle we will now edit the contrastConfiguration to specify the appName and serverName that we specified as options with the Java agent in the previous step.
contrastConfiguration {
    username = "alreadySetup"
    apiKey = "alreadySetup"
    serviceKey = "alreadySetup"
    apiUrl = "alreadySetup"
    orgUuid = "alreadySetup"
    appName = "mytestapp"
    serverName = "mytestserver"
}
  • We can now run the verification task at any time to check for vulnerabilities.
gradle build contrastVerify -x test

Example

Below is a sample configuration for the Contrast Gradle Plugin:

buildscript {
  repositories {
    maven {
      url "https://plugins.gradle.org/m2/"
    }
  }
  dependencies {
    classpath "gradle.plugin.com.contrastsecurity:ContrastGradlePlugin:1.1.1"
  }
}

apply plugin: "com.contrastsecurity.contrastplugin"
contrastConfiguration {
    username = "test_user"
    apiKey = "testApiKey"
    serviceKey = "testServiceKey"
    apiUrl = "https://www.app.contrastsecurity.com/Contrast/api"
    orgUuid = "QWER-ASDF-ZXCV-ERTY"
    appName = "Test Application"
    serverName = "jenkins.slave1"
    minSeverity = "Medium"
}