How to view and convert analyzer's results (SARIF, HTML, and other formats)

• Supported formats
• The PlogConverter utility (Windows)
  • Description
  • Parameters
  • Exit codes
  • Example of a conversion command
• The plog-converter utility (Linux, macOS)
  • Description
  • Parameters
  • Exit codes
  • Example of a conversion command
• Automatic notifications of the analyzer warnings

PVS-Studio can display reports results as:

• a raw output of the analyzer;
• a Plog report;
• a JSON report.

You can view the file with the analysis results in the PVS-Studio's plugin for an IDE or in C and C++ Compiler Monitoring UI.

These report formats are not suitable for direct viewing in a text editor or in automated emails. That's why the PVS-Studio distribution kit includes a special utility that allows you to convert the analysis results to other formats.

The name of this utility depends on the platform:

• Windows: PlogConverter.exe;
• Linux, macOS: plog-converter.

Supported formats

Below is the list of formats supported by the conversion utility.

The PlogConverter utility (Windows)

Description

To convert a PVS-Studio report to one of the listed formats, use the PlogConverter utility from the PVS-Studio distribution kit for Windows. You can find the PlogConverter utility in the PVS-Studio installation directory (by default, the path is C:\Program Files (x86)\PVS-Studio). The source code of the utility is available on GitHub.

Parameters

The "‑‑help" flag displays the main information about the utility:

PlogConverter.exe –-help

To run the utility in the terminal's command line, execute:

PlogConverter.exe [options] <path to PVS-Studio log>

Utility parameters:

• ‑‑renderTypes (or -t): specifies formats to which the report will be converted. A combination of various formats is possible: just list them and separate them with commas. If a format is not specified, the report is converted to all formats.
  • JSON: the recommended format to use. Supported by all PVS-Studio plugins and utilities. This format is recommended if you need to combine several reports into one or convert a Plog report into a JSON format.
  • Plog: a format to view the report on Windows. However, it is better to use a more universal JSON format. You can choose the Plog format if you need to combine several reports into one or convert a JSON report to the Plog format.
  • Html: an html file format. This report is easy to use for automated emails.
  • FullHtml: an html file format. If you choose this format, PlogConverter converts the analyzer messages and source files to html files. This allows you to view the analyzer report, sort messages, and navigate through code in a browser. As a result of conversion, you'll get a directory named 'fullhtml' located on the path set via the '-o' flag. If you set the '-n' parameter, the directory will have the specified name and the '.fullhtml' postfix;
  • Txt: a report format with the plaintext representation of analyzer messages.
  • Csv: a report format with delimiters. It's convenient to use this format in Microsoft Excel.
  • Totals: a report format that contains a summary about the number of different warning types (GA, OP, 64, CS, MISRA, ...) and different levels of certainty. You can view a detailed description of the warnings' certainty levels and sets of diagnostic rules in the documentation, section "Getting acquainted with the PVS-Studio static code analyzer on Windows".
  • TaskList: a report format for viewing in Qt Creator.
  • TeamCity: a report format for uploading and viewing in TeamCity CI.
  • Sarif: an open format for data exchanging between static analysis tools. Read more here.
  • SarifVSCode: an extended Sarif report format. Suitable for working with the Sarif Viewer plugin for Visual Studio Code.
  • MisraCompliance: a report format that contains information about code compliance with the MISRA standard.
  • GitLab: a report format compatible with GitLab Code Quality.
  • DefectDojo: a report format for uploading and viewing in DefectDojo.
