#Расширение CodeScoring.SCA для Visual Studio Code

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

Расширение CodeScoring.SCA поддерживает версии Visual Studio Code 1.95.0 и выше.

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

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

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

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

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

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

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

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

• Visual Studio Code, установленный в Вашей системе
• Доступ к установке CodeScoring с активными учетными данными
• Дистрибутив codescoring-sca расширения для vscode (.vsix)

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

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

#Шаг 1: Загрузите расширение

Расширение поставляется в виде платформенно-независимого файла codescoring-sca-<version>.vsix.

#Шаг 2: Установите расширение из файла VSIX

1. Откройте Visual Studio Code
2. Перейдите в Файл → Настройки → Расширения (или нажмите Ctrl+Shift+X или Cmd+Shift+X на MacOS)
3. Нажмите на меню с тремя точками (...) в правом верхнем углу панели расширений
4. Выберите "Установить из VSIX..." из выпадающего меню
5. Перейдите к месту, куда вы сохранили файл .vsix
6. Выберите файл и нажмите "Установить"
7. Дождитесь завершения установки

#Шаг 3: Найдите расширение CodeScoring

После установки вы должны увидеть логотип CodeScoring в панели действий VS Code (боковая панель слева).

1. Нажмите на иконку CodeScoring в панели действий
2. Откроется боковая панель "CODESCORING: CODESCORING SCA"

#Шаг 4: Настройте расширение

1. В боковой панели CodeScoring SCA нажмите кнопку "Configure Extension"
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. Вернитесь к настройкам VS Code
8. Нажмите на ссылку "Set API Token" в настройках плагина
9. Вставьте скопированный токен при появлении запроса
10. Плагин должен отобразить подтверждение, что токен действителен

#4.3 Загрузите Johnny CLI

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

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

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

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

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

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

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

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

• В настройках VS Code измените platformType на local
• Или в settings.json:

"codescoringSca.platformType": "local"

2. В настройках найдите поле Codescoring Sca: Johnny Cli Path, помеченное [LOCAL platform ONLY]
3. Нажмите на ссылку действия "Browse..."
4. Перейдите к месту, где вы ранее загрузили Johnny CLI
5. Выберите исполняемый файл Johnny CLI

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

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

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

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

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

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

• В настройках VS Code измените installationType на local
• Или в settings.json:

  "codescoringSca.installationType": "local"

2. В настройках найдите поле Codescoring Sca: Johnny Cli Path, помеченное [LOCAL INSTALLATION ONLY]
3. Очистите, если необходимо, значение в этом поле (пустое значение - это значение по умолчанию)
4. Теперь при первом запросе сканирования Johnny CLI будет загружен с API URL. Это позволит Вам автоматически получить обновление клиента, как только оно будет доступно. Загруженный клиент будет сохранен в следующем месте:
   • Linux: ~/.config/Code/User/globalStorage/CodeScoring.codescoring-sca/johnny
   • Windows: %APPDATA%\Code\User\globalStorage\CodeScoring.codescoring-sca\johnny.exe
   • MacOS: ~/Library/Application Support/Code/User/globalStorage/CodeScoring.codescoring-sca/johnny

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

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

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

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

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

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

• В настройках VS Code измените installationType на docker
• Или в settings.json:

"codescoringSca.installationType": "docker"

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

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

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

   "codescoringSca.dockerOptions": "--memory=2g --cpus=2"

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

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

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

{
  "codescoringSca.installationType": "docker",
  "codescoringSca.dockerImage": "johnny-depp:2025.29.0",
  "codescoringSca.dockerRegistry": "sample-codescoring-registry.com",
  "codescoringSca.dockerOptions": ""
}

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

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

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

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

#Метод 1: Использование боковой панели

1. Откройте папку проекта в VS Code
2. Нажмите на иконку CodeScoring в панели действий
3. В боковой панели "CODESCORING: CODESCORING SCA" нажмите кнопку "Run Scan"

#Метод 2: Использование палитры команд

1. Нажмите Ctrl+Shift+P (или Cmd+Shift+P на MacOS), чтобы открыть палитру команд
2. Введите "Run Johnny CLI Scan"
3. Выберите "CodeScoring SCA: Run Johnny CLI Scan" из списка

#Метод 3: Использование строки состояния

1. Посмотрите на нижнюю строку состояния VS Code
2. Найдите индикатор "CodeScoring CLI"
3. Нажмите на него, чтобы открыть меню Johnny CLI
4. Выберите "Run Johnny CLI Scan" из списка

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

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

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

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

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

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

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

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

