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

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

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

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

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
      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
    username: ""
    password: ""
    db: 0

logging:
  level: info

#Секция codescoring

#Формирование 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. Для Docker используется auth-token-url.

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

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

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

По умолчанию 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

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

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

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

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

#file-type-filter

Фильтр работает только для репозиториев не-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:

Для 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

#codescoring.resilience.retry

#codescoring.resilience.circuit-breaker

#http.server

#http.client

#cache.judge

#cache.redis

#logging