• ‑‑analyzer (or -a): filters warnings by mask. The filter mask has the 'MessageType:MessageLevels' form. 'MessageType' can take one of the following types: GA, OP, 64, CS, MISRA, Fail, OWASP, AUTOSAR. 'MessageLevels' can take values from 1 to 3.
• ‑‑excludedCodes (or -d): Specifies a list of warnings (separated by ",") to exclude from the resulting report.
• ‑‑includePaths (or -i): Include in the report only warnings issued on specified files. You can use this parameter to pass file paths (absolute or relative) or wildcard masks. Separate the paths or masks with the ';' character. Note that you can include paths only for those reports that don't contain the SourceTreeRoot marker.
• ‑‑excludePaths (or -e): excludes from the report all warnings issued in certain files. You can use this parameter to pass file paths (absolute or relative) or wildcard masks. Separate the paths or masks with the ';' character. Note that you can exclude paths only for those reports that don't contain the SourceTreeRoot marker.
• ‑‑settings (or -s): sets the path to the PVS-Studio settings file. This file has various settings for the analyzer. PlogConverter reads the 'DisableDetectableErrors' parameter from the passed file and disables diagnostics specified in the report.
• ‑‑srcRoot (or -r): sets the replacement of the "SourceTreeRoot" marker. If during the check the path to the root directory of the project was replaced with a "SourceTreeRoot" marker (|?|), then this parameter becomes mandatory (otherwise the project files will not be found).
• ‑‑outputDir (or -o): specifies the directory where the converted reports will be saved. If this parameter is not set, the files are written to the startup directory.
• ‑‑outputNameTemplate (or -n): specifies a template file name without an extension. All converted reports will have the same name but different extensions.
• ‑‑errorCodeMapping (or -m): enables the display of CWE ID and/or SAST ID for found warnings: "-m cwe,misra,autosar,owasp". If the 'cwe' value is specified, warnings in the report will have CWE ID. If 'misra', 'autosar' or 'owasp' is specified, then the display of SAST ID will be enabled for the rules of the corresponding standard.
• ‑‑indicateWarnings (or -w): sets the exit code of the PlogConverter utility to '2' if warnings remain after the log is filtered.
• ‑‑pathTransformationMode (or -R): sets the path transformation mode when converting the report. This option requires "‑‑srcRoot". This option works only for those formats that support relative paths: JSON, Plog. Acceptable values:
  • toAbsolute — paths are converted to the absolute ones;
  • toRelative — paths are converted to the relative ones.
• ‑‑misraDeviations: MISRA rules, violations of which are not taken into account. The rules are separated by ";". If all the MISRA violations found by the analyzer are specified in the ‑‑misraDeviations option, the final report will show that the project complies with the MISRA standard.
• ‑‑grp: path to the Guideline Re-categorization Plan text file. Use this option only when you generate the MISRA Compliance report. Guideline Re-categorization Plan is a file that specifies the category changes for the MISRA rules. You can read more about the MISRA rule category here.
• ‑‑noHelpMessages: exclude links to the documentation for diagnostics from the analyzer's warnings.
• ‑‑keepFalseAlarms(or -f): preserve warnings marked as False Alarms in the report.
• ‑‑countWarnings (or -c): allows to display the number of messages matching the arguments of this command. Command format: -c {Groups or Error Codes}:{Levels};{Other Arguments}... Example commands: -c GA:1,2;OP:1 | -c V003 | -c V502,V504:1 | -c ALL
• ‑‑generateDiffWith (or -D): generates a report with the difference between the report provided by this option and the input report.
• ‑‑filterSecurityRelatedIssues: keep only security related issues in the output log.

Exit codes

The PlogConverter utility has several non-exit codes that don't necessarily indicate some issues with the tool. If the utility didn't return '0', it doesn't mean the utility worked with an error.

Below is the description of the PlogConverter exit codes:

• '0' — the report was successfully converted;
• '1' — an error occurred when one of the output files was generated.
• '2' — an output file has unfiltered or unsuppressed warnings. To make this mode work, pass the ‑‑indicateWarnings (-w) flag to the utility;
• '3' — a general (non-specific) error in the utility's operation, an exception was caught during the work. Usually, it means the PlogConverter code has an error.
• '4' — incorrect command line arguments were passed to the utility, or a file passed as an argument wasn't found.
• '5' — there was an attempt to replace absolute paths with relative ones, but the report format doesn't support this option.

Example of a conversion command

PlogConverter.exe -t Json,Csv -a GA:1,2;OWASP:1 -o D:\Logs -r
D:\projects\projectName -m CWE,OWASP -n PVS-Log PVS-Studio.log

Here's what happens:

