CodeSonar GitLab Integration: Tips and Troubleshooting

• Trusted HTTPS GitLab Server Certificate
• Trusted HTTPS CodeSonar Hub Server Certificate
• Download an HTTPS certificate in Base-64 ASCII (PEM) format
• Warnings for files outside your repository
• Hub Code Navigation needs a Launch Daemon
• Hub Message Says to Run codesonar install-launchd
• Vulnerability severity categories

Trusted HTTPS GitLab Server Certificate

The CodeSonar GitLab Integration tools will attempt to post a summary report of the analysis to your merge request. If the CodeSonar cspython does not trust your GitLab server's HTTPS certificate you will see an "SSL" error in your pipeline job log. You can optionally provide a custom ASCII-encoded certificate authority (CA) file to the upload_gitlab_mr_notes.py script using the --cafile option. The CA file should include the root certificate of the certificate authority signing chain for your GitLab HTTPS certificate.

Additional tips for how to download the certificate file are provided further below.

The path to the certificate file must be specified in the YAML configuration file. The path must exist on the runner. An easy way to ensure that the path exists is to add the certificate to your Git repository and refer to it using a relative path.

Example YAML configuration:

  ...
  after_script:
    - >
        cspython $SARIF2SAST/upload_gitlab_mr_notes.py
        --api-token-variable GITLAB_TOKEN
        --report sast-summary-report.md
        --cafile path/to/your/gitlab_certificate.pem

[HTTPS hubs only] Trusted HTTPS CodeSonar Hub Server Certificate

The codesonar command (and analysis tools) on a runner machine may not automatically trust the CodeSonar hub for the analysis. A CodeSonar hub will be trusted if its hub server certificate is signed by a certificate authority known to the CodeSonar analysis tools.

Like a typical web browser, CodeSonar comes with a default set of known, trusted certificate authorities. If the CodeSonar analysis tools do not trust your hub, you have several options for registering the hub server certificate: - Option 1: Run a CodeSonar command interactively, then verify the hub's certificate when prompted. - Option 2: Modify CodeSonar's list of trusted certificate authorities to include the root signing certificate for your hub.

Option 1: Run a CodeSonar command interactively, then verify the hub's certificate when prompted.

1. Run the following command, where https://<host>:<port> is the hub location.

   codesonar get -o - https://<host>:<port>/index.csv
   

   This command retrieves the list of root-level projects on the hub in CSV format. You can run a different codesonar command if you prefer: the important thing is to trigger the certificate interaction.

2. If the CodeSonar client does not currently trust the hub certificate, it will prompt you with a range of options. To trust the hub certificate for subsequent codesonar commands in the current environment, enter T.

When trust is established and saved this way, it is saved in user settings; it will not affect other operating users on the same system.

Option 2: Modify CodeSonar's list of trusted certificate authorities to include the root signing certificate for your hub.

Use this approach if the interactive method is not feasible, or if trust must be established for all OS users.

1. Obtain your hub's root signing certificate in Base-64 ASCII ("PEM") format. (See download instructions below.)
   • If your hub uses a self-signed certificate, then your hub's HTTPS server certificate is also the root signing certificate.
   • If your hub's certificate is not self-signed, then you will need a PEM file containing only the first certificate in the certificate signing chain. Most web browsers will let you download individual signing certificates in PEM format.
2. Append this certificate to the gtr/cacerts.pem file in the CodeSonar installation directory.

Download an HTTPS certificate in Base-64 ASCII (PEM) format

Depending on your configuration, you may need to download and subsequently present an HTTPS certificate for one or both of the following. - Your GitLab server. - Your CodeSonar hub (the hub server certificate). This applies to HTTPS hubs only: HTTP hubs do not have a hub server certificate.

You can download this certificate from the hub's Configure HTTPS page: Settings -> HTTP -> Configure HTTPS.

For more information about certificates in CodeSonar, see the CodeSonar manual: How CodeSonar Works > CodeSonar Structure> Hub > TLS Certificates.

In both cases you will need to present the certificate as a Base-64 ASCII ("PEM") file

If you cannot copy the certificate directly from the server, then you can download it over the network. A certificate does not need to be verified or trusted in order to download it over an SSL/TLS channel, however you should verify it if you have the means to do so.

