Including Go Components in a CodeSonar Project

JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.2p0

CONFIDENTIAL

CodeSecure Inc

Third-Party External

Including Go Components in a CodeSonar Project

This page describes how to extend your CodeSonar-facing build so that your CodeSonar project includes:

the Go source files involved in your regular software build, and
analysis results for those files, produced by the Go Staticcheck analyzer.

Overview
Including Go Components In Your CodeSonar Project
Warning Classes
codesonar go_scan.py
Example Makefile
Try the Example Makefile
Related Links

Overview

This page describes how to extend your CodeSonar-facing build so that your CodeSonar project includes:

the Go source files involved in your regular software build, and
analysis results for those files, produced by the Go Staticcheck analyzer.

Incorporating Go components follows the standard process for including a tier 3 component. The specializations to that process are summarized in the following table. For detailed instructions, see Including Go Components In Your CodeSonar project, below. We also provide an example Makefile.

Language Tools	You will need a Go installation.
Third-Party Analyzer	Go Staticcheck
Third-Party Analysis Step	You do not need to explicitly invoke Staticcheck: it is invoked in the codesonar go_scan.py subcommand.
Extend CodeSonar-facing Build	Invoke codesonar go_scan.py on your Go module. This will analyze the corresponding source files with Staticcheck, then add the Staticcheck SARIF results and the source files to the CodeSonar project.

Including Go Components In Your CodeSonar Project

Incorporating Go components follows the standard process for including a tier 3 component.

Install any required language tools, such as compilers.
Make sure you have a Go installation.
If you are installing now, make sure you install the same version that is used in the rest of your organization.
Install the third-party analyzer.
If you don't already have a Staticcheck installation, install Staticcheck now
Install the third-party SARIF converter, if needed.
There is nothing to do for this step: Staticcheck can produce SARIF output.
Extend the regular build to invoke the third-party analyzer (and SARIF converter, if needed).
You do not need a separate analysis step.
Extend the CodeSonar-facing build.
Extend your CodeSonar-facing build by adding one or more invocations of codesonar go_scan.py.
All the Go source files must be present before codesonar go_scan.py is invoked. Different build systems have different mechanisms for specifying this requirement. For example, you might be able to specify that the CodeSonar-facing build depends on the Go files, or that the CodeSonar-facing build can only take place if the regular build has already occurred.
If you have not already set up a CodeSonar-facing build for your regular software project, you will need to create one.
Perform the CodeSonar build/analysis, observing the entire execution of your CodeSonar-facing build.

Diagram: including Go components in a CodeSonar project

The following diagram illustrates the extended software build described above, and its interactions with the CodeSonar build/analysis.

The CodeSonar-facing build could include the entire regular build, or any part of the regular build, but it does not need to. The only thing that CodeSonar must observe is the codesonar go_scan.py invocation.

Diagram illustrating the procedure described on this page: extend a build that executes Staticcheck on Go source files into a CodeSonar-facing build by adding invocations of 'codesonar import_sarif.py' to import the SARIF output from staticcheck and corresponding Go source files.

Note

In this section (and throughout this manual), $CSONAR indicates the CodeSonar installation directory.

If you have defined environment variable CSONAR to the location of the CodeSonar installation directory, you can use $CSONAR directly in your command lines. On Windows systems, use %CSONAR% in place of $CSONAR.
If you don't want to use environment variables, replace $CSONAR with the path to your CodeSonar installation directory before using the command lines.

Warning Classes

When a SARIF file is imported into a CodeSonar project, the SARIF importer determines an associated warning class for each rule object in the SARIF rules, creating this warning class if it does not already exist.

The SARIF importer has special handling for warning classes derived from SARIF produced by Staticcheck. For more information, see Warning Classes Corresponding to Staticcheck Rules.

codesonar go_scan.py

To analyze Go source files with Staticcheck and then add the source files and analysis results to a project, CodeSonar observes the execution of a command that incorporates one or more invocations of codesonar go_scan.py.

codesonar go_scan.py go_pkg_or_file₁ [go_pkg_or_file₂ ...] [-C moddir, -directory moddir] \
[-include-sources file_pat] [-exclude-sources file_pat] [-staticcheck staticcheck_path] \
[-X+sc_options_list] [-sarif-output sarif_fname] [-source-max-bytes num] [@infile]

where:

