Настройка сервиса

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

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

Конфигурация OSA Proxy задается в файле osa-proxy.yml. Пример ниже показывает типовую рабочую конфигурацию с несколькими экосистемами, настройками CodeScoring, HTTP-клиента, Redis-кэша и логирования.

Совместимость с legacy Judge

Для CodeScoring версии ниже 2026.20.0 укажите codescoring.legacy-judge: true. В версиях до 2026.20.0 используется legacy API Judge, а OSA Proxy по умолчанию работает с текущим API Judge.

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

codescoring:
  url: https://codescoring.example.com
  token: "<token>"
  work-mode: strict_wait
  osa-proxy-url: https://osa-proxy.example.com
  enable-status-line: true
  block-on-codescoring-errors: true
  remove-blocked-versions: true
  legacy-judge: false
  stage: proxy
  block-status-code: 403
  judge-concurrency: 10
  resilience:
    retry:
      max-attempts: 3
      wait-duration: 1s
      exponential-backoff-multiplier: 2
    circuit-breaker:
      failure-rate-threshold: 50
      minimum-number-of-calls: 10
      sliding-window-size: 20
      wait-duration-in-open-state: 30s
      permitted-number-of-calls-in-half-open-state: 5

http:
  server:
    read-timeout: 2m
    read-header-timeout: 5s
    idle-timeout: 120s
    shutdown-timeout: 10s
  client:
    connection-timeout: 10s
    response-timeout: 30s
    max-manifest-body-size: 200mb
    max-idle-conns: 100
    max-idle-conns-per-host: 10
    idle-conn-timeout: 90s

pypi:
  enabled: true
  repository:
    - name: pypi
      registry: https://pypi.org
      packages-registry: https://files.pythonhosted.org
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true
    - name: pytorch-pypi
      registry: https://download.pytorch.org
      packages-registry: https://download.pytorch.org
      additional-packages-registries:
        download.pytorch.org: https://download.pytorch.org
        download-r2.pytorch.org: https://download-r2.pytorch.org
        files.pythonhosted.org: https://files.pythonhosted.org
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

maven:
  enabled: true
  repository:
    - name: maven
      registry: https://repo1.maven.org/maven2
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

nuget:
  enabled: true
  repository:
    - name: nuget
      registry: https://api.nuget.org
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

npm:
  enabled: true
  repository:
    - name: npm
      registry: https://registry.npmjs.org
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

composer:
  enabled: true
  repository:
    - name: composer
      registry: https://repo.packagist.org
      packages-registry: https://api.github.com
      additional-packages-registries:
        github.com: https://github.com
        gitlab.com: https://gitlab.com
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

ruby:
  enabled: true
  repository:
    - name: ruby
      registry: https://rubygems.org
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

go:
  enabled: true
  repository:
    - name: go
      registry: https://proxy.golang.org
      sumdb-registry: https://sum.golang.org
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

debian:
  enabled: true
  repository:
    - name: debian
      registry: https://deb.debian.org/debian
      distro: bookworm
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

alpine:
  enabled: true
  repository:
    - name: alpine
      registry: https://dl-cdn.alpinelinux.org/alpine
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

rpm:
  enabled: true
  repository:
    - name: rpm
      registry: https://mirror.stream.centos.org/10-stream/AppStream/x86_64/os
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

docker:
  enabled: true
  repository:
    - name: docker
      registry: https://registry-1.docker.io
      auth-token-url: https://auth.docker.io
      work-mode: strict_wait

cache:
  judge:
    enabled: false
    ttl: 24h
    refresh-after: 30m
    proactive-refresh-enabled: false
    proactive-refresh-interval: 2h
    proactive-refresh-workers: 10
    key-prefix: "cs:judge:"
  redis:
    address: redis:6379
    password: ""
    db: 0

logging:
  level: info

Секция `codescoring`

Параметр	Назначение
`url`	URL платформы CodeScoring.
`token`	Токен доступа к CodeScoring.
`work-mode`	Глобальный режим работы, если он не переопределен на уровне репозитория.
`osa-proxy-url`	Внешний URL OSA Proxy, который используется при формировании ссылок и ответов.
`enable-status-line`	Добавляет причину блокировки в HTTP/1.1 status line, если клиент ее отображает.
`block-on-codescoring-errors`	Блокирует загрузку при ошибках CodeScoring или ошибках сканирования.
`remove-blocked-versions`	Удаляет заблокированные версии из манифестов. Если `false`, версии остаются с пометкой о блокировке, где это поддерживается форматом.
`block-status-code`	HTTP-код для блокировки. По умолчанию используется `403`.
`judge-concurrency`	Количество параллельных запросов к Judge. Используется, чтобы ограничить нагрузку на Judge при проверке больших списков версий и фоновом обновлении кэша.
`resilience.retry`	Настройки повторных запросов к CodeScoring.
`resilience.circuit-breaker`	Настройки circuit breaker для временной деградации внешних вызовов.

Секции пакетных менеджеров

Каждая экосистема содержит флаг enabled и список repository. Имя репозитория становится частью URL OSA Proxy:

npm:
  enabled: true
  repository:
    - name: company-npm
      registry: https://registry.npmjs.org
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait
      url-encoded-config: true

Такой репозиторий будет доступен по адресу:

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

Поля scan-manifest и scan-package включают проверку манифестов и скачиваемых артефактов. Поддержка этих режимов зависит от экосистемы; подробнее см. Поддерживаемые протоколы. Параметр work-mode на уровне репозитория переопределяет глобальный codescoring.work-mode.

Особенности экосистем

Для composer и pypi доступны packages-registry и additional-packages-registries, если артефакты загружаются с отдельных хостов. Для go указывается sumdb-registry, если нужно проксировать SumDB. Для Docker используется auth-token-url.

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

По умолчанию Redis-кэш выключен:

cache:
  judge:
    enabled: false
  redis:
    address: redis:6379

Чтобы включить кэширование:

cache:
  judge:
    enabled: true
    ttl: 24h
    refresh-after: 30m
    proactive-refresh-enabled: false
    proactive-refresh-interval: 2h
    proactive-refresh-workers: 10
    key-prefix: "cs:judge:"
  redis:
    address: redis:6379
    password: ""
    db: 0

Логирование

Уровень логирования задается в logging.level. Поддерживаются значения debug, info, warn и error.

logging:
  level: info

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

Корневые секции

Параметр	Назначение
`pypi`	Настройки PyPI-репозиториев.
`maven`	Настройки Maven-репозиториев.
`nuget`	Настройки NuGet-репозиториев.
`npm`	Настройки npm-репозиториев.
`composer`	Настройки Composer/Packagist-репозиториев.
`ruby`	Настройки RubyGems-репозиториев.
`go`	Настройки Go module proxy.
`debian`	Настройки Debian-репозиториев.
`alpine`	Настройки Alpine APK-репозиториев.
`rpm`	Настройки RPM/YUM/DNF-репозиториев.
`docker`	Настройки Docker Registry API v2.
`codescoring`	Подключение к CodeScoring и поведение проверок.
`http`	Таймауты и лимиты HTTP-сервера и HTTP-клиента.
`cache`	Redis-кэш вердиктов Judge.
`logging`	Уровень логирования сервиса.

Общие параметры секций пакетных менеджеров

Параметр	Где доступен	Назначение
`enabled`	Все пакетные менеджеры	Включает регистрацию маршрутов для экосистемы. Если `false`, репозитории этой секции не обслуживаются.
`repository`	Все пакетные менеджеры	Список upstream-репозиториев для экосистемы.
`repository[*].name`	Все пакетные менеджеры	Имя репозитория. Для non-Docker экосистем становится первым сегментом URL: `/{name}/...`. Должно быть уникальным среди включенных маршрутов.
`repository[*].registry`	Все пакетные менеджеры	URL upstream-реестра, куда OSA Proxy проксирует запросы.
`repository[*].work-mode`	Все пакетные менеджеры	Режим работы для конкретного репозитория. Если пустой, используется `codescoring.work-mode`.
`repository[*].scan-manifest`	`npm`, `composer`, `maven`, `nuget`, `pypi`, `ruby`, `go`	Включает проверку и модификацию манифестов/metadata.
`repository[*].scan-package`	Все, кроме `docker`	Включает проверку скачиваемых файлов пакетов. Для `docker` сканирование образов включено логикой Docker Registry proxy.
`repository[*].url-encoded-config`	Все, кроме `docker`	Включает поддержку URL-safe Base64-контекста в пути для сценариев через Nexus/JFrog и применения политик к конкретному repository context.
`repository[*].file-type-filter`	Все, кроме `docker`	Ограничивает, какие файлы отправляются на пакетное сканирование, по расширениям. Если параметр не задан или выключен, фильтрация не применяется.

Специфичные параметры репозиториев

Параметр	Где доступен	Назначение
`packages-registry`	`pypi`, `composer`	Базовый URL отдельного хоста, с которого скачиваются файлы пакетов, если он отличается от metadata registry.
`additional-packages-registries`	`pypi`, `composer`	Карта дополнительных host -> registry для пакетов, которые публикуют артефакты на нескольких доменах. Нужна для корректной маршрутизации ссылок на внешние package hosts.
`sumdb-registry`	`go`	URL Go checksum database, например `https://sum.golang.org`, если SumDB-запросы должны проходить через OSA Proxy.
`distro`	`debian`, `alpine`	Имя дистрибутива или ветки репозитория, которое используется при обработке metadata и путей пакетов.
`auth-token-url`	`docker`	URL token service Docker Registry. Для Docker Hub обычно `https://auth.docker.io`; для JFrog/Nexus указывается соответствующий endpoint менеджера репозиториев.

`file-type-filter`

Параметр Назначение

additional-allowed-extensions YAML-массив строк. Наличие этого поля включает фильтр: после этого проходят только расширения из встроенного preset и из additional-allowed-extensions, а остальные неизвестные расширения блокируются. Можно указывать с точкой или без точки; значения нормализуются к нижнему регистру и форме с точкой.

scanned-extensions YAML-массив строк. Включает фильтр и заставляет handler рассматривать файлы с этими расширениями как package artifacts для сканирования и краткоживущего кэша результата сканирования. Можно указывать с точкой или без точки.

Параметр	Назначение
`additional-allowed-extensions`	YAML-массив строк. Наличие этого поля включает фильтр: после этого проходят только расширения из встроенного preset и из `additional-allowed-extensions`, а остальные неизвестные расширения блокируются. Можно указывать с точкой или без точки; значения нормализуются к нижнему регистру и форме с точкой.
`scanned-extensions`	YAML-массив строк. Включает фильтр и заставляет handler рассматривать файлы с этими расширениями как package artifacts для сканирования и краткоживущего кэша результата сканирования. Можно указывать с точкой или без точки.

Фильтр работает только для репозиториев не-Docker экосистем. Если секция file-type-filter отсутствует или задана как {}, фильтр выключен: OSA Proxy работает как без фильтра, то есть запросы проходят по обычным правилам handler'а и совместимость с прежним поведением сохраняется. Чтобы включить фильтр, добавьте хотя бы одно из полей additional-allowed-extensions / scanned-extensions. Учитывается именно наличие ключа: например, additional-allowed-extensions: [] включает фильтр, но не добавляет расширений сверх встроенного preset.

При включенном фильтре OSA Proxy:

пропускает metadata/manifest-запросы без проверки расширения;
извлекает имя файла из URL path, декодирует URL-encoded символы и сравнивает расширение без учета регистра;
разрешает файл, если его расширение входит во встроенный preset экосистемы или в additional-allowed-extensions;
разрешает sidecar-файлы checksums и подписи (.metadata, .sha256, .sha512, .sha1, .asc, .md5), только если базовый артефакт тоже разрешен;
сразу блокирует все остальные package file-запросы до обращения к upstream и CodeScoring.

Встроенные presets:

Экосистема	Разрешенные расширения
`npm`	`.tgz`
`composer`	`.zip`, `.tar`, `.tgz`, `.tar.gz`, `.tar.bz2`, `.tar.xz`
`pypi`	`.whl`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.zip`, `.egg`
`nuget`	`.nupkg`, `.snupkg`
`ruby`	`.gem`
`go`	`.zip`
`alpine`	`.apk`
`rpm`	`.rpm`, `.drpm`
`debian`	`.deb`, `.udeb`, `.dsc`, `.orig.tar.gz`, `.orig.tar.xz`, `.orig.tar.bz2`, `.debian.tar.gz`, `.debian.tar.xz`, `.debian.tar.bz2`, `.diff.gz`
`maven`	`.pom`, `.jar`, `.war`, `.ear`, `.rar`, `.dar`, `.zip`, `.tar.gz`, `.aar`, `.apk`, `.aab`, `.nar`, `.hpi`, `.jpi`, `.kar`, `.eba`, `.sar`, `.par`, `.car`, `.mar`, `.har`, `.obr`, `.module`

Для Debian также разрешаются source tarballs вида .orig-*.tar.gz, .orig-*.tar.xz и .orig-*.tar.bz2.

additional-allowed-extensions расширяет только allow-list фильтра. Само наличие этого поля переводит репозиторий в режим allow-list: OSA Proxy разрешает встроенные расширения экосистемы и расширения из additional-allowed-extensions, а все остальные неизвестные package file-расширения блокирует. Параметр нужен, когда в репозитории есть допустимые файлы с нестандартными расширениями и их не нужно блокировать самим фильтром. Он не заставляет handler отправлять такие файлы на package scan: если стандартная стратегия экосистемы не считает расширение сканируемым, запрос пройдет дальше как обычный passthrough. Чтобы новый тип файла также участвовал в package scan, добавьте это расширение в scanned-extensions.

scanned-extensions используется для второго поведения: файлы с этими расширениями считаются сканируемыми package artifacts, даже если стандартная стратегия экосистемы их не распознает. Для таких расширений включается кэш результата сканирования на короткое время, чтобы родственные файлы с одной базой имени могли использовать один вердикт. Например, для Maven можно указать scanned-extensions: [.jar, .pom], чтобы demo-1.0.0.jar и demo-1.0.0.pom группировались по базе demo-1.0.0.

Пример:

npm:
  enabled: true
  repository:
    - name: npm
      registry: https://registry.npmjs.org
      scan-package: true
      file-type-filter:
        additional-allowed-extensions: [tgz, license]
        scanned-extensions: [tgz]

В этом примере .tgz разрешается preset'ом npm и участвует в package scan, а .license дополнительно разрешается фильтром, но не становится сканируемым артефактом.

Пример поведения для npm

Без секции file-type-filter фильтр выключен. Npm handler работает по стандартной логике: package tarball left-pad-1.0.0.tgz отправляется на package scan, а остальные запросы обрабатываются как metadata или passthrough в зависимости от маршрута.

npm:
  enabled: true
  repository:
    - name: npm
      registry: https://registry.npmjs.org
      scan-package: true

Пустая секция также оставляет фильтр выключенным:

npm:
  enabled: true
  repository:
    - name: npm
      registry: https://registry.npmjs.org
      scan-package: true
      file-type-filter: {}

Чтобы включить фильтр без добавления новых расширений, можно задать пустой список. Тогда для npm разрешены только встроенный preset .tgz и sidecar-файлы к разрешенным артефактам. Запрос к left-pad-1.0.0.tgz пройдет и будет проверен, а запрос к left-pad-1.0.0.exe будет заблокирован до upstream и CodeScoring.

npm:
  enabled: true
  repository:
    - name: npm
      registry: https://registry.npmjs.org
      scan-package: true
      file-type-filter:
        additional-allowed-extensions: []

Если нужно разрешить нестандартный файл, но не отправлять его на package scan, добавьте расширение только в additional-allowed-extensions:

npm:
  enabled: true
  repository:
    - name: npm
      registry: https://registry.npmjs.org
      scan-package: true
      file-type-filter:
        additional-allowed-extensions: [license]

В такой конфигурации .tgz будет сканироваться как npm package, .license пройдет фильтр как допустимый файл, а .exe будет заблокирован фильтром.

`codescoring`

Параметр	Значение по умолчанию	Назначение
`url`	Обязательный параметр	URL платформы CodeScoring.
`token`	Обязательный параметр	Токен доступа к CodeScoring API.
`work-mode`	Не задан	Глобальный режим работы: `warmup`, `spectator`, `moderate`, `strict`, `strict_wait`.
`osa-proxy-url`	Не задан	Внешний URL OSA Proxy. Используется при генерации ссылок и подмене URL в ответах.
`enable-status-line`	`false`	Добавляет причину блокировки в HTTP/1.1 status line. Не влияет на HTTP/2 и HTTP/3; Docker-клиенты читают JSON body.
`block-on-codescoring-errors`	`false`	Блокирует скачивание, если CodeScoring вернул ошибку или пакет не удалось проверить.
`remove-blocked-versions`	`true`	Удаляет заблокированные версии из манифестов. При `false` версии остаются в metadata с пометкой о блокировке, если формат это поддерживает.
`legacy-judge`	`false`	Включает совместимость с версиями Judge до `2026.20.0`. Используйте только для инсталляций CodeScoring со старой версией сервиса Judge.
`stage`	Не задан	Значение stage/context, передаваемое в проверки CodeScoring. Обычно используется `proxy`.
`block-status-code`	`403`	HTTP-код ответа при блокировке пакета.
`judge-concurrency`	`10`	Ограничивает количество параллельных обращений к Judge. Чем ниже значение, тем меньше одновременных запросов OSA Proxy отправляет в Judge при проверке больших списков версий и фоновом обновлении кэша. Версии отправляются чанками до `900` PURL, поэтому параметр становится заметен, когда один пакет содержит больше `900` версий и проверка разбивается на несколько запросов.
`resilience`	См. ниже	Настройки устойчивости запросов к CodeScoring.

`codescoring.resilience.retry`

Параметр	Значение по умолчанию	Назначение
`max-attempts`	`3`	Максимальное количество попыток запроса.
`wait-duration`	`1s`	Пауза между попытками.
`exponential-backoff-multiplier`	`2`	Множитель exponential backoff для увеличения паузы между повторами.

`codescoring.resilience.circuit-breaker`

Параметр	Значение по умолчанию	Назначение
`failure-rate-threshold`	`50`	Процент ошибок, после которого circuit breaker открывается.
`minimum-number-of-calls`	`10`	Минимальное число вызовов для расчета error rate.
`sliding-window-size`	`20`	Размер окна, по которому считается статистика ошибок.
`wait-duration-in-open-state`	`30s`	Время ожидания перед переходом из open в half-open.
`permitted-number-of-calls-in-half-open-state`	`5`	Количество пробных запросов в half-open состоянии.

`http.server`

Параметр	Значение по умолчанию	Назначение
`read-timeout`	`2m`	Максимальное время чтения всего входящего запроса.
`read-header-timeout`	`5s`	Максимальное время чтения HTTP-заголовков.
`idle-timeout`	`120s`	Время удержания idle keep-alive соединения.
`shutdown-timeout`	`10s`	Таймаут graceful shutdown.

`http.client`

Параметр	Значение по умолчанию	Назначение
`connection-timeout`	`10s`	Таймаут установки соединения с upstream-реестрами и CodeScoring.
`response-timeout`	`30s`	Таймаут ожидания ответа.
`max-manifest-body-size`	`200mb`	Максимальный размер тела manifest/metadata, которое сервис готов обрабатывать. Поддерживаются значения вроде `200mb`.
`max-idle-conns`	`100`	Максимальное количество idle HTTP-соединений.
`max-idle-conns-per-host`	`10`	Максимальное количество idle HTTP-соединений на один host.
`idle-conn-timeout`	`90s`	Время жизни idle-соединения в HTTP-клиенте.

`cache.judge`

Параметр	Значение по умолчанию	Назначение
`enabled`	`false`	Включает Redis-кэш результатов проверки Judge.
`ttl`	`24h`	Время жизни записи кэша.
`refresh-after`	`30m`	Возраст записи, после которого ее можно обновлять в фоне.
`proactive-refresh-enabled`	`false`	Включает фоновое обновление устаревающих записей.
`proactive-refresh-interval`	`2h`	Период запуска фонового обновления.
`proactive-refresh-workers`	`10`	Количество workers для фонового обновления.
`key-prefix`	Не задан	Префикс Redis-ключей, например `cs:judge:`.

`cache.redis`

Параметр	Назначение
`address`	Адрес Redis в формате `host:port`.
`password`	Пароль Redis.
`db`	Номер Redis database.

`logging`

Параметр	Значение по умолчанию	Назначение
`level`	`info`	Уровень логирования: `debug`, `info`, `warn`, `warning`, `error`. Неизвестное значение трактуется как `info`.

Страница была полезна?

#Настройка сервиса

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

#Секция codescoring

#Секции пакетных менеджеров

#Особенности экосистем

#Кэш вердиктов

#Логирование

#Справочник параметров

#Корневые секции

#Общие параметры секций пакетных менеджеров

#Специфичные параметры репозиториев

#file-type-filter

#Пример поведения для npm

#codescoring

#codescoring.resilience.retry

#codescoring.resilience.circuit-breaker

#http.server

#http.client

#cache.judge

#cache.redis

#logging