Просмотр и конвертация результатов анализа (форматы SARIF, HTML и др.)

• Поддерживаемые форматы
• Утилита PlogConverter (Windows)
  • Описание
  • Параметры
  • Коды возврата
  • Пример команды конвертации
• Утилита plog-converter (Linux, macOS)
  • Описание
  • Параметры
  • Коды возврата
  • Пример команды конвертации
• Автоматическое оповещение о предупреждениях анализатора

Результатом анализа проекта с помощью PVS-Studio может быть:

• необработанный вывод анализатора;
• Plog-отчёт;
• JSON-отчёт.

Полученные файлы можно просматривать в плагине PVS-Studio для IDE или в приложении C and C++ Compiler Monitoring UI.

Эти форматы отчёта неудобны для прямого просмотра в текстовом редакторе или рассылки по электронной почте. Поэтому в состав дистрибутива PVS-Studio входит специальная утилита, позволяющая преобразовывать результаты анализа в другие форматы.

Название утилиты преобразования отчётов зависит от платформы:

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

Поддерживаемые форматы

Приведём далее список форматов, поддерживаемых утилитой конвертации отчётов.

Утилита PlogConverter (Windows)

Описание

Для преобразования отчёта PVS-Studio в один из перечисленных форматов можно воспользоваться утилитой PlogConverter, поставляемой в дистрибутиве PVS-Studio для Windows. Утилиту PlogConverter можно найти в установочной директории PVS-Studio (по умолчанию это путь C:\Program Files (x86)\PVS-Studio). Кроме этого, исходный код утилиты доступен на GitHub.

Параметры

Флаг "‑‑help" выведет основную информацию об утилите:

PlogConverter.exe –-help

Для запуска утилиты в командной строке терминала выполнить:

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

Параметры утилиты:

• ‑‑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".
  • TaskList: формат отчёта для просмотра в Qt Creator.
  • TeamCity: формат отчёта, предназначенный для загрузки и просмотра в TeamCity CI.
  • Sarif: открытый формат для обмена данными между инструментами статического анализа. Более подробно о нём можно прочитать здесь.
  • SarifVSCode: расширенный формат отчёта Sarif. Подходит для работы с плагином Sarif Viewer для Visual Studio Code.
  • MisraCompliance: формат отчёта о проверке кода на соответствие стандарту MISRA.
  • GitLab: формат отчёта совместимый с GitLab Code Quality.
  • DefectDojo: формат отчёта, предназначенный для загрузки и просмотра в DefectDojo.
• ‑‑analyzer (или -a): производит фильтрацию предупреждений по маске. Маска фильтрации имеет вид: 'MessageType:MessageLevels'. 'MessageType' может принимать один из следующих типов: GA, OP, 64, CS, MISRA, Fail, OWASP, AUTOSAR. 'MessageLevels' может принимать значения от 1 до 3.
• ‑‑excludedCodes (или -d): задает список предупреждений (через ","), которые нужно исключить из результирующего отчёта.
• ‑‑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, можно прочитать здесь.
• ‑‑noHelpMessages: исключить из предупреждений анализатора ссылки на документацию диагностических правил.
• ‑‑keepFalseAlarms (или -f): сохранить в отчете предупреждения, отмеченные как ложные.
• ‑‑countWarnings (или -с): позволяет отобразить количества сообщений, соответствующее аргументам данной команды. Формат команды -c {Группы или Коды диагностик}:{Уровни };{Другие аргументы }... Пример команд: -c GA:1,2;OP:1 | -c V003 | -c V502,V504:1 | -c ALL.
• ‑‑generateDiffWith (или -D): генерирует отчёт с различиями между отчётом указанном в данной опции и входным отчётом.
• ‑‑filterSecurityRelatedIssues: оставляет в результирующем отчёте только сообщения, имеющие маркировку по ГОСТ Р 71207-2024.

Коды возврата

Утилита PlogConverter имеет несколько ненулевых кодов возврата, которые не означают проблемы в работе самой утилиты. Если утилита вернула не '0', это ещё не значит, что она отработала с ошибкой.

