TICS Administration Guide

Configuring Black Duck

It is possible to incorporate Black Duck results in TICS.

Prerequisites

For a successful Black Duck integration, the following prerequisites must be met:

The results must be available in the Black Duck server dashboard. TICS only retrieves the results and does not perform the analysis.
The Black Duck properties have to be configured correctly, see below.
The Black Duck authentication token has to be configured correctly, see below.
The Black Duck data fetcher, bdfetcher, has to be configured correctly, see below.
The Black Duck rulesets have to be configured correctly, see below.

Basic configuration

To use Black Duck, one has to set up the required properties in either the global configuration file SERVER.yaml or in the project-specific configuration file PROJECTS.yaml. Black Duck properties configured globally in SERVER.yaml will apply to all projects. If the properties are declared both on the SERVER level, i.e. in SERVER.yaml, and also on the PROJECT level, i.e. PROJECTS.yaml, the project-specific properties will overwrite the global properties. If they are declared in the PROJECT level, they can be declared either inside or outside a branch name (inside VIEWS) of a project.

Syntax

The following properties can be declared either on the SERVER level or on the PROJECT level. Of these properties, it is mandatory to have the URL configured.

TOOLS:
  BlackDuck:
    WEBSERVICE:
      URL: URL of a Black Duck server, for example: https://blackduck.tiobe.com
      [AUTHENTICATIONKEYFILE: a relative path of a file containing a Black Duck authentication token.
        The path is relative to the default folder of the TICS configuration directory, i.e. ticsfs/cfg/default]
      [PAGESIZE: Page size for Black Duck API calls. Value should be between 1 and 1000.
        If set outside this range, or not configured, the Black Duck data fetcher will use the value 1000.]
      [TIMEOUT: The time a webservice call may take (in seconds) before it is aborted. Value should be larger than 0.
        If set outside this range, or not configured, the Black Duck data fetcher will use the value 1800.]
      [NR_OF_RETRIES: The number retries when the data cannot be fetched because of connection timeout. Value should be larger than 0.
        If set outside this range, or not configured, the Black Duck data fetcher will use the value 5.]
      [RETRY_INTERVAL: The time (in seconds) between retries. Value should be larger than 0.
        If set outside this range, or not configured, the Black Duck data fetcher will use the value 3.]

The DATASOURCES property and its sub-properties are mandatory and have to be applied on the PROJECT level, either inside or outside a branch name, as shown in the following examples:

project name:
  TOOLS:
    BlackDuck:
      DATASOURCES : [
        [
        PROJECT: Project name in the Black Duck server
        VERSIONS: [Project versions in the Black Duck server],
        ]+
      ]

project name:
  VIEWS:
    branch name:
      TOOLS:
        BlackDuck:
          DATASOURCES : [
            [
            PROJECT: Project name in the Black Duck server
            VERSIONS: [Project versions in the Black Duck server],
            ]+
          ]

Examples for DATASOURCES and other properties:

TICS needs the Black Duck project/version names to be configured to fetch results. Note that at the moment TICS will only allow a data source from one project and one project version. If multiple projects and/or multiple versions are configured, only the first project and the first version will be used. The rest will be ignored. The configuration of DATASOURCES, as well as other properties, are shown in the following examples:

cpp-game-project:
  TOOLS:
    BlackDuck:
      DATASOURCES:
      - PROJECT: blackduck-demo-cpp
        VERSIONS:
        - NAME: 1.0.0
      WEBSERVICE:
        URL: https://blackduck.tiobe.com
        AUTHENTICATIONKEYFILE: ../common/blackduck-auth-key.yaml
        PAGESIZE: 500
        TIMEOUT: 5
        NR_OF_RETRIES: 10
        RETRY_INTERVAL: 2

cpp-game-project:
  VIEWS:
    master:
      TOOLS:
        BlackDuck:
          WEBSERVICE:
            URL: https://blackduck.tiobe.com
            AUTHENTICATIONKEYFILE: blackduck-auth-key.yaml
            PAGESIZE: 400
            TIMEOUT: 10
            NR_OF_RETRIES: 3
            RETRY_INTERVAL: 4
          DATASOURCES:
          - PROJECT: blackduck-demo-cpp
            VERSIONS:
            - NAME: 4.0.0

Authentication Token

An authentication token is required to fetch data from the Black Duck server. This token is used for authenticating API calls from TICS to the BlackDuck server. An authentication token can be generated from the Black Duck server dashboard in the 'My Access Tokens' menu.
There are two ways to provide this authentication token to TICS:

Adding a yaml-formatted authentication key file in the TICS configuration directory.
Configuring an authentication token in the environment variable TICS_BD_AUTHTOKEN.

Configuring an authentication key file

One way to configure the Black Duck authentication token is to add a yaml-formatted authentication key file in the TICS configuration directory. This authentication key file should contain the field token followed by an authentication token value as shown in the example below:

token: TokenFromAuthFileC00MjlkLTg2MWItMmM1NDE0MmU2N2IyOmM5YWEyMzdhLTEwMGYtNDM2My04OTJkLTliYWUyMGFjY1234567

Once the authentication key file has been added in the TICS configuration directory, configure the AUTHENTICATIONKEYFILE property for Black Duck. Assign a relative path of the authentication key file to the property as shown in the example below:

TOOLS:
  BlackDuck:
    WEBSERVICE:
      URL: https://blackduck.tiobe.com
      AUTHENTICATIONKEYFILE: ../common/blackduck-auth-key.yaml

Configuring a TICS_BD_AUTHTOKEN environment variable

Alternatively, the BlackDuck authentication token can be set up in the environment variable TICS_BD_AUTHTOKEN as shown in the example below.

C:\Users\Public>set TICS_BD_AUTHTOKEN
TICS_BD_AUTHTOKEN=PresetTokenInEnvVarMzllLTg5MTItMDYxNzk2ZTMwMzJhOjljZWM1Yzg5LWM1NGUtNDc0Ny1hZWU3LWY5Y2QyZDNhN1234567

If both the AUTHENTICATIONKEYFILE property and the environment variable TICS_BD_AUTHTOKEN are configured, TICS will use the authentication token configured in the AUTHENTICATIONKEYFILE property.

Black Duck Fetcher

TICS uses a Black Duck fetcher, an executable java artifact called bdfetcher that fetches data from the Black Duck server. To use Black Duck properly in TICS, bdfetcher needs to be specified as one of the checkers in the checkers property of config.yaml as shown below.

versions:
  checkers:
    bdfetcher:
      artifact: chk/bdfetcher.zip

Black Duck Rulesets

Black Duck rulesets should be configured in SERVER.yaml for metric SECURITY of each relevant language. Black Duck rulesets are prefixed with 'BLACKDUCK_' as shown in the examples below:

C:
  RULESETS:
  - METRIC: SECURITY
    RULESDIR: 4.0/security/BLACKDUCK_C
    NAME: BlackDuck C Security

CPP:
  RULESETS:
  - METRIC: SECURITY
    RULESDIR: 4.0/security/BLACKDUCK_CPP
    NAME: BlackDuck CPP Security