Работа с ядром Java анализатора из командной строки

• Установка ядра Java анализатора
• Аргументы ядра Java анализатора
• Запуск анализа
  • Как изменить версию Java для запуска анализатора?
• Файл конфигурации Java анализатора
• Глобальный файл настроек Java анализатора
• Коды возврата ядра Java анализатора
• Обновление PVS-Studio Java

Сценарий, при котором Java анализатор запускается напрямую через обращение к ядру, является продвинутым и не рекомендуется в качестве основного. Для удобной интеграции и использования Java анализатора PVS-Studio рекомендуем воспользоваться:

• плагином в сборочную систему Gradle;
• плагином в сборочную систему Maven;
• плагином для IDE IntelliJ IDEA и OpenIDE;
• расширением для Visual Studio Code.

Установка ядра Java анализатора

На Windows ядро Java анализатора возможно установить через инсталлятор PVS-Studio для Windows. Скачать его можно на странице загрузки.

Кроме этого, на всех операционных системах возможно скачать ZIP архив для Java на странице загрузки. В этом архиве содержится ядро Java анализатора (папка с именем 7.42.105102 в директории pvs-studio-java). Ядро анализатора надо распаковать в необходимое вам место или по стандартному пусти установки ядра Java анализатора:

• Windows: %APPDATA%/PVS-Studio-Java;
• Linux и macOS: ~/.config/PVS-Studio-Java.

Аргументы ядра Java анализатора

Для получения информации про все доступные аргументы анализатора, необходимо выполнить команду --help:

java -jar pvs-studio.jar --help

Аргументы анализатора:

• --additional-warnings — список диагностических правил, которые будут добавлены к анализу. Имеет больший приоритет, чем настройки --enabled-warnings, --disabled-warnings и --analysis-mode. Значение по умолчанию отсутствует. При перечислении нескольких правил в качестве разделителя используется пробел. Пример: --additional-warnings V6001 V6002 V6003;
• --analysis-mode — список активных групп диагностических правил. Приоритет меньше, чем у настроек --enabled-warnings, --disabled-warnings и --additional-warnings. Значение по умолчанию: GA. При перечислении нескольких групп в качестве разделителя используется пробел. Пример: --analysis-mode GA OWASP. Доступные группы:
  • GA (правила общего назначения);
  • OWASP (правила, соответствующие OWASP Top Ten и OWASP ASVS).
• --analyze-only-list — путь к текстовому файлу, который содержит список путей к файлам и/или директориям для анализа (каждая запись должна быть на отдельной строке). Поддерживаются относительные (будут раскрыты относительно каталога запуска) и абсолютные пути. Файлы и/или директории, считанные из файла, указанного в этом аргументе, объединяются в общий список со значениями из аргумента --analyze-only. Эта настройка имеет меньший приоритет, чем настройка --exclude. Значение по умолчанию отсутствует;
• --analyze-only — список файлов и/или директорий, которые нужно проанализировать (абсолютные или относительный пути, которые будут раскрыты относительно каталога запуска). Файлы и/или директории, переданные в этом аргументе, объединяются в общий список с файлами и/или директориями из аргумента --analyze-only-list. При отсутствии значения для данной настройки будут проанализированы все файлы. Эта настройка имеет меньший приоритет, чем -- exclude. Значение по умолчанию отсутствует. При перечислении нескольких файлов или директорий в качестве разделителя используется пробел. Пример: --analyze-only "path/to/file1" "path/to/file2" "path/to/dir";
• --cfg (-c) — конфигурационный файл для запуска ядра анализатора. В этом файле должны быть сохранены значения аргументов командной строки ядра Java анализатора в JSON-формате. Более подробная информация об этом файле находится в документации. Значение по умолчанию отсутствует;
• --convert — запуск в режиме конвертации. Режимы:
  • toFullhtml — преобразует отчёт с предупреждениями в формат .fullhtml;
  • toSuppress — преобразует отчёт с предупреждениями в формат файла подавления (suppress-файл);
