Using CodeSonar With Continuous Integration Tools

• Tool-Specific Notes
• Typical Setup
• Running a launch daemon
• Running CodeSonar in Docker
• codesonar_citool.py

Tool-Specific Notes

Typical Setup

In many cases, using CodeSonar with a continuous integration tool entails the following three steps.

• Make sure there is a CodeSonar launch daemon running on the analysis machine, with the same owner as the continuous integration tool process.
  • If the analysis machine is running Windows, check to see whether there is a cslaunchd service on the analysis machine, with the same owner as the continuous integration tool process. If not, set one up.
  • Otherwise, arrange to start the launch daemon at system startup.
• Set up the continuous integration tool to run a CodeSonar build/analysis based on the regular project build command.
  The codesonar command must include either the -foreground option or the -wait option (but not both). Note that -foreground cannot be used with -remote analysis-launchd.

  For example, suppose we have a software project called MyProj and a CodeSonar hub running at alexmachine:7340.

  Suppose MyProj is written in...	...and the continuous integration tool invokes the regular build with...	...then:
  C or C++	make normal	Replace make normal with codesonar analyze MyProj -foreground alexmachine:7340 make normal
  Java	ant compile (With source files in directory sources and output written to directory buildoutput/classes.)	Augment ant compile to ant compile codesonar analyze MyProj -foreground alexmachine:7340 cs-java-scan -include-artifacts buildoutput/classes -include-sources sources

• Set up the continuous integration tool so that after the CodeSonar analysis runs, the analysis results are used to make a pass/fail determination according to your organization's criteria.

  In most cases, your determination will concern the warnings issued by the analysis. For example, a "pass" determination might require that the analysis report no warnings at all, or that it not report any new warnings (that is, warnings that are not present in some designated baseline analysis). You can use a script to download web GUI pages in order to make this determination: we provide a number of annotated download script examples that you may find helpful.

  • The example scripts that download warnings from an analysis will be helpful if you are interested in all the results of the performed analysis.
  • If you are interested in comparing the analysis results with those of another analysis on the hub, you can download the results of an analysis comparison. This will be a warning search results page for a query of the form
    (aid:A_new UNION aid:A_baseline ) DIFFERENCE (aid:A_new INTERSECT aid:A_baseline )
    where A_new, A_baseline are the Analysis IDs of the analysis you just performed and the analysis to compare it against, respectively.
    The example scripts that find the most recent analysis of a named project illustrate the process of constructing and executing a scripted search in the project domain, which may provide a useful starting point for scripting a search in the warning domain. If you are not sure what your constructed URL should look like, perform one or more analysis comparisons in the CodeSonar GUI and inspect the URLs of the resulting pages.

Running a Launch Daemon

In general, using CodeSonar with a continuous integration tool requires that the analysis machine be running a CodeSonar launch daemon (cslaunchd) with the same owner as the continuous integration tool process.

We provide instructions for running the launch daemon on Windows and on other systems.

[Windows] Setting Up A Launch Daemon Service

1. If the hub is not currently running, start it.
2. Determine the owner of the continuous integration tool process (for example, by checking the Windows Task Manager).
3. Does the analysis machine already have a cslaunchd service with the same owner?
   • YES: you don't need to do anything further and can skip the remaining steps.
   • NO: you will need to set up a service with the same owner. The remaining steps explain how to do this.
4. Get a command prompt as this owner. The method for getting a command prompt depends on whether the owner is SYSTEM, or a Windows user account.
   • SYSTEM: follow the instructions provided by Microsoft
   • Windows user account : suppose the owner of the continuous integration tool process is alextest, and the alextest account belongs tothe MYCOMPANY domain. Then execute the following command.
     runas /user:MYCOMPANY\alextest cmd.exe
     If alextest is a local Windows account - and therefore has no domain - the command will look like the following.
     runas /user:alextest cmd.exe
5. A new console window will open. In this new window, execute the following command to start the configuration tool.
   codesonar config
6. In the configuration tool main menu, select Install, connect to existing hub and work through the guided steps to connect to the hub at host:port.
7. Provide authentication for the service when prompted to do so.

[other systems] Starting the Launch Daemon At System Startup

Suppose that the CodeSonar hub that the continuous integration tool will use is located at host:port.

1. Determine the owner of the continuous integration tool process (for example, by executing TOP).
2. Arrange for that user account to run the following command on the analysis machine at system startup.
   codesonar install-launchd host:port
   Depending on your hub's access controls, you may need extend the command to specify user credentials for a hub user account with permission to start a launch daemon. For details, see Hub Authentication: Authenticated codesonar Subcommands.

   The exact mechanism used to run the command at system startup will depend on the tools and commands available on your system. Read your system documentation or consult your system administrator for information and instructions. Good candidates include:

   • crontab
   • /etc/rc.d
   • /etc/init.d

Running CodeSonar in Docker

You can run CodeSonar inside Docker. The following caveats apply.

• We do not recommend running CodeSonar analyses inside Docker unless the software being analyzed is normally built inside Docker.
• We do not recommend running a CodeSonar hub inside Docker unless you are familiar with using Docker and have a compelling reason to run your hub inside it.

We provide a Dockerfile at $CSONAR/codesonar/docker/Dockerfile

Comments in the Dockerfile explain how to use it and describe the various adjustments that you will need to make to your CodeSonar analysis. Read these comments before using the Dockerfile or otherwise attempting to run CodeSonar inside Docker.

Note: CodeSonar 9.0 introduced substantial changes to the shipped Dockerfile, including changes to how the the Dockerfile is invoked. If you have been using Docker with an earlier CodeSonar version and are now upgrading, consult the Dockerfile comments to determine what changes you need to make.

codesonar_citool.py

The codesonar_citool.py wrapper supports running the CodeSonar build/analysis in a continuous integration (CI) context and performing specified checks on the analysis results.
For details, see codesonar_citool.py: A Wrapper for CI Contexts.