Configuring Mend SCA, a software composition analysis tool from Mend.io

It is possible to incorporate Mend SCA results in TICS.

Prerequisites

For a successful Mend SCA integration, the following prerequisites must be met:

Basic Configuration

To use Mend SCA, 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. Mend SCA 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:
  Mend:
    WEBSERVICE:
      URL: URL of a Mend SCA server, for example: https://saas-eu.mend.io/. This will be used to provide links to the Mend SCA server in the TICS annotated source.
      [API: API base URL of a Mend SCA server, for example: https://api-saas-eu.mend.io/. If this is not provided,
        the mendfetcher will take the Mend SCA server URL value and add an 'api-' prefix in front of its subdomain as the API value.]
      [AUTHENTICATIONKEYFILE: a relative path of a file containing a Mend SCA authentication token.
        The path is relative to the default folder of the TICS configuration directory, i.e. ticsfs/cfg/default]
      [PAGESIZE: Page size for Mend SCA API calls. Value should be between 1 and 10000.
        If set outside this range, or not configured, the Mend SCA data fetcher will use the value 50.]
      [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 Mend SCA 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 Mend SCA 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 Mend SCA data fetcher will use the value 3.]
      [HOSTNAMEVERIFICATION: Enable or disable host name verification of the Mend SCA server. Can be set with values
        'true', '1', 'false' or '0'. If configured, will be used to set (or override) the value of
        environment variable TICSHOSTNAMEVERIFICATION. If TICSHOSTNAMEVERIFICATION is not configured, the Mend SCA fetcher will enable the
        host name verification by default.]
      [TRUSTSTRATEGY: Set the strategy to establish trustworthiness of certificates of the Mend SCA Server. Can be set with
        relevant values such as 'all' or 'self-signed'. If configured, will be used to set (or override) the value of
        environment variable TICSTRUSTSTRATEGY. If TICSTRUSTSTRATEGY is not configured, the Mend SCA fetcher will use the self-signed
        trust strategy by default.]

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:
    Mend:
      DATASOURCES : [
        [
        APPLICATION: Application name in the Mend SCA server
        PROJECTS: [Project names in the Mend SCA server],
        ]+
      ]

project name:
  VIEWS:
    branch name:
      TOOLS:
        Mend:
          DATASOURCES : [
            [
            APPLICATION: Application name in the Mend SCA server
            PROJECTS: [Project names in the Mend SCA server],
            ]+
          ]

Examples for DATASOURCES and other properties:

TICS needs the Mend SCA application/project names to be configured to fetch results. Mend SCA has a notion of applications, which are also referred to as products. Each application can consist of one or more projects. Note that at the moment TICS will only allow a data source from one application and one project. If multiple applications and/or multiple projects are configured, only the first application and the first project of the application will be used. The rest will be ignored. The configuration of DATASOURCES, as well as other properties, are shown in the following examples: 

JavaPackager-1.7.2:
  TOOLS:
    Mend:
      DATASOURCES:
      - APPLICATION: JavaPackager
        PROJECTS:
        - NAME: JavaPackager-1.7.2
      WEBSERVICE:
        URL: https://saas-eu.mend.io/
        API: https://api-saas-eu.mend.io/
        AUTHENTICATIONKEYFILE: ../common/mend-auth-keys.yaml
        PAGESIZE: 50
        TIMEOUT: 5
        NR_OF_RETRIES: 10
        RETRY_INTERVAL: 2

JavaPackager-1.7.2:
  VIEWS:
    master:
      TOOLS:
        Mend:
          WEBSERVICE:
            URL: https://saas-eu.mend.io/
            AUTHENTICATIONKEYFILE: mend-auth-keys.yaml
            PAGESIZE: 400
            TIMEOUT: 10
            NR_OF_RETRIES: 3
            RETRY_INTERVAL: 4
          DATASOURCES:
          - APPLICATION: JavaPackager
            PROJECTS:
            - NAME: JavaPackager-1.7.2

Authentication Keys

Three authentication keys are required to fetch data from the Mend SCA server, as shown below:

These three keys are used for authenticating API calls from TICS to the Mend SCA server. There are two ways to provide this authentication token to TICS:

Configuring an authentication key file

One way to configure the Mend SCA authentication token is to add a yaml-formatted authentication key file in the TICS configuration directory. This authentication key file should contain the fields email, orgtoken and userkey followed by relevant values as shown in the example below: 

email: mend.user@foobar.com
orgtoken: 1234abab-1234-5678-a910-123456abc312
userkey: abcd1238143abcd123ba38591a81abcd1232162acbfebabcd123a354fabcd123

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

TOOLS:
  Mend:
    WEBSERVICE:
      URL: https://saas-eu.mend.io
      AUTHENTICATIONKEYFILE: ../common/mend-auth-keys.yaml

Configuring authentication environment variables

Alternatively, the Mend SCA authentication keys can be set up in the environment variables TICS_MEND_EMAIL, TICS_MEND_ORGTOKEN and TICS_MEND_USERKEY as shown in the example below. 

C:\Users\Public>set TICS
TICS_MEND_EMAIL=mend.user@foobar.com
TICS_MEND_ORGTOKEN=1234abab-1234-5678-a910-123456abc312
TICS_MEND_USERKEY=abcd1238143abcd123ba38591a81abcd1232162acbfebabcd123a354fabcd123

If both the AUTHENTICATIONKEYFILE property and the authentication keys environment variables TICS_MEND_EMAIL, TICS_MEND_ORGTOKEN and TICS_MEND_USERKEY are configured, TICS will use the authentication keys configured in the AUTHENTICATIONKEYFILE property.

Mend SCA Fetcher

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

versions:
  checkers:
    mendfetcher:
      artifact: chk/mendfetcher/MendFetcher-0.0.4.zip
The latest version of mendfetcher can be found on our download site inside the codecheckers/mendfetcher folder.

Mend SCA Rulesets

Mend SCA rulesets should be configured in SERVER.yaml for metric SECURITY of each relevant language. Mend SCA rulesets are prefixed with 'MEND_' as shown in the examples below. 

JAVA:
  RULESETS:
  - METRIC: SECURITY
    RULESDIR: 4.0/security/MEND_JAVA
    NAME: Mend Java Security

PYTHON:
  RULESETS:
  - METRIC: SECURITY
    RULESDIR: 4.0/security/MEND_PY
    NAME: Mend Python Security