Quick Start (CodeSonar SaaS)

This section is designed to get you started using CodeSonar SaaS as quickly as possible. If you get stuck, see the links provided for more detailed information. For a guided introduction to CodeSonar see the tutorial.

• Overview
• Quick Start
• More Example Build/Analysis Commands

Overview

In most cases we recommend starting with the CodeSonar tutorial. However, if you want to get started as quickly as possible (for example, because you have used CodeSonar before and just need a refresher), the steps are as follows.

1. Install CodeSonar, if you have not already done so.
2. Identify the CodeSonar SaaS hub and analysis launch daemon that you will be using.
3. Ensure that you have the required credentials for your CodeSonar SaaS hub user account.
4. Build and analyze your project.
5. Browse the analysis results on the CodeSonar SaaS hub.

Quick Start

1. Install CodeSonar

Install CodeSonar, if you have not already done so: see section Installing or Upgrading CodeSonar.
Note that you will not need to set up a hub: a hub is provided as part of your CodeSonar SaaS deployment.

2. Identify the CodeSonar SaaS hub and analysis launch daemon that you will be using

CodeSecure will provide this information when you purchase CodeSonar SaaS.

• The hub manages information about the analysis and its results. It is identified by a URL of the form https://hmname.codesonar.com:port.
• The analysis launch daemon is responsible for starting CodeSonar analysis processes.
  For CodeSonar SaaS, you will typically specify your analysis launch daemon as /saas/*, which instructs the hub to choose a suitable launch daemon from among all those available in the /saas launchd group.

3. Ensure that you have the required credentials

Ensure that you have the required credentials for your CodeSonar SaaS hub user account.

These credentials will depend on how your organization has chosen to manage hub authentication. In general, you will need to provide either

• a username and password,
  or
• a TLS certificate

to authorize CodeSonar operations such as running an analysis, or browsing results on the hub.
If you have not already been provided with these credentials, obtain them from your local CodeSonar administrator before proceeding.

4. Build and Analyze

The codesonar binary resides in the $CSONAR/codesonar/bin subdirectory of the CodeSonar installation. To invoke CodeSonar without specifying the path, add $CSONAR/codesonar/bin to your PATH environment variable.

On the command line, execute the following.

where:

For example, to analyze a C/C++ project whose regular build command is make myproj:

• CodeSonar will interactively prompt for a hub username and password to authenticate this command
• The CodeSonar build and analysis will take place in two phases.
  1. Build. CodeSonar will build a CodeSonar project on your local machine. This will create various files in directories /myfiles/ and /myfiles/cs-myproj.prj_files.
  2. Analysis. Once the CodeSonar project is built, the project files are uploaded to the SaaS hub. The hub selects a suitable SaaS analysis launch daemon from the /saas/* set, then instructs that launch daemon to launch an analysis of the project files.
     The degree of parallelism in the analysis will depend on the setting of ANALYSIS_SLAVES.
• Analysis results will be sent to the hub at https://example.codesonar.com:7340, and associated with the CodeSonar project called cs-myproj. If this project does not already exist on the hub, it will be created.

For more details, see section Command Line Build/Analysis.

5. Browse

When CodeSonar has finished building and analyzing your project, it will print the URL at which the analysis results will be available.

1. Use a web browser to open the URL.
   You will be prompted to sign in to the hub (unless you already have an active hub session).
2. Provide the same credentials that you used to authorize the CodeSonar build/analysis.
   Once you have signed in, you will be navigated to the Analysis page for the analysis you just performed.

The Analysis page displays information about a single CodeSonar analysis and its results. By default it will show the Warnings tab, which contains a table with a line of information about each warning issued by the analysis.

• If the analysis is still running, the Analysis State field will describe the current state of the analysis. Use your browser's Reload command to refresh the page.
• When the analysis is finished, the Analysis State field will read Finished.

To view a warning report, click anywhere on its entry in the summary table. A warning report page will open, containing:

• summary information for the CodeSonar analysis of the project,
• summary information for the warning, and
• a code excerpt with lines of interest highlighted, together with line numbers and annotations indicating problem conditions (where present).

For more details, see section Warning Report.

More Example Build/Analysis Commands

C analysis; certificate-based authentication; default certificate locations

Build a CodeSonar project based on the software whose normal build command is gcc -c myNativeProj.c .

• Determine locations for certificate and private key as described in the documentation for -auth certificate. Use the certificate for hub authentication, and the private key to sign responses to the hub.
• Build the CodeSonar project locally. This will create various files in directories /myfiles/ and /myfiles/cs-mycproj.prj_files.
• Once the CodeSonar project is built, upload the project files are uploaded to the SaaS hub at https://example.codesonar.com:7340. The hub will select a suitable SaaS analysis launch daemon from the /saas/* set, then instruct that launch daemon to launch an analysis of the project files.
  • Send analysis results and other analysis information to the hub at https://example.codesonar.com:7340.

Java analysis; certificate-based authentication; specified certificate locations

Build a CodeSonar project based on the classes contained in Example.jar and the source file Example.java, both located in the current working directory.

• Use the certificate located at ~/.csurf/codesonar/mysaascert.pem for hub authentication.
• Sign responses to the hub with the private key located at ~/.csurf/codesonar/mysaasprivkey.pem.
• Build the CodeSonar project locally. This will create various files in directories /myfiles/ and /myfiles/cs-myjavaproj.prj_files.
• Once the CodeSonar project is built, upload the project files are uploaded to the SaaS hub at https://example.codesonar.com:7340. The hub will select a suitable SaaS analysis launch daemon from the /saas launchd group, then instruct that launch daemon to launch an analysis of the project files.
  • Analyze all classes contained in Example.jar, and produce warnings relevant to Example.java.
  • Send analysis results and other analysis information to the hub at https://example.codesonar.com:7340.

C# analysis; password-based authentication; specified username and password file

Build a CodeSonar project based on the classes contained in Example.dll, located in the current working directory, where the current working directory also contains the corresponding Example.pdb file.

• Authenticate with username and password:
  • username: alex
  • password: the value stored in file /myfiles/creds/pwfile.txt
• Build the CodeSonar project locally. This will create various files in directories /myfiles/ and /myfiles/cs-mycsharpproj.prj_files.
• Once the CodeSonar project is built, upload the project files are uploaded to the SaaS hub at https://example.codesonar.com:7340. The hub will select a suitable SaaS analysis launch daemon from the /saas/* set, then instruct that launch daemon to launch an analysis of the project files.
  • Analyze all classes contained in Example.dll.
  • Expect to also find file Example.pdb in the current directory.
    • Use the information in Example.pdb to identify the source files corresponding to Example.dll.
      If the identified source files cannot be loaded, CodeSonar will not be able to issue warnings for Example.dll.
    • If Example.pdb is not present, issue an alert.
  • Output warnings relevant to the identified source files.
  • Send analysis results and other analysis information to the hub at https://example.codesonar.com:7340.

Further Examples

Example build/analysis command lines are presented at a number of locations in this manual. In particular, each of the following pages provides several annotated examples.

If you adapt one of these examples for CodeSonar SaaS use, ensure that you have included the following.