• 'PVS-Studio.log' is converted to the JSON and CSV formats;
• the resulting report will contain 1st and 2nd level warnings of the General Analysis diagnostic group, and 1st level warnings from the OWASP diagnostic group;
• the '|?|' marker in the paths to files is replaced by 'D:\projects\projectName';
• the analyzer warnings will have CWE_ID and SAST_ID;
• converted reports will be in the 'D:\Logs' folder and will be named as 'PVS-Log.json' and 'PVS-Log.csv'.

The plog-converter utility (Linux, macOS)

Description

To convert a PVS-Studio report to one of the listed formats, use the plog-converter utility, which is available with the PVS-Studio C/C++ packages and archives for Linux and macOS. After installing the package or the PVS-Studio C/C++ archive, you can use the plog-converter utility to convert analyzer reports to different formats (*.xml, *.tasks, etc.). The source code of the utility is available on GitHub.

Parameters

The "‑‑help" flag displays the main information about the utility:

plog-converter --help

To run the utility in the terminal's command line, execute:

plog-converter [options] <path to PVS-Studio log>

All the options can be listed in any order you want.

Available options:

• ‑‑renderTypes (or -t): specifies the possible options for converting the report. This is a mandatory argument for running the utility. A combination of various formats is possible, just type ‑‑renderTypes (-t) before each format or separate them with a comma and pass as the flag arguments:
  • json: the recommended format to use. Supported by all PVS-Studio plugins and utilities. This format is recommended to use if you need to combine several reports into one or to convert a Plog report into the JSON format;
  • html: an HTML file format. This report is easy to use for automated emails;
  • fullhtml: an HTML file format. If you choose this format, PlogConverter converts the analyzer messages and source files to html files. This allows you to view the analyzer, sort messages and navigate through code in a browser. When you pass this value, you must also pass the ‑‑output (-o) argument. As a result of conversion, you'll get a directory located on the path set via the '-o' flag. If you set the '-n' parameter or set two or more report formats, the directory will have the '.fullhtml' postfix;
  • errorfile: the GCC and Clang output format;
  • errorfile-verbose: the extended 'errorfile' output format that supports displaying additional items (if there are any);
  • csv: a report format with delimiters. It's convenient to use in Microsoft Excel.
  • tasklist: a report format for viewing in Qt Creator;
  • tasklist-verbose: the extended 'tasklist' output format that supports displaying additional items (if there are any);
  • teamcity: a report format for uploading and viewing in TeamCity CI.
  • sarif: an open format for data exchanging between static analysis tools. You can read more here;
  • sarif-vscode: the extended Sarif report format. Suitable for working with the Sarif Viewer plugin for Visual Studio Code;
  • totals: a report format that contains a summary about the number of warnings that belong to different groups (GA, OP, 64, CS, MISRA, ...) and different levels of certainty. You can find a detailed description of warning levels and diagnostic groups in our documentation, section "Getting acquainted with the PVS-Studio static code analyzer on Windows";
  • misra-compliance: a report format for checking code for compliance with MISRA. When you pass this value, you must also pass the ‑‑output (-o) argument.
  • gitlab: a report format compatible with GitLab Code Quality.
  • defectdojo : a report format for uploading and viewing in DefectDojo.
• ‑‑analyzer (or -a): filters warnings by mask. The filtering mask has the following form: 'MessageType:MessageLevels'. 'MessageType' can be one of the following types: GA, OP, 64, CS, MISRA, Fail, OWASP. 'MessageLevels' can take values from 1 to 3. A combination of various masks is possible, just separate them with ";" (without spaces). By default, only warnings from General Analysis Level 1 and 2 will remain in the report. Default value: GA:1,2
• ‑‑output (or -o): a path to the output's file/directory. If the flag is not set, the output will be sent to a standard output thread. Besides:
  • If you specify two or more report formats, this parameter is interpreted as a path to the resulting directory where all generated reports will be located. During generation, an extension corresponding to the format will be added to each file.
  • If you specify one report format, then as a result you'll get either a file or a directory — depending on the format.
