How to integrate TrustSource with Maven

Quick installation

It’s easy to include TrustSource into your existing Maven projects. Utilize the ecs-mvn-plugin by declaring it in your pom and using the given example as a template.
Then configure the plugin with your security credentials and bind it for example to the maven install lifecycle.

To retrieve the TrstSource API key, login to the TrustSource web application. Goto profile settings by clicking the gear-icon in the navigation bar and copy one of your company’s API keys to your clipboard. Paste this value between the <apiKey>...</apiKey> tags of your project’s pom.xml file. Enter your TrustSource username, probably your e-mail address, between the <userName>...</userName> tags and find a resonable project name to enter it between the <projectName>...</projectName> tags. The scan will be mapped to this project, if it already exists.

 PLEASE NOTE: If you do _not_ provide any project name, TrustSource will sort the scan into "unassigned" project. You may configure the project association afterwards in the module settings. The plugin will give you a notification at the end of the transferred data display, such as

      "info":"attention: you are using an unknown project 'PROJECTNAME'! Please
      change param or create new project. Current module will be available
      in Unassigned Modules"

Simple example pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>de.eacg</groupId>
      <artifactId>ecs-mvn-plugin</artifactId>
      <version>0.1.9</version>
      <configuration>
        <apiKey>YOUR API KEY GOES HERE</apiKey>
        <userName>LOGINNAME(e-mail) GOES HERE</userName>
        <projectName>THE NAME OF YOUR PROJECT</projectName>
        <baseUrl>https://app.trustsource.io</baseUrl>
      </configuration>
      <executions>
        <execution>
          <id>dependency-scan</id>
          <phase>install</phase>
          <goals>
            <goal>dependency-scan</goal>
          </goals>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Execute on command line:

mvn clean install

Multi module reactor build

If you use a more complex, maven multi module setup, you may define the ecs-mvn-plugin in the <pluginManagement> section of your module pom. All your children projects inherit this definition.

TrustSource requires unique project names. Therefore you have to define the project name and moduleId in every child-modules pom within the <configuration>-tag.
Alternatively, split your project name in 2 parts, the first part contains your projects main name and the second part is dynamically resolved for every sub-
module you want to scan, e.g.:

<projectName>My new cool Project-${project.name}</projectName>

Now apply the plugin to one or more child modules by including the following lines in the <build> element of the pom.

pom.xml for child modules

<build>
  <plugins>
    <plugin>
      <groupId>de.eacg</groupId>
      <artifactId>ecs-mvn-plugin</artifactId>
      <configuration>
        <projectName>unique project name</projectName>
      </configuration>
    </plugin>
  </plugins>
</build>

Provide your credentials using a property file

If you do not want to include your sensitive credentials in the pom, which may be managed by a version control system, store this information in a separate file. This file may by for example located in your user home directory and should have json data format. If you externalize your security credentials, they are reusable for different projects, even if this projects utilize different build tools.

properties file ‘ecs-settings.json’ in your home directory:

{
    "userName": "email@yourdomain.com",
    "apiKey": "234434-fb9b-46f2-db84-ec3f57a46f2"
}

Afterwards simply adjust the configuration of the ecs-mvn-plugin by specifying an additional <credentials> element. In the element define the path to your properties file and ecs-mvn-plugin will then read the properties from this file. The tilde, ‘~’, represents your user home directory, the dot, ‘.’ stands for the current working directory and forward slashes ‘/’ are used to separate subdirectories.

configuration of the ecs-mvn-plugin:

<plugin>
    <groupId>de.eacg</groupId>
    <artifactId>ecs-mvn-plugin</artifactId>
    <version>0.1.9</version>
    <configuration>
        <credentials>~/ecs-settings.json</credentials>
        <projectName>THE NAME OF YOUR PROJECT</projectName>
    </configuration>
   ...
</plugin>

Other maven life cycles

If you do not want to transfer the detected dependency information for every maven install call, bind the ecs-mvn-plugin for example to the deploy lifecycle. (not recommended!)

If you haven’t configured the <distributionManagement> element in your poms, because you prefer your own style distribution, then you have to disable the maven distribution plugin to prevent error messages while invoking the deploy lifecycle phase (mvn deploy).

Disable the maven deployment plugin (PLEASE NOTE: VERSION MIGHT HAVE BEEN CHANGED):

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-deploy-plugin</artifactId>
  <version>2.8.2</version>
  <configuration>
    <skip>true</skip>
  </configuration>
</plugin>                

All relevant ecs-mvn-plugin configuration parameters

credentials

Path to a json file, which holds ‘userName’ and ‘apiKey’ credentials. Use ‘~’ as shortcut to your home directory, and ‘.’ for the current working directory. A forward slash ‘/’ separates directories.

Optional: default: apiKey and userName are expected to be set in the plugin configuration

apiKey

This key permits the access to TrustSource server. Create or retrieve the key from your profile settings of the TrustSource web application.

Required, if not specified in credentials file.

userName

Identifies the initiator of the data transfer.

Required, if not specified in credentials file.

projectName

For which project is the dependency information transferred.

Required

skip

Set to true do disable the ecs-mvn-plugin.

Optional: default: false

skipTransfer

Set to true to execute a dry run and do not transfer anything.

Optional: default: false

Query plugin help on command line:

mvn help:describe -Dplugin=de.eacg:ecs-mvn-plugin \
-Dgoal=dependency-scan -Ddetail=true

System requirements

JDK

1.7 or later

Maven

3.0 or later