• Русский

    • OSA Proxy

    Реализация OSA Proxy

    Эта страница относится к текущей реализации OSA Proxy. Архивная Java/Spring-реализация доступна в разделе Архивная Java/Spring-реализация.

    OSA Proxy — это прокси-сервис, выступающий посредником между пакетными менеджерами и их удалёнными репозиториями. Он интегрируется с платформой CodeScoring и обеспечивает автоматическое сканирование загружаемых компонентов и блокировку небезопасных пакетов в соответствии с политиками безопасности.

    Сервис перехватывает запросы, выполняемые пакетными менеджерами, отправляет их в исходные репозитории, анализирует полученные пакеты, модифицирует ответы и управляет доступом к компонентам.

    В основе сервиса используется асинхронная модель обработки и механизм автоматических повторов при временных ошибках.

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

    OSA Proxy поддерживает следующие типы реестров:

    • npm;
    • Composer;
    • Maven;
    • Gradle (через Maven-совместимые репозитории);
    • Ivy (sbt / Apache Ivy);
    • NuGet;
    • PyPI;
    • R (CRAN);
    • CocoaPods;
    • Swift Package Registry;
    • RubyGems;
    • Conan v2;
    • Go modules;
    • Hex;
    • Debian;
    • Alpine;
    • RPM;
    • Docker Registry API v2.
    Альтернативные репозитории

    OSA Proxy может работать не только с публичными реестрами, но и с менеджерами репозиториев, которые реализуют протоколы соответствующих экосистем, например Sonatype Nexus Repository, JFrog Artifactory или CodeScoring.Save.

    Интеграция с Artifactory и Nexus

    Настройка автоматического discovery, клиентских маршрутов, repository context и ответов о блокировке описана на страницах JFrog Artifactory и Nexus Repository.

    Основные возможности

    Сканирование манифестов и пакетов

    Для поддерживаемых экосистем доступны два уровня проверки:

    • сканирование манифестов — анализ metadata/индексов пакетов и исключение заблокированных политиками версий из ответа пакетному менеджеру;
    • сканирование пакетов — проверка скачиваемых архивов, бинарных пакетов или образов перед передачей клиенту.

    Поддержка уровней зависит от экосистемы. Например, npm, Maven, NuGet, PyPI, CocoaPods, Swift, Go, Hex, Composer и RubyGems поддерживают проверку metadata и пакетов, а R, Debian, Alpine и RPM — проверку скачиваемых пакетов без модификации системных индексов.

    Блокировка небезопасных компонентов

    Если компонент нарушает политики безопасности, OSA Proxy может удалить небезопасные версии из metadata, заблокировать скачивание артефакта и вернуть настраиваемый HTTP-код блокировки.

    Модификация ответов

    При включенном сканировании манифестов сервис модифицирует ответы upstream-реестров: удаляет заблокированные версии, обновляет ссылки на скачивание через прокси и сохраняет формат ответа, ожидаемый пакетным менеджером.

    Кэширование вердиктов

    Для снижения нагрузки на CodeScoring и ускорения повторных запросов OSA Proxy поддерживает Redis-кэш результатов проверки Judge. Кэш выключен по умолчанию и настраивается в секции cache.

    Маршруты

    Для всех экосистем, кроме Docker, имя маршрута берется из поля name в секции repository файла osa-proxy.yml.

    Тип реестраФорма маршрута
    npm, Composer, Maven, Ivy, NuGet, PyPI, R, CocoaPods, Swift, Ruby, Go, Hex, Debian, Alpine, RPMGET /{repository-name}/{path...}
    Docker/v2/{path...} и GET /token

    Например, репозиторий npm с именем npm будет доступен по адресу:

    https://osa-proxy.example.com/npm/

    Docker-режим использует стандартные endpoints Docker Registry API v2 и не добавляет имя репозитория в путь:

    docker pull osa-proxy.example.com/library/alpine:latest

    Если включено несколько Docker-репозиториев, используйте поддомены, где поддомен соответствует repository[*].name, например dockerhub.osa-proxy.example.com. Подробнее см. в разделе Настройка Docker.

    Служебные endpoints

    Основной порт сервиса (по умолчанию 8080)

    EndpointНазначение
    GET /healthzПроверка жизнеспособности процесса (liveness probe).
    GET /readyzПроверка готовности сервиса к обработке запросов (readiness probe).
    GET /metricsМетрики сервиса в формате Prometheus.

    Порт администрирования (по умолчанию 8081)

    При включенном admin.enabled: true на защищённом административном listener доступны:

    EndpointНазначение
    GET /swagger/Интерактивная документация Swagger UI.
    GET /openapi.jsonСпецификация OpenAPI 3 в формате JSON.
    GET /api/v1/statusСостояние хранилища, статус синхронизации реплик и номер ревизии.
    GET /api/v1/runtime/repositoriesСписок всех активных маршрутов (статических и динамических).
    GET /api/v1/configurationЭкспорт желаемого состояния динамической конфигурации репозиториев.
    GET /api/v1/configuration/repositories/{package_type}Чтение желаемой конфигурации репозиториев одной пакетной экосистемы.
    PUT /api/v1/configuration/repositories/{package_type}Замена желаемого списка репозиториев одной пакетной экосистемы (требуются Configuration Store и If-Match).
    POST /api/v1/configuration/revisions/{revision}/rollbackАтомарный откат конфигурации к указанной ревизии.
    DELETE /api/v1/cache/purlsТочечное удаление записей из кэша вердиктов по PURL.
    DELETE /api/v1/cache/packages/{packageType}Очистка записей кэша вердиктов по типу пакета и имени.

    Подробнее о настройке токена доступа и вызове методов см. в разделе Admin API и управление.

    Режимы работы

    Поведение проверки задается параметром work-mode. Его можно указать глобально в codescoring.work-mode и переопределить для конкретного репозитория через repository[*].work-mode.

    • warmup — разогрев кэша без блокировки компонентов;
    • spectator — разогрев кэша и сохранение результатов запросов без блокировки;
    • moderate — блокировка по политикам, загрузка непросканированных компонентов разрешена;
    • strict — блокировка по политикам, загрузка непросканированных компонентов запрещена;
    • strict_wait — блокировка по политикам с ожиданием проверки для непросканированных компонентов.
    Страница была полезна?