polyspace-results-export

(DOS/UNIX) Export Polyspace results to external formats such as CSV or JSON

Since R2020b

Syntax

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

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

Description

Note

This Polyspace^® command is available in polyspaceroot\polyspace\bin. Here, polyspaceroot is the Polyspace installation folder, for instance, C:\Program Files\Polyspace\R2024b (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 [export options] exports Polyspace analysis results stored locally in resultsFolder to an external format exportFormat.

polyspace-results-export -format exportFormat -host hostName -run-id runID [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.

Examples

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 with option -list-project.

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

For more information on this command, see polyspace-access (Polyspace Access).

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 Configure Report Generator with Client Keystore.

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

Input Arguments

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 Set Baseline Polyspace as You Code Results on Command Line (Polyspace Access).

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 (Polyspace Access) with option -list-project.

export options — Additional options for exporting results

string

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.

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

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 command. For more information on the command, see polyspace-access (Polyspace Access).

Version History

Introduced in R2020b

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).