Интеграция PVS-Studio Java в сборочную систему Gradle
- Интеграция плагина PVS-Studio в Gradle
- Запуск анализа
- Запуск анализа без доступа к сети
- Конфигурация
- Обновление PVS-Studio Java анализатора
Статический анализатор кода PVS-Studio Java состоит из 2-х основных частей: ядра, выполняющего анализ, и плагинов для интеграции в сборочные системы (Maven и Gradle) и IDE (IntelliJ IDEA и Android Studio).
Функции плагинов:
- Предоставление удобного интерфейса для запуска и настройки анализатора;
- Развёртывание в системе ядра анализатора;
- Сбор и передача данных (наборы исходных файлов и classpath) о структуре проекта ядру анализатора.
Интеграция плагина PVS-Studio в Gradle
Для интеграции плагина при использовании Groovy DSL необходимо добавить следующий код в скрипт сборки build.gradle
:
buildscript {
repositories {
mavenCentral()
maven {
url uri('https://cdn.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']
}
Для Kotlin DSL необходимо добавить следующий код в build.gradle.kts
:
import com.pvsstudio.WarningGroup
buildscript {
repositories {
mavenCentral()
maven {
url = uri("https://cdn.pvs-studio.com/java/pvsstudio-maven-repository/")
}
}
dependencies {
classpath("com.pvsstudio:pvsstudio-gradle-plugin:latest.release")
}
}
apply<com.pvsstudio.PvsStudioGradlePlugin>()
extensions.configure<com.pvsstudio.AnalyzerConfig>("pvsstudio") {
outputType = "text"
outputFile = ".pvs/output.txt"
analysisMode = setOf(WarningGroup.GA, WarningGroup.OWASP)
}
Запуск анализа
Перед первым запуском анализа вам необходимо будет ввести лицензию. Как это сделать — можно узнать в этой документации.
Для запуска анализа выполните команду:
./gradlew pvsAnalyze
Обратите внимание: при анализе проекта плагин запускает ядро Java анализатора. При запуске ядра анализатора будет использована версия языка Java, соответствующая версии JDK, из которого используется файл java
для запуска ядра Java анализатора через настройку плагина javaPath
). Если хотите изменить версию языка Java, которая будет использована при анализе, то используйте для запуска ядра Java анализатора файл java
из JDK соответствующей версии.
Запуск анализа без доступа к сети
Для работы плагина нужно скачать его зависимости. Если вам нужно работать с плагином в системе без доступа в сеть, вы должны создать офлайн репозиторий c зависимостями плагина.
Для загрузки зависимостей и подготовки к офлайн использованию примените такую команду:
./gradlew build --refresh-dependencies
Запускать эту команду нужно из директории с файлом build.gradle
(корневой директории проекта). В этом случае все необходимые зависимости для сборки и анализа проекта будут сохранены в стандартной папке локального репозитория:
- Windows:
%userprofile%/.gradle/caches/modules-2/files-2.1
- Linux/macOS:
~/.gradle/caches/modules-2/files-2.1
.
Вы должны иметь подключение к сети во время запуска этой команды, чтобы зависимости могли загрузиться. Для последующей работы интернет-соединение уже не нужно.
В системе должно быть установлено ядро Java той же версии, что и плагин. Узнать, как установить ядро Java анализатора, можно в отдельной документации.
Использование анализатора в таком случае не отличается от обычного. Для того чтобы Gradle не начинал скачивать зависимости, используйте флаг ‑‑offline
. Команда запуска анализа в офлайн режиме:
./gradlew pvsAnalyze –-offline
Конфигурация
Ниже представлен список настроек анализатора, которые могут быть указаны в блоке pvsstudio
файла build.gradle
(для Groovy DSL) или build.gradle.kts
(для Kotlin DSL):
outputType = "TYPE"
(Groovy/Kotlin) — формат, в котором будет представлен отчёт анализатора (text
,log
,json
,xml
,tasklist
,html
,fullhtml
,errorfile
). Значение по умолчанию:json
;outputFile = "PATH"
(Groovy/Kotlin) — путь до файла с отчётом, куда будут записаны результаты анализа. Формат содержимого не зависит от расширения файла, указанного в данном параметре. Значение по умолчанию:$projectDir/PVS-Studio
+расширение формата из настройки outputType
. Для отчёта в форматеfullhtml
необходимо указать директорию, в которой будет создана папка с именемfullhtml
, содержащая файл отчёта анализатора (index.html
). Значение по умолчанию:$projectDir/fullhtml
.
Внимание. Вместо использования настройки outputFile
более предпочтительным сценарием является использование консольных утилит PlogConverter (Windows) и plog-converter (Linux и macOS). Эти утилиты позволяют конвертировать отчёт анализатора в большее количество форматов (например, SARIF), а также предоставляют дополнительные возможности: фильтрация предупреждений из отчёта, преобразование путей в отчёте с абсолютных на относительные и наоборот, получение разницы между отчётами и др.
licensePath = "PATH"
(Groovy/Kotlin) — путь до файла с лицензией. Допустимые расширения файла: .xml, .lic. Значение по умолчанию:- Windows:
%APPDATA%/PVS-Studio/Settings.xml
, - macOS и Linux:
~/.config/PVS-Studio/PVS-Studio.lic
.
- Windows:
threadsNum = NUMBER
(Groovy/Kotlin) — данный параметр позволяет задать число потоков, на которое будет распараллелен анализ. Возможно задать эту настройку для всей системы в файлеglobal.json
. Значение по умолчанию:число доступных процессоров
;sourceTreeRoot = "PATH"
(Groovy/Kotlin) — корневая часть пути, которую анализатор будет использовать при генерации относительных путей в диагностических сообщениях. По умолчанию при генерации диагностических сообщений PVS-Studio выдаёт абсолютные пути до файлов, на которые анализатор выдал срабатывания. С помощью данной настройки можно задать корневую часть пути (путь до директории), которую анализатор будет автоматически подменять на специальный маркер. Замена произойдет, если путь до файла начинается с заданной корневой части. В дальнейшем отчёт с относительными путями возможно использовать для просмотра результатов анализа в окружении с отличающимся расположением исходных файлов. Например, в разных операционных системах. Значение по умолчанию отсутствует;analysisMode = ["GA", ....]
(Groovy) /setOf(WarningMode.GA, ....)
(Kotlin) — список активных групп диагностических правил. Доступные группы:GA
(правила общего назначения),OWASP
(правила согласно OWASP ASVS). НастройкиenabledWarnings
,disabledWarnings
иadditionalWarnings
имеют больший приоритет, чем эта настройка. То есть, если диагностическая группа отключена (или включена), то можно при анализе включить (или отключить) отдельные диагностики при помощи этих настроек. Значение по умолчанию:GA
;enabledWarnings = ["VXXXX", ....]
(Groovy) /setOf("VXXXX", ....)
(Kotlin) — список активных диагностик. Во время анализа будут использованы только те диагностики, которые заданы в этом списке. При отсутствии значения данной настройки все диагностики считаются включёнными, если дополнительно не задана настройкаdisabledWarnings
. Эта настройка имеет меньший приоритет чем, настройкаdisabledWarnings
иadditionalWarnings
, но больший, чем настройкаanalysisMode
. Значение по умолчанию отсутствует;disabledWarnings = ["VXXXX", ....]
(Groovy) /setOf("VXXX", ....)
(Kotlin) — список выключенных диагностик. Диагностики, перечисленные в этом списке, не будут применены во время анализа. При отсутствии данной настройки все диагностики считаются включёнными, если дополнительно не задана настройкаenabledWarnings
. Эта настройка имеет больший приоритет, чем настройкиenabledWarnings
иanalysisMode
, но меньший, чемadditionalWarnings
. Значение по умолчанию отсутствует;additionalWarnings = ["VXXXX", ....]
(Groovy) /setOf("VXXXX", ....)
(Kotlin) — список включённых по умолчанию диагностик, которые будут добавлены к анализу. Если диагностика добавлена в этот список, то наличие её в спискахenabledWarnings
иdisabledWarnings
игнорируется. Кроме того, эта диагностика будет включена, даже если группа диагностик, в которую она входит, отключена (т.е. вanalysisMode
не содержится этой группы). Эта настройка имеет больший приоритет, чем настройкиenabledWarnings
,disabledWarnings
иanalysisMode
. Значение по умолчанию отсутствует;exclude = ["PATH", ....]
(Groovy) /setOf("PATH", ....)
(Kotlin) — список файлов и/или директорий, которые нужно исключить из анализа (абсолютные или относительные пути, которые будут раскрыты относительно корневой директории проекта). При отсутствии данной настройки будут проанализированы все файлы, если дополнительно не задана настройкаanalyzeOnly
илиanalyzeOnlyList
. Эта настройка имеет больший приоритет, чем настройкиanalyzeOnly
иanalyzeOnlyList
. Значение по умолчанию отсутствует;analyzeOnly = ["PATH", ....]
(Groovy) /setOf("PATH", ....)
(Kotlin) — список файлов и/или директорий, которые нужно проанализировать (абсолютные или относительные пути, которые будут раскрыты относительно корневой директории проекта). Также можно записать эти пути построчно в файл и передать путь до этого файла в настройкуanalyzeOnlyList
. При отсутствии данной настройки будут проанализированы все файлы, если дополнительно не задана настройкаexclude
илиanalyzeOnlyList
. Эта настройка имеет меньший приоритет, чем настройкаexclude
. Файлы и/или директории, переданные в этой настройке, объединяются в общий список с файлами и/или директориями из настройкиanalyzeOnlyList
. Значение по умолчанию отсутствует;analyzeOnlyList = "PATH"
(Groovy/Kotlin) — путь к текстовому файлу, содержащему список путей к файлам и/или каталогам для анализа (каждая запись должна быть на отдельной строке). Поддерживаются относительные (будут раскрыты относительно корневой директории проекта) и абсолютные пути. При отсутствии данной настройки будут проанализированы все файлы, если дополнительно не задана настройкаexclude
илиanalyzeOnly
. Эта настройка имеет меньший приоритет, чем настройкаexclude
. Файлы и/или директории, считанные из файла, указанного в этой настройке, объединяются в общий список с файлами и/или директориями из настройкиanalyzeOnly
. Значение по умолчанию отсутствует;suppressBase = "PATH"
(Groovy/Kotlin) — путь до suppress-файла, содержащего подавленные сообщения анализатора. Сообщения из suppress-файла не попадут в отчёт при последующих проверках проекта. Добавить сообщения в suppress-файл можно через интерфейс плагина PVS-Studio для IntelliJ IDEA и Android Studio, а также при помощи задачиpvsSuppress
из плагинаpvsstudio-gradle-plugin
. Значение по умолчанию:$projectDir/.PVS-Studio/suppress_base.json
;failOnWarnings = BOOLEAN
(Groovy/Kotlin) — флаг, позволяющий завершить задачуpvsAnalyze
неудачей, если анализатор выдал какое-либо предупреждение. Этот флаг позволяет отслеживать наличие предупреждений анализатора в отчёте, полученном при анализе. Данное поведение может быть удобным при интеграции в CI/CD. Значение по умолчанию:false
;incremental = BOOLEAN
(Groovy/Kotlin) — флаг, позволяющий запустить анализ инкрементально. В этом режиме анализируются только изменившиеся файлы. Значение по умолчанию:false
;forceRebuild = BOOLEAN
(Groovy/Kotlin) — флаг, позволяющий принудительно перестроить целиком закэшированную метамодель программы, содержащую информацию о её структуре и типах данных. Перестройка метамодели проекта может быть необходима при обновлении версии анализатора или если метамодель проекта оказалась повреждена. При использовании данной настройки отключается инкрементальный режим анализа проекта (настройкаincremental
). Значение по умолчанию:false
;disableCache = BOOLEAN
(Groovy/Kotlin) — флаг, позволяющий отключить кэширование метамодели программы. При отключённом кэше модель проекта не кэшируется и строится каждый раз заново. Этот флаг бывает полезно использовать при выяснении причин ошибок в анализаторе. При отключении кэширования метамодели проекта также отключается инкрементальный режим анализа проекта (настройкаincremental
). Значение по умолчанию:false
;timeout = NUMBER
(Groovy/Kotlin) — таймаут анализа одного файла (в минутах). Позволяет увеличивать или уменьшать максимальное время, которое анализатор будет тратить на анализ одного файла. Возможно задать эту настройку для всей системы в файлеglobal.json
. Значение по умолчанию:10
;javaPath = "PATH"
(Groovy/Kotlin) — задаёт путь до java интерпретатора, с которым будет запускаться ядро анализатора. Возможно задать эту настройку для всей системы в файлеglobal.json
. Для анализа файлов исходного кода будет использована версия языка Java, соответствующая версии JDK, путь до которой указан в этом параметре. По умолчанию PVS-Studio попытается использовать путь из переменной окруженияPATH
;jvmArguments = ["FLAG", ....]
(Groovy) /setOf("FLAG", ....)
(Kotlin) — дополнительные флаги JVM, с которыми будет запускаться ядро анализатора. Этот флаг позволяет настраивать JVM, которая будет запускать ядро Java анализатора. Возможно задать эту настройку для всей системы в файлеglobal.json
. Значение по умолчанию:["-Xss64m"]
;compatibility = BOOLEAN
(Groovy/Kotlin) — флаг, активирующий диагностическое правило V6078, которое обнаруживает потенциальные проблемы совместимости API между выбранными версиями Java SE. Диагностика V6078 позволяет убедиться, что API JDK, которое вы используете в проекте, не изменится или не исчезнет в более поздних версиях JDK. Значение по умолчанию:false
;sourceJava = NUMBER
(Groovy/Kotlin) — задаёт версию Java SE, на которой разработано приложение. Эта настройка используется диагностикой анализатора V6078, если включена настройкаcompatibility
. Минимальное значение:8
. Максимальное значение:14
;targetJava = NUMBER
(Groovy/Kotlin) — задаёт версию Java SE, на совместимость с которой необходимо проверить API, используемое в приложении (sourceJava
). Эта настройка используется диагностикой анализатора V6078, если включена настройкаcompatibility
. Минимальное значение:8
. Максимальное значение:14
;excludePackages = ["PACK", ....]
(Groovy) /setOf("PACK", ....)
(Kotlin) — пакеты, которые вы хотите исключить из анализа совместимости (диагностика V6078). Эта настройка используется диагностикой анализатора V6078, если включена настройкаcompatibility
. Значение по умолчанию отсутствует.securityRelatedIssues = BOOLEAN
(Groovy/Kotlin) — предупреждения, относящиеся к потенциальным проблемам безопасности и классифицируемые согласно ГОСТ Р 71207-2024, будут выделены дополнительной маркировкой в полеSAST
в результатах анализа.
Настройки могут быть переданы через командную строку в момент запуска анализа. Формат определения:
-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
или build.gradle.kts
у вас всегда будет использоваться последняя версия 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"