• --disable-cache — отключает кэширование метамодели программы. При отключённом кэше модель проекта не кэшируется и строится каждый раз заново. Отключается и инкрементальный режим анализа проекта, даже если указан флаг --incremental. Значение по умолчанию: false;
• --disabled-warnings — список диагностических правил, которые не будут включены во время анализа. При отсутствии данной настройки все диагностики считаются включёнными. Эта настройка имеет больший приоритет, чем --enabled-warnings и --analysis-mode, но меньший, чем --additional-warnings. Значение по умолчанию отсутствует;
• --dst-convert — путь до файла или каталога, куда будет записан результат преобразования (файл для toSuppress, директория для toFullhtml);
• --enabled-warnings — список активных диагностических правил. Во время анализа будут использованы только те диагностические правила, которые перечислены в этом списке. Эта настройка имеет меньший приоритет, чем --disabled-warnings и --additional-warnings, но больший, чем --analysis-mode. Значение по умолчанию отсутствует. При перечислении нескольких правил в качестве разделителя используется пробел. Пример: --enabled-warnings V6001 V6002 V6003;
• --exclude — список файлов и/или директорий, которые нужно исключить из анализа (относительные пути, которые будут раскрыты относительно каталога запуска, или абсолютные пути). Эта настройка имеет больший приоритет, чем --analyze-only и --analyze-only-list. Значение по умолчанию отсутствует. При перечислении нескольких файлов или директорий в качестве разделителя используется пробел. Пример: --exclude "path/to/file1" "path/to/file2" "path/to/dir";
• --ext-file — путь до файла с classpath. Значение по умолчанию отсутствует. В качестве разделителя classpath используется : в *nix-системах и ; — в Windows-системах. Пример: --ext-file "path/to/project_classpath_file";
• --ext (-e) — определение classpath. Значение по умолчанию отсутствует. При перечислении нескольких сущностей classpath в качестве разделителя используется пробел. Пример: --ext "path/to/file.jar" "path/to/dirJars";
• --fail-on-warnings — устанавливает ненулевой код возврата программы, если анализатор выдал хотя бы одно предупреждение на проекте. Данное поведение может быть удобным при интеграции в CI/CD. Значение по умолчанию: false;
• --force-rebuild — позволяет принудительно перестроить целиком закэшированную метамодель программы. При использовании данного флага отключается инкрементальный режим анализа проекта, даже если указан флаг --incremental. Значение по умолчанию: false;
• --help (-h) — вывод в консоль справочной информации об аргументах ядра Java анализатора;
• --incremental (-i) — запускает инкрементальный режим анализа PVS-Studio. Анализируются только изменившиеся файлы. Значение по умолчанию: false;
• --java-path — задаёт путь до исполняемого файла java, с которым будет запускаться ядро анализатора. Эту настройку можно задать для всей системы в файле global.json. Если не использовать java-path, то PVS-Studio попытается использовать путь из переменной окружения PATH;
• --logging — уровень логирования при запуске анализа. При включении в поддиректории .PVS-Studio/logs относительно директории текущего запуска Java анализатора будут созданы файлы логов для текущего запуска. При передаче некорректного значения логирование будет отключено. Значение по умолчанию: OFF. Варианты допустимых значений:
  • OFF;
  • ERROR;
  • WARN;
  • INFO;
  • DEBUG;
  • TRACE;
  • ALL.
• --output-file (-o) — путь до файла с отчётом анализатора. Формат содержимого отчёта не зависит от расширения файла, указанного в этом аргументе. Значение по умолчанию: ./PVS-Studio + расширение формата из аргумента --output-type. Для отчёта в формате .fullhtml необходимо указать директорию, в которой будет создана папка с именем fullhtml, содержащая файл отчёта анализатора (index.html). Значение по умолчанию: ./fullhtml. Примечание. Вместо использования аргумента --output-file более предпочтительным сценарием является использование консольных утилит PlogConverter (Windows) и plog-converter (Linux и macOS). Эти утилиты позволяют конвертировать отчёт анализатора в большее количество форматов (например, SARIF), а также предоставляют дополнительные возможности: фильтрация предупреждений из отчёта, преобразование путей в отчёте с абсолютных на относительные и наоборот, получение разницы между отчётами и др.;
• --output-type (-O) — формат, в котором будет представлен отчёт анализатора. Значение по умолчанию: json. Допустимые варианты значений:
  • text;
  • log;
  • json;
  • xml;
  • tasklist;
  • html;
  • fullhtml;
  • errorfile.
