Coverity on Polaris CLI Command Reference

Coverity on Polaris
Version
latest
This is a reference for the Coverity on Polaris CLI arguments and usage.

Usage and Syntax

  • polaris (-h | --help)
  • polaris (-v | --version)
  • polaris [options] <command> [<arguments>...]
  • polaris [--co=<config-option>]... [options] <command> [<arguments>...]
  • polaris (--test-settings --co=<config-option>...) [options] <command> [<arguments>...]

Description

Invokes the given <command> with the given <arguments>. The supported <arguments> are specific to the given <command> being invoked.

Global Options

Global options work with any commands, and some of them work with no command . You can get command line help, specify a configuration file, remove a locally stored access token, or print a version message. The options usually have a short version and a long version.

Table 1. Global Options
Option Definition
-c, --configuration-file <file> Specifies the configuration file to use. Defaults to polaris.yml in the current working directory. To generate one for you, use setup command. For more information, run polaris help setup.
--co Overrides the configuration file for whatever property comes right after it. The property stored in the configuration file is ignored when analysis runs, and the parameter entered on the command line is used. See Overriding the Configuration File from the Coverity on Polaris CLI.
-h, --help Use this option to display usage information for the Coverity on Polaris CLI command. Any subsequent options are ignored.

For details on a specific command, use help (no dashes) followed by the command name. For example, to better understand the capture command, use this command: 

$ polaris help capture
-i, --invalidate-access-token If specified, removes the access token from the local system. This common option cannot be used alone and must be used as part of the Coverity on Polaris command; for example: 
$ polaris -i initialize
-p, --persist-config Saves configurations to the YML file when they are set in the command line. Must be accompanied by the --co command.
-s, --server-url <url> Use this option to specify the Coverity on Polaris server URL. Using this command line option takes precedence over the POLARIS_SERVER_URL environment variable, which in turn takes precedence over the server URL setting in the yml file.
-v, --version This option displays the current version of the Coverity on Polaris CLI. As of version 2020.07, the version is automatically included in the console output log files. Running a scan displays the CLI version in the first line of output.
-w When you use the -w flag, the Coverity on Polaris CLI waits for analysis to finish before proceeding with other commands. Always use the -w flag when running polaris analyze locally.
Note:

To get help on the options supported for a specific command, use:

polaris help command.

For more information see help command below.

Analyze

Description

The analyze command triggers analysis on captured artifacts. It can also be used to upload a configuration file (see tables below).

  • For central mode, this command uploads the capture directory to the Coverity on Polaris server where the submitted artifacts are analyzed.
  • For local mode, captured artifacts are analyzed locally.

Assuming you passed the -w flag to wait for the analysis to finish, the Coverity on Polaris CLI displays a brief summary of the analysis, similar to the following example. 

  [INFO] [r56csk01] Coverity - analyze phase took 5m 41.083s.
  Analysis Completed.
  Coverity analysis
  {
   "JobId": "q23ro8dbgl3vv4e4qdabvc4bls",
   "Status": "Success"
  }     Job issue summary
     {
      "IssuesBySeverity": {
       "High": 0,
       "Medium": 5,
       "Low": 0
      },
      "Total": 5,
      "NewIssues": 1,
      "ClosedIssues": 0,
      "SummaryUrl": "https://dev01.dev.polaris.com/projects/67d0f4df-12f2-4dbd-beb9-530a583fdb1c/branches/e8a22884-20a9-4571-a142-50fca02bf6eb"
       }

Options

