polyspace-results-export

R2026b

(System Command) Export Polyspace results to external formats such as CSV or JSON

Syntax

polyspace-results-export -format exportFormat -results-dir resultsFolder [filter options] [export options]

polyspace-results-export -format exportFormat -host hostName -run-id runID [filter options] [export options] [polyspace access options]

Description

The polyspace-results-export system command exports Polyspace^® static analysis results to external formats such as CSV or JSON.

Note

This Polyspace command is available in polyspaceroot\polyspace\bin. Here, polyspaceroot is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2026b (see also Installation Folder for desktop products or Installation Folder for server products). To avoid typing the full path to this command, add this location to the PATH environment variable in your operating system.

polyspace-results-export -format exportFormat -results-dir resultsFolder [filter options] [export options] exports Polyspace analysis results stored locally in resultsFolder to an external format exportFormat. Use filter options to export a subset of results.

example

polyspace-results-export -format exportFormat -host hostName -run-id runID [filter options] [export options] [polyspace access options] exports Polyspace analysis results stored in Polyspace Access™ to an external format exportFormat. Specify the Polyspace Access instance by using hostName and the project on Polyspace Access by using runID.

When you export results from Polyspace Access, the exported results include a Polyspace Access URL for each finding. Click the URL to view the code, results details, and other information associated with the finding in the Polyspace Access interface.

example

Examples

collapse all

Export Polyspace Results Stored Locally

Export results from a project myProject in the Polyspace user interface to JSON format.

Suppose your project is stored in C:\Polyspace_Workspace. To export results from a specific module in the project, specify the path to the folder that directly contains results from the module.

polyspace-results-export -format json-sarif -results-dir C:\Polyspace_Workspace\myProject\Module_1\BF_Result -output-name C:\Polyspace_Workspace\reports\myProject\myProject.json

Export Results Stored in Polyspace Access

Note

To generate reports of results on Polyspace Access at the command line, you must have a Polyspace Bug Finder™ Server™ or Polyspace Code Prover™ Server installation.

Suppose that you want to export the results of a project on Polyspace Access to JSON format.

To connect to Polyspace Access, provide a host name and your login credentials including your encrypted password. To encrypt your password, use the polyspace-access command and enter your user name and password at the prompt.

polyspace-access -encrypt-password 
login: jsmith
password:
CRYPTED_PASSWORD LAMMMEACDMKEFELKMNDCONEAPECEEKPL
Command Completed

Store the login and encrypted password in a credentials file and restrict read and write permission on this file. Open a text editor, copy these two lines in the editor, then save the file as myCredentials.txt for example.

 -login jsmith
 -encrypted-password LAMMMEACDMKEFELKMNDCONEAPECEEKPL

To restrict the file permissions, right-click the file and select the Permissions tab on Linux^® or the Security tab on Windows^®.

To specify project results on Polyspace Access, specify the run ID of the project. To obtain a list of projects with their latest run IDs, use the polyspace-access -list-project (Polyspace Access) command.

polyspace-access -host example-access-server -credentials-file myCredentials.txt -list-project
Connecting to https://example-access-server:9443
Connecting as jsmith
Get project list with the last Run Id
Restricted/Code_Prover_Example (Code Prover) RUN_ID 14
public/Bug_Finder_Example (Bug Finder) RUN_ID 24
public/CP/Code_Prover_Example (Polyspace Code Prover) RUN_ID 16
public/Polyspace (Code Prover) RUN_ID 28
Command Completed

If Polyspace Access uses the HTTPS protocol, use the polyspace-report-generator binary to configure polyspace-results-export to enable communications with Polyspace Access over HTTPS. See Choose Between HTTP and HTTPS Configuration for Polyspace Access (Polyspace Access).

Export results from the project with run ID 16 to JSON format.

polyspace-results-export -credentials-file myCredentials.txt -format json-sarif -host myAccessServer -run-id 16

Export Filtered Results for a Quality Gate

Export only red run-time check results from local analysis results to create a simple quality gate in a CI/CD pipeline.

Export red run-time check results from a local results folder to a CSV file. If the output file is not empty, the quality gate fails.

