CodeSonar-GitHub Integration: Tips and Troubleshooting

Trusted HTTPS GitHub Server Certificate

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

Additional tips for downloading an HTTPS certificate file are provided 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:

  ...
      - name: Push Summary Report
        if: ${{ github.event.pull_request }}
        run: >
          "$CSPYTHON" "$CODESONAR_GITHUB/sarif_summary.py"
          warnings.sarif
          "$CODESONAR_HUB_URL"
          "$CODESONAR_PROJECT_FILE"
          | "$CSPYTHON" "$CODESONAR_GITHUB/push_github_pr_comment.py"
          --api-url "$GITHUB_API_URL"
          --cafile "$GITHUB_CAFILE"
          "$GITHUB_REPOSITORY"
          "$PULL_REQUEST_ID"
          GITHUB_TOKEN

[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.

  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 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. Additional tips for downloading an HTTPS certificate file are provided 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.

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.

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 "github_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.

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 GitHub workflow, 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 the overview document describe how to set up a workflow 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.

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

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

    Setup instructions:

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

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

This can occur in the following cases.

Vulnerability severity categories and risk levels

The GitHub code scanning result produced for each CodeSonar warning report is assigned a severity, which is based on the CodeSonar warning class Significance as shown in the following table.

CodeSonar Significance Severity
security Error
reliability Error
redundancy Warning
style Warning
diagnostic Warning

For more about CodeSonar warning class Significance, see the CodeSonar manual: Using CodeSonar > Bugs, Weaknesses and Warnings > Warning Class Significance

The GitHub summary report produced by this integration also includes a table summarizing the scanning results by risk level, which is based on the CodeSonar warning Score as shown the following table.

CodeSonar Score Risk Level
0 - 20 Low
21 - 55 Medium
56 - 100 High

For more about CodeSonar warning Score, see the CodeSonar manual: How CodeSonar Works > CodeSonar Structure > Warning > Warnings: Instances and Groups

Warnings for files outside your repository

If your software build uses files that are not in your repository, the sarif_summary converter will produce warnings that show up in your GitHub workflow job log.

Self-hosted Runner using Docker on Linux

If your GitHub runner is self-hosted on Linux, then you must install the GitHub runner software on the host operating system in order to run GitHub workflow jobs inside a Docker container. The GitHub runner process cannot both run inside a Docker container and also execute Docker-based workflow jobs. GitHub may add support for this in the future.

GitHub Actions error: "Workflow runs completed with no jobs"

Double-check that the branch names specified in the workflow on:pull_request and on:push keywords indeed contain the target branch of your Pull Request (or push). Typical default branch names for Git are main and master.

Notes 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.