External Integrations - Continuous Integration (CI)

Customized integrations are available for the following CI tools. We also provide general-purpose instructions for integrating your CI tool with CodeSonar.

Tool-Specific Notes

AnthillPro A community-developed CodeSonar integration plug-in is available
Buildbot Follow the typical setup
CruiseControl Follow the typical setup 
Jenkins See CodeSonar Jenkins integration
GitHub See CodeSonar GitHub CI/CD documentation
GitLab See CodeSonar GitLab CI/CD documentation
JIRA See CodeSonar JIRA CI/CD Documentation (are available for version 7.0.0-8.14.1) 

 

Contents

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

Typical Setup

  • 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, ensuring that the codesonar command includes the -foreground option.

    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:Anew UNION aid:Abaseline ) DIFFERENCE (aid:Anew INTERSECT aid:Abaseline )
      where Anew, Abaseline 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.
  • CodeSonar cannot run in a Docker container running Windows as the guest operating system.

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.

Was this article helpful?
0 out of 0 found this helpful

Articles in this section

GrammaTech Resource Library
Welcome to GrammaTech's resource library. Here you will find useful information about software development in the IoT era, where devices must not only function with impeccable quality and safety but also remain resilient to cyber attacks.
Shift Left Academy
Shift Left Academy is an educational resource to help implement a security first approach. Shift Left focuses on finding and preventing defects and security vulnerabilities early in the software development process
Blog
Posts by topic including static analysis, software assurance, and binary analysis