polyspace-results-export -format csv -results-dir C:\Polyspace_Workspace\myProject\results -family RTE -color Red -output-name red_rte_results.txt

The command exports only results where the family is Run-time Check AND the color is Red.

Export MISRA Coding Rule Violations

Export only MISRA C:2023 violations that have not been reviewed.

Export unreviewed MISRA C:2023 results to a CSV file.

polyspace-results-export -format csv -results-dir ./results -family "MISRA C:2023" -status Unreviewed -output-name misra_unreviewed.txt

You can also use the family ID instead of the display name: -family MISRA-C-2023.

Export New Results Compared to a Baseline

Export only new results that were introduced since a specific baseline run on Polyspace Access.

Export results from run ID 24 that are new compared to baseline run ID 16.

polyspace-results-export -format csv -host myAccessServer -run-id 24 -resolution New -baseline 16 -credentials-file myCredentials.txt

To compare against the oldest run in the project, use -baseline first instead of specifying a run ID.

Combine Multiple Filter Values

Export results that match multiple colors or multiple statuses by repeating the filter option.

Export all red and orange results that still require review (status is Unreviewed, To investigate, or To fix).

polyspace-results-export -format csv -results-dir ./results -color Red -color Orange -status Unreviewed -status "To investigate" -status "To fix"

The command exports results where the color is (Red OR Orange) AND the status is (Unreviewed OR To investigate OR To fix).

Input Arguments

collapse all

`exportFormat` — Output format for results
`csv` | `json-sarif` | `console`

Format in which the Polyspace results are exported: csv for tab separated values (TSV) output or json-sarif for JSON output. If you use the polyspace-bug-finder-access command for single-file analysis (Polyspace as You Code™), you can export the results to the console using the format console.

Each result consists of information such as result name, family, and so on. Both TSV and JSON formats result in almost the same content being exported but the exported content might refer to the same type of information by different names.

In the TSV format, each result consists of tab-separated information in columns such as ID, Family, Group, Color, Check, and so on.
To package and potentially filter your result data, use the csv format. For instance, you can import the TSV file to Microsoft^® Excel^® and use Excel filters on the results.
In the JSON format, each result consists of almost the same information as JSON object properties. The properties shown for a result sometimes use a name that is different from the name used in the CSV format. For instance, to get the full rule checker name for a result, use the ruleId property of a result in combination with the id and name property of a rule. The reason for the difference is that the JSON format follows the standard notation provided by the OASIS Static Analysis Results Interchange Format (SARIF).
The JSON format contains some additional information such as the checker short name and the full message that accompanies a result. Use the JSON format if you want to use this short name or message. You can also use this format for a more standardized reporting of results. For instance, if you use several static analysis tools and want to report their results in one interface by using a single parsing algorithm, you can export all the results to the standard SARIF JSON format.

The console output is preformatted in a form similar to compiler errors and warnings, and contains less information than the other formats. console format is only available for Polyspace as You Code results. In particular, if you baseline Polyspace as You Code results using integration results in the Polyspace Access web interface, use the JSON or CSV format for maximum benefits from the baselining. See Command Line: Configure Baseline Results in Polyspace as You Code (Polyspace as You Code).

`resultsFolder` — Result folder path
string

Path to a folder containing Polyspace analysis results (.psbf or .pscp file). If you do not specify a folder path, the command looks for analysis results in the current folder.

Example: C:\Polyspace_Workspace\My_project\Module_1\results

`hostName` — Polyspace Access machine host name
string

hostName corresponds to the host name that you specify in the URL of the Polyspace Access interface, for example https://hostName:port/metrics/index.html. If you are unsure about which host name to use, contact your Polyspace Access administrator. The default host name is localhost. You must specify a host name to generate a report for results on the Polyspace Access database.

Example: my-company-server

`runID` — Polyspace Access run ID
integer

Run ID of the project findings that you export. A unique run ID is assigned to each analysis run that you upload to Polyspace Access.

You can see the run ID of a project in the Polyspace Access web interface. To get the run ID of a project at the command line, use the command polyspace-access -list-project (Polyspace Access).

