# Просмотр и конвертация результатов анализа \(форматы SARIF, HTML и др\.\) Результатом анализа проекта с помощью PVS\-Studio может быть: * необработанный вывод анализатора; * Plog\-отчёт; * JSON\-отчёт\. Полученные файлы можно просматривать в плагине PVS\-Studio для IDE или в приложении _C and C\+\+ Compiler Monitoring UI_\. Эти форматы отчёта неудобны для прямого просмотра в текстовом редакторе или рассылки по электронной почте\. Поэтому в состав дистрибутива PVS\-Studio входит специальная утилита, позволяющая преобразовывать результаты анализа в другие форматы\. Название утилиты преобразования отчётов зависит от платформы: * Windows: PlogConverter\.exe; * Linux, macOS: plog\-converter\. ## Поддерживаемые форматы Приведём далее список форматов, поддерживаемых утилитой конвертации отчётов\. |\*\*Формат\*\*|\*\*Расширение\*\*|\*\*Инструменты\*\*|\*\*Описание\*\*| |---|---|---|---| |PVS\\\-Studio Log \\\(Plog\\\)|\\\.plog|Visual Studio,
SonarQube,
Compiler Monitoring UI|Для Windows пользователей Visual Studio и SonarQube| |JSON|\\\.json|Visual Studio
IntelliJ IDEA
Rider
CLion|Для пользователей плагинов PVS\\\-Studio в IDE и SonarQube| |SARIF|\\\.sarif|Visual Studio, Visual Studio Code, есть визуализация в GitHub Actions|Универсальный формат отчёта статического анализатора| |TaskList|\\\.tasks|Qt Creator|Для работы с отчётом в Qt Creator| |TaskList Verbose|\\\.tasks|Qt Creator|Расширение формата TaskList с поддержкой отображения дополнительных позиций| |CSV|\\\.csv|Microsoft Excel
LibreOffice Calc|Для просмотра предупреждений в табличном виде| |Simple Html|\\\.html|Email Client
Browser|Для рассылки отчётов почтой| |Full Html|Folder|Browser|Для просмотра предупреждений с навигацией по коду в браузере| |Error File|\\\.err|IDEs, Vim, Emacs, etc|Для просмотра отчётов в любом редакторе, поддерживающем формат вывода компилятора| |Error File Verbose|\\\.err|IDEs, Vim, Emacs, etc|Расширение формата Error File с поддержкой отображения дополнительных позиций| |TeamCity|\\\.txt|TeamCity|Для загрузки и просмотра предупреждений в TeamCity| |MISRA Compliance|\\\.html|Email Client
Browser|Для проверки кода на соответствие стандартам MISRA| |GitLab|\\\.json|GitLab|Для просмотра предупреждений в формате GitLab Code Quality| |DefectDojo|\\\.json|DefectDojo|Для загрузки и просмотра предупреждений в DefectDojo| |Markdown|\\\.markdown|VS Code, GitHub|Для просмотра предупреждений в формате таблицы Markdown| ## Утилита PlogConverter \(Windows\) ### Описание Для преобразования отчёта PVS\-Studio в один из перечисленных форматов можно воспользоваться утилитой PlogConverter, поставляемой в [дистрибутиве PVS\-Studio для Windows](https://pvs-studio.ru/ru/pvs-studio/download-all/)\. Утилиту PlogConverter можно найти в установочной директории PVS\-Studio \(по умолчанию это путь _C:\\Program Files \(x86\)\\PVS\-Studio_\)\. Кроме этого, исходный код утилиты доступен на [GitHub](https://github.com/viva64/PlogConverter-MSBuild-VS)\. ### Параметры Флаг "\-\-help" выведет основную информацию об утилите: ```cpp PlogConverter.exe –-help ``` Для запуска утилиты в командной строке терминала выполнить: ```cpp PlogConverter.exe [options] ``` Параметры утилиты: * \-\-renderTypes \(или \-t\): указывает форматы, в которые будет преобразован отчёт\. Возможна комбинация разных форматов: для этого их нужно перечислить через запятую\. Если конкретный формат не указан, то отчёт конвертируется во все форматы\. * JSON: рекомендуемый для использования формат отчёта\. Поддерживается всеми плагинами PVS\-Studio для IDE и утилитами\. Этот формат рекомендуется, если нужно объединить несколько отчётов в один или сконвертировать Plog\-отчёт в JSON\-формат\. * Plog: формат отчёта для просмотра на Windows\. Вместо него рекомендуется использовать более универсальный формат JSON\. Формат Plog можно выбрать, если нужно объединить несколько отчётов в один или сконвертировать JSON\-отчёт в Plog\-формат\. * Html: формат отчёта в виде html\-файла\. Такой отчёт удобно использовать для автоматических рассылок на email\. * FullHtml: формат отчёта в виде html\-файла\. При выборе этого формата PlogConverter конвертирует сообщения анализатора и исходные файлы в html\-файлы\. Это позволяет просматривать отчёт анализатора в браузере с сортировкой по сообщениям и навигацией по коду\. Результатом конвертации будет директория с именем 'fullhtml', которая будет находиться по пути, указанному через флаг '\-o'\. При этом если указан параметр '\-n', то директория будет иметь заданное название и постфикс '\.fullhtml'; * Txt: формат отчёта с plaintext\-представлением сообщений анализатора\. * Csv: формат отчёта с разделителями\. Такой отчёт удобно читать в Microsoft Excel\. * Totals: формат отчёта, содержащий суммарную информацию о количестве предупреждений разных типов \(GA, OP, 64, CS, MISRA, \.\.\.\) и разных уровней достоверности\. Детальное описание уровней достоверности предупреждений и наборов диагностических правил приведено в разделе документации "[Знакомство со статическим анализатором кода PVS\-Studio](https://pvs-studio.ru/ru/docs/manual/0007/)"\. * TaskList: формат отчёта для просмотра в Qt Creator\. * TeamCity: формат отчёта, предназначенный для загрузки и просмотра в TeamCity CI\. * Sarif: открытый формат для обмена данными между инструментами статического анализа\. Более подробно о нём можно прочитать [здесь](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sarif)\. * MisraCompliance: формат отчёта о проверке кода на соответствие стандарту MISRA\. * GitLab: формат отчёта совместимый с GitLab Code Quality\. * DefectDojo: формат отчёта, предназначенный для загрузки и просмотра в DefectDojo\. * Markdown: формат отчета в виде таблицы Markdown\. * \-\-analyzer \(или \-a\): производит фильтрацию предупреждений по маске\. Маска фильтрации имеет вид: 'MessageType:MessageLevels'\. 'MessageType' может принимать один из следующих типов: GA, OP, 64, CS, MISRA, Fail, OWASP, AUTOSAR\. 'MessageLevels' может принимать значения от 1 до 3\. * \-\-excludedCodes \(или \-d\): задает список предупреждений \(через ","\), которые нужно исключить из результирующего отчёта\. Например: `-d V595,V730`\. * \-\-includePaths \(или \-i\): позволяет включить в отчет предупреждения, выданные только в определенных файлах\. Через этот параметр вы можете передать список путей \(абсолютных или относительных\) или wildcard\-масок\. В качестве разделителя используется символ ';'\. **Обратите внимание**, что фильтрация путей возможно только для отчетов, не содержащих _SourceTreeRoot_\-маркер\. * \-\-excludePaths \(или \-e\): позволяет исключить все предупреждения, выданные в определенных файлах\. Через этот параметр вы можете передать список путей \(абсолютных или относительных\) или wildcard\-масок\. В качестве разделителя используется символ ';'\. **Обратите внимание**, что исключение путей возможно только для отчетов, не содержащих _SourceTreeRoot_\-маркер\. * \-\-settings \(или \-s\): задаёт путь к файлу настроек PVS\-Studio\. Он содержит различные настройки для анализатора\. PlogConverter прочитает из переданного файла параметр 'DisableDetectableErrors' и исключит предупреждения указанных диагностик из отчёта\. * \-\-srcRoot \(или \-r\): задаёт замену "SourceTreeRoot" маркера\. Если при проверке путь до корневого каталога проекта был заменен на "SourceTreeRoot" маркер \(\|?\|\), то этот параметр становится **обязательным** \(иначе файлы проекта не будут найдены\)\. * \-\-outputDir \(или \-o\): задаёт директорию, куда будут сохранены сконвертированные отчёты\. Если параметр не задан, то файлы записываются в директорию запуска\. * \-\-outputNameTemplate \(или \-n\): задаёт шаблонное имя файла без расширения\. Все сконвертированные отчёты будут иметь одно и то же имя, но разные расширения\. * \-\-errorCodeMapping \(или \-m\): позволяет включить отображение CWE ID и/или SAST ID для найденных предупреждений: "\-m cwe,misra,autosar,owasp"\. Если указано значение 'cwe', то для предупреждений в отчёте будет указано CWE ID\. Если указано 'misra', 'autosar' или 'owasp_', _то для правил соответствующего стандарта будет включено отображение SAST ID\. * \-\-indicateWarnings \(или \-w\): устанавливает возвращаемый код утилиты PlogConverter, равный '2', если после фильтрации лога остались предупреждения\. * \-\-pathTransformationMode \(или \-R\): устанавливает режим преобразования путей при конвертации отчёта\. Опция требует "\-\-srcRoot"\. Опция работает только для тех форматов, которые поддерживают относительные пути: JSON, Plog\. Допустимые значения: * toAbsolute – пути преобразуются в абсолютные; * toRelative – пути преобразуются в относительные\. * \-\-misraDeviations: правила MISRA, для которых не будут учитываться нарушения\. Правила отделяются друг от друга символом ";"\. Если все найденные анализатором нарушения MISRA указаны в опции \-\-misraDeviations, то в итоговом отчёте проект будет считаться удовлетворяющим стандарту MISRA\. * \-\-grp: путь до текстового файла Guideline Re\-categorization Plan\. Эту опцию следует использовать только при генерации отчёта MISRA Compliance\. Guideline Re\-categorization Plan — это файл, в котором указаны изменения категорий для правил MISRA\. Подробнее о том, что такое категория правила MISRA, можно прочитать [здесь](https://pvs-studio.ru/ru/blog/posts/cpp/0863/)\. * \-\-noHelpMessages: исключить из предупреждений анализатора ссылки на документацию диагностических правил\. * \-\-keepFalseAlarms \(или \-f\): сохранить в отчете предупреждения, отмеченные как ложные\. * \-\-countWarnings \(или \-с\): позволяет отобразить количества сообщений, соответствующее аргументам данной команды\. Формат команды \-c \{Группы или Коды диагностик\}:\{Уровни \};\{Другие аргументы \}\.\.\. Пример команд: \-c GA:1,2;OP:1 \| \-c V003 \| \-c V502,V504:1 \| \-c ALL\. * \-\-generateDiffWith \(или \-D\): генерирует отчёт с различиями между отчётом указанном в данной опции и входным отчётом\. * \-\-filterSecurityRelatedIssues: оставляет в результирующем отчёте только сообщения, имеющие маркировку по ГОСТ Р 71207\-2024\. * \-\-csvSeparator: задаёт разделитель столбцов для CSV файлов\. ### Коды возврата Утилита PlogConverter имеет несколько ненулевых кодов возврата, которые не означают проблемы в работе самой утилиты\. Если утилита вернула не '0', это ещё не значит, что она отработала с ошибкой\. Описание кодов возврата PlogConverter: * '0' — конвертация отчёта прошла успешно; * '1' — при генерации одного из выходных файлов возникла ошибка; * '2' — выходной отчёт содержит неотфильтрованные или неподавленные предупреждения\. Чтобы этот режим работал, утилите нужно передать флаг \-\-indicateWarnings \(\-w\); * '3' — общая \(неспецифичная\) ошибка при работе утилиты, перехваченное исключение при работе\. Обычно это сигнализирует о наличии ошибки в коде самого PlogConverter; * '4' — утилите были переданы неверные аргументы командной строки или один из файлов, переданный как аргумент, не был найден\. * '5' — ошибка при попытке заменить абсолютные пути на относительные в формате отчёта, который это не поддерживает\. ### Пример команды конвертации ```cpp 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 ``` В данном примере происходит следующее: * лог с названием 'PVS\-Studio\.log' конвертируется в форматы JSON и CSV; * в итоговый отчёт попадут только предупреждения 1\-го и 2\-го уровней диагностик общего назначения, а также предупреждения 1\-го уровня диагностик OWASP; * маркер '\|?\|' в путях до файлов с ошибками будет заменён на 'D:\\projects\\projectName'; * предупреждения анализатора будут содержать CWE\_ID и SAST\_ID; * сконвертированные отчёты будут находиться в директории 'D:\\Logs' и называться 'PVS\-Log\.json' и 'PVS\-Log\.csv'\. ## Утилита plog\-converter \(Linux, macOS\) ### Описание Для преобразования отчёта PVS\-Studio в один из перечисленных форматов можно воспользоваться утилитой plog\-converter, поставляемой вместе с пакетами и архивами PVS\-Studio С/C\+\+ для [Linux](https://pvs-studio.ru/ru/docs/manual/0039/) и [macOS](https://pvs-studio.ru/ru/docs/manual/0042/)\. После [установки пакета или из архива PVS\-Studio C/C\+\+](https://pvs-studio.ru/ru/pvs-studio/download-all/) вы сможете использовать утилиту plog\-converter для конвертации отчётов анализатора в различные форматы \(\*\.xml, \*\.tasks и т\.п\.\)\. Кроме этого, исходный код утилиты доступен на [GitHub](https://github.com/viva64/plog-converter)\. ### Параметры Флаг "\-\-help" выведет основную информацию об утилите: ```cpp plog-converter --help ``` Для запуска утилиты в командной строке терминала выполнить: ```cpp plog-converter [options] ``` Все опции могут быть указаны в произвольном порядке\. Доступные опции: * \-\-renderTypes \(или \-t\): задает возможные варианты конвертации отчёта\. Это обязательный аргумент запуска утилиты\. Возможна комбинация разных форматов перечислением через повторение \-\-renderTypes \(\-t\) перед каждым форматом или через запятую в качестве аргумента флага: * json: рекомендуемый для использования формат отчёта\. Поддерживается всеми плагинами PVS\-Studio для IDE и утилитами\. Этот формат рекомендуется, если нужно объединить несколько отчётов в один или сконвертировать Plog\-отчёт в JSON\-формат; * html: формат отчёта в виде HTML\-файла\. Такой отчёт удобно использовать для автоматических рассылок на email; * fullhtml: формат отчёта в виде HTML\-файла\. При выборе этого формата plog\-converter конвертирует сообщения анализатора и исходные файлы в html\-файлы\. Это позволяет просматривать отчёт анализатора в браузере с сортировкой по сообщениям и навигацией по коду\. При передаче этого значения нужно обязательно передать аргумент \-\-output \(\-o\)\. Результатом конвертации будет директория по пути, указанному через флаг '\-o'\. При этом если указан параметр '\-n', либо указано два или более форматов отчета, то результирующая директория будет иметь постфикс '\.fullhtml'; * errorfile: формат вывода GCC и Clang; * errorfile\-verbose: расширенный формат вывода 'errorfile' с поддержкой отображения дополнительных позиций \(при их наличии\); * csv: формат отчёта с разделителями\. Такой отчёт удобно читать в Microsoft Excel; * tasklist: формат отчёта для просмотра в Qt Creator; * tasklist\-verbose: расширенный формат вывода 'tasklist' с поддержкой отображения дополнительных позиций \(при их наличии\); * teamcity: формат отчёта, предназначенный для загрузки и просмотра в TeamCity CI; * sarif: открытый формат для обмена данными между инструментами статического анализа\. Более подробно можно прочитать [здесь](https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sarif); * totals: формат отчёта, содержащий суммарную информацию о количестве предупреждений разных типов \(GA, OP, 64, CS, MISRA, \.\.\.\) и разных уровней достоверности\. Детальное описание уровней достоверности предупреждений и наборов диагностических правил приведено в разделе документации "[Знакомство со статическим анализатором кода PVS\-Studio](https://pvs-studio.ru/ru/docs/manual/0007/)"; * misra\-compliance: формат отчёта о проверке кода на соответствие стандарту MISRA\. При передаче этого значения нужно обязательно передать аргумент \-\-output \(\-o\); * gitlab: формат отчёта совместимый с GitLab Code Quality; * defectdojo: формат отчёта, предназначенный для загрузки и просмотра в DefectDojo\. * \-\-analyzer \(или \-a\): производит фильтрацию предупреждений согласно маске\. Маска фильтрации имеет следующий вид: 'MessageType:MessageLevels'\. 'MessageType' может принимать один из следующих типов: GA, OP, 64, CS, MISRA, Fail, OWASP\. 'MessageLevels' может принимать значения от 1 до 3\. Возможна комбинация разных масок через ";" \(без пробелов\)\. По умолчанию в созданном отчёте останутся только предупреждения General Analysis 1 и 2 уровня\. Значение по умолчанию: GA:1,2 * \-\-output \(или \-o\): путь к файлу или директории, куда будет осуществляться вывод\. Если флаг не указан, то вывод будет осуществляться в стандартный поток вывода\. При этом: * Если указано два или более формата отчета, этот параметр интерпретируется как путь до результирующей директории, в которой будут находиться все сгенерированные отчеты\. При генерации к каждому файлу добавится расширение, соответствующее формату\. * Если указан один формат отчета, то результатом будет либо файл, либо директория, в зависимости от формата\. * \-\-stdout: позволяет дублировать текст отчета в стандартный поток вывода, если указан флаг \-\-output\. * \-\-settings \(или \-s\): путь к файлу конфигурации\. Файл аналогичен файлу конфигурации анализатора PVS\-Studio\.cfg\. Из этого файла используется информация об исключённых директориях \(exclude\-path\)\. * \-\-srcRoot \(или \-r\): задает замену "SourceTreeRoot" маркера\. Если при проверке путь до корневого каталога проекта был заменён на "SourceTreeRoot" маркер \(\|?\|\), то этот параметр становится **обязательным** \(иначе файлы проекта не будут найдены\)\. * \-\-excludedCodes \(или \-d\): список исключённых диагностик, разделённых запятыми: "\-d V595,V730"\. * \-\-errorCodeMapping \(или \-m\): включить отображение CWE ID и/или SAST ID для найденных предупреждений: "\-m cwe \-m misra \-m autosar \-m owasp"\. Если указано значение 'cwe', то для предупреждений в отчёте будет указано CWE ID\. Если указано 'misra', 'autosar' или 'owasp_', _то для правил соответствующего стандарта будет включено отображение SAST ID\. * \-\-includePaths \(или \-I\): включить в отчёт только предупреждения, выданные в указанных файлах\. Через этот параметр вы можете передать путь \(абсолютный или относительный\) или шаблон glob\. Если путей несколько, то передайте каждый их них через этот параметр\. **Обратите внимание**, что фильтрация путей возможно только для отчетов, не содержащих _SourceTreeRoot_\-маркер\. * \-\-excludePaths \(или \-E\): позволяет исключить все предупреждения, выданные в определенных файлах\. Через этот параметр вы можете передать путь \(абсолютный или относительный\) или шаблон glob\. Если путей несколько, то передайте каждый их них через этот параметр\. **Обратите внимание**, что исключение путей возможно только для отчетов, не содержащих _SourceTreeRoot_\-маркер\. * \-\-cerr \(или \-e\): использовать _stderr_ вместо _stdout_\. * \-\-grp: путь к текстовому файлу Guideline Re\-categorization Plan\. Используется только при генерации отчёта в формате MISRA Compliance\. Guideline Re\-categorization Plan — это файл, в котором указаны изменения категорий для правил MISRA\. Подробнее о том, что такое категория правила MISRA, можно прочитать [здесь](https://pvs-studio.ru/ru/blog/posts/cpp/0863/)\. * \-\-indicateWarnings \(или \-w\): устанавливает возвращаемый код утилиты plog\-converter, равный '2', если после фильтрации лога в отфильтрованном выходном файле \(файлах\) остались предупреждения\. * \-\-pathTransformationMode \(или \-R\): устанавливает режим преобразования путей при конвертации отчёта\. Опция требует "\-\-srcRoot"\. Опция работает только для тех форматов, которые поддерживают относительные пути: json\. Допустимые значения: * toAbsolute – пути преобразуются в абсолютные; * toRelative – пути преобразуются в относительные\. * \-\-misraDeviations: позволяет указать нарушения MISRA\. Нужно перечислить через ";" правила MISRA, для которых не будут учитываться нарушения\. Если все найденные анализатором нарушения MISRA указаны в опции \-\-misraDeviations, то в итоговом отчёте проект будет считаться удовлетворяющим стандарту MISRA\. * \-\-noHelpMessages: исключить из предупреждений анализатора ссылки на документацию диагностических правил\. * \-\-name \(или \-n\): шаблонное имя для результирующих отчетов\. Используется для генерации двух и более форматов отчета – во время работы к шаблонному имени будет добавлено соответствующее расширение\. По умолчанию при генерации нескольких отчетов используется имя входного отчета без расширения\. При этом если входных отчетов несколько, то имя будет 'MergedReport'\. * \-\-keepFalseAlarms: сохранить в отчете предупреждения, отмеченные как ложные\. * \-\-filterSecurityRelatedIssues: оставляет в результирующем отчёте только сообщения, имеющие маркировку по ГОСТ Р 71207\-2024\. ### Коды возврата Описание кодов возврата plog\-converter: * '0' — конвертация отчёта прошла успешно; * '1' — общая \(неспецифичная\) ошибка при работе утилиты, перехваченное исключение при работе\. Обычно это сигнализирует о наличии ошибки в коде 'plog\-converter'а; * '2' — выходной отчёт содержит неотфильтрованные или неподавленные предупреждения\. Чтобы этот режим работал, утилите нужно передать флаг \-\-indicate\-warnings \(\-w\)\. * '5' — ошибка при попытке заменить абсолютные пути на относительные в формате отчёта, который это не поддерживает\. ### Пример команды конвертации ```cpp 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 ``` В данном примере происходит следующее: * лог с названием 'PVS\-Studio\.log' конвертируется в форматы JSON и CSV; * в итоговый отчёт попадут только предупреждения 1\-го и 2\-го уровней диагностик общего назначения, а также предупреждения 1\-го уровня диагностик OWASP; * в путях до файлов с ошибками маркер '\|?\|' будет заменён на '/home/user/projects/projectName'; * предупреждения анализатора будут содержать CWE\_ID и SAST\_ID; * сконвертированные отчёты будут находиться в папке '/home/user/Logs' и называться 'PVS\-Log\.json' и 'PVS\-Log\.csv'\. ## Автоматическое оповещение о предупреждениях анализатора В составе дистрибутива PVS\-Studio поставляется утилита BlameNotifier\. Она позволяет оповещать разработчиков, заложивших в репозиторий код, на который анализатор выдал предупреждения\. Также возможна настройка оповещения обо всех обнаруженных предупреждениях определённого круга лиц\. Это может быть полезно менеджерам и руководителям команд\. Более подробно данная утилита описана в соответствующем разделе документации: "[Оповещение команд разработчиков \(утилита blame\-notifier\)](https://pvs-studio.ru/ru/docs/manual/0050/)"\.