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.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
General

codesonar_citool.py: A Wrapper for CI Contexts

codesonar_citool.py is a wrapper that supports running the CodeSonar build/analysis in a continuous integration (CI) context and performing specified checks on the analysis results.

Overview

codesonar_citool.py is a wrapper that supports running the CodeSonar build/analysis in a continuous integration (CI) context and performing specified checks on the analysis results.

There are four general forms.

Command Form Description
build Accumulate different components toward a CodeSonar project without analyzing the project.
analyze Build a CodeSonar project, run the analysis and output the analysis results to a hub, evaluate the analysis results.
check Check the results of a previously completed analysis.
update Update analysis properties and warning annotations for a previously completed analysis.

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

build : Accumulate Project Components Without Analyzing

Use the build form of the command to accumulate components toward a CodeSonar project, but not finalize or analyze the project.

This form has similar functionality to the regular codesonar build command, with some key differences:

The general form of the command is:

$CSONAR/codesonar/bin/cspython $CSONAR/csonar-ci/py/tools/codesonar_citool.py build project_file \
[GLOBAL_OPTS] [CS_BUILD_OPTS] hub_address command

Where:

project_file specifies the path to your CodeSonar project file, as for codesonar build.
[GLOBAL_OPTS] specifies zero or more of the global options for codesonar_citool.py.
[CS_BUILD_OPTS] specifies zero or more standard codesonar build options.
hub_address is the location of your CodeSonar hub, specified as protocol://host:port. The command will fail if a hub is not already running at this location.
command is the command that invokes your CodeSonar-facing build.

analyze : Build and Analyze Project, Evaluate Analysis Results

Use the analyze form of the command to build and analyze a CodeSonar project, then run a specified set of checks with respect to a specified subset of the analysis results.

In most respects this form extends the functionality of the regular codesonar analyze command. However, interactive functionality, such as prompting for a password, is not available.

The general form of the command is:

$CSONAR/codesonar/bin/cspython $CSONAR/csonar-ci/py/tools/codesonar_citool.py analyze project_file \
[GLOBAL_OPTS] [CS_ANALYZE_OPTS] [SEARCH_OPTS] [CHECK_OPTS] hub_address [command]

Where:

project_file specifies the path to your CodeSonar project file, as for codesonar analyze .
[GLOBAL_OPTS] specifies zero or more of the global options for codesonar_citool.py.
[CS_ANALYZE_OPTS] specifies zero or more standard codesonar analyze options.
[SEARCH_OPTS] optionally specifies the subset of analysis warnings that should be subject to the checks specified by the CHECK_OPTS. If no SEARCH_OPTS are specified, the checks (if any) will be performed on all warnings produced by the analysis.
[CHECK_OPTS] specifies zero or more checks to perform on the warnings produced by the analysis. Note that the default alert check will be applied if you do not explicitly specify any -check alert checks.
hub_address is the location of your CodeSonar hub, specified as protocol://host:port. The command will fail if a hub is not already running at this location.
command is the command that invokes your CodeSonar-facing build. If you have already accumulated all required components with one or more build invocations, you can omit this.

check : Check Results of an Existing Analysis

Use the check form of the command to perform checks on an existing analysis. This can be an analysis performed with $CSONAR/codesonar/bin/cspython $CSONAR/csonar-ci/py/tools/codesonar_citool.py analyze, or one performed with the standard codesonar analyze.

The general form of the command is:

$CSONAR/codesonar/bin/cspython $CSONAR/csonar-ci/py/tools/codesonar_citool.py check analysis_ref \
[GLOBAL_OPTS] [SEARCH_OPTS] [CHECK_OPTS] hub_address

Where:

analysis_ref specifies the analysis of interest. See Specifying analysis_ref for check and update Commands for details.
[GLOBAL_OPTS] specifies zero or more of the global options for codesonar_citool.py.
[SEARCH_OPTS] optionally specifies the subset of analysis warnings that should be subject to the checks specified by the CHECK_OPTS. If no SEARCH_OPTS are specified, the checks (if any) will be performed on all warnings produced by the analysis.
[CHECK_OPTS] specifies zero or more checks to perform on the warnings produced by the analysis. Note that the default alert check will be applied if you do not explicitly specify any -check alert checks.
hub_address is the location of your CodeSonar hub, specified as protocol://host:port. The command will fail if a hub is not already running at this location.

