Интеграция PVS-Studio Java в сборочную систему Maven

• Интеграция плагина PVS-Studio в Maven
• Запуск анализа
• Запуск анализа без доступа к сети
• Конфигурация
  • Как изменить версию Java для запуска анализатора
• Обновление PVS-Studio Java
  • Использование прокси

Статический анализатор кода PVS-Studio Java состоит из 2-х основных частей: ядра, выполняющего анализ и плагинов для интеграции в сборочные системы (Maven и Gradle) и IDE (PVS-Studio для IntelliJ IDEA и Android Studio).

Функции плагинов:

• Предоставление удобного интерфейса для запуска и настройки анализатора;
• Развёртывание в системе ядра анализатора;
• Сбор и передача данных (наборы исходных файлов и classpath) о структуре проекта ядру анализатора.

Интеграция плагина PVS-Studio в Maven

Для интеграции плагина необходимо добавить следующий код в файл pom.xml:

<pluginRepositories>
  <pluginRepository>
    <id>pvsstudio-maven-repo</id>
    <url>https://files.pvs-studio.com/java/pvsstudio-maven-repository/</url>
  </pluginRepository>
</pluginRepositories>
<build>
  <plugins>
    <plugin>
      <groupId>com.pvsstudio</groupId>
      <artifactId>pvsstudio-maven-plugin</artifactId>
      <version>7.33.85174</version>
      <configuration>
        <analyzer>
          <outputType>text</outputType>
          <outputFile>path/to/output.txt</outputFile>
          <analysisMode>GA,OWASP</analysisMode>
        </analyzer>
      </configuration>
    </plugin>
  </plugins>
</build>

Запуск анализа

Перед запуском анализа вам необходимо будет ввести лицензию. Как это сделать — можно узнать в этой документации.

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

mvn pvsstudio:pvsAnalyze

Кроме того, анализ можно включить в цикл сборки проекта, добавив элемент <execution>:

<plugin>
  <groupId>com.pvsstudio</groupId>
  <artifactId>pvsstudio-maven-plugin</artifactId>
  <version>7.33.85174</version>
  <executions>
    <execution>
      <phase>compile</phase>
      <goals>
        <goal>pvsAnalyze</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Обратите внимание: при анализе проекта плагин запускает ядро Java анализатора. При запуске ядра анализатора будет использована версия языка Java, соответствующая версии JDK, из которого используется файл java для запуска ядра Java анализатора (настройка плагина <javaPath>). Если хотите изменить версию языка Java, которая будет использована при анализе, то используйте для запуска ядра Java анализатора файл java из JDK соответствующей версии.

Запуск анализа без доступа к сети

Для работы плагина нужно скачать его зависимости. Если вам нужно работать с плагином в системе без доступа в сеть, вы должны создать офлайн репозиторий c зависимостями плагина. Для этого вы можете использовать maven-dependency-plugin.

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

mvn dependency:go-offline

Запускать эту команду нужно из директории с файлом pom.xml (корневой директории проекта). В этом случае все необходимые зависимости для сборки и анализа проекта будут сохранены в стандартной папке локального репозитория: %userprofile%/.m2/repository на Windows или ~/.m2/repository на Linux/macOS.

Для сохранения офлайн репозитория в другую папку используйте параметр maven.repo.local. Команда в таком случае будет выглядеть так:

mvn dependency:go-offline -Dmaven.repo.local=/custom/path

Вы должны иметь подключение к сети во время запуска этой команды, чтобы зависимости могли загрузиться. Для последующей работы интернет-соединение уже не нужно.

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

Использование анализатора в таком случае не отличается от обычного. Для того чтобы maven не начинал скачивать зависимости, используйте флаг ‑‑offline(-o). Пример команды запуска анализа в офлайн режиме с использованием пользовательского локального репозитория:

mvn -o pvsstudio:pvsAnalyze -Dmaven.repo.local=/custom/path

Конфигурация

В блоке <analyzer> производится настройка анализатора. Ниже представлен список настроек анализатора.

