CodeSonar GitLab CI/CD Integration

NOTICE: An internal or private access GitLab repository is required for this CodeSonar integration.

The CodeSonar GitLab Integration package provides tools, examples, and documentation to help you add CodeSonar to your GitLab Continuous Integration (CI) pipelines. Using CodeSonar in your GitLab pipelines will allow you to automatically analyze code changes when they are pushed to your GitLab project. Basic analysis results can be viewed directly in GitLab. Detailed analysis results can be viewed in the CodeSonar hub.

Prerequisites

IMPORTANT: An internal or private access GitLab repository is required. Limitations imposed by the CodeSonar End User License Agreement (EULA) prohibit the use of CodeSonar for code analysis on a public repository.

You will need to prepare one or more GitLab pipeline job runner hosts.

GitLab Static Analysis features (Ultimate Edition)

GitLab provides several Static Application Security Testing (SAST) features, including a "security report" which can display the results of a CodeSonar analysis in GitLab. The GitLab SAST features are only available in GitLab Ultimate edition. If you do not have GitLab Ultimate edition, then you will not have access to the security report in GitLab and you may need to adjust your pipeline job definitions so that they do not make use of the advanced SAST features.

Security scan report (Ultimate Edition)

A GitLab security scan report is available for each merge request. When you perform a static analysis in a GitLab pipeline associated with a merge request, the results of the analysis are uploaded as a pipeline "artifact" and are presented in a security scan report web page. After a successful pipeline analysis, you can find a link to "View full report" near the top of your merge request page. Since a security scan report is associated with each pipeline you run, you can also find a link to the report in the "Security" tab of each pipeline page.

The report shows a list of all results found by the analysis. Clicking on a result item will show a popup containing item details.

Security scan results

Project Security dashboard (Ultimate Edition)

GitLab provides a "Security Dashboard" and a "Vulnerability Report" that can display aggregate security scan information for your repository project's default branch. The security dashboard provides information about vulnerabilities found in your project over time. The vulnerability report is similar to a merge request security scan report, but it is intended to apply to your project as a whole.

This document will not describe how to configure the GitLab security dashboard or the project vulnerability report, however, make note of the following.

GitLab provides some documentation for using custom scanners with the security dashboard: https://docs.gitlab.com/ee/user/application_security/sast/#customizing-the-sast-settings.

Pipeline Setup

There are many benefits to setting up a continuous integration (CI) pipeline. However, the setup process can be complicated for a variety of reasons. The information below is intended to help you navigate the complexities of introducing CodeSonar static analysis into a pipeline and managing the code analysis data produced when the pipeline is executed.

Detailed instructions for preparing a pipeline for analysis with CodeSonar 7.3 or later are provided in the following platform-specific documents:

More instruction document links are provided further below.

The remaining sections of this document provide a platform-neutral summary of the pipeline configuration steps.

General pipeline configuration procedure

The following general steps are required for preparing a pipeline for CodeSonar analysis:

  1. Create and install an analysis data server host.
  2. Create a basic pipeline that can build your code.
  3. Install CodeSonar and integration tools in build runner environment.
  4. Update pipeline job definition to perform CodeSonar analysis.

Several systems and services will be involved, including:

The following diagram depicts the typical relationships between these systems and services.

CodeSonar GitLab Services Diagram

1. Create and install an analysis data server host

If you are using CodeSonar SaaS, or if your CodeSonar hub is already set up with remote analysis launch daemons for use with -remote and -remote-archive, you can use your existing infrastructure and do not need to set up a separate host: go on to 2. Create a basic pipeline that can build your code.

A CodeSonar analysis produces several analysis data artifacts which contain information about the source code as it was interpreted by your compilers. The analysis data artifacts are created on the host machine that does the analysis, and can be quite large. The CodeSonar hub needs access to the analysis data artifacts in order to enable many advanced features of code navigation, etc.

A typical pipeline consists of several jobs, each of which generates artifacts and transfers them to subsequent jobs upon completion. Artifacts that are not transfered will be deleted by the pipeline job runner process. The CodeSonar analysis data created in a pipeline job must therefore be transferred (i.e. "relocated") to a persistent storage location outside the pipeline runner environment so that they will remain available after the pipeline runs.

We will refer to the host system for the analysis data persistent storage as an "analysis data server".

2. Create a basic pipeline that can build your code

In order to analyze your code using CodeSonar in a GitLab pipeline, you must first create a working pipeline that can compile and build your code. This requires the following.

If you do not already have a working build pipeline, you must create one specific to your code before introducing CodeSonar.

3. Install CodeSonar and integration tools in build runner environment

In order to initiate the CodeSonar analysis, you must install CodeSonar in your GitLab runner environment. For Docker-based runners, this involves adding CodeSonar to the Docker image used when building your code. Without Docker, this involves installing CodeSonar on the runner host itself.

Install the following in your GitLab build runner environment

CodeSonar and the integration tools may not automatically trust the HTTPS certificates provided by your hub or your GitLab server. You may need to take steps to ensure that the CodeSonar installation in your runner environment will trust the certificates: see the Troubleshooting section for details.

4. Update pipeline job definition to perform CodeSonar analysis

You will need to modify your GitLab pipeline job definition to integrate the CodeSonar build/analysis.

CodeSonar works by creating an internal representation (IR) of your software, then performing a suite of analyses on that representation. The IR creation stage works differently for different source languages:

Modify the GitLab pipeline job you identified in step 2 so that it also builds and analyzes a CodeSonar project based on your code.

You will do this by adding zero or more codesonar build commands, plus a final codesonar analyze command. For full details of the CodeSonar build/analysis command line, see the manual: Using CodeSonar > Building and Analyzing Projects > Command Line Build/Analysis

Make sure your codesonar build and codesonar analyze commands account for the following.

Authentication Notes

There are two main options for authenticating a codesonar command line.

You can use GitLab "CI/CD Variables" to provide credentials for authentication. CI/CD Variables can be created and updated on the GitLab project CI/CD Settings page.

For more information about authentication in CodeSonar, see the manual: How CodeSonar Works > CodeSonar Structure > Hub > Authentication and Access Control

Other Notes

The CodeSonar GitLab integration package includes a few script programs which are used to process analysis results and share the results with GitLab. These scripts must be executed using the cspython Python interpreter included with CodeSonar.

Execute the pipeline

The typical way to trigger a pipeline is by pushing new code commits to a GitLab merge request. After a successful analysis in the pipeline, you can view your analysis results in GitLab and on the CodeSonar hub. This allows you to automatically scan for newly introduced issues in your code and to verify that known issues have been fixed.

Note for CodeSonar 7.2 and earlier

The -remote-archive option was introduced in CodeSonar 7.3. If you are using an earlier CodeSonar version, or if you do not want to use -remote-archive, you will need to do one of the following.

Further Information