• --security-related-issues — позволяет выделить дополнительной маркировкой в поле SAST предупреждения, относящиеся к потенциальным проблемам безопасности и классифицируемые согласно ГОСТ Р 71207—2024. Значение по умолчанию: false;
• --sourcetree-root — корневая часть пути, которую анализатор будет использовать при генерации относительных путей в отчёте для диагностических предупреждений. Значение по умолчанию отсутствует; Пример: --sourcetree-root /path/to/project/directory;
• --src-convert — путь до отчёта анализатора с предупреждениями (*.json);
• --src (-s) — набор файлов или директорий анализируемого проекта. Значение по умолчанию отсутствует. При перечислении нескольких файлов или директорий в качестве разделителя используется пробел. Пример: --src "path/to/file1" "path/to/file2" "path/to/dir";
• --suppress-base — путь до suppress-файла, содержащего подавленные предупреждения анализатора. Предупреждения из этого файла не попадут в отчёт при следующих проверках проекта. Значение по умолчанию: ./.PVS-Studio/suppress_base.json;
• --threads (-j) — число потоков анализа. Также возможно задать эту настройку для всей системы в файле global.json. Значение по умолчанию: число доступных логических ядер;
• --timeout — таймаут анализа одного файла (в минутах). Эту настройку можно задать для всей системы в файле global.json. Значение по умолчанию: 10;
• --activate-license — позволяет сохранить в файл информацию о лицензии, указанной через аргументы --user-name и --license-key. Значение по умолчанию: false;
• --license-key — лицензионный ключ;
• --license-path — путь до файла с лицензией. Допустимые расширения файла: .xml, .lic. Значение по умолчанию: %APPDATA%/PVS-Studio/Settings.xml (Windows) или ~/.config/PVS-Studio/PVS-Studio.lic (macOS и Linux);
• --user-name — имя пользователя анализатора, привязанное к лицензионному ключу;
• --compatibility — активирует диагностическое правило V6078, которое обнаруживает потенциальные проблемы совместимости API между выбранными версиями Java SE. Значение по умолчанию: false;
• --exclude-packages — пакеты, которые будут исключены из анализа совместимости. Эта настройка используется диагностическим правилом V6078, если включена настройка --compatibility. Пример: --exclude-packages "package1" "package2" "package3";
• --source-java — версия Java SE, на которой разработано проверяемое приложение. Эта настройка используется диагностическим правилом V6078, если включена настройка --compatibility. Минимальное значение: 8. Максимальное значение: 14;
• --target-java — версия Java SE, на совместимость с которой проверяется API, используемое в приложении (--source-java). Эта настройка используется диагностикой анализатора V6078, если включена настройка --compatibility. Минимальное значение: 8. Максимальное значение: 14.

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

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

Примеры быстрого запуска ядра Java анализатора:

java -jar pvs-studio.jar -s A.java B.java C.java -e Lib1.jar Lib2.jar -j4 
-o report.txt -O text --user-name someName –-license-key someSerial

java -jar pvs-studio.jar -s src/main/java --ext-file classpath.txt -j4 
-o report.txt -O text --license-path PVS-Studio.lic

Обратите внимание:

• анализатору для работы необходим набор исходных файлов (или директорий с исходными файлами) для анализа, а также classpath, чтобы корректно построить метамодель программы;
• при анализе проекта плагин запускает ядро Java анализатора, которое по умолчанию использует версию java из переменной окружения PATH. Задать другую версию можно при помощи аргумента java-path, подробное описание которого находится выше в разделе Аргументы ядра Java анализатора.

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

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

/path/to/jdk_folder/bin/java -jar pvs-studio.jar ^
-s A.java B.java C.java -e Lib1.jar Lib2.jar -j4 ^
-o report.txt -O text --user-name someName –-license-key someSerial

