#Плагин 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).

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

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

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

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

Точная настройка сканирования производится с помощью модификации 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Docker Image: johnny-depp:2025.29.0 (по умолчанию)
• Docker Registry: <адрес-реестра-кодскоринг>
• Пример полного пути к образу: sample-codescoring-registry.com/johnny-depp:2025.29.0

3. Опционально: Дополнительные опции 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), если он существует на момент открытия проекта

#Пример использования конфигурации сканирования 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" или отдельные быстрые исправления для обновления уязвимых зависимостей
6. Просмотр алертов: Вы можете нажать на панель Alerts для просмотра алертов по сработавшим политикам

#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
• Открывается в: на выбор, внешний браузер, внутренний предпросмотр, редактор кода

#7.9 Панель алертов

В панели Alerts представлена информация по алертам для сработавших политик по итогам анализа. Для каждого алерта показывается:

• Название политики
• Уровень алерта
• Статус блокировки
• Список пакетов с критериями

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

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

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

#Логи плагина

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

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

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

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

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

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

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

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

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