update : Update an Existing Analysis

Use the update form of the command to update information about an existing analysis and its warnings.

The general form of the command is:

$CSONAR/codesonar/bin/cspython $CSONAR/csonar-ci/py/tools/codesonar_citool.py update analysis_ref \
[GLOBAL_OPTS] [SEARCH_OPTS] [UPDATE_OPTS] hub_address

Where:

analysis_ref specifies the analysis of interest. See Specifying analysis_ref for check and update Commands for details.
[GLOBAL_OPTS] specifies zero or more of the global options for codesonar_citool.py.
[SEARCH_OPTS] optionally specifies the subset of analysis warnings that should be subject to any warning updates specified by the UPDATE_OPTS. If no SEARCH_OPTS are specified, the specified updates will be performed on all warnings produced by the analysis.
[UPDATE_OPTS] specifies zero or more updates to perform. You can update warning properties, user-assigned analysis properties, or both. Warning property updates are performed on the warnings that match the specified SEARCH_OPTS, or on all warnings produced by the analysis if no SEARCH_OPTS are specified.
hub_address is the location of your CodeSonar hub, specified as protocol://host:port. The command will fail if a hub is not already running at this location.

Command Options

The various forms of the codesonar_citool.py command have a large number of options.

Global Options GLOBAL_OPTS

The global options can be used with all forms of the codesonar_citool.py command.

-tmpdir temp Save temporary files, including temporary files used for authentication, to directory temp.
standard authentication options You can authenticate using the standard CodeSonar hub authentication options. [-auth authtype],
[-hubuser username],
[-hubpwfile pwfile],
[-hubbearerfile bearerfile],
[-hubcert certfile],
[-hubkey privatekeyfile] For details, see Hub Authentication: Authenticated codesonar Subcommands.
-hubbearervar variable Get the hub bearer token from the environment variable whose name is variable. This will implicitly create a temporary file containing the token and provide it to the standard CodeSonar -hubbearerfile option. The temporary file will be deleted after program execution.
-hubcertvar variable Get the hub user certificate as a value from the environment variable whose name is variable. This will implicitly create a temporary file containing the certificate and provide it to the standard CodeSonar -hubcert option. The temporary file will be deleted after program execution.
-hubkeyvar variable Get the hub user certificate private key as a value from the environment variable whose name is variable. This will implicitly create a temporary file containing the key and provide it to the standard CodeSonar -hubkey option. The temporary file will be deleted after program execution.
-hubpwvar variable Get the hub user password from the environment variable whose name is variable. This will implicitly create a temporary file containing the password and provide it to the standard CodeSonar -hubpwfile option. The temporary file will be deleted after program execution.
-cs-environment-format vartemplate Specifies an alternate environment variable format for recognized CodeSonar variables when -use-environment is enabled. vartemplate defines a variable name pattern containing one ? character. The default template is CODESONAR_?, which will recognize variable names like CODESONAR_HUBUSER, etc.
-use-environment When this is specified, codesonar_citool.py will make use of variables and system information from the local environment.
  • The command will automatically use certain environment variables to determine parameters for hub authentication, remote analysis configuration, etc. See Environment Variables, below, for a list of recognized environment variables.
  • Search language expressions specified in the command can use environment variables.
Options that take a variable argument, such as -hubpwvar, do not depend on this option.

Search Options SEARCH_OPTS

The search options can be used with the analyze, check, and update forms of the codesonar_citool.py command.

Use these options to restrict the following to a particular subset of the warnings produced by the analysis.

If no search options are specified, checks/updates are applied to all warnings produced by the analysis, and output files include information about all warnings.

-comparison-analysis comp_analysis Apply checks/updates only to warnings that are issued by the current analysis but not by comp_analysis. You can specify comp_analysis in any of the following ways.
num [an integer] Use the analysis whose Analysis ID is num.
?asearch_exp Use the analysis that matches the search specified by Analysis Search Language expression asearch_exp.

If asearch_exp contains spaces or other special characters, it must be appropriately quoted or escaped.

asearch_exp can use parameters that you define with -search-param.

  • If -use-environment is specified, then any environment variable may also be used as a parameter. This allows environment variables to be correctly encoded as string literal values within the search expression.
  • Parameters must be prefixed by a $ character and may be enclosed in {{ and }} characters. If a literal $character is required, use the sequence $$.
  • Ensure that your quoting style does not permit the shell to expand these parameters. For example, if you are using a bash shell and your asearch_exp includes parameters, use single-quoting.