Файл конфигурации Java анализатора

Для упрощения команды запуска анализа можно вынести аргументы командной строки в специальный JSON-файл. В дальнейшем этот файл можно передать в ядро анализатора через флаг --cfg.

Синтаксис файла выглядит следующим образом:

{
  "single-value-parameter": "value",
  "multiple-values-parameter": ["value1", "value2", "value3"]
}

Каждый параметр в файле конфигурации представляет собой полное имя флага командной строки со значением, которое будет передано в этом флаге.

Пример файла конфигурации:

{
  "src": ["A.java", "B.java", "C.java"],
  "threads": 4,
  "output-file": "report.txt",
  "output-type": "text",
  "user-name": "someName",
  "license-key": "someSerial"
  ....
}

В таком случае запуск анализатора сведётся к следующей строке:

java -jar pvs-studio.jar –-cfg cfg.json

Примечание. Параметры, переданные через командную строку, имеют более высокий приоритет, чем параметры, заданные в файле конфигурации.

Глобальный файл настроек Java анализатора

Часть настроек ядро Java анализатора берёт из файла global.json. Этот файл расположен в папке по стандартному пути установки ядра Java анализатора:

• Windows: %APPDATA%/PVS-Studio-Java/global.json;
• Linux и macOS: ~/.config/PVS-Studio-Java/global.json.

Вот список этих настроек:

• java — Значение по умолчанию: java;
• jvm-arguments — Значение по умолчанию: ["-Xss64m"];
• threads — Значение по умолчанию: число доступных процессоров. Это значение возможно переопределить через аргумент --threads командной строки ядра Java анализатора;
• timeout — Значение по умолчанию: 10. Это значение возможно переопределить через аргумент --timeout командной строки ядра Java анализатора;
• verbose — Значение по умолчанию: true.

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

Информацию о том, какие из этих настроек возможно переопределить в плагинах PVS-Studio для Java, вы найдёте в соответствующих разделах документации:

• Maven;
• Gradle;
• PVS-Studio для IntelliJ IDEA и Android Studio.

Коды возврата ядра Java анализатора

• 0 — анализ успешно завершён. Ошибки могут быть как найдены, так и не найдены;
• 50 — произошла ошибка при анализе;
• 51 — переданы невалидные аргументы при запуске анализа;
• 52 — при анализе используется невалидная или просроченная лицензия;
• 53 — анализ успешно завершен, и анализатор нашёл потенциальные ошибки в коде проекта. Этот код возврата будет возвращен только при использовании флага ядра Java анализатора --fail-on-warnings;
• 54 — при анализе попытались использовать Enterprise возможности ядра Java анализатора, но при этом использовали не Enterprise лицензию.

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

Каждый раз при запуске анализа проверяется наличие новой версии анализатора PVS-Studio. Если вышла новая версия анализатора, то в файле с результатами анализа будет содержаться сообщение: "A newer version of PVS-Studio is available (7.42.105102)". Это сообщение содержит последнюю версию ядра Java анализатора.

Кроме этого, получить последнюю версию PVS-Studio можно из файла по ссылке.

Для обновления ядра Java анализатора скачайте ZIP-архив на странице загрузки. В этом архиве содержится ядро Java анализатора (папка с именем 7.42.105102 в директории pvs-studio-java). Ядро Java анализатора надо распаковать в необходимое место или в стандартную директорию:

• Windows: %APPDATA%/PVS-Studio-Java;
• Linux и macOS: ~/.config/PVS-Studio-Java.

Весь этот процесс можно автоматизировать при помощи различных скриптов, что позволит всегда использовать последнюю версию ядра Java анализатора.

Была ли полезна эта страница документации?

Ваше сообщение отправлено

Мы ответим вам на:

Если вы так и не получили ответ, пожалуйста, проверьте, отфильтровано ли письмо в одну из следующих стандартных папок:

• Промоакции
• Оповещения
• Спам

Напишите, пожалуйста, на какой вопрос вы не смогли найти ответ, и наши разработчики ответят вам лично по почте.

Даю согласие на обработку своих персональных данных в соответствии с Политикой обработки персональных данных