For the purpose of HTTPS verification by a client (e.g. codesonar or cspython), it is often preferred to provide only the top (root) certificate in the certificate chain, but the entire chain will usually be sufficient (if you have the means to download it). In general, the bottom ("leaf") certificate in the certificate chain will not work. For self-signed certificates, there is only one certificate in the chain, but in other cases there may be more.

You can download an HTTPS certificate from your browser or by using the OpenSSL command line.

• From your browser. Most browsers provide a way to download an HTTPS certificate in ASCII format. The instructions for downloading the certificate are dependent on both the type of browser and the operating system.

  • Using Google Chrome on Linux, you can "Export" the top certificate in the "Certificate Hierarchy" in "Base64-encoded ASCII, single certificate" format.
  • Using Google Chrome on Windows, you can "View" the top certificate in the "Certificate Path", and "Copy to File" using "Base-64 encoded X.509 (.CER)" format.
  • Firefox provides a custom certificate view which allows the entire certificate chain to be downloaded in ASCII ("PEM") format.

• Using the OpenSSL command line. You can use the OpenSSL command line to download the bottom (leaf) certificate. This should be sufficient for self-signed certificates. It may also work in other cases, depending on the client.

  For example:

  openssl s_client -connect $HOST:443 -showcerts | openssl x509 -outform PEM -out $CAFILE
  

  where $HOST is the name of your HTTPS server host (e.g. codesonar.example.com) and $CAFILE is the name of the file where you want to save the certificate.

  OpenSSL may already be installed on your operating system. CodeSonar also includes a copy in its third-party/openssl/inst/bin subdirectory.

Warnings for files outside your repository

If your software build uses files that are not in your repository, the sarif2sast converter will produce warnings that show up in your GitLab pipeline job log.

• If these are user code files represent user code that you forgot to add to the repository, add them to resolve the warnings

