CodeSonar-GitHub Integration

NOTICE: A private GitHub repository with a GitHub Enterprise license is required for this CodeSonar integration.

GitHub provides a Continuous Integration (CI) and Continuous Delivery (CD) solution with the GitHub Actions feature. CodeSonar can be used within a GitHub Action workflow to automatically scan and analyze the source code in your GitHub repository.

This CodeSonar-GitHub integration package provides tools and examples to help you configure CodeSonar to analyze your code and report results to your GitHub repository web location.

Contents

• Prerequisites
• GitHub Advanced Security Code Scanning
• Overview: Continuous Integration Workflow Setup
  • Links to pages with detailed, system-specific instructions
• Setting Up
  • A. Create and install an analysis data server
  • B. Create a basic workflow that can build your code
  • C. Install CodeSonar and integration tools in the build runner environment
  • D. Update the workflow definition to perform CodeSonar analysis
• Further Information

Prerequisites

• GitHub Enterprise account with Advanced Security enabled.

• Access to a licensed CodeSonar hub.

• A CodeSonar hub user account to be used in automated workflow jobs.

• A mechanism for preserving your analysis files after the workflow has finished: one of the following.

  • You are using CodeSonar SaaS.
  • Your hub already has one or more associated remote analysis launch daemons that you can use to perform remote-managed analyses.
  • You have available resources to set up an Analysis Data Server to manage the files.

• CodeSonar software installation package.

• CodeSonar-GitHub integration tools package.

  These instructions are designed for CodeSonar 7.3 or later. With some modifications, they can also be used with CodeSonar 7.1 and 7.2.

• Familiarity with Git, GitHub, YAML, and shell programming (bash, powershell, etc.).

• A Developer workstation where you can check out and modify code using the Git command line.

• A private GitHub repository containing a code project to analyze.

• If you are using Docker on a Linux-based GitHub runner, you will also need access to a Docker Registry where you can store Docker images containing CodeSonar software.

IMPORTANT: A private GitHub repository with a GitHub Enterprise license is required. Limitations imposed by the CodeSonar End User License Agreement (EULA) prohibit the use of CodeSonar for Code scanning on a public GitHub repository. Code scanning on a private GitHub repository requires a GitHub Enterprise license. A "self-hosted" GitHub runner will be needed in order to build code and communicate analysis results to your CodeSonar hub.

You will need to prepare one or more GitHub workflow runner hosts.

• A host that will run the CodeSonar build/analysis.

  If you already have a runner host that can compile your code, you can add CodeSonar to it. Otherwise, you will need to create a new runner host for this purpose.

• A host that will arrange for analysis file management after the workflow has completed.

  If you are running 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.

  Otherwise, you will need to set up an Analysis Data Server host to store large analysis artifacts from your workflow jobs and share them with the CodeSonar hub.

GitHub Advanced Security Code Scanning

GitHub provides an Advanced Security Code scanning feature for reporting and managing code analysis results associated with a GitHub repository. Typically a code scan is configured to be done when new code is submitted to a GitHub Pull Request. Results of the CodeSonar analysis associated with a GitHub Pull Request can be viewed under the Pull Request "Checks" tab.

GitHub provides an upload-sarif workflow Action which allows code analysis results in SARIF format to be reported to GitHub. Since CodeSonar can generate a SARIF representation of your code analysis, you can use CodeSonar in a GitHub workflow to perform an automatic code scan.

Overview: Continuous Integration Workflow Setup

There are many benefits to setting up a continuous integration (CI) workflow using a GitHub Actions workflow. However, the set-up 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 workflow and managing the code analysis data produced when the workflow is executed.

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

• A. Create and install an analysis data server
• B. Create a basic workflow that can build your code
• C. Install CodeSonar and integration tools in the build runner environment
• D. Update the workflow definition to perform CodeSonar analysis

The remaining sections in this document outline the steps above.

For detailed, system-specific instructions, see the linked pages:

• Analysis data server: Linux and Docker | Linux | Windows
• Workflow configuration: Linux and Docker | Linux | Windows

A. Create and install an analysis data server

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 B. Create a basic workflow 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 workflow consists of several jobs, each of which generates artifacts and transfers them to subsequent jobs upon completion. Artifacts that are not transferred will be deleted by the workflow job runner process. The CodeSonar analysis data created in a workflow must therefore be transferred to a persistent storage location outside the runner environment so that they will remain available after the workflow runs.

• CodeSonar 7.1 and later provide the -remote option for CodeSonar analysis. With this option, you can specify a launch daemon outside the runner environment to perform remote-managed analysis. The analysis directory is automatically transferred to a location under the launch daemon home directory at the start of the analysis phase.
• CodeSonar 7.3 and later also provide the remote-archive option for CodeSonar analysis. With this option you can specify a launch daemon to manage the analysis directory once the analysis has transitioned to daemon mode, and the analysis directory is automatically transferred at that stage.
• For more information, see the CodeSonar manual: How CodeSonar Works > CodeSonar Structure > Analysis > Analysis

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

• The analysis data server must have enough storage space to accommodate the analysis data produced by the execution of many workflows.
• The analysis data server must run a CodeSonar launch daemon ("launchd") process so that the analysis data can be shared with your hub. Therefore:
  • You must install CodeSonar on the analysis data server.
  • You must run a CodeSonar launch daemon process there, using -launchd-home <hdir> to specify a suitable home directory <hdir> under which the launch daemon will store the various analysis directories for your analyses.