1. Проверьте уведомления: Посмотрите на уведомления в правом нижнем углу VS Code, нажав на "View Report"
2. Откройте дерево уязвимостей (открывается само по умолчанию): Используйте кнопку "Open Vulnerabilities View" из боковой панели
3. Просмотрите уязвимости: Панель уязвимостей покажет все обнаруженные проблемы безопасности в Ваших зависимостях
4. Изучите детали: Вы можете нажимать на отдельные уязвимости, чтобы увидеть подробную информацию
5. Примените исправления: Используйте опции быстрого исправления для обновления уязвимых зависимостей
6. Откройте панель алертов: Используйте кнопку Open Alerts View в боковом меню плагина для открытия окна со списком алертов по сработавшим политикам

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

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

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

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

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

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

7.3.1 Структура древовидного представления

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

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

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

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

• По критичности -> Расположению (по умолчанию): По уровню критичности, подгруппировка по пакету
• По критичности -> Пакету (PURL): По уровню критичности, подгруппировка по имени пакета в алфавитном порядке
• По расположению: Группировка по пути к файлу
• По пакету (PURL): Группировка по пакету

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

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

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

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

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

• Нажмите на предлагаемые обновления версий при наведении мышкой на уязвимый компонент, чтобы автоматически обновить на последнюю версию зависимости
• При нажатии Ctrl+. (Cmd+. на MacOS), когда курсор находится на уязвимом компоненте, Вам предложится выбрать конкретную версию для обновления (при наличии нескольких)

Индивидуальные исправления

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

или

• Наведите курсор клавиатуры на уязвимую зависимость
• Нажмите Ctrl+. (Cmd+. на MacOS)
• Выберите подходящую версию из списка, если их несколько

или

• Кнопка Fix Selected: Выберите один уязвимый компонент или уязвимость, принадлежащую этому компоненту, и компонент будет обновлен до последней безопасной версии

Массовые исправления

• Кнопка Fix All: Обновляет все уязвимые компоненты с доступными исправлениями, видимые в данный момент в дереве, при этом учитывает примененные фильтры (установленные с помощью кнопки с лупой на панели инструментов)

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

Автозагрузка

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

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

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

• Загрузить BOM: Ctrl+Shift+P (или Cmd+Shift+P на MacOS) → "Load BOM File"
• Закрыть BOM: Очищает все данные об уязвимостях и освобождает память

#7.7 Сравнение BOM

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

Автоматическое сравнение

При открытии проекта:

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

Ручное сравнение при открытом BOM

1. Имеется загруженный BOM (целевой)
2. Выполните команду "Compare BOMs"
3. Выберите базовый файл BOM
4. Отобразится результат сравнения в панели DIFF

Ручное сравнение двух произвольных BOM

1. Закройте BOM при необходимости
2. Выполните команду "Compare BOMs"
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)

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

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

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

Вы также можете искать/фильтровать дерево BOM DIFF, чтобы сосредоточиться на интересующих Вас компонентах. Чтобы очистить поиск, нажмите кнопку "Clear Comparison Search" в правом верхнем углу BOM DIFF.

#7.8 Отчеты

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

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

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

• Команда: "View Latest Scan Report"
• Открывается в: Предварительном просмотре HTML в VS Code
• Адаптируется к выбранной цветовой схеме VSCode в момент генерации

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

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

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

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

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

Горячие клавиши

Настройте в параметрах VS Code, например:

{
  "key": "ctrl+shift+s",
  "command": "codescoring-sca.runJohnnyCLI"
}

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

#Логи расширения

• Для подробного понимания шагов функциональности проверьте лог файл расширения, расположенный:
  • Windows: %USERPROFILE%\.vscode\extensions\codescoring-sca-[version]\out\logs\extension.log
  • macOS/Linux: ~/.vscode/extensions/codescoring-sca-[version]/out/logs/extension.log

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

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

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

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

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

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

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

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

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

1. Начальная настройка: Полное сканирование при запуске проекта
2. Обзоры: Сравнивайте BOM между версиями
3. CI/CD:

• Перед коммитом: Выполните полное сканирование
• Поделитесь конфигурацией: Закоммитьте .codescoring/config.yaml
• Игнорируйте временные файлы: Добавьте в .gitignore:

  .codescoring/report.html
  .codescoring/bom.json.*
• Отслеживайте основной BOM: Версионируйте .codescoring/bom.json
• Стандартизируйте: Стандартизируйте настройки расширения

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

1. Code Review:

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

2. Release Management:

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

3. Compliance:

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