• If they are system headers, adjust the setting of CodeSonar configuration variable SYSTEM_INCLUDE_PATHS to account for them.

  1. If your repository does not already include a CodeSonar configuration file for the project, create one now and add it to version control.

     cd <builddir>
     codesonar create-conf <projname>
     git add <projname>.conf
     

     where
     • <builddir> is the directory from which you issue the codesonar analyze command.
     • <projname> is the name of your CodeSonar project: if you have set up your pipeline as described in the examples linked from README.md, this will match the value of the GitLab CI_PROJECT_NAME variable.
     • you will need to give the full path to the codesonar executable if it is not in your PATH.
  2. Open <projname>.conf for editing.

  3. Add one or more SYSTEM_INCLUDE_PATHS rules to specify the locations of your system headers.

     You will see that the in-file documentation for the SYSTEM_INCLUDE_PATHS parameter includes a number of commented-out rules. You can use these as examples to construct your own rules (but make sure your rules aren't commented out with #).

     (Note that you don't need to uncomment the example rules if you aren't modifying them: the general template configuration file contains the same rules in uncommented form and is included in every analysis. You can view the general template configuration file at $CSONAR/codesonar/template.conf, where $CSONAR is your CodeSonar installation directory.)

  For more information, see the CodeSonar manual.

  • General information about configuration files: Using CodeSonar > Building and Analyzing a CodeSonar Project > Options, Preferences, and Configuration Files > Configuration Files
  • Parameter index (listing SYSTEM_INCLUDE_PATHS and many other parameters): Using CodeSonar > Building and Analyzing a CodeSonar Project > Options, Preferences, and Configuration Files > Compiler-Independent Configuration File Parameter Index for CodeSonar

Hub Message Says to Run codesonar install-launchd

You may see an error like the following in the CodeSonar GUI when you try to view certain information.

Please execute
/opt/codesonar/codesonar/bin/codesonar install-launchd codesonar.example.com:7341 -hubuser "gitlab_ci"
on runner-dymnpbks-project-42-concurrent-0 as the OS user root and try again.

The requested information is stored on the computer that ran the analysis (runner-dymnpbks-project-42-concurrent-0).
...

This occurs if the requested information resides in the project analysis directory (<prjname>.prj_files/), but the hub cannot communicate with a launch daemon managing that directory.

This generally indicates one of the following.

• The project analysis directory has been removed.
• The project analysis directory still exists, but its managing launch daemon is not running.

If the project analysis directory has been removed

Once CodeSonar has finished analyzing your project, it transitions to daemon mode to service any requests from the hub for information stored in the project analysis directory (<prjname>.prj_files/). This information includes source file listings and procedure-granularity metrics. It does not include analysis results such as warning reports, which are stored directly on the hub.

If you are running the CodeSonar analysis in a GitLab pipeline, the location of the project analysis directory will depend on whether or not your codesonar analyze command includes the -remote or -remote-archive option.

Option	Behavior
-remote <analysis-launchd>	Data and control for the CodeSonar analysis phase are managed remotely by <analysis-launchd>, which retains control when the analysis transitions to daemon mode (unless -remote-archive is also specified). Introduced in CodeSonar 7.1.
-remote-archive <archive-launchd>	The CodeSonar analysis phase is performed locally, but the analysis data and control are transferred to a remote <archive-launchd> when the analysis transitions to daemon mode. Introduced in CodeSonar 7.3.
neither	The CodeSonar analysis phase is performed locally; data and control remain local when the analysis transitions to daemon mode.

The instructions linked from README.md describe how to set up a pipeline that uses codesonar analyze with -remote-archive (or -remote) so that there is a copy of the project analysis directory in a persistent location when the analysis phase finishes. - It is still possible to explicitly delete the project analysis directory, either using standard system tools or via the CodeSonar GUI. For best results, only delete project analysis directories when you are sure you are no longer interested in their contents.

If you don't use either of these options, the project analysis directory will be cleaned up along with all other data from the pipeline job when the job finishes. If you are currently in this situation, you will need to adjust your pipeline to make sure the data is stored in a persistent location.

• For CodeSonar 7.3 and later:

  1. Set up an analysis data server with a CodeSonar launch daemon <ld> that can manage your project analysis directories remotely.

     Setup instructions: Linux (no Docker) | Linux with Docker | Microsoft Windows

  2. Adjust your codesonar analyze command to add -remote-archive <ld>.

• For CodeSonar 7.2 and earlier:

  1. Set up a relocating analysis data server.

     Setup instructions: Linux (no Docker) | Linux with Docker | Microsoft Windows

  2. Set up an additional pipeline job to move the project analysis directory to this analysis data server after analysis is complete, then register the new directory location using the codesonar relocate command.

     There are several options for copying the analysis data files from the analysis runner working directory, including docker volume bind mounts, scp/rsync, or the pipeline's artifact mechanism. To use pipeline artifacts, you can upload an archive containing the analysis files using job keyword artifacts:paths, and you can download the artifacts in a subsequent job using keyword needs:artifacts. You will need to ensure artifacts expire quickly so that they do not take up too much space on your GitLab server. The analysis files should be copied into a unique directory, perhaps named using your pipeline's ID number, available in the CI_PIPELINE_ID predefined variable.

     If a suitable launch daemon for managing the project analysis directory is not already running, the codesonar relocate command will start one. For more information this command, see the CodeSonar manual: Using CodeSonar -> Typical CodeSonar Tasks -> Analysis Tasks -> Relocate Analysis Files.

If the project analysis directory still exists, but its managing launch daemon is not running

This can occur in the following cases.

• Your pipeline copies the project analysis directory to a new location but does not register this new location with the hub.

  To fix this, have your pipeline job invoke codesonar relocate to inform the hub of the new location. For details, see the CodeSonar manual:

  Using CodeSonar > Typical CodeSonar Tasks >Analysis Tasks > Relocate Analysis Files

• There was a managing launch daemon for the project analysis directory, but it stopped running. For example, perhaps the launch daemon did not restart when the system restarted.

  • To address the immediate issue, run codesonar install-launchd on the machine that contains the project analysis directory. Use the same command options that you used when you set up the launch daemon.
  • To avoid future occurrences, make sure your pipeline is configured to restart your launch daemon when the system restarts.

Vulnerability severity categories

GitLab displays a "severity" category associated with each result of a security scan. CodeSonar analysis results are assigned a category based the Score of each CodeSonar warning.

CodeSonar Score	GitLab Severity
0 - 20	Low
21 - 55	Medium
56 - 100	High

---