go_pkg_or_file₁ [go_pkg_or_file₂ ...]	Each go_pkg_or_file_i specifies a package (directory name) or Go source file, relative to the Go module specified with -C/-directory. To analyze all packages in the module, specify . (dot). To analyze an individual package in the module, specify the package name. Note that this must match a directory name in the module directory. To analyze an individual Go source file in the top level directory of the module, specify the file name. The codesonar go_scan.py command must include at least one go_pkg_or_file_i argument.
[-C moddir] [-directory moddir]	The Go module directory: that is, the directory containing the go.mod file. Staticcheck will be run in moddir. If -C/-directory is not specified, Staticcheck will be run in the current working directory. Any go_pkg_or_file_i arguments are interpreted relative to moddir. For example: codesonar go_scan.py . For the Go module whose root directory is the current working directory, analyze all packages. codesonar go_scan.py . -C mymod For the Go module whose root directory is mymod, analyze all packages. codesonar go_scan.py file.go mypA mypB -C mymod For the Go module whose root directory is mymod, analyze file mymod/file.go, package mypA, and package mypB.
[-include-sources file_pat] [-exclude-sources file_pat]	All Go source files (.go) indicated by the -C/-directory and go_pkg_or_file_i argument combination will be analyzed with Staticcheck. By default, this set of Go source files is then imported into the CodeSonar project. Use -include-sources and -exclude-sources to adjust the imported set by adding or removing files. file_pat is a recursive glob pattern representing a source file path. It matches all files whose file path matches file_pat. When a single codesonar go_scan.py invocation contains a combination of -include-sources and -exclude-sources options, the set of imported files is determined by applying the corresponding inclusions and exclusions in the order in which they appear on the command line. Note: Your shell may be configured to expand patterns into file and directory names. If so, make sure you quote the file_pat appropriately to indicate that the shell should pass it through to codesonar go_scan.py. In most cases, this means using single quotes ('); for Windows cmd, use double quotes (").
[-staticcheck staticcheck_path]	Specifies the path to your staticcheck executable. If -staticcheck staticcheck_path is not specified, CodeSonar will try to find staticcheck in your PATH. If it is unsuccessful, codesonar go_scan.py will fail.
[-X+sc_options_list]	The +-separated list of options and values in sc_options_list are passed to the Staticcheck invocation. You can specify multiple Staticcheck options in a single sc_options_list; you can also specify -X multiple times in a single codesonar go_scan.py invocation. For example, the following are equivalent: both specify that Staticcheck must be invoked with -go 1.0 and -tests=false. codesonar go_scan.py -X+-go+1.0+-tests=false [... remaining go_scan.py options] codesonar go_scan.py -X+-go+1.0 -X+-tests=false [... remaining go_scan.py options]
[-sarif-output sarif_fname]	Specifies that the SARIF output from Staticcheck should be written to file sarif_fname. The primary use case for this option is in projects for which you wish to retain the SARIF results after the CodeSonar build/analysis has finished. If -sarif-output sarif_fname is not specified, codesonar go_scan.py will use a temporary file for the SARIF output.
[-source-max-bytes num]	Specifies a maximum size of num bytes for imported Go source files: files larger than this maximum size will be ignored by the importer. If -source-max-bytes is not specified, the importer will ignore files larger than 500KB.
[@infile]	infile is a text file containing a list of build option entries to be added to the codesonar go_scan.py command line. The entries must be separated by one or more whitespace characters (including newline). The entries will be added to the command line at the location where the @infile argument occurred, in the order in which they appear in infile.

Importing Go source files with codesonar go_scan.py

The codesonar go_scan.py subcommand imports Go source files into the CodeSonar project using the same mechanism as codesonar import_sarif.py, because CodeSonar does not have a full front end for Go.

There are several consequences when files are directly imported with codesonar import_sarif.py.

The CodeSonar analysis checks are not applied to Go source files.
Code Coloring and Interaction are not applied to Go source files when they are displayed in the CodeSonar web GUI.
The Go source files will have file-level IR only. Plug-ins that make use of other IR information will not cover these files.
The Extension API is not available for Go source files. CodeSonar will not recognize or interpret Extension API directives that are present in these files.

Example Makefile

An example Makefile for a Go project is shown below. We also provide an example Makefile for a mixed-language project that has a Go component: see Including Tier 3 Components in a CodeSonar Project: Example Makefile

Unhighlighted rules and targets are those that would be in the Makefile if it only built the regular project.
Rules and targets that are highlighted like this have been added to define a CodeSonar-facing build, which incorporates the Staticcheck analysis.

GOMODULE=$(SRCDIR)/go_component

.PHONY: all clean csonar_facing

all: GoComponent

GoComponent: $(GOMODULE)/go_component.go $(GOMODULE)/go.mod
	cd "$(GOMODULE)" && go build -o ../GoComponent

# Invoke codesonar go_scan.py to analyze our Go source file with Staticcheck,
# then import the SARIF results and the source file into the CodeSonar project.
csonar_facing: $(GOMODULE)/go_component.go
	"$(CSONAR)"/codesonar/bin/codesonar go_scan.py go_component.go -C "$(GOMODULE)"

clean:
	rm GoComponent

Try the Example Makefile

We have provided a minimal sample project so you can experiment with the example Makefile.

Sign in to a machine where CodeSonar is installed.
Select or create a working directory. The working directory location must be outside both your CodeSonar installation directory and your hub directory.
If any of the following are not installed, install them now and ensure that they are in your PATH.
- Go
- Staticcheck
Save the example files to the working directory (right-click on the link and select Save Target As... or equivalent).
- Makefile.Go.txt
- go_component.tar.gz
cd to the working directory.
Rename the Makefile (this simplifies the CodeSonar analysis command later).
mv Makefile.Go.txt Makefile
Extract the example Go project.
gzip -cd go_component.tar.gz | tar xf -
If you do not have gzip and tar, use your regular system tools to extract the contents of go_component.tar.gz into ./go_component.
Edit Makefile to add a setting for SRCDIR at the top (above the GOMODULE setting). If CSONAR isn't defined in your environment, set that as well.
```
SRCDIR=.
```
or
```
SRCDIR=.
CSONAR=path/to/your/codesonar/installation
#  on Windows, typically CSONAR=C:\\Program Files\\CodeSecure\\CodeSonar
```
Build and analyze the CodeSonar project. If your hub is at the default location, your command will be something like:
codesonar analyze GoExample make csonar_facing
For full codesonar analyze command details, see Command Line Build/Analysis.
When the analysis finishes, view the Analysis page in the hub GUI.
- The Warnings tab shows a warning instance for each Staticcheck result. Click any table entry to view the corresponding warning report.
- The Files tab has an entry for the Go source file go_component.go. You can click on the file name to view a source listing: as noted above, there is no additional source highlighting or navigation.
- There are no entries in the Procedures tab: source files imported with codesonar go_scan.py have file-level internal representation (IR) only.

Other Targets in the Example Makefile

If you are interested, you can try building other targets in the example Makefile.

To build the GoComponent binary along with the SARIF analysis results file, invoke make all.
If you wish, you can invoke make clean before invoking codesonar analyze.
For this particular Makefile, doing so will not affect make csonar_facing.