Including Rust 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

General

Third-Party External

Including Rust Components in a CodeSonar Project

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

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

Overview
Including Rust Components In Your CodeSonar Project
Warning Classes
codesonar rust_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 Rust source files involved in your regular software build, and
analysis results for those files, produced by the Rust Clippy analyzer.

Incorporating Rust 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 Rust Components In Your CodeSonar project, below. We also provide an example Makefile.

Language Tools	You will need a Rust installation.
Third-Party Analyzer	clippy and clippy-sarif
Third-Party Analysis Step	You do not need to explicitly invoke clippy or clippy-sarif: they are invoked in the codesonar rust_scan.py subcommand.
Extend CodeSonar-facing Build	Invoke codesonar rust_scan.py on your Rust package. This will analyze the package source files with Clippy, use clippy-sarif to convert the Clippy results to SARIF format, then add the SARIF results and the source files to the CodeSonar project.

Including Rust Components In Your CodeSonar Project

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

Install any required language tools, such as compilers.
Make sure you have a Rust installation, including cargo and rustup.
Install the third-party analyzer.
If you don't already have a clippy installation, install clippy.
Install the third-party SARIF converter, if needed.
If you don't already have a clippy-sarif installation, install clippy-sarif.
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 rust_scan.py to analyze the indicated Rust packages with Clippy, convert the Clippy output to SARIF, and then import the SARIF results and Rust source files into the CodeSonar project.
All the Rust source files must be present before codesonar rust_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 Rust files, or that the CodeSonar-facing build can only take place if the regular build has already occurred.
Perform the CodeSonar build/analysis, observing the entire execution of your CodeSonar-facing build.

Diagram: including Rust 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 for a Rust component, or any part of that regular build, but it does not need to. The only thing that CodeSonar must observe is the codesonar rust_scan.py invocation.

Diagram illustrating the procedure described on this page: extend a build that involves Rust source files into a CodeSonar-facing build.

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 Rust Clippy via clippy-sarif. For more information, see Warning Classes Corresponding to Rust Clippy Rules.

codesonar rust_scan.py

To analyze Rust source files with Clippy 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 rust_scan.py.

codesonar rust_scan.py cargo_projdir [-C rundir, -directory rundir] \
[-include-sources file_pat] [-exclude-sources file_pat] \
[-cargo cargo_path] [-cargo-clippy clippy_path] [-clippy-sarif clippy_sarif_path] \
[-clippy-exit-ok clippy_code] [-Xclippy_options_list] [-sarif-output sarif_fname] \
[-source-max-bytes num] [@infile]

where:

cargo_projdir	The path to the directory containing your Cargo project file (Cargo.toml), relative to the directory specified with -C/-directory. All Rust source files (.rs) in this directory tree will be imported into the CodeSonar project unless explicitly excluded with -exclude-sources.
[-C rundir] [-directory rundir]	Clippy will be run in rundir. If -C/-directory is not specified, Clippy will be run in the current working directory. The cargo_projdir argument is interpreted relative to rundir. For example: codesonar rust_scan.py . Analyze the Rust project whose Cargo.toml file is located in the current working directory. codesonar rust_scan.py . -C mymod Analyze the Rust project whose Cargo.toml file is located in directory mymod. Paths specified with -cargo, -cargo-clippy, and -clippy-sarif are also interpreted relative to rundir.
[-include-sources file_pat] [-exclude-sources file_pat]	By default, all Rust source files (.rs) in the directory tree rooted at cargo_projdir will be imported into the CodeSonar project. Use -include-sources and -exclude-sources to adjust this 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 rust_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 rust_scan.py. In most cases, this means using single quotes ('); for Windows cmd, use double quotes (").
[-cargo cargo_path]	Specifies the path to your cargo executable. A relative value for cargo_path will be interpreted with respect to the directory specified with -C/-directory. If -cargo cargo_path is not specified, CodeSonar will try to find cargo in your PATH. If it is unsuccessful, codesonar rust_scan.py will fail.
[-cargo-clippy clippy_path]	Specifies the path to your cargo-clippy executable. A relative value for clippy_path will be interpreted with respect to the directory specified with -C/-directory. If -cargo-clippy clippy_path is not specified, CodeSonar will try to find cargo-clippy in your PATH. If it is unsuccessful, codesonar rust_scan.py will fail.
[-clippy-exit-ok clippy_code]	Specifies that codesonar rust_scan.py should ignore the clippy_code return code from Clippy, rather than exiting with failure as it otherwise would. In particular, you may wish to ignore return code 101: Clippy typically returns this code when it encounters rule violations. You can specify this option multiple times to ignore multiple Clippy return codes.
[-clippy-sarif clippy_sarif_path]	Specifies the path to your clippy-sarif executable. A relative value for clippy_sarif_path will be interpreted with respect to the directory specified with -C/-directory. If -clippy-sarif clippy_sarif_path is not specified, CodeSonar will try to find clippy-sarif in your PATH. If it is unsuccessful, codesonar rust_scan.py will fail.
[-X+clippy_options_list]	The +-separated list of options and values in clippy_options_list are passed to the Clippy invocation. You can specify multiple Clippy options in a single clippy_options_list; you can also specify -X multiple times in a single codesonar rust_scan.py invocation. If your option or options must be placed after an occurrence of -- on the cargo clippy command line, use -X to specify the --. For example, the following are equivalent: both specify that Clippy must be invoked with -W missing-docs and --cap-lints warn. codesonar rust_scan.py -X+--+-W+missing-docs+--cap-lints+warn [... remaining rust_scan.py options] codesonar rust_scan.py -X+-- -X+-W+missing-docs -X+--cap-lints+warn [... remaining rust_scan.py options]
[-sarif-output sarif_fname]	Specifies that the SARIF output from Clippy 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 rust_scan.py will use a temporary file for the SARIF output.
[-source-max-bytes num]	Specifies a maximum size of num bytes for imported Rust 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 rust_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 Rust source files with codesonar rust_scan.py

The codesonar rust_scan.py subcommand imports Rust 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 Rust.

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

The CodeSonar analysis checks are not applied to Rust source files.
Code Coloring and Interaction are not applied to Rust source files when they are displayed in the CodeSonar web GUI.
The Rust 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 Rust source files. CodeSonar will not recognize or interpret Extension API directives that are present in these files.

Example Makefile

An example Makefile for a Rust project is shown below. We also provide an example Makefile for a mixed-language project that has a Rust 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 Clippy analysis.

RUST_PKG=$(SRCDIR)/rust_component

.PHONY: all clean RustComponent csonar_facing

all: RustComponent

# The regular Rust build is managed by cargo.
# In this example the package only has one source file, main.rs.
# If there were other source files, they would be dependencies too.
RustComponent: $(RUST_PKG)/src/main.rs $(RUST_PKG)/Cargo.toml
	cargo build --manifest-path $(RUST_PKG)/Cargo.toml

# Invoke codesonar rust_scan.py to:
# - Analyze our Rust source files (in this case, $(RUST_PKG)/src/main.rs) with Clippy.
# - Convert the Clippy results to SARIF format with clippy-sarif.
# - Import the SARIF and Rust source files into the CodeSonar project.
csonar_facing: $(RUST_PKG)/src/main.rs
	"$(CSONAR)"/codesonar/bin/codesonar rust_scan.py $(RUST_PKG)

clean:
	cd $(RUST_PKG) && cargo clean

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.
- Rust, including cargo and rustup
- clippy
- clippy-sarif
Save the example files to the working directory (right-click on the link and select Save Target As... or equivalent).
- Makefile.Rust.txt
- rust_component.tar.gz
cd to the working directory.
Rename the Makefile (this simplifies the CodeSonar analysis command later).
mv Makefile.Rust.txt Makefile
Extract the example Rust project.
gzip -cd rust_component.tar.gz | tar xf -
If you do not have gzip and tar, use your regular system tools to extract the contents of rust_component.tar.gz into ./rust_component.
Edit Makefile to add a setting for SRCDIR at the top (above the RUST_PKG 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 RustExample 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 Clippy result. Click any table entry to view the corresponding warning report.
- The Files tab has an entry for the Rust source file main.rs. 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 import_sarif.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 RustComponent binary along with the SARIF analysis results file, invoke make all.
You can invoke make clean before invoking codesonar analyze.
For this particular Makefile, doing so will not affect make csonar_facing.