Overriding the Configuration File from the Coverity on Polaris CLI

Coverity on Polaris
Version
latest
The --co option enables you to override the configuration file from the command line, so you can change parameters on the fly as you run Coverity on Polaris analysis.

How to Use the --co Option

The --co option overrides the configuration file for the property that comes right after it. The property stored in the configuration file is ignored when analysis runs, and the parameter entered in the command line is used. The configuration file is not changed unless you also use the -p flag. When the --co override is used alone, it applies one time – to the analysis you run when you apply the option.

Here's an example: 

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

In this example, the branch name is changed to "different_branch" regardless of what is stored in the configuration file.

When using this option:

  • If you want to override more than one property, your command must contain more than one instance of the --co option.

  • Test your command with the --test-settings option before running it live, as explained below.

Properties in the Configuration File

The --co option identifies properties in the configuration file by way of a naming convention that employs dot notation to string together the name of a nested property and names of all the property's parents where they exist. The project branch becomes project.branch in the preceding example, because the only parent of branch is project, as shown in this excerpt from a configuration file. 

               project:
   name: ${scm.git.repo}
   branch: ${scm.git.branch}
   revision:
      name: ${scm.git.commit}
      date: ${scm.git.commit.date}

Any parameter in your configuration file can be called out in the same way when you use the --co option to modify it.

For example, the revision name, as opposed to the project name, is specified as project.revision.name, because the parents of that parameter, in order of occurrence, are project and revision.

Because project.revision.name is set to the variable ${scm.git.commit} in the preceding excerpt, it always returns the value of the current git commit. However, by running the command polaris --co project.revision.name='"different_name"' analyze, you could temporarily override the configuration file in question and run analysis with the revision name "different_name", which is included in the results and is visible in your Coverity on Polaris dashboard, instead of the difficult-to-read commit hash.

Using the --test-settings Option

To verify that your command line overrides are successful, execute your command first with the --test-settings option. When this is included, Coverity on Polaris returns the settings that are in active memory, so that you can see if the override was successful. Here's an example:

polaris --test-settings --co project="{\"branch\":\"new branch\", \"name\":\"new name\"}" analyze

When you are satisfied with the results, run the command without the --test-settings option.

Changing Your Configuration File from the Command Line

To change settings from the command line and store them permanently in your configuration file, use the --persist-config option, as shown in the following example. 

polaris --persist-config --co project.branch='"different_branch"' analyze

This example changes the name of the project branch before running analysis and also permanently revises the configuration file so that Coverity on Polaris continues to use this branch name every time it analyzes the project.

Updating Your Configuration File from the Command Line

To update your configuration file, use the --persist-config option, as shown in the following examples.

Mac, Linux
polaris --persist-config --co project.name=\"newProjectname\" analyze

Windows 

polaris --persist-config --co project.name=\"newProjectname\" analyze

Windows (PowerShell)

polaris --persist-config --co project.name='\"newProjectname\"' analyze

Simplified Versions of the Override Commands

With the Coverity on Polaris 2020.10 release, simplified versions of the --co commands are provided.

Override command formats prior to version 2020.10 are still valid. However, if you are setting up new processes that include overrides, the new simplified formats have better ease of use.

Considerations for simplified override commands

  1. Curly brackets ({ & }), square brackets ([ & ]), colon (:), and comma (,) are treated as the JSON elements to evaluate and format the value string, and are used to append double quotes around a key/value.
  2. If you want a JSON element to be treated as a part of a string, it must be escaped using the backslash escape character (\). The Coverity on Polaris CLI automatically removes the escape character while formatting.
  3. Do not provide unnecessary white spaces inside the string. This is because the Coverity on Polaris CLI cannot differentiate between the mandatory white spaces; for example, white spaces as a part of a regex value, and an unwanted white space. If provided, the white space is treated as a part of the string and won't be automatically discarded.

The following examples provide the existing (standard) and simplified version for each override command.

Mac and Linux Examples

Update the project name

Standard version:

polaris --co project.name=\"newProjectname\" analyze

Simplified version:

polaris --co project.name=newProjectname analyze

Update more than one field in an object; for example, name and branch

Standard version:

polaris --co project='{"branch":"new_branch", "name":"new_name"}' analyze

