Command Line Overview

Note: This platform is renamed Coverity on Polaris. Unless otherwise specified, references to Polaris or Polaris Software Integrity Platform in this documentation are referring to Coverity on Polaris.

The Polaris CLI Scan Client (Polaris CLI) coordinates with the Polaris Software Integrity PlatformTM (Polaris) server to perform analysis on source code. The Polaris CLI has options that control how analysis happens.

The Polaris CLI runs the tools that analyze software to find quality and security issues. The Polaris CLI itself is distinct from the analysis tools it can install and run.

The syntax of the command is:

polaris [common-options] command [command-options] [arguments]

The command that is passed will determine the phase to execute. The commands and phases have identical names. The options you pass in the command determine:

  • The tools to install.
  • The name of the project.
  • Authentication of the current user.
  • The build artifacts to be captured and processed.
  • The build commands to be executed.
  • The build artifacts to be cleaned after the build.

For more information on Polaris CLI options, see CLI Command Reference.

The polaris.yml configuration file also controls how analysis happens and enables customization based on your environment. For more information, refer to the configuration file help topics.

Note that Polaris automatically generates the correct configuration in the default configuration file for many project types, including Gradle. To upload a configuration file, pass the --upload-local-config option with polaris analyze.

Finally, environment variables can also supply information to the command line tools.

Phases

The Polaris CLI progresses through the following phases (see CLI Phases).

  1. initialize
  2. setup
  3. configure
  4. install
  5. capture
  6. prepare
  7. analyze
Note: All commands executed with Polaris will execute all the phases preceding it.

When each CLI phase completes, the command line tells you how long it took, rounded to the nearest millisecond. For example:

[INFO] [y4wq7aho] Coverity - analyze phase took 1h 12m 36.543s

For tool-independent phases, such as setup, no tool name displays in the output.

Example 1

$ polaris analyze -w 

Use this command to run all phases, submit files, and wait for the Coverity on Polaris server to finish performing the analysis. If you have not previously run the Polaris CLI, you might still be able to run this command, enter a server URL access token when prompted, and be able to complete a full analysis of your project without further configuration. Coverity on Polaris makes some educated guesses about the project configuration; for nonstandard project configurations, you must edit the YML configuration file and possibly the options you are using with the Polaris CLI.

The CLI generates a clean command and a build command during configuration file creation (polaris.yml). You might need to change these to meet your needs.

At the conclusion of the analysis, the Polaris CLI prints a brief summary of the issues, with counts reported by severity and with counts for new issues and closed issues:


     Job issue summary
     {
      "IssuesBySeverity": {
       "High": 0,
       "Medium": 5,
       "Low": 0
      },
      "Total": 5,
      "NewIssues": 1,
      "ClosedIssues": 0,
      "SummaryUrl": "https://subdomain.polaris.synopsys.com/projects/67d0f4df-12f2-4dbd-beb9-530a583fdb1c/branches/e8a22884-20a9-4571-a142-50fca02bf6eb"
       }
    

To see more detailed results in the Polaris UI, copy the project summary link at the end of the response and paste it into the address bar of your web browser.

Example 2

$ polaris --co project.branch='"different_branch"' analyze

This example uses the --co option to change the name of the project branch, temporarily overriding that setting in the configuration file. Use the --co option to change your configurations quickly and from the command line when running analysis. For more information, see Overriding the Configuration File from the CLI.

Example 3

$ polaris -c other-configuration.yml prepare

Proceeds through the life cycle through the prepare phase using a specific configuration file.

Example 4

$ polaris -i setup

Removes the locally stored access token, then runs up through the setup phase. You are prompted to enter an access token.