• English

Плагин CodeScoring SCA для IntelliJ based IDEs

Плагин предоставляет возможности анализа состава программного обеспечения (SCA) для IntelliJ IDEA и других IDE, основанных на IntelliJ движке, подсвечивая уязвимые зависимости в файлах вашего проекта и предоставляя подробную информацию об уязвимостях через интеграцию с Johnny CLI.

Плагин CodeScoring SCA поддерживает версии IntelliJ IDEA 2024.1 и выше, а также все IDE на базе IntelliJ Platform (OpenIDE, GIGA IDE, PyCharm, WebStorm, PhpStorm, RubyMine, GoLand, CLion, Rider, Android Studio).

Поддерживаемые экосистемы

Языки и менеджеры пакетов

Экосистема	Файлы манифеста	Сгенерированные файлы версий	Особенности
Java/JVM	pom.xml, .gradle, .gradle.kts, ivy.xml	gradle.lockfile, gradle-dependency-tree.txt, maven-dependency-tree.txt	Полная поддержка Maven и Gradle
JavaScript/Node	package.json	package-lock.json, yarn.lock, npm-shrinkwrap.json, pnpm-lock.yaml	NPM, Yarn, PNPM
Python	setup.py, pyproject.toml, pipfile	requirements.txt, requirements.pip, Pipfile.lock, poetry.lock	Pip, Poetry, Pipenv
Ruby	Gemfile, gems.rb, *.gemspec	Gemfile.lock, gems.locked	Bundler и RubyGems
Go	go.mod	go.sum	Go модули
Rust	Cargo.toml	Cargo.lock	Cargo
PHP	composer.json	composer.lock	Composer
C#/.NET	.csproj, packages.config, .nuspec, paket.dependencies	packages.lock.json, project.assets.json, paket.lock, project.lock.json	NuGet и Paket
Swift	Package.swift	Package.resolved	Swift Package Manager
Objective-C	Podfile, *.podspec	Podfile.lock	CocoaPods для iOS/macOS
C/C++	conanfile.txt, conanfile.py	conan.lock	Conan менеджер пакетов
Conda	environment.yml, meta.yml, environment.yaml, meta.yaml	conda-lock.yml	Conda окружения

Обнаружение файлов по умолчанию

• Автоматическое: Сканирует все поддерживаемые файлы
• Рекурсивное: Ищет в подкаталогах проекта

Точная настройка сканирования производится с помощью модификации config.yaml файла

Начало работы

Предварительные требования

Перед началом убедитесь, что у вас есть:

• IntelliJ IDEA 2024.1 или новее (или любая совместимая поддерживаемая IDE на основе IntelliJ Platform)
• Доступ к установке CodeScoring с активными учетными данными
• Дистрибутив codescoring-intellij плагина (.zip файл)

Требуемые разрешения

• Файловая система: Чтение файлов проекта, запись файлов .codescoring, загрузка исполняемого файла, выполнение загруженного CLI
• Сеть: Связь с CodeScoring API
• API VS Code: Интеграция с редактором

Шаг 1: Загрузите плагин

Плагин поставляется в виде файла codescoring-intellij-<version>.zip.

Шаг 2: Установите плагин из ZIP файла

1. Откройте IntelliJ based IDE
2. Перейдите в File → Settings (или \<IDE Name> → Preferences на macOS)
3. В диалоге настроек выберите Plugins в левой боковой панели
4. Нажмите на значок шестеренки (⚙) в верхней части панели плагинов
5. Выберите "Install Plugin from Disk..." из выпадающего меню
6. Найдите место, куда вы загрузили файл .zip
7. Выберите файл и нажмите "OK"
8. Дождитесь завершения установки
9. Подтвердите установку плагина от CodeScoring
10. Перезапустите IntelliJ based IDE при появлении запроса

Шаг 3: Найдите плагин CodeScoring

После установки и перезапуска вы должны увидеть окно инструментов CodeScoring.

1. Найдите вкладку окна инструментов "CodeScoring SCA" (обычно внизу или слева в IDE)
2. Если не видно, перейдите в View → Tool Windows → CodeScoring SCA
3. Это откроет окно инструментов CodeScoring SCA с панелью Dashboard

Шаг 4: Настройте плагин