Описание кодов возврата PlogConverter:

• '0' — конвертация отчёта прошла успешно;
• '1' — при генерации одного из выходных файлов возникла ошибка;
• '2' — выходной отчёт содержит неотфильтрованные или неподавленные предупреждения. Чтобы этот режим работал, утилите нужно передать флаг ‑‑indicateWarnings (-w);
• '3' — общая (неспецифичная) ошибка при работе утилиты, перехваченное исключение при работе. Обычно это сигнализирует о наличии ошибки в коде самого PlogConverter;
• '4' — утилите были переданы неверные аргументы командной строки или один из файлов, переданный как аргумент, не был найден.
• '5' — ошибка при попытке заменить абсолютные пути на относительные в формате отчёта, который это не поддерживает.

Пример команды конвертации

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 и macOS. После установки пакета или из архива PVS-Studio C/C++ вы сможете использовать утилиту plog-converter для конвертации отчётов анализатора в различные форматы (*.xml, *.tasks и т.п.). Кроме этого, исходный код утилиты доступен на GitHub.

Параметры

Флаг "‑‑help" выведет основную информацию об утилите:

plog-converter --help

Для запуска утилиты в командной строке терминала выполнить:

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

Все опции могут быть указаны в произвольном порядке.

Доступные опции:

• ‑‑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: открытый формат для обмена данными между инструментами статического анализа. Более подробно можно прочитать здесь;
  • sarif-vscode: расширенный формат отчёта Sarif. Подходит для работы с плагином Sarif Viewer для Visual Studio Code;
  • totals: формат отчёта, содержащий суммарную информацию о количестве предупреждений разных типов (GA, OP, 64, CS, MISRA, ...) и разных уровней достоверности. Детальное описание уровней достоверности предупреждений и наборов диагностических правил приведено в разделе документации "Знакомство со статическим анализатором кода PVS-Studio";
  • 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,misra,autosar,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, можно прочитать здесь.
• ‑‑indicateWarnings (или -w): устанавливает возвращаемый код утилиты plog-converter, равный '2', если после фильтрации лога в отфильтрованном выходном файле (файлах) остались предупреждения.
• ‑‑pathTransformationMode (или -R): устанавливает режим преобразования путей при конвертации отчёта. Опция требует "‑‑srcRoot". Опция работает только для тех форматов, которые поддерживают относительные пути: json. Допустимые значения:
  • toAbsolute – пути преобразуются в абсолютные;
  • toRelative – пути преобразуются в относительные.
• ‑‑misraDeviations: позволяет указать нарушения MISRA. Нужно перечислить через ";" правила MISRA, для которых не будут учитываться нарушения. Если все найденные анализатором нарушения MISRA указаны в опции ‑‑misraDeviations, то в итоговом отчёте проект будет считаться удовлетворяющим стандарту MISRA.
• ‑‑noHelpMessages: исключить из предупреждений анализатора ссылки на документацию диагностических правил.
• ‑‑name (или -n): шаблонное имя для результирующих отчетов. Используется для генерации двух и более форматов отчета – во время работы к шаблонному имени будет добавлено соответствующее расширение. По умолчанию при генерации нескольких отчетов используется имя входного отчета без расширения. При этом если входных отчетов несколько, то имя будет 'MergedReport'.
• ‑‑keepFalseAlarms: сохранить в отчете предупреждения, отмеченные как ложные.

Коды возврата

Описание кодов возврата plog-converter:

• '0' — конвертация отчёта прошла успешно;
• '1' — общая (неспецифичная) ошибка при работе утилиты, перехваченное исключение при работе. Обычно это сигнализирует о наличии ошибки в коде 'plog-converter'а;
• '2' — выходной отчёт содержит неотфильтрованные или неподавленные предупреждения. Чтобы этот режим работал, утилите нужно передать флаг ‑‑indicate-warnings (-w).
• '5' — ошибка при попытке заменить абсолютные пути на относительные в формате отчёта, который это не поддерживает.

Пример команды конвертации

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