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

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

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

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

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

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

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

buildscript {
  repositories {
    mavenCentral()
    maven {
      url uri('https://files.pvs-studio.com/java/pvsstudio-maven-repository/')
    }
  }
  dependencies {
    classpath 'com.pvsstudio:pvsstudio-gradle-plugin:latest.release'
  }
}
apply plugin: com.pvsstudio.PvsStudioGradlePlugin
pvsstudio {
  outputType = 'text'
  outputFile = 'path/to/output.txt'
  analysisMode = ['GA', 'OWASP']
}

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

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

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

./gradlew pvsAnalyze

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

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

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

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

./gradlew build --refresh-dependencies

Запускать эту команду нужно из директории с файлом build.gradle (корневой директории проекта). В этом случае все необходимые зависимости для сборки и анализа проекта будут сохранены в стандартной папке локального репозитория: %userprofile%/.gradle/caches/modules-2/files-2.1 на Windows или ~/.gradle/caches/modules-2/files-2.1 на Linux/macOS.

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

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

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

./gradlew pvsAnalyze –-offline

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

Ниже представлен список настроек анализатора, которые могут быть указаны в блоке pvsstudio файла build.gradle:

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

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

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

Пример:

./gradlew pvsAnalyze -Ppvsstudio.outputType=text
                     -Ppvsstudio.outputFile=path/to/output.txt
                     -Ppvsstudio.disabledWarnings=V6001;V6002;V6003

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

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

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

....
javaPath = "C:/Program Files/Java/jdk19.0.5/bin/java"
....

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

Благодаря использованию latest.release в качестве версии плагина в файле build.gradle у вас всегда будет использоваться последняя версия PVS-Studio для анализа.

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

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

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

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

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

./gradlew pvsAnalyze "-Dhttp.proxyUser=USER" "-Dhttp.proxyPassword=PASS"