ECS - eliminate risks from your open source projects

Sign-in. Create a project. Run a scan. Manage compliance. Across the whole project portfolio. Compliance and risk management are a few clicks away.

ECS - Installation instructions

ECS provides plugins for various build tools and package managers. These plugins analyze your project structure and detect all dependencies, even the transient. This information is gathered and finally transferred to the ECS-server. Only meta information about the dependencies like names, unique identifiers, licenses and repository urls are transferred.

Here you will find installation instructions for various  package manager and taskrunner combinations and configuration hints for the optimal integration in your project.

Additionally we support a sample project on github. Checkout this project, provide your username and apiKey and play around with the predefined Maven, Gradle, Grunt, and Gulp scripts.

Supported tools and technologies


Demo project  Demo project

Checkout our demo project located at Github

As an entry point to your ECS experience, we provide a project which has configuration examples for all supported technologies at  github logo

To checkout this project, open a terminal window and enter:

    
git clone https://github.com/eacg-gmbh/ecs-sample-project

Most of the examples require the ecs-configuration file: .ecsrcs.json in your home directory. This file contains your security credentials and has the following structure:
properties file ‚.ecsrcs.json‘ in your home directory:

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

Replace ‚userName‘ and ‚apiKey‘ with your own credentials which are available after subscribing and login to the ECS-Application.

Afterwards you should try the following commands which all have in common, that they collect dependency information and transfer it directly to the ECS-application. If the the transfer was successful you will see the newly created modules in the application and now you are able to play around with your module and project settings.

maven

mvn clean install ecs-mvn:dependency-scan

gradle

gradle ecsScan

grunt

grunt exec:mvn

grunt exec:gradle

gulp

grunt

java logomaven logoMaven

 Quick installation

It’s easy to include ECS 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 ECS ApiKey, login to the ECS web application. Goto profile settings by clicking the gear-icon in the navigation bar and copy one of your company’s ApiKeys to your clipboard. Paste this value between the <apiKey>...</apiKey> tags of your project’s pom.xml file. Enter your ECS username, probably your e-mail address, between the <userName>...</userName> tags and find a resonable projectname to enter it between the <projectName>...</projectName> tags.

Simple example pom.xml:

<build>
  <plugins>
    <plugin>
      <groupId>de.eacg</groupId>
      <artifactId>ecs-mvn-plugin</artifactId>
      <version>0.1.4</version>
      <configuration>
        <apiKey>YOUR API KEY GOES HERE</apiKey>
        <userName>LOGINNAME(e-mail) GOES HERE</userName>
        <projectName>THE NAME OF YOUR PROJECT</projectName>
      </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

 Advanced Setup

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.

ECS 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. Like so:

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

Now simply 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>
Export your credentials to 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.4</version>
    <configuration>
        <credentials>~/ecs-settings.json</credentials>
        <projectName>THE NAME OF YOUR PROJECT</projectName>
    </configuration>
   ...
</plugin>

 Reference

Other maven lifecycles

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. 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:

<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 ECS server. Create or retrieve the key from your profile settings of the ECS 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

gradle logo  Gradle

Quick installation

Use the ECS-gradle-plugin to transfer the dependencies of your Gradle project. Use the given example build.gradle file as a template, provide your security credentials and name your project.

To retrieve the ECS ApiKey, login to the ECS web application. Goto profile settings by clicking the gear-icon in the navigation bar and copy one of your company’s ApiKeys to your clipboard. Use this value inside the apiKey string and enter your ECS username, probably your e-mail address, as a value for the userName variable. Find a resonable projectname and place it into the projectName variable.

Then on the commandline execute:

gradle ecsScan
Simple example build.gradle:

// define the module coordinates for the gradle plugin
buildscript {
    dependencies {
        classpath 'de.eacg:ecs-gradle-plugin:0.1.3'
    }
    repositories {
        mavenCentral()
    }
}

// apply the plugin to current project
apply plugin: 'de.eacg.ecs.plugin.gradle'


// configure the plugin 
ecsPlugin{
    userName = 'LOGINNAME(e-mail) GOES HERE'
    apiKey = 'YOUR API KEY GOES HERE'
    projectName = 'THE NAME OF YOUR PROJECT'
}

 Advanced Setup

Use of a properties file

The ecs-gradle-plugin is able to read the ecs-access credentials (userName, apiKey) from a properties file in json format. This allows sharing of the ecs-credentials with other projects and also with other build tools.

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

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

Adjust the configuration of the ecs-gradle-plugin by specifying an additional credentials variable in your build.gradle file. In the variable define the path to your properties file and the ecs-gradle-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.

The modified build.gradle:

...
ecsPlugin {
    credentials = '~/ecs-settings.json'
}
...
Multi module projects

In a more complex gradle multi project setup, you may define the classpath for the plugin and the projects for which to execute the plugin in the root build.gradle file. Execute the plugin only for sub-projects which are the start point for your dependency tree.
Your root build.gradle may look like this:

Example multi project build.gradle file:

buildscript {
    dependencies {
        classpath 'de.eacg:ecs-gradle-plugin:0.1.3'
    }
    repositories {
        mavenCentral()
    }
}

...

project(':ecs-gradle-sample-depA') {
    apply plugin: 'de.eacg.ecs.plugin.gradle'
    ecsPlugin {
        credentials = '~/.ecsrc.json'
    }
}
New incubating plugin mechanism introduced in Gradle 2.1