1. В окне инструментов CodeScoring SCA нажмите кнопку "Settings" (значок шестеренки) на панели инструментов
2. Откроется страница настроек CodeScoring SCA

4.1 Проверьте URL API

1. В настройках найдите поле API URL
2. Вам необходимо использовать URL CodeScoring, установленный в Вашей организации. При необходимости, обратитесь к администратору.

4.2 Сгенерируйте и установите токен API

1. Откройте веб-браузер и перейдите по адресу: <API URL>/cabinet/profile
2. Войдите в свою учетную запись CodeScoring
3. Убедитесь, что вы находитесь на странице своего профиля
4. Найдите поле "API token"
5. Нажмите кнопку "Generate" рядом с полем токена API
6. Скопируйте значение сгенерированного токена API
7. Вернитесь к настройкам IntelliJ-based IDE
8. Вставьте токен в поле "API Token"
9. Нажмите "Validate Token" для проверки работы токена
10. Плагин должен отобразить подтверждение того, что токен действителен

4.3 Загрузите Johnny CLI (Опционально)

1. Перейдите на страницу релизов: <API URL>/download/ (обратите внимание на завершающую косую черту)
2. Загрузите последний релиз исполняемого файла в зависимости от вашей операционной системы

4.4 Настройте Johnny CLI

Существует три способа получить Johnny CLI для анализа ваших зависимостей с помощью нашего сервиса.

4.4.1 Локальная установка

Предварительные требования:

• Johnny CLI должен быть загружен и файл сделан исполняемым в системе
• Операционная система должна разрешать запуск исполняемого файла (для проверки запустите один раз файл в консоли с параметром --help вручную)

Шаги настройки:

1. Задайте тип установки Local

2. В настройках выберите "Local executable" в выпадающем списке Installation Type

3. В поле Johnny CLI Path нажмите кнопку выбора папки

4. Перейдите к месту, куда вы ранее загрузили Johnny CLI
5. Выберите исполняемый файл Johnny CLI
6. Нажмите "OK" для сохранения настроек

Примечание: Если плагин спросит об изменении прав доступа к файлу (chmod +x), нажмите "Да", чтобы разрешить плагину сделать файл исполняемым.

4.4.2 Автоматическая загрузка клиента

Предварительные требования:

• Должен быть настроен API URL
• Должен быть настроен токен API и валидация должна пройти успешно

Шаги настройки:

1. Установите тип установки на Local

2. В настройках выберите "Local executable" в выпадающем списке Installation Type

3. Оставьте поле Johnny CLI Path пустым

4. Теперь при первом запросе сканирования Johnny CLI будет загружен с API URL. Это позволит Вам автоматически получить обновление клиента, как только оно будет доступно. Загруженный клиент будет сохранен в следующем месте:
   • Linux/MacOS: ~/.codescoring/johnny
   • Windows: %USERPROFILE%\.codescoring\johnny.exe

4.4.3 Использование Docker

Установка Docker позволяет запускать Johnny CLI в изолированном контейнере, что полезно, когда вы не хотите устанавливать его непосредственно в вашей системе.

Предварительные требования:

• Docker должен быть установлен и запущен в вашей системе
• Ваш пользователь должен иметь права на выполнение команд Docker

Шаги настройки:

1. Установите тип установки на Docker

2. В настройках выберите "Docker" в выпадающем списке Installation Type

3. Настройте Docker образ

4. Docker Image: johnny-depp:2025.29.0 (по умолчанию)

5. Docker Registry: <адрес-реестра-кодскоринг>

6. Пример полного пути к образу: sample-codescoring-registry.com/johnny-depp:2025.29.0

7. Опционально: Дополнительные опции Docker Добавьте пользовательские опции запуска Docker при необходимости в поле Additional Docker Options:

   --memory=2g --cpus=2
   

Как это работает:

• Клиент автоматически монтирует каталог вашего проекта в контейнер
• Сканирование выполняется внутри контейнера, а результаты сохраняются в вашем проекте
• Ручные команды Docker не требуются - плагин обрабатывает все автоматически

Устранение неполадок с установкой Docker:

• "Docker not found": Убедитесь, что Docker установлен и команда docker находится в вашем PATH
• Permission denied: Добавьте вашего пользователя в группу docker: sudo usermod -aG docker $USER
• Image pull failed: Проверьте учетные данные реестра и сетевое подключение
• Container exits immediately: Проверьте Event Log для получения подробных сообщений об ошибках