Table 2. Options and usage for the analyze command
Command Description
--coverity-ignore-capture-failure Allows Coverity on Polaris to proceed with the analysis when a capture fails. The option configures Coverity on Polaris to ignore capture failures from Coverity if at least one file is captured. If nothing is captured, Coverity on Polaris exits with a capture error. This feature is useful when you decide to proceed with the analysis because some amount of capture failure is not relevant. A failed capture might have enough files to make the results worth reviewing.
-w, --wait Waits for the analysis to complete. It is mandatory to be used with local mode. This flag is optional when using central analysis. In case -w is not passed, the CLI concludes the execution by displaying the submitted job ID. When -w is passed, the CLI waits for the scan to complete before displaying a short summary of results of completed analysis.
--upload-local-config Uploads the local configuration to the configuration server upon successful capture. Only project administrators are allowed to perform this action. The uploaded configuration will not be enforced by default. To enforce use of the centralized configuration file, change the setting in the Coverity on Polaris Web Interface.
[--] [<build-command>...] A build command to generate outputs of the build.
-rp, --run-property Creates a property and value that can be used to retrieve a specific run or group of runs from the /run-properties endpoint on the Common Objects Service of Coverity on Polaris API. Properties should be of the format <property_key>=<property_value>. Use up to 50 custom properties within a run; Keys are limited to 128 characters and values to 999 characters. The total length of all custom properties is limited to 1200 characters. Note that run properties are not encrypted, so they shouldn't contain sensitive data. See examples below.

Examples

Table 3. Examples for the analyze command
Command Description
$ polaris -c polaris.yml analyze -w Analyzes a project and waits for the analysis to complete.
$ polaris -c polaris.yml capture Captures artifacts for analysis.
$ polaris analyze --coverity-ignore-capture-failure Ignores Coverity capture failures and proceeds with the analysis.
$ polaris analyze --upload-local-config Uploads the local configuration to the configuration server upon successful capture.
$ polaris analyze -- mvn clean install The build command used in the capture command for Maven projects.
$ polaris analyze -w -rp pipeline=DevOps3 The -rp option creates a key called "pipeline" with a string value of "DevOps3".
$ polaris analyze -w --run-property language=Java --run-property language=.net The --run-property option creates a key called "language" with a list value of ["Java", ".net"]. (Note that You can use both string values and list values with different properties in the same run.)

Capture

Description

The capture command goes with the project's build to capture source files for analysis.

The capture command can be used to:

  • Determine what is analyzed based on the configuration file.
  • Execute a file system capture.
  • Run a build.
  • Save data to the work directory.

The default working directory is /.blackduck/polaris in your project directory. You can change this with a captureDir entry in the configuration file.

For build capture, this command:

  • Runs a build.
  • Attempts to clean up the project, using the cleanCommands defined in the configuration file.
  • Runs a build as defined by buildCommands in the configuration file.
  • As the build progresses, Coverity on Polaris extracts the data it needs and saves it in the working directory.

You can override the build command at the command line. Anything after a double dash is used as the build command.

Options

Table 4. Options for the capture command
Command Description
--coverity-ignore-capture-failure Allows Coverity on Polaris to proceed to analysis when a capture fails. This option configures Coverity on Polaris to ignore any capture failures from Coverity if at least one file is captured; if nothing is captured, Coverity on Polaris exits with a capture error. This feature is useful when you decide to proceed to analysis because some amount of capture failure is not relevant. A failed capture might have enough files to make the results worth reviewing.
[--] [<build-command>...] A build command to generate outputs of the build.

Examples

Table 5. Examples for the capture command
Command Description
$polaris capture --coverity-ignore-capture-failure Ignores Coverity capture failures and proceeds for analysis.
$polaris capture -- mvn clean install For Maven projects, the build command to be used with the capture command, regardless of what's defined in the configuration file.

Configure

Description

The configure command reads and validates the supplied configuration file. If you are not sure how to make a configuration file for Coverity on Polaris, use the setup life cycle.

Options

None.

Examples

Table 6. Examples for the configure command
Command Description
polaris configure Configuration.
polaris -c polaris.yml setup Generates a configuration file.
polaris -c polaris.yml analyze --upload-local-config -w Centralizes project configuration as a project administrator.

Help

Description

The help command displays detailed help documentation. It shows users options supported for a specific command or gets information on all supported commands.

Options

None.

Examples

Table 7. Examples for the help command
Command Description
polaris help <command> Shows options supported for a specific command. For example polaris help analyze.
polaris help Gets information on all supported commands.

Initialize

Description

The initialize command:

  • Performs a compatibility check.
  • Validates the server status and access token.

Options

None.