`export options` — Additional options for exporting results
string

Option Description

Option	Description
`-output-name outputName`	Name of the exported file. The default name is `results_list.txt` (TSV) or `results_list.json` (JSON). The file is saved on the path from which you call the command. To save the file in a different folder, specify the full path to the folder, for instance `-output-name C:\PathTo\OtherFolder`. This option is not compatible with the console output format (`-format console`).
`-set-language-english`	Use this option if your display language is set to a language other than English but you want the exported results in English.
`-key-mode file-scope \| function-scope`	Specify how the entries in the Key column of the exported results are calculated: `file-scope` (default) — The key is calculated from the result name, result type, and file location. `function-scope` — The key is calculated from the result name, result type, and function location if the results is located inside a function, or file location otherwise. Keys generated in this mode are prefixed with `FN` if the result is inside a function. See also Enable Function Scope for Exported Keys.

-output-name
                    outputName

Name of the exported file. The default name is results_list.txt (TSV) or results_list.json (JSON).

The file is saved on the path from which you call the command. To save the file in a different folder, specify the full path to the folder, for instance -output-name C:\PathTo\OtherFolder.

This option is not compatible with the console output format (-format console).

-set-language-english Use this option if your display language is set to a language other than English but you want the exported results in English.

-key-mode file-scope | function-scope

Specify how the entries in the Key column of the exported results are calculated:

file-scope (default) — The key is calculated from the result name, result type, and file location.
function-scope — The key is calculated from the result name, result type, and function location if the results is located inside a function, or file location otherwise. Keys generated in this mode are prefixed with FN if the result is inside a function.

To see options available with this command, enter polyspace-results-export -h.

`filter options` — Options to filter the exported results
string

Use filter options to export a subset of results. You can combine multiple filter options. When you use different filter options together, the command exports only results that match all specified criteria (AND logic). When you specify multiple values for the same option, the command exports results that match any of the specified values (OR logic).

To specify multiple values for the same option, repeat the option for each value. For instance, -color Red -color Orange exports results that are either red or orange.

Filter values use flexible string matching: spaces and capitalization are ignored. For instance, -status Tofix matches To fix.

Option	Description
`-family` `familyName`	Family of results to export. Specify either the family display name or the family ID. For instance, `-family "Run-time Check"` or `-family RTE` both select run-time check results. To specify more than one family, repeat the option for each family. Example: `-family "MISRA C:2023" -family "MISRA C++:2023"`
`-color Red` \| `Orange` \| `Gray` \| `Green` \| `Black`	Color of results to export. The color indicates the severity of a finding. For instance, red indicates a definite error for run-time checks. To specify more than one color, repeat the option for each color. Example: `-color Red -color Orange`
`-severity High` \| `Medium` \| `Low` \| `Unset`	Severity of results to export. The severity is a review attribute that you assign to a finding in the Polyspace Access web interface or at the command line. To specify more than one severity, repeat the option for each severity. Example: `-severity High -severity Medium`
`-status Unreviewed` \| `"To investigate"` \| `"To fix"` \| `Justified` \| `"No action planned"` \| `"Not a defect"` \| `Other`	Review status of results to export. To specify more than one status, repeat the option for each status. Example: `-status "To fix" -status "To investigate"`
`-impact High` \| `Medium` \| `Low`	Impact level of defect results to export. To specify more than one impact level, repeat the option for each level. Example: `-impact High -impact Medium`
`-resolution New` \| `Fixed` \| `Unresolved` \| `Resolved`	Resolution of findings in the current run compared to a baseline run. Use this option with `-baseline` to compare two runs from the same project. The resolution types are: `New` — Results that are in the current run but not in the baseline run. `Fixed` — Results that are fixed in the current run, either because the result was fixed in the source code, or because the source code containing the result is deleted or no longer part of the analysis. `Unresolved` — Results from the baseline run that are still present in the current run. `Resolved` — Results that are `Fixed` in the current run or results with a status of `Justified`, `No Action Planned`, or `Not A Defect` in the current run. If you do not specify a baseline, the software compares the current run to the run that immediately precedes it. To specify more than one resolution, repeat the option for each resolution. Example: `-resolution New -resolution Unresolved`
`-baseline runID` \| `first`	Run ID of the project run you use as a baseline when comparing results resolution to the current run. This option requires option `-resolution`. If you do not specify a baseline, the software compares the current run to the run that immediately precedes it. Specify `first` to use the oldest run in the project as the baseline. Example: `-baseline 123` Example: `-baseline first`