Alternative: relocating analysis data server

If you are using CodeSonar 7.2 or earlier, you will need to extend your workflow to explicitly relocate the analysis directory to your analysis data server.

1. Copy the analysis directory and all its contents to your analysis data server.
2. Use the codesonar relocate command to inform the hub of the new analysis directory location.

For details, see the Tips and Troubleshooting page.

B. Create a basic workflow that can build your code

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

• A GitHub repository project containing the source code that you want to analyze.
• A GitHub workflow job definition file (e.g. .github/workflows/build.yaml) which includes instructions for building your code.
• A GitHub workflow job runner environment which contains all of the necessary build tools and compilers required to build your code.

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

• For instructions on how to set up a new GitHub workflow, see https://docs.github.com/en/actions/learn-github-actions.
• If you already have a working build workflow, you do not need to create another one: you can add CodeSonar to the existing workflow at step D.

In practice, it is generally necessary to prepare a "self-hosted" GitHub runner that can build your code. This will allow CodeSonar analysis results to be communicated securely to a private CodeSonar hub.

• For information about self-hosted GitHub runners, see https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners.

C. Install CodeSonar and integration tools in the build runner environment

In order to initiate the CodeSonar analysis, you must install CodeSonar in your GitHub 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 items to your GitHub build runner environment

• CodeSonar.
• The CodeSonar-GitHub integration package.

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

D. Update the workflow definition to perform CodeSonar 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.

• C and C++: CodeSonar observes the compiler invocations in your regular software build.

  You must therefore build the CodeSonar project in the same job as your regular software build.

• Java and C#: CodeSonar collects the source code and compiled object files ("binaries": JARs, DLLs, etc.) after your regular software build has taken place: it does not need to observe the build directly.

  You can build the CodeSonar project in the same job as your regular software build, but this is not required: it is sufficient for CodeSonar to have access to the source code and binaries produced by the build.

• If your software project contains multiple programming languages, build the CodeSonar project in the same job as your regular software build.

To modify the GitHub workflow job you identified in step B so that it also builds and analyzes a CodeSonar project based on your code, do the following.

1. Add zero or more codesonar build commands, plus a final codesonar analyze command.

   For full details of the CodeSonar build/analysis command line, see the CodeSonar manual: Using CodeSonar > Building and Analyzing Projects > Command Line Build/Analysis

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

   • Authentication credentials for a hub user account that can authorize the analysis. With factory settings, it is sufficient for the account to have the built-in User role. (See Authentication Notes, below.)

   • For CodeSonar SaaS, your codesonar analyze command must include -wait and -remote "./saas/*". It must not include -foregound.

   • For non-SaaS CodeSonar, your codesonar analyze command must do one of the following.

     • Specify -wait and -remote <analysis-launchd>, where <analysis-launchd> is a suitable remote analysis launch daemon: either one you set up on your analysis data server host, or one that existed previously. <analysis-launchd> will manage both the analysis of your project and the hub interaction with analysis files when the analysis has completed. The command must not include -foregound.

       • Specify -wait and -remote-archive <archive-launchd>, where <archive-launchd> is a suitable remote analysis launch daemon: either one you set up on your set up on your analysis data server host, or one that existed previously. The analysis files will be transferred to <archive-launchd> after the analysis completes, and will manage all subsequent hub interaction with analysis files. The command must not include -foregound.

       If you are using CodeSonar 7.2 or earlier, -remote-archive is not available. See the Tips and Troubleshooting page for further options.

   • You may wish to specify -name <analysis-name> to provide a custom analysis name: for example, to relate the analysis to a specific GitHub pull request record.

Execute the workflow

The typical way to trigger a workflow is by pushing new code commits to a GitHub pull request. After a successful analysis in the workflow, you can view your analysis results in GitHub 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.

Authentication Notes

These instructions discuss two options for authenticating a codesonar command line: certificate and password.

• -auth certificate -hubcert <certfile> -hubkey <privkeyfile>

  Presents the certificate in <certfile> to the hub, using the private key stored in <privkeyfile> to sign its response to the hub's challenge. The authenticated hub user will be the one whose username matches the Subject Common Name specified in the certificate.

• -auth password -hubuser <user-name> -hubpwfile <pwfilename>

  Authenticates hub user <user-name> using the password stored in <pwfilename>.

You can use GitHub Secrets to provide credentials for authentication.

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

Bearer Authentication

From CodeSonar 8.0 you also have the option of bearer authentication.

• -auth bearer -hubbearerfile <bearerfile>

  Presents the bearer token in <bearerfile> to the hub for authentication. The authenticated hub user will be the Session User associated with the corresponding session.

For more information about sessions and bearer token authentication, see the CodeSonar manual: How CodeSonar Works > CodeSonar Structure > Hub > User Session and Anonymous Sessions

Other Notes

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

• sarif_summary.py

  Converts analysis results from the SARIF format retrieved by codesonar get into a format suitable for upload to GitHub. It also generates a summary report of warning results and evaluates warning results to conditionally trigger a workflow failure.

• push_github_pr_comment.py

  Posts a summary of warning results to your Pull Request conversation.

Further Information

See the Tips and Troubleshooting document for additional information.

---