Examples

Table 8. Examples for the initialize command
Command Description
polaris initialize Performs a compatibility check, then validates the server status and access token.
polaris -i initialize Invalidates an existing access token.
polaris -s <url> initialize Passes the server instance to use.

Install

Description

The install command downloads and installs the required client tools packages from the server. These tools are used to generate the data submitted to the server for analysis.

Options

None.

Examples

Table 9. Examples for the install command
Command Description
polaris install Downloads and installs the required client tools packages from the server.

Prepare

Description

The prepare command performs required additional processing on the captured artifacts before they are analyzed.

Options

Table 10. Options for the prepare command
Command Description
--coverity-ignore-capture-failure

Allows Coverity on Polaris to proceed to analysis when a capture fails. This option configures Coverity on Polaris to ignore any capture failures from Coverity if at least one file is captured; if nothing is captured, Coverity on Polaris exits with a capture error. This feature is useful when you decide to proceed to analysis because some amount of capture failure is not relevant. A failed capture might have enough files to make the results worth reviewing.
[--] [<build-command>...] A build command to generate outputs of the build.

Examples

Table 11. Examples for the prepare command
Command Description
$polaris prepare --coverity-ignore-capture-failure Ignores Coverity capture failures and proceeds for analysis.
$polaris prepare -- mvn clean install For Maven projects, the build command used in the capture command.

Setup

Description

The setup command automatically creates a configuration based on the project directory contents.

Project settings are generated based on SCM information if available. Alternatively, it is generated using the project directory name when the project is not a part of an SCM. SCM inference is subjected to the availability of respective SCM binaries in $PATH. Currently, only git and svn are supported.

The location of the project directory is inferred from the location of the output configuration file given by the -c option. This defaults to polaris.yml in the current directory.

Build settings are generated based on the available build system files such as pom.xml and build.xml.

For file system capture settings, all the supported non-compiled artifacts are configured for capture.

It is recommended that you review and change the generated configuration as per your project requirements.

Options

Table 12. Options for the setup command
Command Description
-b <build_command_spec>, --build-command <build_command_spec> A build command to generate outputs of the build. The format is <build_type>=<build_command> where type is a supported build system. Note that <build_command> is assumed to be whitespace delimited.
-c <clean_command_spec>, --clean-command <clean_command_spec> A clean command to generate outputs of the build. The format is <build_type>=<clean_command> where type is a supported build system. Note that <clean_command> is assumed to be whitespace delimited.
-f <artifacts_spec>, --artifacts <artifacts_spec>

A collection of non-compiled artifacts to analyze of the form <artifact_type>=<include> where <artifact_type> is a supported non-compiled artifact type and <include> is specified as "<operator>: <argument>". Operator is one of file, directory, or include Regex and <argument> is the operator specified argument; for example, a path if <operator> is directory.
-p <name>, --project-name <name> The name to assign to the project.
-t <tools_spec>, --tools <tools_spec> A comma-separated list of tool names to be installed with the latest version. If a tool has subtools, each subtool must be qualified with the tool name followed by a ':' character; for example, coverity.
--analysis-mode <mode>

An option to allow you to configure Coverity analysis mode with the setup command option.
--project-property <property_spec>

An option to define the custom project properties. The properties must be of the format <property_key>=<property_value>. A maximum of five properties can be added to a project.

Examples

Table 13. Examples for the setup command
Command Description
$ polaris setup --clean-command shell="make -f win32/Makefile.gcc clean" Specifies that make -f win32/Makefile.gcc clean must be run in a shell to clean the project.
$ polaris setup --build-command shell="make -f win32/Makefile.gcc" Specifies that make -f win32/Makefile.gcc must be run in a shell to build the project.
$ polaris setup -f "javascript=directory: extjs" -f "python=directory: pysrc" Specifies that JavaScript files in the extjs directory must be included in the analysis, as well as Python files in pysrc.
$ polaris setup -p test-project Assigns the name test-project to the project.
$ polaris setup --analysis-mode local Specifies that local mode is used for analysis.
polaris -v Displays the version of the Polaris CLI.