Simplified version:

polaris --co project="{branch:new branch,name:new name}" analyze

Override multiple options

Standard version:

polaris --co project='{"branch":"new branch", "name":"new_name"}' --co capture.coverity.buildless.project.languages='["java","javascript"]' analyze

Simplified version:

polaris --co project="{branch:new branch, name:new_name}" --co capture.coverity.buildless.project.languages=[java,javascript] analyze

Provide cov-analyze flags

Standard version:

polaris --co analyze.coverity.cov-analyze='["--aggressiveness-level", "low", "--enable", "FORWARD_NULL"]' -c config.yml analyze

Simplified version:

polaris --co analyze.coverity.cov-analyze="[--aggressiveness-level,low,--enable,FORWARD_NULL]" -c config.yml analyze

Provide a complete section of the YAML file

Standard version:

polaris --co install='{"coverity":{"version":"2019-06"}}' -c polaris.yml capture

Simplified version:

polaris --co install={"coverity":{version:2019-06}} -c polaris.yml capture

Set a build command

Standard version:

polaris --co capture.build.cleanCommands=‘[{“shell”:[“mvn”,“-f”, “pom.xml”]}]’ analyze

Simplified version:

polaris --co capture.build.cleanCommands=[{shell:[mvn,-B,-f,pom.xml]}] analyze

Windows Examples

Update the project name

Standard version:

polaris --co project.name=\"newProjectname\" analyze

Simplified version:

polaris --co project.name=newProjectname analyze

Update more than one field in an object; for example, name and branch

Standard version:

polaris --co project="{\"branch\":\"new branch\", \"name\":\"new name\"}" analyze

Simplified version:

polaris --co project="{branch:new branch,name:new name}" analyze

Override multiple options

Standard version:

polaris --co project="{\"branch\":\"new branch\", \"name\":\"new name\"}" --co capture.coverity.buildless. project.languages="[\"java\",\"javascript\"]" analyze

Simplified version:

polaris --co project="{branch:new branch, name:new_name}" --co capture.coverity.buildless.project.languages=[java,javascript] analyze
Provide cov-analyze flags

Standard version:

polaris --co analyze.coverity.cov-analyze="[\"--aggressiveness-level\", \"low\", \"--enable\", \"FORWARD_NULL\"]" -c config.yml analyze
Simplified version:
polaris --co analyze.coverity.cov-analyze="[--aggressiveness-level,low,--enable,FORWARD_NULL]" -c config.yml analyze
Provide a complete section of the YAML file

Standard version:

polaris --co install="{\"coverity\":{\"version\":\"2019-06\"}}" -c polaris.yml capture

Simplified version:

polaris --co install={"coverity":{version:2019-06}} -c polaris.yml capture

Set a build command

Standard version:

polaris --co capture.build.cleanCommands="[{\"shell\":[\"mvn\"]}]" analyze

Simplified version:

polaris --co capture.build.cleanCommands="[{shell:[mvn]}]" analyze

Modifying the build and clean commands when MSBuild's location is not included in the %PATH% variable. Note that the MSBuild version number in this command must be replaced (twice) with the version used for your project, and the name of the WebGoat.NET.sln file must be replaced with the name of your project file.

Standard version:

polaris --co capture.build.cleanCommands='[{\"shell\":"["\"C:\\Program Files (x86)\\Microsoft Visual Studio\\2017\\Enterprise\\MSBuild\\15.0\\Bin\\msbuild.exe\"",\"WebGoat.NET.sln\",\"/t:Clean\"]"}]' --co capture.build.buildCommands="[{\"shell\":"["\"C:\\Program Files (x86)\\Microsoft Visual Studio\\2017\\Enterprise\\MSBuild\\15.0\\Bin\\msbuild.exe\"",\"WebGoat.NET.sln\",\"/nologo\",\"/nr:false\",\"/t:Build\","\"/p:platform=any cpu\"",\"/p:configuration=release\",\"/p:VisualStudioVersion=15.0\"]"}]' analyze

Simplified version:

polaris --test-settings --co capture.build.cleanCommands='[{shell:[C\:\\Program Files (x86)\\Microsoft Visual Studio\\2017\\Enterprise\\MSBuild\\15.0\\Bin\\msbuild.exe,WebGoat.NET.sln,/t\:Clean]}]' --co capture.build.buildCommands='[{shell:[C\:\\Program Files (x86)\\Microsoft Visual Studio\\2017\\Enterprise\\MSBuild\\15.0\\Bin\\msbuild.exe,WebGoat.NET.sln,/t\:Build\,p\:platform=any cpu,p\:configuration=release,p\:VisualStudioVersion=15.0]}]' analyze

Windows PowerShell Examples

Update the project name

Standard versions:

polaris --co project.name='\"newProjectname\"' -c config.yml analyze
polaris --co project.name=='"newProjectname"' -c config.yml analyze
polaris --co project.name=='newProjectname' -c config.yml analyze

Simplified version:

polaris --co project.name=newProjectname -c config.yml analyze

Update more than one field in an object; for example, name and branch

Standard version:

polaris --co project='{\"branch\":\"new branch\", \"name\":\"new name\"}' -c config.yml analyze

Simplified version:

polaris --co project="{branch:new branch,name:new name}" -c config.yml analyze

Override multiple options

Standard version:

polaris.exe --co project='{\"branch\":\"new branch\", \"name\":\"new name\"}' --co capture.coverity.buildless.project.languages='[\"java\",\"javascript\"]' -c config.yml analyze

Simplified version:

polaris --co project="{branch:new branch, name:new_name}" --co capture.coverity.buildless.project.languages=[java,javascript] -c config.yml analyze

Provide cov-analyze flags

Standard version:

polaris --co analyze.coverity.cov-analyze='[\"--aggressiveness-level\", \"low\", \"--enable\", \"FORWARD_NULL\"]' -c config.yml analyze

Simplified version:

polaris --co analyze.coverity.cov-analyze="[--aggressiveness-level,low,--enable,FORWARD_NULL]" -c config.yml analyze

Provide a complete section of the YAML file

Standard version:

polaris --co install='{\"coverity\":{\"version\":\"2019-06\"}}' -c polaris.yml capture

Simplified version:

polaris --co install={"coverity":{version:2019-06}} -c polaris.yml capture

Set a build command

Standard version:

polaris --co capture.build.cleanCommands='[{\"shell\":[\"mvn\"]}]' -c .\polaris.yml capture

Simplified version:

polaris --co capture.build.cleanCommands="[{shell:[mvn]}]" -c .\polaris.yml capture

Modifying the build and clean commands when MSBuild's location is not included in the %PATH% variable. Note that the MSBuild version number in this command must be replaced with the version used for your project, and the name of the WebGoat.NET.sln file must be replaced with the name of your project file.

Standard version:

polaris --co capture.build.cleanCommands='[{\"shell\":"["\"C:\\Program Files (x86)\\Microsoft Visual Studio\\2017\\Enterprise\\MSBuild\\15.0\\Bin\\msbuild.exe\"",\"WebGoat.NET.sln\",\"/t:Clean\"]"}]' --co capture.build.buildCommands="[{\"shell\":"["\"C:\\Program Files (x86)\\Microsoft Visual Studio\\2017\\Enterprise\\MSBuild\\15.0\\Bin\\msbuild.exe\"",\"WebGoat.NET.sln\",\"/nologo\",\"/nr:false\",\"/t:Build\","\"/p:platform=any cpu\"",\"/p:configuration=release\",\"/p:VisualStudioVersion=15.0\"]"}]' -c .\polaris.yml analyze

Simplified version:

polaris --co capture.build.cleanCommands='[{shell:[C\:\\Program Files (x86)\\Microsoft Visual Studio\\2017\\Enterprise\\MSBuild\\15.0\\Bin\\msbuild.exe,WebGoat.NET.sln,/t\:Clean]}]' --co capture.build.buildCommands='[{shell:[C\:\\Program Files (x86)\\Microsoft Visual Studio\\2017\\Enterprise\\MSBuild\\15.0\\Bin\\msbuild.exe,WebGoat.NET.sln,/t\:Build\,p\:platform=any cpu,p\:configuration=release,p\:VisualStudioVersion=15.0]}]' -c .\polaris.yml analyze