Metadata-Version: 2.5
Name: efs-sbom
Version: 1.0.5
Summary: Easy FSTEC SBOMs — генерация, проверка и обогащение SBOM (CycloneDX) под требования ФСТЭК и ГОСТ Р 56939-2024
Project-URL: Homepage, https://github.com/happykust/efs
Project-URL: Repository, https://github.com/happykust/efs
Project-URL: Issues, https://github.com/happykust/efs/issues
Project-URL: Changelog, https://github.com/happykust/efs/blob/main/CHANGELOG.md
Author-email: Kirill Nikolaevskiy <me@happykust.dev>
Maintainer-email: Kirill Nikolaevskiy <me@happykust.dev>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: compliance,cyclonedx,fstec,gost,sbom,security,supply-chain
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: Russian
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.12
Requires-Dist: jsonschema>=4.22.0
Requires-Dist: odfpy>=1.4.1
Requires-Dist: platformdirs>=4.9.4
Requires-Dist: questionary>=2.0
Requires-Dist: referencing>=0.35.0
Requires-Dist: requests>=2.32.5
Requires-Dist: rfc3339-validator>=0.1.4
Requires-Dist: rfc3987>=1.3.8
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# efs — Easy FSTEC SBOMs

[![CI](https://github.com/happykust/efs/actions/workflows/ci.yml/badge.svg)](https://github.com/happykust/efs/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/efs-sbom.svg)](https://pypi.org/project/efs-sbom/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)

CLI-приложение для подготовки перечня заимствованных программных компонентов под требования ФСТЭК России и ГОСТ Р 56939-2024: генерация SBOM, валидация, обогащение ссылками на исходный код и ГОСТ-свойствами, объединение и экспорт в CSV/ODT.

Формат — CycloneDX 1.6 (JSON) с расширениями ГОСТ (`GOST:attack_surface`, `GOST:security_function`, `GOST:source_langs`, `GOST:provided_by`).

## Возможности

### Генерация SBOM

`efs scan` запускает внешний сканер — cdxgen или trivy — с настройками из конфига, поэтому команда сборки перечня одинакова на всех машинах и в CI. Для cdxgen параметры записываются в `.cdxgenrc`, для trivy задаются подкоманда (`fs`, `image`, `repo`) и дополнительные аргументы. Сам efs код не сканирует.

### Постобработка вывода сканера

`efs postprocess` превращает машинный вывод в перечень:

* убирает поля, которые сканер добавляет для себя, и оставляет то, что требует схема;
* проставляет ГОСТ-свойства — из конфига поштучно или значением по умолчанию;
* подставляет ссылки на исходный код по purl, с приоритетом точной записи с версией над записью без версии;
* выводит язык программирования из экосистемы purl и пишет каждый язык отдельным свойством `GOST:source_langs`, как требует ФСТЭК;
* исключает компоненты, которые в перечень не входят: `exclude: true` уносит и те зависимости, которых больше никто не держит, `exclude: "direct"` убирает только сам компонент, `exclude: false` оставляет компонент принудительно;
* удаляет компоненты-манифесты (`package-lock.json`, `uv.lock`, `pom.xml`), перенося их связи на корневой компонент, чтобы каскад не принял реальные зависимости продукта за ненужные;
* заполняет сведения о самом продукте — название, версию, изготовителя, назначение, ссылку на исходники или `GOST:provided_by`;
* дописывает в конфиг компоненты, которых там ещё нет, чтобы следующий прогон видел полный список.

### Проверка

`efs check` отвечает на два разных вопроса: корректен ли файл и годится ли он к сдаче.

* валидация по схеме CycloneDX 1.6 с обнаружением дубликатов ключей JSON;
* отдельная схема для контейнерной формы перечня: проверяется, что образ не заявляет поверхность атаки и функции безопасности ниже, чем у входящих в него компонентов;
* проверка доступности ссылок на репозитории (`--check-vcs`) — git, svn, hg и fossil, многопоточно, с кешированием результатов между запусками;
* проверка ссылок на дистрибутивы исходного кода (`--check-source-distribution`);
* проверка заполненности: ГОСТ-свойства, языки, назначение образа, сведения о продукте, наличие либо ссылки на исходники, либо указания на сертифицированное СЗИ.

Коды возврата различают ситуации: `0` — перечень готов, `1` — ошибки схемы или недоступные ссылки, `3` — схема в порядке, но перечень не заполнен. Команда пригодна для проверки в CI без разбора вывода.

### Поиск ссылок на исходный код

`efs update` ищет репозитории по purl: сначала через ecosyste.ms, затем через резолверы конкретных экосистем — PyPI, npm, Maven Central, NuGet, RubyGems, Debian Sources, Fedora, CentOS Stream, Rocky Linux, ALT Linux. Найденный адрес не записывается на веру, а проверяется как настоящий репозиторий. Команда также переносит выверенные вручную данные из прошлой ревизии перечня (`--update`), чтобы работа не повторялась при каждой сборке.

`efs config find-vcs` делает то же самое для конфига и пропускает компоненты, по которым решение уже принято: с заполненной ссылкой, исключённые и поставляемые в составе СЗИ.

### Сводный перечень

`efs merge` собирает перечень уровня продукта из перечней отдельных сервисов: каждый входной файл становится одним компонентом, ГОСТ-свойства агрегируются по правилу `yes` важнее `indirect` важнее `no`, языки объединяются. Отдельный режим — слияние сырых отчётов trivy с дедупликацией компонентов, зависимостей и уязвимостей.

### Экспорт

`efs export csv` и `efs export odt` выгружают перечень в таблицу и в документ по отчётной форме, отдельно для обычного перечня и для контейнерной формы.

### Конфигурация

Единый файл `.efs-config.json` описывает продукт, значения по умолчанию, настройки сканера и каждый компонент: ссылку на исходники, ГОСТ-свойства, языки, изготовителя, pedigree для форков, правило исключения. `efs config init` создаёт его из готового SBOM и обновляет при последующих запусках, `efs config migrate` переносит старые файлы маппинга, `efs config status` показывает, что осталось заполнить. Для первого знакомства есть интерактивный мастер `efs init`.

## Требования

* Python 3.12 или выше
* [cdxgen](https://github.com/CycloneDX/cdxgen) или [trivy](https://github.com/aquasecurity/trivy) — для генерации SBOM
* git, subversion, mercurial — опционально, для проверки ссылок на репозитории

## Установка

```bash
uv tool install efs-sbom     # или: pip install efs-sbom
```

Из исходников:

```bash
git clone https://github.com/happykust/efs.git
cd efs
uv sync
```

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

```bash
efs scan                                  # сгенерировать SBOM (cdxgen или trivy)
efs config init bom.json                  # создать конфиг из SBOM
                                          # отредактировать .efs-config.json
efs postprocess bom.json result.json \
  --app-name "МойПродукт" --app-version "1.0.0" --manufacturer "ООО МояКомпания"
efs check result.json                     # проверить схему и заполненность
efs export odt result.json perechen.odt   # выгрузить документ
```

Или пройти всё через интерактивный мастер:

```bash
efs init
```

`efs check` возвращает `0`, если перечень готов, `1` при ошибках схемы и `3`, если перечень не заполнен, — команда годится для проверки в CI.

## Документация

| Документ | О чём |
|----------|-------|
| [Подготовка перечня под ФСТЭК](docs/fstec.md) | Путь от исходников до готового документа: что требуется, что заполняется автоматически, а что руками |
| [Справочник команд](docs/commands.md) | Все команды с аргументами и примерами |
| [Конфиг `.efs-config.json`](docs/config.md) | Структура конфига, ГОСТ-свойства, исключения, pedigree, языки |

Пример заполненного перечня — [`examples/example-sbom.json`](examples/example-sbom.json); он проходит `efs check` и годится как образец.

## Разработка

```bash
uv sync              # зависимости, включая dev-группу
uv run pytest        # тесты
uv run ruff check .  # линтер
uv run ruff format . # форматирование
```

Как оформлять изменения и выпускать релизы — в [CONTRIBUTING.md](CONTRIBUTING.md). Об уязвимостях сообщайте по процедуре из [SECURITY.md](SECURITY.md), не через публичный issue. Правила общения — в [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

## Происхождение

Проект является производной работой от [sbom-checker](https://gitlab.community.ispras.ru/sdl-tools/sbom-checker), разработанного в Институте системного программирования РАН (ИСП РАН) и распространяемого на условиях Apache License 2.0. Атрибуция приведена в файле [NOTICE](NOTICE).

## Лицензия

[Apache-2.0](LICENSE)