The following filter options are available only when exporting results from Polyspace Access (using -host and -run-id):

Option	Description
`-assignee name`	Export only results assigned to the specified user. To specify more than one assignee, repeat the option for each assignee. Example: `-assignee jsmith -assignee jdoe`
`-unassigned`	Export all unassigned results.
`-sqo-level 1` \| `2` \| `3` \| `4` \| `5` \| `6` \| `Exhaustive`	Software quality objective (SQO) level that must be satisfied. If you specify an SQO level, the command exports only open results that must be fixed or justified to satisfy the requirements of the specified level. The SQO levels 1 to 6 specify an increasingly stricter set of requirements in terms of Polyspace results. Example: `-sqo-level 6`
`-imported-reviews "Not applied"` \| `Written` \| `Overwritten` \| `Unconfirmed`	Export results based on the status of imported review information. Use this option to export results from a project (target) whose review information was imported from another project (source). Specify one of these types: `Not applied` — Review information was imported but the target project kept its original values. `Written` — Review information from the source was written to the target only where review fields were previously empty. `Overwritten` — Review information from the source was written to the target even where review fields were not previously empty. `Unconfirmed` — Results where the import has not been confirmed by a reviewer. To specify more than one type, repeat the option for each type. Example: `-imported-reviews Written -imported-reviews Overwritten`

`polyspace access options` — Additional options for exporting results from Polyspace Access
string

Option	Description
`-port portNumber`	`portNumber` corresponds to the port number that you specify in the URL of the Polyspace Access interface, for example `https://hostname:portNumber/metrics/index.html`. If you are unsure about which port number to use, contact your Polyspace Access administrator. The default port number is `9443`.
`-protocol http \| https`	HTTP protocol to connect to Polyspace Access. Default value is `https`.
`-credentials-file file_path`	Full path to the text file where you store your login credentials. Use this option if, for instance, you use a command that requires your Polyspace Access credentials in a script but you do not want to store your credentials in that script. While the script runs, someone inspecting currently running processes cannot see your credentials. You can store only one set of credentials in the file, either as `-login` and `-encrypted-password` entries on separate lines, for instance: -login jsmith -encrypted-password LAMMMEACDMKEFELKMNDCONEAPECEEKPL or as an `-api-key` entry: -api-key keyValue123 Make sure that you restrict the read and write permissions on the file where you store your credentials. For example, to restrict read and write permissions on file `login.txt` in Linux, use this command: chmod go-rwx login.txt
`-api-key keyValue`	API key you use as a login credential instead of providing your login and encrypted password. To assign an API key to a user, see Configure User Manager (Polyspace Access) or contact your Polyspace Access administrator. Use the API key if, for instance, you use a command that requires your Polyspace Access login credentials as part of an automation script with a CI tool like Jenkins^®. If a user updates his or her password, you do not need to update the API key associated with that user in your scripts. It is recommended that you store the API key in a text file and pass that file to the command by using `-credentials-file`. See the description for option `-credentials-file`.
`-login username` `-encrypted-password ENCRYPTED_PASSWD`	Credentials that you use to log into Polyspace Access. The argument of `-encrypted-password` is the output of the `polyspace-access -encrypt-password` (Polyspace Access) command.

Version History

Introduced in R2020b

expand all

R2023a: CWE ID column is removed

The column that lists the CWE™ rules that are mapped to Bug Finder defects is removed. Polyspace supports the CWE standard natively, and when you export analysis results, violations of CWE rules are reported in the same way as violations of other coding standards, one results per line. See also Common Weakness Enumeration (CWE).