Шаг 5: Запустите первое сканирование

Теперь, когда плагин настроен, вы можете запустить первое сканирование зависимостей:

Метод 1: Использование dashboard

1. Откройте проект в IntelliJ-based IDE
2. Откройте окно инструментов CodeScoring SCA
3. В панели Dashboard нажмите кнопку "Run Scan"

!

Метод 2: Использование главного меню

1. Перейдите в Tools → CodeScoring SCA → Run Scan

Метод 3: Использование панели инструментов

1. Найдите вкладку плагина CodeScoring SCA и ее главную панель инструментов
2. Нажмите кнопку "Run Scan" (см скриншот из метода 1)

Шаг 6: Тонкая настройка конфигурации сканирования

После завершения сканирования вы увидите новый каталог .codescoring, содержащий:

1. config.yaml - файл конфигурации для Johnny CLI, вы можете прочитать о нем в этом разделе. Вы можете менять этот файл, так как он никогда не будет перезаписан.
2. donotfix.yaml - файл конфигурации со списком шаблонов имен файлов, которые должны быть исключены из действий Quick Fix. Вы можете изменять этот файл.
3. report.html - отчет, сгенерированный в формате html, содержащий вывод Johnny CLI в формате цветной таблицы. Перезаписывается во время каждого сканирования.
4. bom.json - файл результатов сканирования, созданный Johnny CLI в формате cyclone-dx 1.6, он будет загружен автоматически и показан в панели уязвимостей для любого открытого в IntelliJ-based IDE проекта, в котором существует .codescoring/bom.json
5. bom.json.N - где N - это ревизия сканирования, т.е. 0 - предыдущее сканирование, а 5 (например) - самое первое сканирование, и bom.json.0 будет использоваться для сравнения с bom.json (и показан в дереве DIFF), если он существует на момент открытия проекта

your-project/
├── .codescoring/
│   ├── config.yaml       # Конфигурация сканирования
│   ├── donotfix.yaml     # Конфигурация QuickFix
│   ├── report.html       # Последний отчет сканирования
│   ├── bom.json          # Текущие уязвимости
│   ├── bom.json.0        # Предыдущее сканирование (сравнение)
│   └── bom.json.1        # Более старые сканирования...
├── pom.xml              # Ваши зависимости
└── ... ваш код ...

Пример использования конфигурации сканирования CodeScoring

Отредактируйте .codescoring/config.yaml для настройки:

scan:
  general:
    ignore: # Директории для пропуска
      - target
      - build
      - .idea
    with-hashes: true # Включить хеши файлов для точного сопоставления
    only-hashes: false # Использовать только обнаружение на основе хешей
  dir:
    no-recursion: false # Предотвращает рекурсивное сканирование корневой директории

Настройка исключений Quick Fix

Файл .codescoring/donotfix.yml контролирует, какие файлы не должны быть изменены действиями Quick Fix. Это особенно полезно для сгенерированных файлов (таких как lock-файлы), которые должны быть перегенерированы, а не исправлены вручную.

Пример использования конфигурации исключений QuickFix:

# Lock-файлы и сгенерированные файлы, которые не должны быть изменены напрямую
patterns:
  - go.sum
  - package-lock.json
  - yarn.lock
  - Cargo.lock
  - composer.lock
  - "*.generated.*"
  - "**/generated/**"

Синтаксис шаблонов:

• Точное имя файла: go.sum
• Шаблоны с подстановочными знаками: *.lock, *-lock.json
• Шаблоны директорий: **/node_modules/**
• Несколько расширений: *.{lock,generated}

Файл создается автоматически при:

• Первом сканировании в проекте
• Открытии проекта с существующей директорией .codescoring, но без donotfix.yml

Примечание: Файлы, соответствующие этим шаблонам, все равно будут сканироваться на наличие уязвимостей и показаны в результатах, но действия Quick Fix (как индивидуальные, так и массовые) будут их пропускать. Пользователи должны перегенерировать эти файлы, используя команды их менеджера пакетов.

Шаг 7: Просмотр результатов сканирования

После завершения сканирования:

1. Проверьте уведомления: Посмотрите на уведомления в правом нижнем углу IntelliJ-based IDE, нажав на "View Report" и "See details in Vulnerabilities view""
2. Откройте дерево уязвимостей: Окно плагина автоматически переключится на панель Vulnerabilities
3. Просмотрите уязвимости: Панель уязвимостей покажет все обнаруженные проблемы безопасности в Ваших зависимостях
4. Изучите детали: Вы можете нажимать на отдельные уязвимости, чтобы увидеть подробную информацию в панели деталей
5. Примените исправления: Используйте кнопки "Fix All" или "Fix Selected" или отдельные быстрые исправления для обновления уязвимых зависимостей

7.1 Подсветка уязвимостей

• Подсветка в коде: Уязвимые зависимости подсвечиваются прямо в файлах кода (build.gradle, pom.xml, package.json и т.д.)
• Цвета критичности:
  • 🔴 Критический (красный)
  • 🟠 Высокий (оранжевый)
  • 🟡 Средний (желтый)
  • 🔵 Низкий (синий)
• Поддержка нескольких файлов: Работает со всеми поддерживаемыми типами файлов
• Наведите курсор на подсвеченные зависимости, чтобы увидеть детали уязвимостей

7.2 Информация при наведении

При наведении курсора на подсвеченные зависимости отображается:

• Идентификатор уязвимости: Номер CVE со ссылкой
• Критичность: Оценка CVSSv3 и уровень
• Описание: Что делает уязвимость
• Ссылки на источники: Информация об официальной регистрации уязвимости
• Рекомендации: Предлагаемые версии для обновления
• Быстрое исправление: Опция обновления в один клик

7.3 Панель уязвимостей

7.3.1 Структура дерева

📊 Уязвимости (247)
├── 🔴 Критические (12)
│   ├── CVE-2023-1234 - Удаленное выполнение кода
│   │   ├── lodash@4.17.20
│   │   └── pom.xml:15
│   └── ...
├── 🟠 Высокие (45)
├── 🟡 Средние (89)
└── 🔵 Низкие (101)

7.3.2 Опции группировки

• Используйте панель уязвимостей для фильтрации по критичности, пакету или другим критериям
• Группируйте уязвимости по различным категориям для лучшей организации

Изменение группировки через кнопку панели инструментов или команду:

• По критичности → Местоположению → Компоненту (по умолчанию): По уровню критичности, подгруппировка по файлу и затем по пакету
• По критичности → Компоненту: По уровню критичности, подгруппировка по имени пакета в алфавитном порядке
• По местоположению → Компоненту: Группировка по пути к файлу
• По имени компонента → Компоненту: Группировка разных версий одного и того же пакета вместе в алфавитном порядке
• По компоненту: По компоненту (с версией, если известна)

7.4 Поиск и фильтрация

Возможности поиска

• Несколько полей: Поиск по:
  • Имени пакета (например, "lodash")
  • Идентификатору CVE (например, "CVE-2023")
  • Пути к файлу (например, "frontend/")
  • Уровню критичности
• Нечеткое сопоставление: Находит частичные совпадения
• Точное совпадение: Ищет точное совпадение слова в кавычках
• Без учета регистра: Не требуется точный регистр

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

• Поле поиска: Для ввода поисковых запросов
• Кнопка очистки: Сброс поиска
• Индикатор результатов: Показывает количество найденных элементов первым элементом дерева уязвимых компонентов

7.5 Быстрые исправления

Быстрые исправления в коде

• Лампочка IntelliJ: Нажмите на лампочку рядом с уязвимой зависимостью

или

• Alt+Enter (⌥ + Enter на MacOS): Используйте горячую клавишу, когда курсор находится на уязвимой зависимости

или

• Update vulnerable dependency внизу на всплывающей карточке уязвимого компонента

или

• кнопка Fix Selected на панели инструментов,

а затем

• Выберите версию: Если доступно несколько безопасных версий, выберите подходящую

Массовые исправления (не работает при группировках по критичности)

• Кнопка Fix All: Обновляет все уязвимые компоненты с доступными исправлениями
• Интеллектуальное обновление: Автоматически выбирает наиболее подходящую безопасную версию
• Отчет об изменениях: Показывает, сколько зависимостей были обновлены
• Исключения: Учитывает шаблоны, определенные в .codescoring/donotfix.yml

7.6 Работа с файлами BOM

Автозагрузка Плагин автоматически загружает файлы BOM из:

1. .codescoring/bom.json (основной)
2. bom.json (корневой каталог проекта)

Ручные операции

• Загрузить BOM: Tools → CodeScoring SCA → Load BOM File
• Закрыть BOM: Tools → CodeScoring SCA → Close BOM

7.7 Сравнение BOM

Сравнивается полный состав всех компонентов, а не только уязвимых. С помощью сравнения можно увидеть различия в полном перечне используемых компонентов и отследить изменения версий. При этом старые версии компонентов будут показаны как удаленные, а новые - как добавленные. Чтобы удобнее было отслеживать изменения в версиях компонентов, можно сгруппировать их по имени пакета (см ниже).

Автоматическое сравнение При открытии проекта:

• Загружает текущий BOM (bom.json)
• Сравнивает с предыдущим (bom.json.0)
• Показывает уведомление об изменениях

Ручное сравнение

1. Выберите Tools → CodeScoring SCA → Compare BOMs
2. Выберите базовый файл BOM
3. Если BOM уже загружен, он будет использован как целевой
4. Если BOM не загружен, выберите целевой файл
5. Отобразится результат сравнения в панели DIFF

Представления сравнения

📊 BOM DIFF (Изменения: 23 добавлено, 15 удалено, 45 обновлено, 73 без изменений)
├── ➕ Добавлено (23)
│   ├── [ADDED] react@18.1.3 0 уязвимостей
│   └── ...
├── ➖ Удалено (15)
├── 🔄 Обновлено (45)
│   ├── [UPDATED] lodash: 4.17.20
│   └── ...
└── ✓ Без изменений (73)

Опции группировки сравнения

• По типу изменения: Добавлено/Удалено/Обновлено/Без изменений (по умолчанию)
• По пакету: Алфавитная группировка пакетов, наиболее полезный вид группировки для отслеживания изменившихся версий пакетов
• По расположению: Группировка по пути к файлу
• По критичности: Группировка по влиянию уязвимости

Фильтрация сравнения

Используйте поле поиска для фильтрации результатов сравнения по:

• Имени пакета
• Типу изменения
• Пути к файлу

7.8 Отчеты

Отчеты сканирования

• Автоматически генерируются: Создаются после каждого сканирования
• Расположение: .codescoring/report.html
• Формат: Цветной HTML с подробной информацией
• Содержимое:
  • Статус сканирования
  • Выполненная команда
  • Сводка результатов
  • Найденные уязвимости
  • Предупреждения от политик
  • Сообщения об ошибках

Просмотр отчетов

• Команда: Tools → CodeScoring SCA → View Report
• Открывается в: на выбор, внешний браузер, внутренний предпросмотр, редактор кода

Шаг 8: Настройки и кастомизация

Список доступных настроек

Настройка	Описание	По умолчанию
API Configuration
API URL	URL вашей установки CodeScoring
API Token	API токен. Безопасно сохраняется	(устанавливается через UI)
Installation Settings
Installation Type	Local executable или Docker	Local executable
Path to Johnny CLI	Путь к Johnny CLI (пустой для автозагрузки)	(автозагрузка)
Docker Image	Имя Docker образа	johnny-depp:2025.29.0
Docker Registry	Реестр Docker	(предоставляется заботой)
Additional Docker Options	Дополнительные опции Docker
UI Settings
Enable vulnerability inspections	Включить инспекции кода	true
Enable quick fixes for vulnerable dependencies	Разрешить быстрые исправления	true
Automatically scan projects on open	Запускать сканирование при открытии проекта	true
Severity Colors
Critical Color	Цвет для критических уязвимостей	(красный)
High Color	Цвет для высоких уязвимостей	(оранжевый)
Medium Color	Цвет для средних уязвимостей	(желтый)
Low Color	Цвет для низких уязвимостей	(синий)
Unknown Color	Цвет для неизвестной критичности	(серый)

Устранение неполадок

Логи плагина

• Для подробного понимания работы плагина проверьте логи IDE:
  • Help → Show Log in Explorer/Finder
  • Ищите записи с "CodeScoring" в idea.log

Распространенные проблемы

Проблемы установки

Проблема	Решение
Плагин не виден после установки	Полностью перезапустите IntelliJ-based IDE, проверьте Settings → Plugins
Ошибка совместимости	Убедитесь, что версия IDE 2024.1 или новее, убедитесь в отсутствии проблем в лог файле
Установка зависает	Проверьте подключение к интернету, попробуйте установить заново

Проблемы конфигурации

Проблема	Решение
Поля настройки не отображаются	Возможно, несовместимая IDE, проверьте версию и тип IDE, загляните в лог-файлы IDE
Валидация токена не удается	Проверьте URL API, сгенерируйте новый токен, проверьте прокси/VPN
Johnny CLI не найден	Проверьте путь, права доступа, антивирус
Docker не работает	Убедитесь, что Docker запущен, проверьте права пользователя

Проблемы сканирования

Проблема	Решение
Сканирование зависает	Проверьте Event Log, попробуйте запустить Johnny CLI вручную.
Нет результатов	Убедитесь, что проект содержит файлы зависимостей
Частичные результаты	Проверьте конфигурацию в .codescoring/config.yaml
Ошибки токена	Проверьте срок действия токена, права доступа

Проблемы отображения

Проблема	Решение
Нет подсветки	Включите в настройках, перезагрузите файлы
Неправильные цвета	Проверьте настройки цветов критичности
Отсутствует панель	View → Tool Windows → CodeScoring SCA
Медленная работа	Уменьшите размер пагинации в настройках

Проблемы исправления

Проблема	Решение
Исправление не удается	Проверьте права на запись файлов
Исправление игнорируется	Проверьте логи плагина и .codescoring/donotfix.yml
Неправильная версия	Вручную укажите версию в файле
Конфликты версий	Исправляйте по одному компоненту
Откат изменений	Используйте систему контроля версий

Получение помощи

1. Проверьте Event Log: View → Tool Windows → Event Log
2. Включите debug логи:
   • Help → Diagnostic Tools → Debug Log Settings
   • Добавьте com.codescoring.intellij
3. Отчеты об ошибках: Просмотрите .codescoring/report.html для деталей сканирования

Свяжитесь с отделом заботы: support@codescoring.ru

Безопасность и конфиденциальность, обработка данных

• Локальное сканирование: Код не отправляется на серверы
• Связь с API: Передаются только метаданные (конфигурационные файлы Вашего пакетного менеджера)
• Хранение токенов: Безопасное хранилище учетных данных VS Code

Рекомендации

Рекомендации по рабочему процессу

1. Начальная настройка: Полное сканирование при запуске проекта
2. Обзоры: Сравнивайте BOM между версиями
3. CI/CD:
   • Перед коммитом: Выполните полное сканирование
   • Поделитесь конфигурацией: Закоммитьте .codescoring/config.yaml и .codescoring/donotfix.yaml
   • Игнорируйте временные файлы: Добавьте в .gitignore:

  .codescoring/report.html
  .codescoring/bom.json.*

- **Отслеживайте основной BOM**: Версионируйте `.codescoring/bom.json`
- **Стандартизируйте**: Стандартизируйте настройки плагина

Интеграция с процессами разработки

1. Code Review:

   • Проверяйте изменения зависимостей
   • Требуйте исправления критических уязвимостей
   • Документируйте принятые риски

2. Release Management:

   • Генерируйте отчеты для каждого релиза
   • Отслеживайте улучшения безопасности
   • Планируйте обновления зависимостей

3. Compliance:

   • Экспортируйте BOM для аудита
   • Отслеживайте лицензии компонентов
   • Поддерживайте историю сканирований

Работа с Lock-файлами

1. Понимание Lock-файлов:

   • Lock-файлы генерируются менеджерами пакетов
   • Они не должны редактироваться вручную
   • Изменения должны вноситься в файлы манифестов

2. Поведение Quick Fix:

   • Файлы, соответствующие шаблонам donotfix.yml, пропускаются
   • Обновите файлы манифестов, затем перегенерируйте lock-файлы
   • Используйте соответствующие команды менеджера пакетов, например:
     • Go: go mod tidy
     • NPM: npm install
     • Yarn: yarn install
     • Cargo: cargo update

3. Рекомендации:

   • Просмотрите donotfix.yaml и настройте шаблоны по необходимости
   • Документируйте ваш процесс перегенерации
   • Автоматизируйте обновления lock-файлов в CI/CD