• <outputType>TYPE</outputType> — формат, в котором будет представлен отчёт анализатора (text, log, json, xml, tasklist, html, fullhtml, errorfile). Значение по умолчанию: json;
• <outputFile>PATH</outputFile> — путь до файла с отчётом анализатора, куда будут записаны результаты анализа. Формат содержимого отчёта анализатора не зависит от расширения файла, указанного в этой настройке. Значение по умолчанию: ${basedir}/PVS-Studio + расширение формата из настройки <outputType>. Для отчёта в формате fullhtml необходимо указать директорию, в которой будет создана папка с именем fullhtml, содержащая файл отчёта анализатора (index.html). Значение по умолчанию: ${basedir}/fullhtml. Внимание. Вместо использования настройки <outputFile> более предпочтительным сценарием является использование консольных утилит PlogConverter (Windows) и plog-converter (Linux и macOS). Эти утилиты позволяют конвертировать отчёт анализатора в большее количество форматов (например, SARIF), а также предоставляют дополнительные возможности: фильтрация предупреждений из отчёта, преобразование путей в отчёте с абсолютных на относительные и наоборот, получение разницы между отчётами и др.;
• <threadsNum>NUMBER</threadsNum> — данный параметр позволяет задать число потоков, на которое будет распараллелен анализ. Возможно задать эту настройку для всей системы в файле global.json. Значение по умолчанию: число доступных процессоров;
• <sourceTreeRoot>PATH</sourceTreeRoot> — корневая часть пути, которую анализатор будет использовать при генерации относительных путей в диагностических сообщениях. По умолчанию при генерации диагностических сообщений PVS-Studio выдаёт абсолютные пути до файлов, на которые анализатор выдал срабатывания. С помощью данной настройки можно задать корневую часть пути (путь до директории), которую анализатор будет автоматически подменять на специальный маркер. Замена произойдет, если путь до файла начинается с заданной корневой части. В дальнейшем отчёт с относительными путями возможно использовать для просмотра результатов анализа в окружении с отличающимся расположением исходных файлов. Например, в разных операционных системах. Значение по умолчанию отсутствует;
• <analysisMode>GA, ....</analysisMode> — список активных групп диагностических правил. Доступные группы: GA (правила общего назначения), OWASP (правила согласно OWASP ASVS). Настройки <enabledWarnings>, <disabledWarnings> и <additionalWarnings> имеют больший приоритет, чем эта настройка. То есть, если диагностическая группа отключена (или включена), то можно включить (или отключить) отдельные диагностики при помощи этих настроек. Значение по умолчанию: GA;
• <enabledWarnings>VXXXX, ....</enabledWarnings> — список активных диагностик. Во время анализа будут использованы только те диагностики, которые заданы в этом списке. При отсутствии значения данной настройки все диагностики считаются включенными, если дополнительно не задана настройка <disabledWarnings>. Эта настройка имеет меньший приоритет чем, настройки <disabledWarnings> и <additionalWarnings>, но больший, чем настройка <analysisMode>. Значение по умолчанию отсутствует;
• <disabledWarnings>VXXXX, ....</disabledWarnings> — список выключенных диагностик. Диагностики, перечисленные в этом списке, не будут применены во время анализа. При отсутствии данной настройки все диагностики считаются включёнными, если дополнительно не задана настройка <enabledWarnings>. Эта настройка имеет больший приоритет, чем настройки <enabledWarnings> и <analysisMode>, но меньший, чем <additionalWarnings>. Значение по умолчанию отсутствует;
• <additionalWarnings>VXXXX, ....</additionalWarnings> — список включённых по умолчанию диагностик, которые будут добавлены к анализу. Если диагностика добавлена в этот список, то наличие её в списках <enabledWarnings> и disabledWarnings> игнорируется. Кроме того, эта диагностика будет включена, даже если группа диагностик, в которую она входит, отключена (т.е. в <analysisMode> не содержится этой группы). Эта настройка имеет больший приоритет, чем настройки <disabledWarnings>, <enabledWarnings> и <analysisMode>. Значение по умолчанию отсутствует;
• <exclude>PATH, ....</exclude> — список файлов и/или директорий, которые нужно исключить из анализа (абсолютные или относительные пути, которые будут раскрыты относительно корневой директории проекта). При отсутствии данной настройки будут проанализированы все файлы, если дополнительно не заданы настройки <analyzeOnly> или <analyzeOnlyList>. Эта настройка имеет больший приоритет, чем настройки <analyzeOnly> и <analyzeOnlyList>. Значение по умолчанию отсутствует;
• <analyzeOnly>PATH, ....</analyzeOnly> — список файлов и/или директорий, которые нужно проанализировать (абсолютные или относительные пути, которые будут раскрыты относительно корневой директории проекта). Также можно записать эти пути построчно в файл и передать путь до этого файла в настройку <analyzeOnlyList>. При отсутствии данной настройки будут проанализированы все файлы, если дополнительно не задана настройка <exclude> или <analyzeOnlyList>. Эта настройка имеет меньший приоритет, чем настройка <exclude>. Файлы и/или директории, переданные в этой настройке, объединяются в общий список с файлами и/или директориями из настройки <analyzeOnlyList>. Значение по умолчанию отсутствует;
• <analyzeOnlyList>PATH</analyzeOnlyList> — аналог настройки <analyzeOnly>. Путь к текстовому файлу, содержащему список путей к файлам и/или каталогам для анализа (каждая запись должна быть на отдельной строке). Поддерживаются относительные (будут раскрыты относительно корневой директории проекта) и абсолютные пути. При отсутствии данной настройки будут проанализированы все файлы, если дополнительно не задана настройка <exclude> или <analyzeOnly>. Эта настройка имеет меньший приоритет, чем настройка <exclude>. Файлы и/или директории, считанные из файла, указанного в этой настройке, объединяются в общий список с файлами и/или директориями из настройки <analyzeOnly>. Значение по умолчанию отсутствует;
• <suppressBase>PATH</suppressBase> — путь до suppress-файла, содержащего подавленные сообщения анализатора. Сообщения из suppress-файла не попадут в отчёт при последующих проверках проекта. Добавить сообщения в suppress-файл можно через интерфейс плагина PVS-Studio для IntelliJ IDEA и Android Studio, а также при помощи задачи pvsstudio:pvsSuppress из плагина pvsstudio-maven-plugin. Значение по умолчанию: ${basedir}/.PVS-Studio/suppress_base.json;
• <failOnWarnings>BOOLEAN</failOnWarnings> — флаг, позволяющий завершить задачу pvsstudio:pvsAnalyze неудачей, если анализатор выдал какое-либо предупреждение. Этот флаг позволяет отлеживать наличие предупреждений анализатора в отчёте, полученном при анализе. Данное поведение может быть удобным при интеграции в CI/CD. Значение по умолчанию: false;
• <incremental>BOOLEAN</incremental> — флаг, позволяющий запустить анализ инкрементально. В этом режиме анализируются только изменившиеся файлы. Значение по умолчанию: false;
• <forceRebuild>BOOLEAN</forceRebuild> — флаг, позволяющий принудительно перестроить целиком закэшированную метамодель программы, содержащую информацию о её структуре и типах данных. Перестройка метамодели проекта может быть необходима при обновлении версии анализатора или если метамодель проекта оказалась повреждена. При использовании данной настройки отключается инкрементальный режим анализа проекта (настройка <incremental>). Значение по умолчанию: false;
• <disableCache>BOOLEAN</disableCache> — флаг, позволяющий отключить кэширование метамодели программы. При отключённом кэше модель проекта не кэшируется и строится каждый раз заново. Этот флаг бывает полезно использовать при выяснении причин ошибок в анализаторе. При использовании данной настройки отключается инкрементальный режим анализа проекта (настройка <incremental>). Значение по умолчанию: false;
• <timeout>NUMBER</timeout> — таймаут анализа одного файла (в минутах). Позволяет увеличивать или уменьшать максимальное время, которое анализатор будет тратить на анализ одного файла. Возможно задать эту настройку для всей системы в файле global.json. Значение по умолчанию: 10;
• <javaPath>PATH</javaPath> — задаёт путь до java интерпретатора, с которым будет запускаться ядро анализатора. Возможно задать эту настройку для всей системы в файле global.json. Для анализа файлов исходного кода будет использована версия языка Java, соответствующая версии JDK, путь до которой указан в этом параметре. По умолчанию PVS-Studio попытается использовать путь из переменной окружения PATH;
• <jvmArguments>FLAG, ....</jvmArguments> — дополнительные флаги JVM, с которыми будет запускаться ядро анализатора. Этот флаг позволяет настраивать JVM, которая будет запускать ядро Java анализатора. Возможно задать эту настройку для всей системы в файле global.json. Значение по умолчанию: ["-Xss64m"];
• <compatibility>BOOLEAN</compatibility> — флаг, активирующий диагностическое правило V6078, которое обнаруживает потенциальные проблемы совместимости API между выбранными версиями Java SE. Диагностика V6078 позволяет убедиться, что API JDK, которое вы используете в проекте, не изменится или не исчезнет в более поздних версиях JDK. Значение по умолчанию: false;
• <sourceJava>NUMBER</sourceJava> — версия Java SE, на которой разработано ваше приложение. Эта настройка используется диагностикой анализатора V6078, если включена настройка <compatibility>. Минимальное значение: 8. Максимальное значение: 14;
• <targetJava>NUMBER</targetJava> — версия Java SE, на совместимость с которой вы хотите проверить API, используемое в вашем приложении (<sourceJava>). Эта настройка используется диагностикой анализатора V6078, если включена настройка <compatibility>. Минимальное значение: 8. Максимальное значение: 14;
• <excludePackages>"PACK", ....</excludePackages> — пакеты, которые вы хотите исключить из анализа совместимости JDK API (диагностика V6078). Эта настройка используется диагностикой анализатора V6078, если включена настройка <compatibility>. Значение по умолчанию отсутствует.