• ‑‑stdout: allows you to duplicate the report text into a standard output, if you set the –output flag.
• ‑‑settings (or -s): a path to the configuration file. The file is similar to the PVS-Studio.cfg configuration file. This file provides information about excluded directories (exclude-path).
• ‑‑srcRoot (or -r): sets the replacement for the "SourceTreeRoot" marker. If during the check the path to the root directory of the project was replaced with the "SourceTreeRoot" marker (|?|), then this parameter becomes mandatory (otherwise the project files will not be found).
• ‑‑excludedCodes (or -d): a comma-separated list of excluded diagnostics: "-d V595,V730".
• ‑‑errorCodeMapping (or -m): enable displaying CWE ID and/or SAST ID for found warnings: "-m cwe,misra,autosar,owasp". If the 'cwe' value is specified, warnings in the report will have CWE ID. If 'misra', 'autosar' or 'owasp' is specified, then SAST IDs will be displayed for the rules of the corresponding standard.
• ‑‑includePaths (or -I): include in the report only warnings issued on specified files. You can use this parameter to pass file paths (absolute or relative) or the template (glob). If you need to include several files, pass each path via this parameter. Note that you can include paths only for those reports that don't contain the SourceTreeRoot marker.
• ‑‑excludePaths (or -E): excludes from the report all warnings issued in certain files. You can use this parameter to pass file paths (absolute or relative) or the template (glob). If you need to exclude several files, pass each path via this parameter. Note that you can exclude paths only for those reports that don't contain the SourceTreeRoot marker.
• ‑‑cerr (or -e): use stderr instead of stdout.
• ‑‑grp: path to the Guideline Re-categorization Plan text file. It's only used if a MISRA Compliance report is generated. Guideline Re-categorization Plan is a file that specifies the category changes for the MISRA rules. You can read more about the MISRA rules category here.
• ‑‑indicateWarnings (or -w): sets the plog-converter utility's return code that equals '2' if warnings remain in the filtered output file(s) after the log was filtered.
• ‑‑pathTransformationMode (or -R): sets the path conversion mode when converting a report. This option requires "‑‑srcRoot". This option works only for those formats that support relative paths: json. Available options:
  • toAbsolute – the paths are converted to absolute;
  • toRelative – the paths are converted to relative.
• ‑‑misraDeviations: specifies MISRA violations. If you list the MISRA rules and separate them with ";", the listed rules won't be taken into account. If all the MISRA violations found by the analyzer are specified in the ‑‑misraDeviations option, the final report will show that the project complies with the MISRA standard.
• ‑‑noHelpMessages: exclude links to the documentation from the analyzer's warnings.
• ‑‑name (or -n): a template name for the resulting reports when generating two or more report formats. The corresponding extension will be added to the template name. By default, when multiple reports are generated, the input report name is used without the extension. If there are several input reports, the name will be 'MergedReport'.
• ‑‑keepFalseAlarms: preserve warnings marked as False Alarms in the report.

Exit codes

Description of the plog-converter exit codes:

• '0' — the report was successfully converted;
• '1' — general (non-specific) error in the utility's work, an exception was caught during the work. Usually it means that the plog-converter code has an error.
• '2' — an output file has unfiltered or unsuppressed warnings. To make this mode work, pass the ‑‑indicate-warnings (-w) flag to the utility;
• '5' — there was an attempt to replace absolute paths with relative ones, but the report format doesn't support this option.

Example of a conversion command

plog-converter -t json -t csv -a 'GA:1,2;OWASP:1' -o /home/user/Logs
-r /home/user/projects/projectName -m cwe -m owasp -n PVS-Log PVS-Studio.log

Here's what happens:

• 'PVS-Studio.log' is converted to the JSON and CSV formats;
• the resulting report will contain 1st and 2nd level warnings of the General Analysis diagnostic group, and 1st level warnings from the OWASP diagnostic group;
• the '|?|' in the paths to files is replaced by '/home/user/projects/projectName';
• the analyzer warnings will have CWE_ID and SAST_ID;
• the converted reports are located in the '/home/user/Logs' folder and are named as 'PVS-Log.json' and 'PVS-Log.csv'.

Automatic notifications of the analyzer warnings

The PVS-Studio distribution kit includes the BlameNotifier utility. It helps notify the developers about errors in the code they committed to the repository. It is also possible to set up notifications about all detected warnings for a certain circle of people. This utility can be helpful for managers and team leads.

You can read more about this utility in the following documentations section: "Notifying the developer teams (blame-notifier utility)".