If asearch_exp matches two or more analyses on the hub, the first one found is used.
Cannot be specified multiple times.
-warning-visibility filter Apply checks/updates only to warnings that satisfy filter: an existing saved warning search. The available searches can be viewed on the Warnings tab of the hub Saved Searches page.
num Use the saved search whose search ID is num.
str Use the saved search whose name is str. If str contains spaces or other special characters, it must be appropriately quoted or escaped.
Cannot be specified multiple times.
-warning-search wsearch_exp Apply checks/updates only to warnings that satisfy wsearch_exp: a Warning Search Language expression. If wsearch_exp contains spaces or other special characters, it must be appropriately quoted or escaped.

This expression can use parameters that you define with -search-param.

  • If -use-environment is specified, then any environment variable may also be used as a parameter. This allows environment variables to be correctly encoded as string literal values within the search expression.
  • Parameters must be prefixed by a $ character and may be enclosed in {{ and }} characters. If a literal $character is required, use the sequence $$.
  • Ensure that your quoting style does not permit the shell to expand these parameters. For example, if you are using a bash shell and your wsearch_exp includes parameters, use single-quoting.
Cannot be specified multiple times.
-search-param param value Define a parameter to use in analysis or warning search expressions for the -comparison-analysis and -warning-search options.
  • param (the parameter name) must consist of alphanumeric characters only.
  • value (the parameter value) will be encoded as a string literal according to the CodeSonar search language syntax.
Can be specified multiple times.

Check Options CHECK_OPTS

The check options can be used with the analyze and check forms of the codesonar_citool.py command.

