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

Статический анализатор кода PVS\-Studio Java состоит из 2\-х основных частей: [ядра](https://pvs-studio.ru/ru/docs/manual/6703/), выполняющего анализ и плагинов для интеграции в сборочные системы \(Maven и [Gradle](https://pvs-studio.ru/ru/docs/manual/6706/)\) и IDE \([PVS\-Studio для IntelliJ IDEA и Android Studio](https://pvs-studio.ru/ru/docs/manual/6704/)\)\.

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

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

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

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

```cpp
<pluginRepositories>
  <pluginRepository>
    <id>pvsstudio-maven-repo</id>
    <url>https://cdn.pvs-studio.com/java/pvsstudio-maven-repository/</url>
  </pluginRepository>
</pluginRepositories>
<build>
  <plugins>
    <plugin>
      <groupId>com.pvsstudio</groupId>
      <artifactId>pvsstudio-maven-plugin</artifactId>
      <version>{{FULL_VERSION_PVS_JAVA}}</version>
      <configuration>
        <analyzer>
          <outputType>text</outputType>
          <outputFile>.PVS-Studio/report.txt</outputFile>
          <analysisMode>GA,OWASP</analysisMode>
        </analyzer>
      </configuration>
    </plugin>
  </plugins>
</build>
```

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

> Перед запуском анализа вам необходимо будет ввести лицензию\. Как это сделать — можно узнать в этой [документации](https://pvs-studio.ru/ru/docs/manual/0046/#PvsStudioJava)\.

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

```cpp
mvn pvsstudio:pvsAnalyze
```

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

```cpp
<plugin>
  <groupId>com.pvsstudio</groupId>
  <artifactId>pvsstudio-maven-plugin</artifactId>
  <version>{{FULL_VERSION_PVS_JAVA}}</version>
  <executions>
    <execution>
      <phase>compile</phase>
      <goals>
        <goal>pvsAnalyze</goal>
      </goals>
    </execution>
  </executions>
</plugin>
```

**Обратите внимание:** при анализе проекта плагин запускает [ядро Java анализатора](https://pvs-studio.ru/ru/docs/manual/6703/), которое по умолчанию использует версию java из переменной окружения `PATH`\. Задать другую версию можно при помощи настройки плагина `javaPath`, подробное описание которой находится ниже в разделе **Конфигурация**\.

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

Для работы плагина нужно скачать его зависимости\. Если вам нужно работать с плагином в системе без доступа в сеть, вы должны создать офлайн репозиторий c зависимостями плагина\. Для этого вы можете использовать [maven\-dependency\-plugin](https://maven.apache.org/plugins/maven-dependency-plugin/go-offline-mojo.html)\. 

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

```cpp
mvn dependency:go-offline
```

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

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

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

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

В системе должно быть установлено ядро Java той же версии, что и плагин\. Узнать, как установить ядро Java анализатора, можно в отдельной [документации](https://pvs-studio.ru/ru/docs/manual/6703/#java_core_install)\.

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

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

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

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

* `<additionalWarnings>VXXXX, ....</additionalWarnings>`_ _—_ _список диагностических правил, которые будут добавлены к анализу\. Эта настройка имеет больший приоритет, чем `<enabledWarnings>`, `<disabledWarnings>` и `<analysisMode>`\. Значение по умолчанию отсутствует;
* `<analysisMode>GA, ....</analysisMode>` — список активных групп диагностических правил\. Настройки `<enabledWarnings>`, `<disabledWarnings>` и `<additionalWarnings>` имеют больший приоритет, чем эта настройка\. То есть, если диагностическая группа отключена \(или включена\), то можно включить \(или отключить\) отдельные диагностические правила при помощи этих настроек\. Значение по умолчанию: `GA`\. Доступные группы: 
  * [`GA`](https://pvs-studio.ru/ru/docs/warnings/#GeneralAnalysisJAVA) \(правила общего назначения\);
  * [`OWASP`](https://pvs-studio.ru/ru/pvs-studio/sast/owasp/#java) \(правила согласно [OWASP Top Ten](https://pvs-studio.ru/ru/pvs-studio/sast/owasptopten/) и [OWASP ASVS](https://pvs-studio.ru/ru/pvs-studio/sast/owasp/)\)\. 
* `<analyzeOnly>PATH, ....</analyzeOnly>`_ _—_ _список файлов и/или директорий, которые нужно проанализировать \(абсолютные или относительный пути, которые будут раскрыты относительно каталога запуска\)\. Файлы и/или директории, переданные в этом аргументе, объединяются в общий список с файлами и/или директориями из аргумента `<analyzeOnlyList>`\. При отсутствии значения для данной настройки будут проанализированы все файлы\. Имеет меньший приоритет, чем настройка `<exclude>`\. Значение по умолчанию отсутствует;
* `<analyzeOnlyList>PATH</analyzeOnlyList>` — путь к текстовому файлу, содержащему список путей к файлам и/или каталогам для анализа \(каждая запись должна быть на отдельной строке\)\. Поддерживаются относительные \(будут раскрыты относительно каталога запуска\) и абсолютные пути\. Файлы и/или директории, считанные из файла, указанного в этом аргументе, объединяются в общий список со значениями из аргумента `<analyzeOnly>`\. Этот настройка имеет меньший приоритет, чем `<exclude>`\. Значение по умолчанию отсутствует;
* `<disableCache>BOOLEAN</disableCache>` — позволяет отключить кэширование метамодели программы\. При отключенном кэше модель проекта не кэшируется и строится каждый раз заново\. При отключении кэширования также отключается [инкрементальный](https://pvs-studio.ru/ru/docs/manual/0024/) режим анализа, даже если указан параметр `<incremental>`\. Значение по умолчанию: `false`;
* `<disabledWarnings>VXXXX, ....</disabledWarnings>` — список диагностических правил, которые не будут применены во время анализа\. При отсутствии данной настройки все диагностические правила считаются включёнными\. Имеет больший приоритет, чем настройки `<enabledWarnings>` и `<analysisMode>`, но меньший, чем `<additionalWarnings>`\. Значение по умолчанию отсутствует;
* `<enabledWarnings>VXXXX, ....</enabledWarnings>` — список активных диагностических правил\. Во время анализа будут использованы только перечисленные\. Эта настройка имеет меньший приоритет, чем `<disabledWarnings>` и `<additionalWarnings>`, но больший, чем `<analysisMode>`\. Значение по умолчанию отсутствует;
* `<exclude>PATH, ....</exclude>` — список файлов и/или директорий, которые нужно исключить из анализа \(абсолютные или относительные пути, которые будут раскрыты относительно каталога запуска\)\. Эта настройка имеет больший приоритет, чем `<analyzeOnly>` и `<analyzeOnlyList>`\. Значение по умолчанию отсутствует;
* `<failOnWarnings>BOOLEAN</failOnWarnings>` — устанавливает ненулевой код возврата программы, если анализатор выдал хотя бы одно предупреждение\. Такое поведение может быть удобным при [интеграции в CI/CD](https://pvs-studio.ru/ru/docs/#IDF1BF21914C)\. Значение по умолчанию: `false`;
* `<forceRebuild>BOOLEAN</forceRebuild>` — позволяет принудительно перестроить целиком закэшированную метамодель программы\. При использовании данного флага отключается [инкрементальный](https://pvs-studio.ru/ru/docs/manual/0024/) режим анализа проекта, даже если указан флаг `<incremental>`\. Значение по умолчанию: `false`;
* `<incremental>BOOLEAN</incremental>` — позволяет запустить анализ [инкрементально](https://pvs-studio.ru/ru/docs/manual/0024/)\. В этом режиме анализируются только изменившиеся файлы\. Значение по умолчанию: `false`;
* `<javaPath>PATH</javaPath>` — задаёт путь до исполняемого файла `java`, с которым будет запускаться ядро анализатора\. Настройку можно задать для всей системы в файле [`global.json`](https://pvs-studio.ru/ru/docs/manual/6703/#java_global_json_file)\.  Если не использовать `<javaPath>`, то PVS\-Studio попытается использовать путь из переменной окружения `PATH`;
* `<jvmArguments>FLAG, ....</jvmArguments>` — дополнительные флаги JVM, с которыми будет запускаться ядро анализатора\. Этот флаг позволяет настраивать JVM, которая будет запускать ядро Java анализатора\. Возможно задать эту настройку для всей системы в [файле global\.json](https://pvs-studio.ru/ru/docs/manual/6703/#java_global_json_file)\. Значение по умолчанию: `["-Xss64m"]`;
* `<licensePath>PATH</licensePath>` — путь до файла с лицензией\. Допустимые расширения файла: `.xml`, `.lic`\. Значение по умолчанию: `%APPDATA%/PVS-Studio/Settings.xml` \(Windows\) или `~/.config/PVS-Studio/PVS-Studio.lic` \(macOS и Linux\);
* `<logging>LEVEL</logging>` — уровень логирования при запуске анализа\. При включении логирования в подпапке `.PVS-Studio/logs` относительно директории текущего запуска Java анализатора будут созданы файлы логов для текущего запуска\. При передаче некорректного значения логирование будет отключено\. Значение по умолчанию: `OFF`\. Допустимые варианты значений: 
  * `OFF`;
  * `ERROR`; 
  * `WARN`;
  * `INFO`;
  * `DEBUG`; 
  * `TRACE`;
  * `ALL`\. 
* `<outputFile>PATH</outputFile>` — путь до файла с отчётом анализатора\. Формат содержимого отчёта не зависит от расширения файла, указанного в этом аргументе\. Значение по умолчанию: `./PVS-Studio` \+ расширение формата из аргумента `--output-type`\. Для отчёта в формате `.fullhtml` необходимо указать директорию, в которой будет создана папка с именем `fullhtml`, содержащая файл отчёта анализатора \(`index.html`\)\. Значение по умолчанию: `./fullhtml`\. **Примечание**\. Вместо использования настройки `<outputFile>` предпочтительнее использовать консольные утилиты [PlogConverter \(Windows\)](https://pvs-studio.ru/ru/docs/manual/0038/#PlogConverter) и [plog\-converter \(Linux и macOS\)](https://pvs-studio.ru/ru/docs/manual/0038/#plog-converter)\. Они позволяют конвертировать отчёт анализатора в большее количество форматов \(например, SARIF\), а также предоставляют дополнительные возможности: фильтрация предупреждений из отчёта, преобразование путей в отчёте с абсолютных на относительные и наоборот, получение разницы между отчётами и др\.;
* `<outputType>TYPE</outputType>` — формат, в котором будет представлен отчёт анализатора\. Значение по умолчанию: `json`\. Допустимые варианты значений:
  * `text`;
  * `log`;
  * `json`;
  * `xml`;
  * `tasklist`;
  * `html`;
  * `fullhtml`; 
  * `errorfile`\. 
* `<securityRelatedIssues>BOOLEAN</securityRelatedIssues>` — позволяет выделить дополнительной маркировкой в поле `SAST` предупреждения, относящиеся к потенциальным проблемам безопасности и классифицируемые согласно ГОСТ Р 71207—2024\. Значение по умолчанию: `false`;
* `<sourceTreeRoot>PATH</sourceTreeRoot>` — корневая часть пути, которую анализатор [будет использовать](https://pvs-studio.ru/ru/docs/manual/0027/) при генерации относительных путей в отчёте для диагностических предупреждений\. Значение по умолчанию отсутствует;
* `<suppressBase>PATH</suppressBase>` — путь до [suppress\-файла](https://pvs-studio.ru/ru/docs/manual/0032/), содержащего подавленные предупреждения анализатора\. Они не попадут в отчёт при последующих проверках проекта\. Значение по умолчанию: `${basedir}/.PVS-Studio/suppress_base.json`;
* `<threadsNum>NUMBER</threadsNum>` — число потоков анализа\. Можно задать эту настройку для всей системы в файле [`global.json`](https://pvs-studio.ru/ru/docs/manual/6703/#java_global_json_file)\. Значение по умолчанию: _число доступных логических ядер_;
* `<timeout>NUMBER</timeout>` — таймаут анализа одного файла в минутах\. Можно задать для всей системы в файле [`global.json`](https://pvs-studio.ru/ru/docs/manual/6703/#java_global_json_file)\. Значение по умолчанию: `10`;
* `<compatibility>BOOLEAN</compatibility>` — активирует диагностическое правило [V6078](https://pvs-studio.ru/ru/docs/warnings/v6078/), которое обнаруживает потенциальные проблемы совместимости API между выбранными версиями Java SE\. Значение по умолчанию: `false`;
* `<excludePackages>"PACK", ....</excludePackages>` — пакеты, которые будут исключены из анализа совместимости\. Эта настройка используется диагностическим правилом [V6078](https://pvs-studio.ru/ru/docs/warnings/v6078/), если включена настройка `<compatibility>`;
* `<sourceJava>NUMBER</sourceJava>` — версия Java SE, на которой разработано анализируемое приложение\. Эта настройка используется диагностическим правилом [V6078](https://pvs-studio.ru/ru/docs/warnings/v6078/), если включена настройка `<compatibility>`\. Минимальное значение: `8`\. Максимальное значение: `14`;
* `<targetJava>NUMBER</targetJava>` — версия Java SE, на совместимость с которой проверяется API, используемое в анализируемом приложении \(`<sourceJava>`\)\. Эта настройка используется диагностическим правилом [V6078](https://pvs-studio.ru/ru/docs/warnings/v6078/), если включена настройка `<compatibility>`\. Минимальное значение: `8`\. Максимальное значение: `14`;

Формат определения:

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

Пример:

```cpp
mvn pvsstudio:pvsAnalyze -Dpvsstudio.outputType=text
                         -Dpvsstudio.outputFile=.PVS-Studio/report.txt
                         -Dpvsstudio.disabledWarnings=V6001;V6002;V6003
```

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

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

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

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

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

Для обновления [pvsstudio\-maven\-plugin](https://mvnrepository.com/artifact/com.pvsstudio/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 с прокси:

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