Since version 0.1.3 of the ecs-grdle-plugin, the new gradle plugin mechanism is supported. This mechanism povides a concise and convenient way to declare a plugin dependency. It works with the Gradle plugin portal to provide easy access to both core and community plugins. Since the ecs-gradle-plugin is a community plugin, the following declaration with fully qualified plugin id and version should be used.
Example declaration of plugin, new style:

plugins {
  id "de.eacg.ecsPlugin" version "0.1.3"
}

There is no need to configure the buildscript classpath. Gradle will resolve the plugin in the plugin portal, locate it, and make it available to the build.
Unfortunatly the new mechanism has some limitations at the moment (see Gradle Documentation). If the restrictions of the new syntax are prohibitive, the recommended approach is to apply plugins using the buildscript {} block.

 Reference

All gradle configuration properties
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 ECS server. Create or retrieve the key from your profile settings of the ECS 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.
Optional: default: the value of the gradle project.name variable
configuration
Gradle configuration for which to execute the dependency analysis (for example: ‚runtime‘)
Optional: default: ‚default‘
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

verbose
Set to true to increase the output during execution of the plugin
Optional: default: false
System requirements
JDK
1.7 or later
Gradle
2.0 or later

npm logo grunt logo npm with Grunt

Quick installation

Use ECS with your npm projects in combination with the Grunt javascript task runner by utilizing the „ecs-grunt-plugin“. Install this plugin with a simple

npm install ecs-grunt-plugin --save-dev

on the command line within your project folder.

Create a new or extend your existing Gruntfile.js by using the provided example Gruntfile.js as a template and replace the ‚user‘ and ‚apiKey‘ properties with your own credentials and find a resonable projectname for the ‚project‘ property.

Simply execute

grunt ecs-scan

on the commandline within your project directory to scan and transfer the dependency information to the ECS-platform.

Simple example Gruntfile.js:

'use strict';

module.exports = function (grunt) {
  grunt.initConfig({
    'ecs-scan': {
      options: {
        npm: {
          project: 'YOUR PROJECT NAME'
        },
        user: 'YOUR LOGIN-NAME (e-mail)',
        apiKey: 'YOUR API KEY',
        baseUrl: 'https://ecs-app.eacg.de'
      }
    }
  });

  grunt.loadNpmTasks("ecs-grunt-plugin");

  grunt.registerTask('default', ['ecs-scan']);
};

npm logo gulp logo npm with Gulp

Quick installation

Use ECS with your npm projects in combination with the Gulp javascript task runner by utilizing the „ecs-grunt-plugin“ in conjuction with the „gulp-grunt“ plugin. Install this two plugins with

npm install ecs-grunt-plugin grunt-gulp --save-dev

on the command line within your project folder.

Create a Gruntfile.js as described in the npm with Grunt section and extend your gulpfile.js as shown in our example.

Simply execute

grunt ecs-scan

on the commandline within your project directory to scan and transfer the dependency information to the ECS-platform.

Simple example gulpfile.js:

'use strict';
var gulp = require('gulp');
require('gulp-grunt')(gulp);

// add the grunt tasks (prefixed with the default namespace 'grunt-')
gulp.task('default', [
    'grunt-scan'
]);

maven logo java logoBower with Grunt

Quick installation

Use ECS with your Bower projects in combination with the Grunt javascript task runner by utilizing the „ecs-grunt-plugin“. Install this plugin with a simple

npm install ecs-grunt-plugin --save-dev

on the command line within your project folder.

Create a new or extend your existing Gruntfile.js by using the provided example Gruntfile.js as a template and replace the ‚user‘ and ‚apiKey‘ properties with your own credentials and find a resonable projectname for the ‚project‘ property.

Simply execute

grunt ecs-scan

on the commandline within your project directory to scan and transfer the dependency information to the ECS-platform.

Simple example Gruntfile.js:

'use strict';

module.exports = function (grunt) {
  grunt.initConfig({
    'ecs-scan': {
      options: {
        bower: {
          project: 'YOUR PROJECT NAME'
        },
        user: 'YOUR USERNAME',
        apiKey: 'YOUR API KEY',
        baseUrl: 'https://ecs-app.eacg.de',
      }
    }
  });

  grunt.loadNpmTasks("ecs-grunt-plugin");

  grunt.registerTask('default', ['ecs-scan']);
};

bower logo  gulp logo Bower with Gulp

Quick installation

Use ECS with your Bower projects in combination with the Gulp javascript task runner by utilizing the „ecs-grunt-plugin“ in conjuction with the „gulp-grunt“ plugin. Install this two plugins with

npm install ecs-grunt-plugin grunt-gulp --save-dev

on the command line within your project folder.

Create a Gruntfile.js as described in the bower with Grunt section and extend your gulpfile.js as shown in our example.

Simply execute

grunt ecs-scan

on the commandline within your project directory to scan and transfer the dependency information to the ECS-platform.

Simple example gulpfile.js:

'use strict';
var gulp = require('gulp');
require('gulp-grunt')(gulp);

// add the grunt tasks (prefixed with the default namespace 'grunt-')
gulp.task('default', [
    'grunt-scan'
]);

maven logonuget

Quick installation

Questions? Ideas? Contact us anytime

The EACG team will be happy to hear from you.

Enterprise Architecture Consulting Group
EACG GmbH
Fellnerstraße 5
60322 Frankfurt am Main
Germany
T:+49 69 153 227 750