-check check_method [+check_arg...] Check the analysis results using check_method; return a nonzero exit code (as specified by -fail-code if the check fails. The check will be applied only to the warnings that satisfy all conditions imposed by the specified search options. Note that the default alert check will be applied if you do not explicitly specify any -check alert checks. See Check Methods for -check for full details.
-dump-sarif sarif_file Save analysis results in SARIF format to sarif_file. Only the warnings that satisfy all conditions imposed by the specified search options will be saved.
-fail-code exit_code If an analysis check fails, return exit_code. Defaults to 1.
-polling-timeout inactivity_seconds An inactivity timeout of inactivity_seconds will be applied to the hub status polling that is performed when the analysis is executed without -wait or -foreground. If there is no analysis activity for longer than inactivity_seconds, the program will exit with a nonzero code.

Defaults to 14400 (4 hours).

If -wait or -foreground is specified, this option has no effect.
-summary report_file Save a summary of analysis results to report_file.

The contents of the summary report are determined by the specified search options and checks.

  • The report contains one section for each check that is performed. There is therefore a section for each check specified with -check, plus a section for the default alert check if it is applied.
  • Only warnings that satisfy all conditions imposed by the specified search options are considered in checks and reported in these sections.
The format of the summary report is determined by the file name:
  • Files with .md extension will be formatted as markdown.
  • Files with .html extension will be formatted as HTML.
  • Otherwise, the file will be formatted as plain text.

Update Options UPDATE_OPTS

The update options can be used with the update form of the codesonar_citool.py command.

For all of these updates, the authorizing hub user must have ANALYSIS_ANNOTATE permission for the specified analysis. Any additional permission requirements for individual updates are noted in the option details.

Note on eligible warnings. If one or more search options are specified, warning updates are only applied to warnings that were issued by the specified analysis and meet all the specified constraints. Otherwise, warning updates are applied to all warnings issued by the specified analysis. Search options do not affect the behavior of -set-property.

-set-property name value Set user-assigned analysis property name to value. If the analysis already has a user-assigned analysis property named name, its value will be updated.
-set-priority priority For each eligible warning, set the warning Priority to priority.

priority is the priority name. For a list of available priority names, see the hub Manage Priorities page.

If the hub has no priority whose name matches priority the command will attempt to create one, failing if the authorizing hub user does not have G_PRIORITY_ADD permission.
-set-state state For each eligible warning, set the warning State to state.

state is the state name. For a list of available state names, see the hub Manage States page.

If the hub has no state whose name matches state the command will attempt to create one, failing if the authorizing hub user does not have G_STATE_ADD permission.
-set-finding finding For each eligible warning, set the warning Finding to finding.

finding is the finding name. For a list of available finding names, see the hub Manage Findings page.

If the hub has no finding whose name matches finding the command will attempt to create one, failing if the authorizing hub user does not have G_FINDING_ADD permission.
-set-owner owner For each eligible warning, set the warning Owner to the hub user whose username is owner.

The owner must have ANALYSIS_OWN_WARNINGS permission for the specified analysis.
-add-note comment For each eligible warning, add comment to the warning Notes.

Environment Variables for -use-environment

When the -use-environment option is specified, various environment variables are recognized and used as command defaults.

The table below shows the default CodeSonar environment variable names that will be recognized and used when -use-environment is specified. If you want to use these variables, you will need to define them to appropriate values.

If -cs-environment-format is also specified, codesonar_citool.py will instead recognize the variable names produced by replacing the CODESONAR_ according to the specified format. Variables with other prefixes will not be affected.

For example, if you specify -cs-environment-format MYCS_? then the recognized environment variables will be MYCS_HUBUSER, MYCS_HUBPWFILE, and so on.

Environment Variable Usage if -use-environment is specified
CODESONAR_HUBUSER Default value for -hubuser: hub user name.
CODESONAR_HUBPWFILE Default value for -hubpwfile: hub user password file path.
CODESONAR_HUBPWVAL Hub user password. This will implicitly create a temporary file containing the key and provide it to the standard CodeSonar -hubpwfile option. The temporary file will be deleted after program execution. A password provided on the command line with -hubpwfile or -hubpwvar will take precedence over this value.
CODESONAR_HUBCERTFILE Default value for -hubcert: hub user certificate file path.
CODESONAR_HUBKEYFILE Default value for -hubkey: hub user certificate private key file path.
CODESONAR_HUBCERTVAL CodeSonar hub user certificate contents. When this value is used, the command will implicitly create a temporary file containing the token and provide it to the standard CodeSonar -hubcert option. The temporary file will be deleted after program execution.
CODESONAR_HUBKEYVAL Hub user certificate private key. This will implicitly create a temporary file containing the key and provide it to the standard CodeSonar -hubkey option. The temporary file will be deleted after program execution.
CODESONAR_HUBBEARERFILE Default value for hubbearerfile: hub user bearer token file path.
CODESONAR_HUBBEARERVAL CodeSonar hub bearer token. This will implicitly create a temporary file containing the token and provide it to the standard CodeSonar -hubbearerfile option. The temporary file will be deleted after program execution.
CODESONAR_PROJECT_PATH Default value for standard CodeSonar -project option: a string /ancestors/project-name.
CODESONAR_REMOTE_ANALYSIS Default value for standard CodeSonar -remote option: a positive integer (ldgroup ID), negative integer (launch daemon ID), or string (ldgroup path).
CODESONAR_REMOTE_ARCHIVE Default value for standard CodeSonar -remote-archive option: a positive integer (ldgroup ID), negative integer (launch daemon ID), or string (ldgroup path).
CODESONAR_WARNING_VISIBILITY Default value for -warning-visibility: a saved search name or ID.

Specifying analysis_ref for check and update Commands

The codesonar_citool.py check and codesonar_citool.py update commands take an analysis_ref argument that specifies the analysis of interest. The analysis_ref can have any of the following forms.

num (integer) Use the analysis whose Analysis ID is num.
path/to/pfiles-name (string not beginning with ?) Use the most recent analysis performed with Analysis Directory path/to/pfiles-name.prj_files.
?asearch_exp (string beginning with ?) Use the analysis that matches the search specified by analysis search language expression asearch_exp. If asearch_exp contains spaces or other special characters, it must be appropriately quoted or escaped. asearch_exp can use parameters that you define with -search-param.
  • If -use-environment is specified, then any environment variable may also be used as a parameter. This allows environment variables to be correctly encoded as string literal values within the search expression.
  • Parameters must be prefixed by a $ character and may be enclosed in {{ and }} characters. If a literal $ character is required, use the sequence $$.
  • Ensure that your quoting style does not permit the shell to expand these parameters. For example, if you are using a bash shell and your asearch_exp includes parameters, use single-quoting.
If asearch_exp matches two or more analyses on the hub, the first one found is used.
 

To report problems with this documentation, please visit https://support.codesecure.com/.