Configuring Coverity

It is possible to incorporate Coverity results in the TICS output for files.

Prerequisites

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

Basic configuration

To use Coverity one has to set-up the required properties in either the SERVER.yaml to apply them for all projects or in PROJECTS.yaml to apply them project specific. If the properties are declared in the SERVER file and also in the PROJECT the project specific properties will overwrite the global properties.

Syntax

The following properties have to be declared either on SERVER or PROJECT level: 

TOOLS:
  Coverity:
    WEBSERVICE:
      USERNAME: 'Login name'
      PASSWORD:PLAIN: 'Password'
      URL: 'URL of Coverity Web API, for example: https://coverity.tomtomgroup.com:443'
      [AUTHENTICATIONKEYFILE: 'The location of an authentication key generated from Coverity Connect']
      [TIMEOUT: The time a webservice call may take (in seconds) before it is aborted ]
      [NR_OF_RETRIES: The number of retries when the data cannot be fetched because of connection timeout ]
      [CONNECTION_RETRY_TIMEOUT: The time (in seconds) between retries]
  [INSTALLDIR: 'Bin directory of Coverity Analysis']
  [INTERMEDIATEDIR:
    PATH: 'Path to an intermediate directory that is used to store the results of the build and analysis.
           It can be used to speed up the analysis by reusing the intermediate directory that Coverity generates
           (Refer to Coverity documentation for details)'
    [FREQ: The number of days, after the intermediate directory was last created, where TICS should refresh
           the intermediate directory. If not configured, the default value of 30 days will be used, i.e. TICS will refresh
           the intermediate directory if it was created over or equal to 30 days ago.]
  ]
  COVBUILD:
    BUILDCOMMAND:['Native project build commands needed for cov-build']
    EXTRAOPTIONS:['Extra options needed for cov-build; See the Coverity documentation for details']
    USECOMPILATIONDATABASE: 0|1. 'Disable or Enable the use of a compilation database for languages that Coverity 
                            supports (eg. C/C++). If not specified, it is enabled by default for these languages.'
    [TIMEOUT: The time (in seconds) that cov-build is allowed to run before TICS terminates the call]
  [COVANALYZE:
    EXTRAOPTIONS:['Extra options needed for cov-analyze; See the Coverity documentation for details']
    [TIMEOUT: The time (in seconds) that cov-analyze is allowed to run before TICS terminates the call]
  ]
  [COVCOMMIT:
    EXTRAOPTIONS:['Extra options needed for cov-commit; See the Coverity documentation for details.']
    [TIMEOUT: The time (in seconds) that cov-commit-defects is allowed to run before TICS terminates the call]
    [ENABLED: 0|1. Enable or disable the COVCOMMIT step. If not specified, it is enabled by default. 
              If disabled, TICS will skip committing violations found during COVANALYZE to Coverity Connect. 
              When COVCOMMIT is disabled, TICS will not provide Coverity Connect details links for the violations.
              The COVCOMMIT step can be disabled only when TICS is using local results to retrieve violations
              (see property USELOCALRESULTS), or when TICS only fetches violations from Coverity Connect
              without performing COVBUILD and COVANALYZE. Otherwise, TICS will throw a configuration error.
              The expected value for this property is an integer 0|1.]
  ]
  [USELOCALRESULTS: 0|1. Enable or disable the use of local disk for getting violations,
           in place of fetching violations from Coverity Connect. If not specified, it is disabled by default.
           If enabled, TICS will get violations from the intermediate directory.
           Therefore, if this property is enabled, BUILDCOMMAND needs to be configured in order to generate
           the intermediate directory. Otherwise, TICS will throw a configuration error.
           The expected value for this property is an integer 0|1.]
  [LICENSE:
    SECURITY:0|1 #Whether your Coverity license includes security analysis.
    FILE: 'Path of a Coverity Analysis license file, relative to the default folder of the TICS
           configuration directory, i.e. ticsfs/cfg/default/. For example: ../common/Coverity/license.dat.
           If not configured, TICS will look for a Coverity Analysis license file in the bin directory of
           the relevant Coverity installation folder.'
  ]
  [SHOWEXTTRACE:Shows or hides external trace information link ]

The following properties have to be applied on PROJECT level: 

VIEWS:
  branch name:
    TOOLS:
      Coverity:
        DATASOURCES : [
          [
          PROJECT: 'Project name in Coverity'
          [BRANCHDIR: ['Strip path used to commit results to Coverity, if it is different from TICS Branchdir']]
          [STREAMS: ['Stream names in Coverity']],
          [TRIAGESTORE: 'Triage store name in Coverity']
          ]+
        ]
        [DYNAMICPROJECTCREATION: 'Enables or disables dynamic Coverity project creation']

Example for DATASOURCES:

TICS needs the Coverity project/stream names to be configured to commit and fetch results. Multiple projects and streams can be configured as follows: 

