scan-results-bridge

Офлайн-конвертация JSON-отчётов средства проверки безопасности CompleteTech в SARIF 2.1.0 или NDJSON с проекцией по умолчанию, сохраняющей конфиденциальность.

Содержание

• Обзор
• Требования
• Быстрый старт
• Офлайн-процесс
• Использование
• Контракты входных данных
• Форматы вывода
• Конфиденциальность и доказательства
• Ограничения
• Интерпретация результатов
• Разработка
• Участие в проекте и безопасность
• Лицензия и брендовые материалы

Обзор

scan_results_bridge.py читает существующие локальные JSON-отчёты и записывает SARIF 2.1.0 или NDJSON. Он необязателен: отдельные средства проверки от него не зависят.

• Офлайн. Он никогда не сканирует цели, не выполняет код, не загружает пакеты, не читает учётные данные и не выгружает данные. Транспорт HEC/syslog и настройка учётных данных не реализованы.
• Только метаданные. Он преобразует предоставленные локальные доказательства. Каждое наблюдение сохраняет exploitability: not_tested; ничего из выдаваемого им не подтверждает эксплуатацию, а указанная исправленная версия никогда не является проверенным развёрнутым патчем или утверждением о безопасности.
• Конфиденциальность по умолчанию. Метки активов, URL-адреса, пути, текстовые описания доказательств и подобные значения заменяются идентификаторами SHA-256, если вы не согласитесь публиковать относительные исходные пути. См. Конфиденциальность и доказательства.
• Отказ при ошибках. Неподдерживаемые инструменты или версии, а также некорректные или противоречивые входные данные приводят к завершению с кодом 2 вместо частичной конвертации.

Требования

• Python 3.10 или новее (CI запускается на 3.10 и 3.14 в Linux, Windows и macOS).
• Устанавливать ничего не нужно: один автономный файл, только стандартная библиотека.
• jsonschema требуется только для необязательной проверки выдаваемого SARIF при разработке.

Быстрый старт

Прилагаемый пример является синтетическим.

# Convert a report to SARIF (the output file must not already exist)
python scan_results_bridge.py --input examples/report.json --format sarif --output report.sarif

# NDJSON to stdout, publishing reported relative source paths
python scan_results_bridge.py --input examples/report.json --format ndjson --include-relative-paths

# A legacy node2shell-check report (placeholder file name), failing CI on findings or unknowns
python scan_results_bridge.py --input node-report.json --input-schema node2shell-v1 --fail-on either

# Run the tests and show all options
python -m unittest -v
python scan_results_bridge.py --help

Не включайте в коммиты посторонние отчёты.

Работа в офлайн-режиме

Инструмент использует только предоставленные локальные данные. Он не связывается с целевыми системами и не запускает оцениваемое программное обеспечение.

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

python scan_results_bridge.py --input REPORT [--input REPORT ...]
    [--input-schema PROFILE] [--format {sarif,ndjson}] [--include-relative-paths]
    [--fail-on {none,findings,unknown,either}] [--output FILE [--force]]

Параметры

Параметр	Значение
--input FILE	Обязательный. Существующий файл отчёта JSON; повторяйте до 20 входных файлов.
--input-schema PROFILE	Входной контракт; по умолчанию contract-v1.0. Один профиль применяется ко всем входным файлам в вызове.
--format {sarif,ndjson}	Формат вывода; по умолчанию sarif.
--include-relative-paths	Включить публикацию допустимых указанных исходных путей. Расположения, полученные из инвентаризации, никогда не публикуются. См. Конфиденциальность и доказательства.
--fail-on {none,findings,unknown,either}	Код выхода 1 по политике после успешного вывода; по умолчанию none. См. Коды выхода.
--output FILE	Записать в новый файл вместо stdout.
--force	Атомарно заменить существующий файл --output. Никогда не заменяет входной файл или сам чекер.

Вывод и прерывание

• По умолчанию вывод направляется в stdout. Существующий файл --output отклоняется, если не указан --force.
• Чекер и каждый входной файл защищены от перезаписи, в том числе через символьные или жёсткие ссылки, даже при --force.
• Весь отчёт формируется до публикации чего-либо, а вывод в файл публикуется атомарно.
• Некорректный, неподдерживаемый или превышающий лимиты вход отклоняется до любого вывода.
• Прерывание завершается с кодом 130, и вывод не повторяется. Прерванный stdout или прерывание на границе фиксации файла может оставить неполную или неопределённую публикацию; проверьте или отбросьте её.

Коды выхода

Код	Значение
0	Преобразование успешно, каждый входной файл сообщил complete: true, и выбранная политика --fail-on выполнена.
1	Преобразование успешно и записано, но --fail-on сработала.
2	Операционная ошибка: некорректный, неподдерживаемый или превышающий лимиты вход, защищённый или недоступный для записи вывод, или входной файл, сообщающий complete: false. Неполный вход всё равно преобразуется и записывается до выхода и помечается как неполный в выводе.
130	Прервано.

Политики --fail-on:

Политика	Код выхода 1, когда вывод содержит
none (по умолчанию)	Никогда.
findings	potentially_affected, precondition_present или likely_exposed.
unknown	unknown, unsupported_runtime или source_discrepancy.
either	Любое из вышеперечисленного.

Выход по политике никогда не подавляет результаты. Код выхода 2 имеет приоритет над 1. Операционные ошибки отличаются от результатов оценки.

Входные контракты

Выберите профиль явно с помощью --input-schema; один профиль применяется ко всем входным файлам в вызове. Неподдерживаемые инструменты или версии, а также некорректные или противоречивые канонические доказательства завершаются с ошибкой и кодом выхода 2. Канонический валидатор поставляется из общего контракта Sharp под той же лицензией на код; установленный общий пакет не требуется.