Настройки могут быть переданы через командную строку в момент запуска анализа. Формат определения:

-Dpvsstudio.<nameSingleParam>=value 
-Dpvsstudio.<nameMultipleParam>=value1;value2;value3

Пример:

mvn pvsstudio:pvsAnalyze -Dpvsstudio.outputType=text
                         -Dpvsstudio.outputFile=path/to/output.txt
                         -Dpvsstudio.disabledWarnings=V6001;V6002;V6003

Обратите внимание, что параметры, явно переданные в командной строке, имеют наивысший приоритет.

Как изменить версию Java для запуска анализатора

По умолчанию анализатор запускает ядро с java из переменной окружения PATH. Если необходимо запустить анализ с другой версией, её можно указать вручную. Для этого в настройке анализатора <javaPath> укажите путь до java из JDK. Версия этой JDK (версия языка Java) будет использована при анализе исходного кода проекта:

....
<javaPath>C:/Program Files/Java/jdk19.0.5/bin/java</javaPath>
....

Обновление PVS-Studio Java

Для обновления pvsstudio-maven-plugin необходимо изменить версию плагина в файле pom.xml.

Использование прокси

При использовании прокси необходимо указать логин и пароль для корректной загрузки ядра анализатора.

Это можно сделать через аргументы:

• -Dhttp.proxyUser, -Dhttp.proxyPassword
• -Dhttps.proxyUser, -Dhttps.proxyPassword
• -Djava.net.socks.username, -Djava.net.socks.password
• -Dftp.proxyUser, -Dftp.proxyPassword

Команда для запуска анализа через плагин для Maven с прокси:

mvn pvsstudio:pvsAnalyze "-Dhttp.proxyUser=USER" "-Dhttp.proxyPassword=PASS"