VIEWS:
  master:
    TOOLS:
      Coverity:
        DATASOURCES:
          - PROJECT:'Maps QA'
            STREAMS:
              - NAME: 'Stream1'
              - NAME: 'Stream2'
          - PROJECT:'Maps QA2'
            STREAMS:
              - NAME: 'Stream3'
        COVBUILD:
          BUILDCOMMAND: ['gradlew']
          EXTRAOPTIONS: ['--instrument']
          TIMEOUT:3600

When BUILDCOMMAND is configured, since TICS is responsible for committing and fetching analysis results to Coverity Connect, only one Project/Stream should be configured.

Example for BRANCHDIR:

This section will give a more detailed explanation to clarify how to define the BRANCHDIR property and why it is needed. The screenshot below shows an actual live set-up where the BRANCHDIR is needed to get TICS to work with Coverity. Now for TICS to work with Coverity it is needed to translate the relative path of TICS to the absolute path of Coverity. As seen on the screenshot below the project name of the Coverity project is Maps QA. The prefix that is needed to translate the path is highlighted in the Coverity path (first green box).

image

The situation above requires the following set-up of properties: 

VIEWS:
  master:
    TOOLS:
      Coverity:
        PROJECT:'Maps QA'
        BRANCHDIR:'/opt/jenkins/workspace/DARTS-Coverity/'

Example for BUILDCOMMAND and LICENSE:

A project can also be configured with BUILDCOMMAND, Cov-build timeout and LICENSE as follows: 

VIEWS:
  master:
    TOOLS:
      Coverity:
        DATASOURCES:
          - PROJECT:'Maps QA'
            BRANCHDIR:'/opt/jenkins/workspace/DARTS-Coverity/'
        COVBUILD:
          BUILDCOMMAND:['gradlew']
          EXTRAOPTIONS:['--instrument']
          TIMEOUT:3600
        LICENSE:
          SECURITY:1
          FILE: '../common/path/to/license.dat'

AUTHENTICATIONKEYFILE:

A Coverity authentication key file can be used instead of a username and password by configuring the location of the file with AUTHENTICATIONKEYFILE in the SERVER.yaml/PROJECTS.yaml as follows: 

  TOOLS:
    Coverity:
      WEBSERVICE:
        URL:'localhost:8080'
        AUTHENTICATIONKEYFILE:'/path/to/coverity-auth-key.txt'

Alternatively, an authentication key file named coverity-auth-key.txt can be added in the TICS configuration directory. In that case, it is not necessary to configure the AUTHENTICATIONKEYFILE property, since TICS will find it automatically. It is also possible to add a file with a custom name in the TICS configuration directory and configure the relative path as: 

  TOOLS:
    Coverity:
      WEBSERVICE:
        URL:'localhost:8080'
        AUTHENTICATIONKEYFILE:'./custom-auth-key.txt'

Note

An authentication key file can be generated from Coverity Connect:

image

DYNAMICPROJECTCREATION:

By default, if the configured Coverity Connect project and stream do not exist, TICS will create them. This feature can be disabled via the configuration option DYNAMICPROJECTCREATION. 

  TOOLS:
    Coverity:
      DATASOURCES:
        - PROJECT:'project_name'
          STREAMS:
            - NAME: 'stream_name'
      DYNAMICPROJECTCREATION:0

SHOWEXTTRACE:

By default, the violation trace from Coverity Connect is shown in the TICS annotations. This feature can be disabled by setting the configuration option SHOWEXTTRACE to 0. 

  TOOLS:
    Coverity:
      SHOWEXTTRACE:0

Running Coverity analysis without Coverity Connect:

TICS now can analyse metrics that uses Coverity, e.g. Abstract Interpretation and Security, without any access to Coverity Connect. TICS will retrieve the results from the local intermediate directory that stores the Coverity analysis results locally. And TICS can be made to disable committing these local results to Coverity Connect. TICS can be configured so that it does not need any access to Coverity Connect. This way, TICS does not need to configure properties for Coverity Connect such as WEBSERVICE and DATASOURCES. In order to do this, set the property USELOCALRESULTS to 1 and COVCOMMIT => ENABLED to 0 as shown in the example below. Note that the property COVBUILD => BUILDCOMMAND must be specified if we enable USELOCALRESULTS. This is because Coverity needs to build and analyze the project to generate the results in the local intermediate directory. 

  TOOLS:
    Coverity:
      COVBUILD:
        BUILDCOMMAND:
          - 'C:/ProgramFiles/MicrosoftVisualStudio/2022/Professional/MSBuild/Current/Bin/MSBuild.exe
            /t:rebuild D:/Development/dev_test/projects/mbedtls-2.16.11/visualc/VS2010/mbedTLS.sln'
      COVCOMMIT:
        ENABLED: 0
      USELOCALRESULTS : 1
      INSTALLDIR: C:/ProgramFiles/Coverity/CoverityStaticAnalysis
      INTERMEDIATEDIR:
        PATH: D:\Development\dev_test\Coverity\idir\mbedtls