oss-analyzer

Набор для анализа кода на 100% с открытым исходным кодом (безопасность и соответствие требованиям) для CI GitLab и GitHub Actions — SCA, SAST, секреты и лицензии, управляемые единой версионируемой политикой. Многоязычные репозитории (Go, Rust, Java/JVM, Python, JS/TS, C/C++). Без SaaS, код не отправляется третьим лицам.

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

oss-analyzer контролирует репозиторий на предмет безопасности и соответствия требованиям в CI: он запускает сканеры, применяет единую версионируемую политику и выносит единый вердикт, с HTML-панелью мониторинга и отчётами для merge request.

flowchart LR
    repo["Your repository"]
    subgraph checks["Scanners: they collect, never block"]
        deps["Dependencies<br/>Syft SBOM<br/>Grype, OSV-Scanner"]
        licenses["Licenses<br/>license gate on the SBOM<br/>policy-licenses.yml"]
        code["Code<br/>Semgrep<br/>policy-semgrep.yml"]
        secrets["Secrets<br/>Gitleaks, whole git history<br/>policy-gitleaks.toml"]
        iac["Dockerfiles, IaC<br/>Trivy"]
        headers["SPDX headers<br/>REUSE"]
    end
    policy{{"Policy<br/>thresholds, modes, exceptions<br/>policy-global.yml"}}
    verdict(["One verdict: pass or block<br/>dashboard, merge request reports"])

    repo --> deps & licenses & code & secrets & iac & headers --> policy --> verdict

Файлы policy-* — это ваши настройки в папке security/: каждый из них необязателен и дополняет значения по умолчанию oss-analyzer (см. Настройка oss-analyzer).

Каждая находка попадает в единый дашборд, здесь — на намеренно уязвимом демонстрационном проекте (590 находок, 333 из них блокирующие):

Три способа запуска — с той же политикой и тем же отчётом:

GitLab CI/CD component

include:
  - component: gitlab.com/thalesgroup/oss-analyzer/[email protected]

Вот и всё, на gitlab.com: компонент опубликован в своём CI/CD Catalog из gitlab.com/thalesgroup/oss-analyzer, доступной только для чтения копии этого репозитория. На self-managed инстансе, который может включать только собственные проекты, отзеркальте этот проект туда и подключите его по его пути на вашем инстансе; его образ остаётся в registry.gitlab.com/thalesgroup/oss-analyzer (OSA_IMAGE_REPOSITORY), с тегом коммита компонента. Анализ выполняется на стадии test в merge request'ах, ветке по умолчанию, расписаниях и тегах; osa_report_aggregate — единственная job, которая может блокировать. Дашборд связан как OSS security dashboard в виджете пайплайна MR, а вкладка Reports в MR показывает найденные проблемы (Security scan, Code Quality).

• Образы берутся из их публичных реестров (Docker Hub, ghcr.io) в закреплённых версиях. За зеркалом реестра переопределите входные параметры OSA_<TOOL>_IMAGE — см. Container images.
• Настройки: по умолчанию применяются настройки организации. Для кастомизации добавьте любой из security/policy-global.yml, policy-licenses.yml, policy-semgrep.yml, policy-gitleaks.toml, содержащий только ваши отличия — см. Customizing oss-analyzer.
• Общие входные параметры:

      inputs:
        OSA_DISTRIBUTION_MODEL: distributed   # saas | distributed | oss_library
        OSA_MODE: audit                       # onboarding: report everything, never block
        OSA_JOB_NEEDS: ["build"]              # wait for your build first
  

  Каждый вход документирован на странице CI/CD Catalog компонента и в templates/analyze.yml.
• Проект с накопленным бэклогом: OSA_MODE: audit сообщает обо всём и ничего не блокирует. OSA_GATE_SCOPE: new продолжает блокировать только новое: в merge request блокирует только то, чего ещё нет в последнем успешном отчёте целевой ветки; в остальных случаях находки сообщаются без блокировки (поэтому нужны merge request pipelines). См. Только новые находки.
• Комментарий-сводка в MR: OSA_ENABLE_MR_COMMENT: true публикует вердикт, блокирующие находки и ссылку на дашборд одним комментарием, обновляемым каждым пайплайном. Для этого нужен project access token (scope api, роль Reporter) в маскированной CI/CD-переменной OSA_GITLAB_TOKEN.
• Проект Maven: Maven Central ограничивает частоту запросов с общих раннеров, и тогда разрешённый граф зависимостей теряется. OSA_MAVEN_MIRROR_URL (например, Maven Central remote вашего репозитория артефактов) вместе с маскированной переменной OSA_MAVEN_MIRROR_AUTH, если требуются учётные данные, разрешает зависимости через зеркало — см. Известные подводные камни.
• Версии: фиксируйте минорную версию (@0.4 следует за её патчами). Интерфейс 0.x может ещё меняться до 1.0.0: ломающее изменение повышает минорную версию, см. CHANGELOG.md.

Переиспользуемый workflow GitHub Actions

jobs:
  security:
    uses: ThalesGroup/oss-analyzer/.github/workflows/security.yml@<ref>
    with:
      oss-analyzer-repository: ThalesGroup/oss-analyzer
      oss-analyzer-ref: <ref>   # the same ref as in `uses:`

Входные данные, разрешения и секреты: см. GitHub Actions.

Локальный анализ без CI

Проанализируйте полученный архив проекта (.zip, .tar.gz) или папку без настройки CI:

security/scripts/analyze-archive.sh my-project.zip

Отчёт и HTML-панель сохраняются в security-reports/<project-name>/ — см. Usage.

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

Полная документация — security/README.md: настройка, каждый входной параметр и настройка, отчёты, известные подводные камни. CHANGELOG.md перечисляет версии, начиная с критических изменений.

Зачем нужен oss-analyzer

Для каждой задачи существуют хорошие сканеры с открытым исходным кодом: Semgrep, Gitleaks, Syft, Grype, OSV-Scanner, Trivy, cdxgen, REUSE. Команде редко не хватает ещё одного сканера. Не хватает того, что между ними: одного решения вместо груды отчётов, правил, которые записаны, а не держатся в памяти, и лицензий, к которым относятся так же серьёзно, как к CVE. oss-analyzer — это та самая часть.

Один анализ, всё программное обеспечение

Каждый запуск рассматривает три поверхности того, что вы поставляете, вместе: