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

Реализация 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
  osa-proxy-url-from-forwarded-headers: false
  enable-status-line: true
  block-on-codescoring-errors: true
  block-message: "Component download blocked by security policy"
  append-block-url-to-message: true
  legacy-judge: false
  stage: proxy
  block-status-code: 403
  judge-concurrency: 16
  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
      remove-blocked-versions: true
      work-mode: strict_wait
    - 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
      remove-blocked-versions: true
      work-mode: strict_wait

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

ivy:
  enabled: true
  repository:
    - name: ivy
      registry: https://scala.jfrog.io/artifactory/ivy-releases
      layout: sbt-default
      scan-package: true
      work-mode: strict_wait

nuget:
  enabled: true
  repository:
    - name: nuget
      registry: https://api.nuget.org
      scan-manifest: true
      scan-package: true
      remove-blocked-versions: true
      work-mode: strict_wait

npm:
  enabled: true
  repository:
    - name: npm
      registry: https://registry.npmjs.org
      scan-manifest: true
      scan-package: true
      remove-blocked-versions: true
      work-mode: strict_wait

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

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

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

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

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

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

docker:
  enabled: true
  repository:
    - name: docker
      registry: https://registry-1.docker.io
      auth-token-url: https://auth.docker.io/token
      scan-container: true
      codescoring-pull-through-proxy: false
      work-mode: strict_wait

admin:
  enabled: false
  address: 127.0.0.1:8081
  write-timeout: 2m
  token-hash: ""

cache:
  judge:
    enabled: false
    redis-db: 1
    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
    username: ""
    password: ""
    db: 0

configuration-store:
  enabled: false
  backend: redis
  deployment-identity: ""
  replica-identity: "osa-proxy-1"
  mode: standalone
  accept-unsafe-durability: false
  redis:
    address: ""

layouts:
  custom-layout: "[organisation]/[module]/[revision]/[type]s/[artifact]-[revision].[ext]"

webhooks:
  - name: downloads
    url: https://hooks.example.com/downloads
    token_env: WEBHOOK_DOWNLOADS_TOKEN
    events: [file_downloaded, scanned_file_downloaded, file_blocked]
    repositories: [npm, maven]
    timeout: 3s
    buffer_size: 256

logging:
  level: info

Секция `codescoring`

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

Текст HTTP status line

HTTP/1.1 status line поддерживает только ASCII. Текст с кириллицей, например Загрузка компонента заблокирована политикой безопасности, не передается в status line. Если причина блокировки должна отображаться в status line Nexus или пакетного менеджера, используйте в block-message только ASCII-символы, например Component download blocked by security policy.

Формирование URL из forwarded headers

Параметр osa-proxy-url-from-forwarded-headers нужен, когда один инстанс OSA Proxy доступен по нескольким внешним URL, например из двух сетевых контуров:

codescoring:
  osa-proxy-url-from-forwarded-headers: true

Reverse proxy каждого контура передает свой X-Forwarded-Proto и X-Forwarded-Host. OSA Proxy использует их при формировании абсолютных ссылок на пакеты в metadata и манифестах, поэтому клиенты каждого контура получают ссылки через доступный им URL. Например, ответы на запросы через osa-proxy.internal.example.com содержат ссылки с этим host, а запросы через osa-proxy.dmz.example.com — ссылки с host DMZ.

Если заголовок X-Forwarded-Proto отсутствует, используется https; если отсутствует X-Forwarded-Host, используется обычный Host. Включайте этот режим только за доверенным reverse proxy, который перезаписывает forwarded headers, а не пропускает значения от клиента.

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

Каждая экосистема содержит флаг 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 включают проверку манифестов и скачиваемых артефактов. При scan-manifest: false metadata npm, NuGet и PyPI не проверяется, но ссылки в ответах по-прежнему переписываются на OSA Proxy. Поддержка режимов зависит от экосистемы; подробнее см. Поддерживаемые протоколы. Параметр work-mode на уровне репозитория переопределяет глобальный codescoring.work-mode.

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

Для composer и pypi доступны packages-registry и additional-packages-registries, если артефакты загружаются с отдельных хостов. Для go указывается sumdb-registry, если нужно проксировать SumDB. Для ivy при scan-package: true необходимо явно выбрать layout: встроенный шаблон (sbt-default или ivy-default) либо пользовательский шаблон из корневой секции layouts. Для docker настраиваются auth-token-url, scan-container и codescoring-pull-through-proxy.

Интеграция с менеджерами репозиториев

Для поддерживаемых экосистем доступны дополнительные варианты передачи в OSA Proxy контекста репозитория и пользователя JFrog Artifactory. Подходящий вариант зависит от версии и конфигурации Artifactory. Подробности по запросу предоставляет поддержка вендора.

Секции artifactory и nexus позволяют периодически получать inventory менеджера репозиториев и автоматически создавать маршруты для выбранных экосистем. Полная настройка discovery, credentials, URL, repository context и ответов о блокировке сгруппирована в отдельных разделах:

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

По умолчанию 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
    tls:
      enabled: false
      ca-file: ""
      server-name: ""

Логирование

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

logging:
  level: info

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

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

Параметр	Назначение
`pypi`	Настройки PyPI-репозиториев.
`maven`	Настройки Maven-совместимых репозиториев для Maven и Gradle.
`ivy`	Настройки Ivy/SBT-репозиториев.
`nuget`	Настройки NuGet-репозиториев.
`npm`	Настройки npm-репозиториев.
`composer`	Настройки Composer/Packagist-репозиториев.
`cocoapods`	Настройки CocoaPods-репозиториев.
`swift`	Настройки Swift Package Manager-репозиториев.
`ruby`	Настройки RubyGems-репозиториев.
`conan`	Настройки Conan v2-репозиториев.
`go`	Настройки Go module proxy.
`hex`	Настройки Hex-репозиториев для Elixir/Erlang.
`r`	Настройки CRAN/R-репозиториев.
`debian`	Настройки Debian-репозиториев.
`alpine`	Настройки Alpine APK-репозиториев.
`rpm`	Настройки RPM/YUM/DNF-репозиториев.
`docker`	Настройки Docker Registry API v2.
`artifactory`	Автоматическое обнаружение и маршрутизация репозиториев JFrog Artifactory.
`nexus`	Автоматическое обнаружение и маршрутизация репозиториев Nexus Repository Manager 3.
`codescoring`	Подключение к CodeScoring и поведение проверок.
`admin`	Настройки отдельного HTTP-сервера администрирования (Admin API, Swagger UI).
`configuration-store`	Хранилище динамической конфигурации в Redis.
`layouts`	Пользовательские шаблоны путей для Ivy-репозиториев.
`webhooks`	Исходящие webhook-уведомления о скачивании и блокировке файлов.
`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`, `cocoapods`, `swift`, `ruby`, `conan`, `go`, `hex`	Включает проверку и модификацию манифестов/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`, `cocoapods`	Карта дополнительных host -> registry для пакетов, которые публикуют артефакты на нескольких доменах. Для CocoaPods разрешает переписывание `source.http` через OSA Proxy. Подробнее в разделе Настройка CocoaPods.
`sumdb-registry`	`go`	URL Go checksum database, например `https://sum.golang.org`, если SumDB-запросы должны проходить через OSA Proxy.
`signing-private-key`	`hex`	Стабильный RSA private key в PEM-формате. Имеет приоритет над `signing-private-key-file`; файл не читается, если заданы оба параметра.
`signing-private-key-file`	`hex`	Путь к стабильному RSA private key, общему для всех реплик. Используется, когда `signing-private-key` пуст. Один из двух параметров обязателен при `scan-manifest: true`.
`remove-blocked-versions`	`npm`, `nuget`, `pypi`, `swift`, `hex`	Удаляет заблокированные версии из metadata; значение по умолчанию — `true`. Для Swift значение `false` добавляет `problem: 410`, а для Hex оставляет release как `retired: security`. Подробнее в разделах Настройка Swift и Настройка Hex.
`distro`	`debian`, `alpine`	Имя дистрибутива или ветки репозитория, которое используется при обработке metadata и путей пакетов.
`auth-token-url`	`docker`	Полный точный URL token endpoint. OSA Proxy не добавляет `/token`; для Docker Hub используйте `https://auth.docker.io/token`. Поле можно не задавать для registry без Bearer token service.
`layout`	`ivy`	Имя шаблона путей (`sbt-default`, `ivy-default` или имя из `layouts`). Обязателен при `scan-package: true`.
`scan-container`	`docker`	Включает проверку манифестов контейнерных образов через CodeScoring. По умолчанию `true`. При `false` манифесты и слои пропускаются без проверки.
`codescoring-pull-through-proxy`	`docker`	Передает публичный URL прокси и временный bypass-токен в CodeScoring для обратного скачивания образа без повторного сканирования. По умолчанию `false`. Требует `codescoring.token`.

`file-type-filter`

Параметр	Назначение
`enabled`	Явно включает фильтрацию по расширениям. Фильтр активируется только при `true`; списки расширений сами по себе его не включают.
`additional-allowed-extensions`	Добавляет расширения к встроенному preset экосистемы. Значения можно указывать с точкой или без неё; они приводятся к нижнему регистру.
`scanned-extensions`	Заставляет handler считать файлы с этими расширениями package artifacts для сканирования и краткоживущего кэша результата.

Фильтр работает только для репозиториев не-Docker экосистем. Он выключен, пока явно не задано enabled: true, в том числе при секции {} или заполненных списках расширений. В выключенном состоянии запросы обрабатываются по обычным правилам handler'а.

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

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

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

Экосистема	Разрешенные расширения
`npm`	`.tgz`
`composer`, `cocoapods`	`.zip`, `.tar`, `.tgz`, `.tar.gz`, `.tar.bz2`, `.tar.xz`
`swift`	`.zip`
`pypi`	`.whl`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.zip`, `.egg`
`nuget`	`.nupkg`, `.snupkg`
`ruby`	`.gem`
`conan`	`.py`, `.tgz`
`go`	`.zip`
`hex`	`.tar`, `.tar.gz`
`r`	`.tar.gz`, `.tgz`, `.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`
`ivy`	Расширения Maven плюс `.tgz`, `.tar`, `.tar.bz2`, `.tar.xz`

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

additional-allowed-extensions только расширяет allow-list: это поле не включает фильтр и не заставляет handler отправлять такие файлы на package scan. Чтобы новый тип файла участвовал в 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:
        enabled: true
        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: {}

Чтобы включить фильтр без добавления новых расширений, задайте enabled: true. Тогда для 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:
        enabled: true

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

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

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

`codescoring`

Параметр	Значение по умолчанию	Назначение
`url`	Обязательный параметр	URL платформы CodeScoring.
`token`	Обязательный параметр	Токен доступа к CodeScoring API.
`work-mode`	`strict_wait`	Глобальный режим работы: `warmup`, `spectator`, `moderate`, `strict`, `strict_wait`.
`osa-proxy-url`	Обязателен при выключенном forwarded-режиме	Абсолютный HTTP(S) URL OSA Proxy. Используется при генерации ссылок и подмене URL в ответах.
`osa-proxy-url-from-forwarded-headers`	`false`	При `true` формирует URL из `X-Forwarded-Proto` и `X-Forwarded-Host`. Используйте, когда один инстанс доступен по разным URL: ссылки на пакеты в metadata и манифестах будут соответствовать URL текущего контура. Fallback — `https` и обычный `Host`. Включайте только за доверенным reverse proxy.
`enable-status-line`	`false`	Добавляет причину блокировки в HTTP/1.1 status line. Не влияет на HTTP/2 и HTTP/3; Docker-клиенты читают JSON body.
`block-on-codescoring-errors`	`true`	Блокирует скачивание, если CodeScoring вернул ошибку или пакет не удалось проверить.
`block-message`	Не задан	Пользовательский текст ответа о блокировке. Если значение не задано или пустое, OSA Proxy использует стандартное сообщение, соответствующее причине блокировки.
`append-block-url-to-message`	`true`	Добавляет ссылку на причину блокировки к пользовательскому сообщению, если ссылка получена от CodeScoring.
`legacy-judge`	`false`	Включает совместимость с версиями Judge до `2026.20.0`. Используйте только для инсталляций CodeScoring со старой версией сервиса Judge.
`stage`	`proxy`	Значение stage/context, передаваемое в проверки CodeScoring.
`block-status-code`	`403`	HTTP-код ответа при блокировке пакета.
`judge-concurrency`	`16`	Ограничивает количество параллельных обращений к Judge. Чем ниже значение, тем меньше одновременных запросов OSA Proxy отправляет в Judge при проверке больших списков версий и фоновом обновлении кэша.
`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.
`redis-db`	Не задан	Переопределяет `cache.redis.db` для кэшей вердиктов и handler'ов.
`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`.
`username`	Имя пользователя Redis ACL.
`password`	Пароль Redis.
`db`	Номер Redis database.
`tls.enabled`	Включает TLS 1.2 или новее для Redis. По умолчанию `false`; проверка сертификата всегда включена.
`tls.ca-file`	Необязательный путь к дополнительному PEM CA bundle. Сертификаты добавляются к системным корням доверия.
`tls.server-name`	Необязательная общая SNI/verify identity для Redis, Sentinel и найденного master. По умолчанию используется hostname каждого подключения.
`sentinel.enabled`	Включает Redis Sentinel; при этом `address` можно не задавать.
`sentinel.master-name`	Имя master-группы Sentinel.
`sentinel.addresses`	Список Sentinel endpoints в формате `host:port`.
`sentinel.username`	Имя пользователя Sentinel ACL.
`sentinel.password`	Отдельный пароль Sentinel.

Полная настройка TLS, корпоративных CA, Docker Compose и Helm приведена в разделе Настройка Redis и кэширования.

`logging`

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

OSA Proxy пишет логи в JSON. Для каждого входящего запроса создаётся одно завершающее событие уровня info с именем http request completed и полями component, method, ограниченным по cardinality route, путём запроса path без query-параметров, status, status_class, outcome и duration_ms. При наличии tracing context событие также содержит trace_id и span_id.

`admin`

Параметр	Значение по умолчанию	Назначение
`enabled`	`false`	Включает выделенный HTTP-сервер администрирования.
`address`	`127.0.0.1:8081`	Сетевой адрес и порт для прослушивания административных запросов.
`write-timeout`	`2m`	Таймаут на запись ответа административного сервера.
`token-hash`	`""`	SHA-256 хэш Bearer-токена в нижнем регистре (hex). Для использования переменной окружения `OSA_PROXY_ADMIN_TOKEN_HASH` укажите в этом поле `${OSA_PROXY_ADMIN_TOKEN_HASH:}`.

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

`configuration-store`

Параметр	Значение по умолчанию	Назначение
`enabled`	`false`	Включает централизованное хранилище динамической конфигурации в Redis.
`backend`	`redis`	Бэкенд хранилища (поддерживается только `redis`).
`deployment-identity`	`""`	Идентификатор кластера/деплоя (обязателен при `enabled: true`).
`replica-identity`	Hostname, затем сгенерированный process identity	Идентификатор для heartbeat и lease реплики. Helm передаёт имя pod через `OSA_PROXY_REPLICA_IDENTITY`.
`mode`	`standalone`	Режим работы Redis: `standalone` или `sentinel`.
`accept-unsafe-durability`	`false`	Разрешает запуск без персистентности (`noeviction` и persistence).
`history-limit`	`20`	Максимальное количество сохраняемых исторических ревизий.
`poll-interval`	`30s`	Интервал опроса хранилища на наличие новых ревизий.
`operation-timeout`	`5s`	Таймаут операций с Redis в хранилище конфигураций.
`heartbeat-interval`	`10s`	Интервал обновления heartbeat реплики.
`lease-ttl`	`30s`	Время жизни lease реплики в реестре активных инстансов.
`redis-db`	`null`	Переопределение номера базы Redis при наследовании подключения из `cache.redis`.
`redis`	`{}`	Выделенные параметры подключения к Redis (аналогичны секции `cache.redis`). При отсутствии блок наследуется из `cache.redis`.

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

`layouts`

Корневая секция layouts содержит карту пользовательских шаблонов путей для репозиториев Ivy (sbt). Ключ — имя шаблона, значение — строка формата раскладки каталогов:

layouts:
  custom-layout: "[organisation]/[module]/[revision]/[type]s/[artifact]-[revision].[ext]"

Подробнее см. в разделе Настройка Ivy.

`webhooks`

Секция webhooks задает список подписок на исходящие HTTP POST-уведомления:

Параметр	Значение по умолчанию	Назначение
`name`	`""`	Читаемое имя подписки.
`url`	—	HTTP(S) URL receiver'а уведомлений. Обязательный параметр.
`token_env`	`""`	Имя переменной окружения с токеном авторизации (передается в `X-CodeScoring-Authentication`).
`enabled`	`true`	Флаг активности подписки.
`events`	—	Список событий: `file_downloaded`, `scanned_file_downloaded`, `file_blocked`.
`repositories`	`[]`	Список имен репозиториев для фильтрации (пустой — все non-Docker репозитории).
`timeout`	`3s`	Таймаут одного HTTP POST запроса к receiver'у.
`buffer_size`	`256`	Размер очереди в памяти для данной подписки.

Подробнее см. в разделе Настройка webhooks.

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

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

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

#Секция codescoring

#Формирование URL из forwarded headers

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

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

#Интеграция с менеджерами репозиториев

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

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

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

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

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

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

#file-type-filter

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

#codescoring

#codescoring.resilience.retry

#codescoring.resilience.circuit-breaker

#http.server

#http.client

#cache.judge

#cache.redis

#logging

#admin

#configuration-store

#layouts

#webhooks