#Архивная Java/Spring-реализация OSA Proxy

#Общее описание

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

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

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

#Поддерживаемые пакетные менеджеры

OSA Proxy обрабатывает запросы к следующим репозиториям:

• Maven Central (https://repo1.maven.org/maven2)
• NPM Registry (https://registry.npmjs.org)
• PyPI (https://pypi.org)
• NuGet V3 (https://api.nuget.org)
• Go (https://proxy.golang.org/)
• Debian (https://ports.ubuntu.com/ubuntu-ports)
• Alpine/APK (https://dl-cdn.alpinelinux.org/alpine)
• RPM (https://repo.almalinux.org/almalinux)
• Docker Registry (https://registry-1.docker.io)

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

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

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

• Сканирование манифестов — анализ и исключение заблокированных политиками безопасности версий из манифеста
• Сканирование пакетов — анализ загружаемых файлов пакета

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

Если компонент нарушает правила политики безопасности:

• небезопасные версии исключаются из списка доступных в манифесте;
• скачивание соответствующих архивов блокируется;
• возвращается настраиваемый код состояния с сообщением о причине блокировки.

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

OSA Proxy автоматически модифицирует ответы от оригинальных репозиториев:

• перенаправляет все URL;
• удаляет заблокированные версии из метаданных;
• пересчитывает контрольные суммы изменённых манифестов, чтобы сохранить корректность формата.

#Кэширование результатов проверки политик

Для ускорения обработки запросов и снижения нагрузки на платформу поддерживается кэширование результатов проверки политик (вердиктов сервиса Judge) в Redis. Поддерживается фоновое обновление устаревших записей.

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

Поведение сканирования пакетов регулируется параметром work-mode. В зависимости от выбранного значения меняется логика обработки сканирования, ожидания и блокировки. Поддерживаются следующие режимы:

• warmup – загрузка данных в кэш CodeScoring без блокировки компонентов;
• spectator – загрузка данных в кэш CodeScoring без блокировки компонентов, сохранение результатов запросов компонентов в платформе;
• moderate – блокировка компонентов, не прошедших проверку политик. Разрешена загрузка непросканированных компонентов;
• strict – блокировка компонентов, не прошедших проверку политик. Запрещена загрузка непросканированных компонентов;
• strict_wait – блокировка компонентов, не прошедших проверку политик. Ожидание проверки для непросканированных компонентов.

#Развертывание

После настройки файла application.yml приложение может быть либо развернуто и выполнено в среде контейнера Docker, либо оркестрировано с помощью Helm-чарта в Kubernetes.

#Развертывание в контейнере Docker

Чтобы запустить приложение как контейнер Docker, выполните следующую команду:

docker run -d \
-p 8080:8080 \
-e SPRING_CONFIG_ADDITIONAL_LOCATION=file:/app/config/ \
-v /path/to/your/config/application.yml:/app/config/application.yml \
--name cs-proxy \
<registry-address>/cs-proxy:<tag>

#Развертывание в Kubernetes (Helm Chart)

Для сред Kubernetes приложение может быть развернуто с использованием предоставленного Helm-чарта, доступного по адресу https://{REGISTRY_URL}/repository/helm.

Порядок установки:

1. Создать namespace.

   kubectl create namespace cs-proxy

2. Создать secret для доступа к приватному реестру Docker-образов, используя адрес (REGISTRY_URL), логин (USERNAME) и пароль (PASSWORD), полученные от вендора.

   kubectl create secret docker-registry codescoring-regcred --docker-server=REGISTRY_URL --docker-username=USERNAME --docker-password=PASSWORD -n cs-proxy

3. Установить Helm предпочтительным способом.

4. Выполнить следующие команды для добавления актуального Helm-репозитория на локальную машину:

   helm repo add codescoring-org https://{REGISTRY_URL}/repository/helm/ --username USERNAME --password PASSWORD
   helm repo update

5. Создать файл values.yaml со следующим содержимым:

   env:
     javaOpts: "-Xmx4g" # Опционально: настройка параметров JVM
   
   config: |
     # Данное поле необходимо заполнить текстом конфигурационного файла application.yml
   
   # Существует возможность создания ресурса Ingress
   ingress:
     enabled: true
     className: ""
     annotations: {}
     hosts:
       - host: cs-proxy.example.com
         paths:
           - path: /
             pathType: Prefix
             backend:
               service:
                 name: cs-proxy
                 port:
                   number: 8080
     tls:
       - secretName: cs-proxy-tls
         hosts:
           - cs-proxy.example.com

6. Выполнить команду для установки чарта

   helm install cs-proxy codescoring-org/cs-proxy -n cs-proxy -f values.yaml --create-namespace --atomic --version CHART_VERSION

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

#Основные параметры

Конфигурация OSA Proxy осуществляется через файл application.yml:

# Параметры CodeScoring
codescoring:
  host: URL-адрес сервера CodeScoring
  token: токен авторизации (с уровнем доступа User и выше)
  work-mode: рабочий режим (применяется только к сканированию пакетов)
              # warmup | Разогрев кэша сканирования без мониторинга запросов, без блокировки
              # spectator | Разогрев кэша сканирования с мониторингом запросов, без блокировки
              # moderate | Блокировка на основе политик с использованием результатов кэша, загрузка непроверенных компонентов разрешена
              # strict | Блокировка на основе политик с использованием результатов кэша, загрузка непроверенных компонентов заблокирована
              # strict_wait | Блокировка на основе политик, ожидание, пока компонент не будет отсканирован
  proxy-manager-host: хост прокси-сервера
  enable-status-line: true/false (добавляет сообщение о причине блокировки в строку состояния)
  block-status-code: статус код для блокировки загрузки пакетов
  block-on-codescoring-errors: блокирует загрузку пакета при 5xx status, ошибках сканирования (scan_failed)
  override-block-url: true/false (заменяет URL в ссылке на причину блокировки на указанный в codescoring.host)
  remove-blocked-versions: true/false (по умолчанию true; при true — заблокированные версии удаляются из манифеста, при false — помечаются как устаревшие)
# Настройки PyPI
pypi:
  enabled: true
  repository:
    - name: internet-pypi
      scan-manifest: true
      scan-package: true
      url-encoded-config: true
      registry: https://pypi.org
      packages-registry: https://files.pythonhosted.org
    - name: arti-pypi
      scan-manifest: true
      scan-package: true
      registry: http://localhost:8081/artifactory/api/pypi/pypi-remote
      packages-registry: http://localhost:8081/artifactory/api/pypi/pypi-remote/packages
    - name: nexus-pypi
      scan-manifest: true
      scan-package: true
      registry: https://localhost:8081/repository/pypi-proxy
      packages-registry: https://localhost:8081/repository/pypi-proxy/packages
# Настройки Maven
maven:
  enabled: true
  repository:
    - name: internet-mvn
      scan-manifest: true
      scan-package: true
      url-encoded-config: true
      registry: https://repo1.maven.org/maven2
    - name: arti-mvn
      scan-manifest: false
      scan-package: true
      registry: http://localhost:8081/artifactory/maven-remote
    - name: nexus-mvn
      scan-manifest: false
      scan-package: true
      registry: http://localhost:8081/repository/maven-proxy
# Настройки NPM
npm:
  enabled: true
  repository:
    - name: internet-npm
      scan-package: true
      scan-manifest: true
      url-encoded-config: true
      registry: https://registry.npmjs.org
    - name: arti-npm
      scan-package: true
      scan-manifest: true
      registry: http://localhost:8081/artifactory/api/npm/npm-remote
    - name: nexus-npm
      scan-package: true
      scan-manifest: true
      registry: http://localhost:8081/repository/npm-proxy
# Настройки NuGet
nuget:
  enabled: true
  repository:
    - name: codescoring-nuget
      scan-package: true
      url-encoded-config: true
      registry: https://api.nuget.org
    - name: arti-nuget
      scan-package: true
      registry: http://localhost:8081/artifactory/api/nuget/v3/nuget-remote
    - name: nexus-nuget
      scan-package: true
      scan-manifest: true
      registry: http://localhost:8081/repository/nuget-v3-proxy
# Настройки GO
go:
   enabled: true
   repository:
     - name: codescoring-go
       scan-manifest: true
       scan-package: true
       url-encoded-config: true
       registry: https://proxy.golang.org/
       sumdb-registry: https://sum.golang.org
     - name: arti-go
       scan-package: true
       scan-manifest: true
       url-encoded-config: true
       registry: http://localhost:8081/artifactory/api/go/go-virt
     - name: nexus-go
       scan-package: true
       scan-manifest: true
       url-encoded-config: true
       registry: http://localhost:8081/repository/go-proxy/
# Настройка Debian
debian:
  enabled: true
  repository:
    - name: codescoring-debian
      scan-package: true
      url-encoded-config: true
      registry: https://ports.ubuntu.com/ubuntu-ports/
      distro: plucky
    - name: arti-debian
      scan-package: true
      url-encoded-config: true
      registry: http://localhost:8081/artifactory/debian-remote
      distro: plucky
    - name: nexus-debian
      scan-package: true
      url-encoded-config: true
      registry: http://localhost:8081/repository/debian11
      distro: bullseye
# Настройка Alpine (APK)
alpine:
  enabled: true
  repository:
    - name: codescoring-alpine
      scan-package: true
      registry: https://dl-cdn.alpinelinux.org/alpine
    - name: arti-alpine
      scan-package: true
      registry: http://localhost:8081/artifactory/alpine-remote
# Настройка RPM
rpm:
  enabled: true
  repository:
    - name: codescoring-rpm
      scan-package: true
      registry: https://repo.almalinux.org/almalinux
    - name: arti-rpm
      scan-package: true
      registry: http://localhost:8081/artifactory/rpm-remote
# Настройка Docker Registry
docker:
  enabled: true
  repository:
    - name: codescoring-docker
      registry: https://registry-1.docker.io
      auth-token-url: https://auth.docker.io
    - name: arti-docker
      registry: http://localhost:8081/artifactory/docker-remote
      auth-token-url: http://localhost:8081

#Дополнительные настройки

#Настройки уровня логирования

logging:
  level:
    ru:
      codescoring: info

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

Чтобы найти заблокированные пакеты в логах приложения, убедитесь, что уровень логирования для ru.codescoring установлен на info или ниже. Компонент PolicyLogger выводит информацию о заблокированных пакетах в следующих форматах:

• Для пакетов, заблокированных политиками: Policy '<policy_name>' blocked package '<package_name>' versions: [<versions>]
• Для пакетов OSA, заблокированных платформой: Policy blocked package '<purl>' for endpoint '<endpoint>': <reason>

#Логирование внешних запросов

Внешние запросы в сторонние реестры можно логировать с помощью логгера ru.codescoring.proxy.logging.RegistryRequestResponseLogger. Для этого необходимо установить уровень логирования trace для данного компонента.

logging:
  level:
    ru.codescoring.proxy.logging.RegistryRequestResponseLogger: trace

#Режим обработки заблокированных версий в манифестах

Параметр codescoring.remove-blocked-versions управляет тем, как заблокированные версии пакетов отображаются в манифестах npm, PyPI и NuGet:

• true (по умолчанию) — заблокированные версии полностью удаляются из манифеста. Пакетный менеджер не видит их и не предлагает пользователю.
• false — заблокированные версии остаются в манифесте, но помечаются как устаревшие с указанием имени сработавшей политики:
  • npm — поле deprecated версии содержит имя политики;
  • PyPI — атрибут data-yanked ссылки на пакет содержит имя политики;
  • NuGet — поле deprecation.message записи содержит имя политики, listed устанавливается в false.

codescoring:
  remove-blocked-versions: false

#Размер буфера для обработки больших манифестов

spring:
  http:
    codecs:
      max-in-memory-size: 150MB (это настройка по умолчанию, уже включенная в приложение, увеличьте ее, если вы столкнулись с очень большими манифестами)

#Политики повторных попыток и circuit breaker для запросов к платформе:

#Настройка повторных попыток

Эта конфигурация определяет политику повторных попыток для сервиса codeScoringApi. Она настроена на обработку временных сбоев путем повторной попытки запроса до 3 раз.

Повторные попытки используют стратегию экспоненциального отступления, начиная с задержки в 1 секунду и удваивая ее с каждой попыткой. Эта политика применяется только к определенным исключениям, таким как WebClientRequestException.

#Настройка Circuit Breaker

Circuit breaker (автоматический выключатель) для codeScoringApi действует как механизм быстрого отказа. Он отслеживает частоту сбоев и, если она достигает 50% (рассчитывается по последним 20 вызовам), он «открывается» и предотвращает дальнейшие запросы в течение 30 секунд. Это дает нижестоящему сервису время на восстановление. После периода ожидания он переходит в «полуоткрытое» состояние, позволяя пройти 5 пробным вызовам, чтобы определить, восстановился ли сервис.

Конфигурация Retry и Circuit Breaker может быть переопределена путем установки следующих свойств, например, для codeScoringApi.

#Добавление truststore сертификатов

spring:
  cloud:
    gateway:
      server:
        webflux:
          httpclient:
            ssl:
              trustedX509Certificates:
                - /usr/local/share/ca-certificates/codescoring.crt
                - /etc/ssl/certs/ca-certificates.crt

#Добавление http proxy

spring:
  cloud:
    gateway:
      httpclient:
        proxy:
          host: proxy.host.ru
          username: 'username'
          port: 9091
          password: 'password'
          non-proxy-hosts-pattern: '(localhost|127.0.0.1|.*\.internal\.com)'

#Настройка Redis и кэширования

Для повышения производительности и снижения нагрузки на платформу CodeScoring поддерживается кэширование результатов работы политик (вердиктов сервиса Judge). Для работы кэширования требуется подключение к Redis.

spring:
  data:
    redis:
      host: localhost
      port: 6379
      database: 0         # Номер базы данных (опционально)
      password: password  # Опционально
      timeout: 2000ms

cache:
  judge:
    enabled: true  # Включение кэширования (по умолчанию false)
    ttl: 24h       # Время жизни записи в кэше
    refresh-after: 30m  # Время, после которого запись считается устаревшей и требует обновления (но все еще может быть отдана из кэша)
    proactive-refresh-enabled: true # Включение проактивного (фонового) обновления кэша
    proactive-refresh-interval: 2h  # Интервал запуска фонового обновления
    key-prefix: "cs:judge:" # Префикс для ключей в Redis

#Swagger UI

OSA Proxy предоставляет Swagger UI для просмотра документации API и управления кэшем.

• URL: http://<osa-proxy-host>:<port>/api/swagger
• Доступные операции:
  • Очистка кэша по PURL
  • Очистка кэша по типу пакета

#Поддерживаемые протоколы

Данный раздел содержит форматы данных и правила модификации ответов для каждого поддерживаемого пакетного менеджера в OSA Proxy.

#Maven

#Обрабатываемые файлы

• maven-metadata.xml - манифест с информацией о версиях
• .jar, .war, .ear - файлы пакетов

#Модификация полей в maven-metadata.xml

<metadata>
  <groupId>...</groupId>
  <artifactId>...</artifactId>
  <versioning>
    <latest>обновляется на последнюю незаблокированную</latest>
    <release>обновляется на последнюю незаблокированную</release>
    <versions>
      <version>удаляются заблокированные версии</version>
    </versions>
  </versioning>
</metadata>

#NPM

#Обрабатываемые файлы

• JSON манифест пакета (путь /{repository}/*)
• .tgz - архивы пакетов

#Модификация полей в NPM манифесте

{
  "name": "package-name",
  "dist-tags": {
    "latest": "обновляется на последнюю незаблокированную версию"
  },
  "versions": {
    "1.0.0": "удаляются заблокированные версии"
  },
  "time": {
    "1.0.0": "удаляются записи для заблокированных версий"
  }
}

#PyPI

#Обрабатываемые файлы

• HTML страницы Simple API (путь /{repository}/simple/*)
• .zip, .tar, .tgz, .tar.gz, .tar.bz2, .egg, .whl - файлы пакетов

#Модификация HTML страниц

• Удаляются ссылки для заблокированных версий
• Перезаписываются URL для скачивания через прокси

<!DOCTYPE html>
<html>
  <body>
    <a href="https://files.pythonhosted.org/packages/example-1.0.0.tar.gz">example-1.0.0.tar.gz</a>
    <a href="https://files.pythonhosted.org/packages/example-2.0.0.tar.gz">example-2.0.0.tar.gz</a>
  </body>
</html>

#NuGet

#Обрабатываемые файлы

• index.json - сервисный индекс
• Registration index JSON
• .nupkg - файлы пакетов

#Модификация registration индекса

{
  "version": "3.0.0",
  "items": [
    {
      "@id": "https://api.nuget.org/v3/registration5-gz-semver2/package/index.json",
      "items": [
        {
          "catalogEntry": {
            "id": "Package",
            "version": "1.0.0"
          }
        },
        {
          "catalogEntry": {
            "id": "Package",
            "version": "2.0.0"
          }
        }
      ]
    }
  ]
}

#Go

#Обрабатываемые файлы

• Список версий (/@v/list)
• .zip — архивы модулей

#Модификация списка версий

• Из списка версий удаляются заблокированные версии.

#Debian

#Обрабатываемые файлы

• .deb — файлы пакетов

#Alpine

#Обрабатываемые файлы

• .apk — файлы пакетов

#RPM

#Обрабатываемые файлы

• .rpm — файлы пакетов

#Docker

#Обрабатываемые файлы

• Manifests (v2 API)
• Слои образов (Blobs)

#Модификация манифестов

• Из мультиархитектурных манифестов (Manifest Lists) удаляются дайджесты заблокированных образов.

#Поведение при полной блокировке пакета

В случае, когда все доступные версии запрашиваемого пакета заблокированы политиками безопасности, OSA Proxy возвращает сообщение о блокировке всех версий.

Поскольку некоторые клиенты пакетных менеджеров могут не отображать это специфическое сообщение о блокировке в пользовательском интерфейсе, рекомендуется использовать утилиту curl для прямой диагностики статуса пакета. Ниже представлены примеры запросов с использованием curl для проверки статуса блокировки для различных типов пакетов:

#Pip

curl http://localhost:8080/codescoring-pypi/simple/имя_пакета

#Maven

curl http://localhost:8080/codescoring-maven/groupid/artifactid/maven-metadata.xml

#npm

curl http://localhost:8080/codescoring-npm/имя_пакета

#NuGet

Хотя NuGet-клиент может выводить причину блокировки всех пакетов в консоли, прямой запрос через curl также позволяет получить подтверждение статуса:

curl http://localhost:8080/codescoring-nuget/nuget-api/v3/registration5-gz-semver2/newtonsoft.json/index.json

#Go

curl http://localhost:8080/codescoring-go/имя_модуля/@v/list

#Cбор метрик

Метрики доступны в OSA Proxy по адресу {osa-proxy-url}/actuator/metrics в формате JSON, а также в формате для prometheus {platform-url}/actuator/prometheus.

Эти метрики собираются для каждого типа репозитория (maven, pypi, nuget, npm, go, debian, alpine, rpm, docker) и позволяют детально отслеживать входящие запросы к прокси-репозиториям.

#Доступные метрики

• gateway_route_<package-type>_requests_seconds_count – общее количество обработанных запросов;
• gateway_route_<package-type>_requests_seconds_sum – суммарное время обработки запросов, используется для расчета среднего времени ответа;
• gateway_route_<package-type>_requests_seconds_max – максимальное время обработки запроса;
• gateway_route_<package-type>_requests_seconds_bucket – SLO (Service Level Objective) метрики времени ответа с бакетами: 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2s, 5s.

В рамках сбора метрик <package-type> заменяется на соответствующий тип репозитория: maven, pypi, nuget, npm, debian, alpine, rpm, docker. Например, для Maven-репозитория метрика будет называться gateway_route_maven_requests_total.

Данные метрики можно отфильтровать по следующим лейблам:

• operation – тип операции, выполняемой с пакетом;
  • scan_package – сканирование пакета;
  • scan_manifest – сканирование манифеста;
  • other – другие операции (например передача файлов не подпадающих под анализ).
• method – HTTP-метод запроса (GET, POST, PUT, и т.д.);
• repository – имя репозитория, к которому был выполнен запрос;
• status – код статуса HTTP-ответа (например, 200, 403, 500);
• outcome – результат обработки запроса;
  • success – запрос успешно обработан;
  • error – произошла ошибка при обработке (статус 400 и выше, кроме кода блокировки);
  • blocked_by_policies – запрос был заблокирован политиками безопасности.

#Метрики обращений в CodeScoring

Для мониторинга взаимодействия с платформой CodeScoring доступны следующие метрики:

• codescoring_api_requests_seconds_count – общее количество запросов к API CodeScoring;
• codescoring_api_requests_seconds_sum – суммарное время выполнения запросов к API;
• codescoring_api_requests_seconds_max – максимальное время выполнения запроса к API;
• codescoring_api_requests_seconds_bucket – SLO метрики времени ответа API с бакетами: 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2s, 5s.

Данные метрики позволяют отслеживать:

• Производительность взаимодействия с платформой CodeScoring
• Количество запросов на сканирование компонентов
• Время отклика API для выявления проблем связи
• Нагрузку на платформу со стороны OSA Proxy

#Параметры в URL в формате Base64

#Применение параметров в URL в формате Base64 для osa-proxy

Взаимодействие с osa-proxy в некоторых сценариях требует явного указания дополнительных параметров в пути URL. Это достигается путём кодирования требуемой информации в формате Base64 (URL-safe).

Основная цель использования Base64-кодированных параметров — предоставление osa-proxy необходимого контекста для корректного применения политик безопасности, особенно когда osa-proxy выступает в роли посредника для внешних репозиториев.

#Автоматическое определение контекста

Когда osa-proxy размещён между клиентом (пакетным менеджером) и внутренним менеджером репозиториев (например, JFrog Artifactory или Nexus Repository Manager), osa-proxy может автоматически извлечь информацию о хосте и имени репозитория из настроек конечного репозитория.

Пример конфигурации, где контекст определяется автоматически:

npm:
  repository:
    - name: codescoring-npm
      # ...
      registry: https://nexus.test.ru/repository/npm-proxy

#Явное указание контекста через Base64-параметры

В случаях, когда osa-proxy напрямую взаимодействует с внешними, общедоступными репозиториями (например, https://registry.npmjs.org), он не имеет возможности самостоятельно получить информацию о внутреннем хосте и имени репозитория. В такой ситуации для osa-proxy критически важно получить эти данные для применения привязанных политик безопасности и правильной обработки запроса.

Для этого используется строка, закодированная в Base64, которая содержит JSON-объект с параметрами, такими как repoManagerHost и repoName. Эта строка встраивается непосредственно в URL запроса, позволяя osa-proxy получить необходимый контекст.

Пример конфигурации, требующей явного указания контекста:

npm:
  repository:
    - name: codescoring-npm
      # ...
      registry: https://registry.npmjs.org # Здесь нужна передача параметров

#Механизм работы:

Закодированная строка параметров в формате Base64 размещается в пути URL сразу после имени репозитория. osa-proxy декодирует эту строку, извлекает параметры и использует их для выполнения своих функций, включая применение политик безопасности, ассоциированных с конкретным внутренним репозиторием.

Общая структура URL: https://<osaproxy-host>/<repository-name>/<base64-parameters>/<rest-of-path>

#Передача контекста для корректной работы политик безопасности, привязаных к репозиториям Nexus и Artifactory

Клиент разработчика -> Nexus / Artifactory -> osa-proxy -> Интернет

Для передачи контекстной информации, включающей хост и имя репозитория вашего менеджера репозиториев, эти данные следует интегрировать в Base64-кодированную строку параметров. Важно строго соблюдать правило, согласно которому данная Base64-строка должна располагаться непосредственно после имени репозитория в URL-адресе.

#Обновление конфигурации

Необходимо пометить репозиторий, как совместимый с Base64 параметрами url-encoded-config: true

npm:
  repository:
    - name: codescoring-npm
      url-encoded-config: true
      # ...
      registry: https://registry.npmjs.org

#Nexus

1. Перейдите в Server Administration -> Repositories.
2. Выберите желаемый тип (например, maven2 (proxy)).
3. В поле Remote storage введите URL вашего экземпляра osa-proxy, включая имя репозитория и параметры, закодированные в Base64.

Пример для прокси-репозитория Maven: https://osaproxy.example.com/internet-maven/eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL3JlcG8xLm1hdmVuLm9yZy9tYXZlbjIiLCJyZXBvTmFtZSI6ImludGVybmV0LW1hdmVuIn0/maven2

#Artifactory

1. Перейдите в Administration -> Repositories -> Remote.
2. В конфигурации установите поле URL на URL osa-proxy. Этот URL должен включать имя репозитория и строку, закодированную в Base64.

Пример для удаленного репозитория PyPI: https://osaproxy.example.com/internet-pypi/eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL3B5cGkub3JnL3NpbXBsZSIsInJlcG9OYW1lIjoiaW50ZXJuZXQtcHlwaSJ9

#Правило

Закодированная строка параметров в формате Base64 должна быть размещена в пути URL сразу после имени репозитория.

Общая структура URL выглядит следующим образом: https://<osaproxy-host>/<repository-name>/<base64-parameters>/<rest-of-path>

Где:

• <osaproxy-host>: Имя хоста экземпляра osa-proxy.
• <repository-name>: Имя репозитория, к которому осуществляется доступ.
• <base64-parameters>: Закодированная в URL-safe Base64 JSON-строка, содержащая параметры.
• <rest-of-path>: Оставшаяся часть пути из настроек пакетного менеджера.

#Пример

Например, нужно передать следующие параметры в виде JSON-объекта.

{"repoManagerHost":"https://nexus.test.ru","repoName":"npm-proxy"}

Для этого следует:

1. Преобразовать JSON-объект в строку.
2. Закодировать строку с использованием URL-safe Base64.

Результат кодирования JSON-объекта выше в Base64: eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL25leHVzLnRlc3QucnUiLCJyZXBvTmFtZSI6Im5wbS1wcm94eSJ9

#Настройка менеджеров пакетов

Чтобы постоянно использовать URL с параметрами в формате Base64 для всех запросов, необходимо обновить конфигурационный файл вашего менеджера пакетов.

#NPM

Для NPM нужно отредактировать файл .npmrc и установить ключ registry.

URL должен включать имя репозитория и строку, закодированную в Base64.

registry=https://osaproxy.example.com/npm-proxy/eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL25leHVzLnRlc3QucnUiLCJyZXBvTmFtZSI6Im5wbS1wcm94eSJ9

#Maven

Для Maven нужно отредактировать файл settings.xml. Вы можете добавить новое <mirror> в секцию <mirrors>.

Тег <url> должен содержать полный URL, включая имя репозитория и строку, закодированную в Base64.

<settings>
  ...
  <mirrors>
    <mirror>
      <id>osa-proxy-mirror</id>
      <mirrorOf>*</mirrorOf>
      <url>https://osaproxy.example.com/my-maven-repo/eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL25leHVzLnRlc3QucnUiLCJyZXBvTmFtZSI6Im5wbS1wcm94eSJ9/maven2</url>
    </mirror>
  </mirrors>
  ...
</settings>

Убедитесь, что значение <mirrorOf> соответствует репозиториям, которые вы хотите проксировать.

#Go

Для Go установите переменную окружения GOPROXY, чтобы она включала имя репозитория и строку, закодированную в Base64.

export GOPROXY="https://osaproxy.example.com/go-repo/eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL25leHVzLnRlc3QucnUiLCJyZXBvTmFtZSI6ImdvLXJlcG8ifQ"

#Debian

Для Debian нужно отредактировать файл /etc/apt/sources.list или файл в /etc/apt/sources.list.d/. Обновите поле URIs.

Types: deb
URIs: https://osaproxy.example.com/debian-repo/eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL25leHVzLnRlc3QucnUiLCJyZXBvTmFtZSI6ImRlYmlhbi1yZXBvIn0=
Suites: stable
Components: main
Signed-By: /path/to/key.gpg

#NuGet

Для NuGet отредактируйте файл NuGet.config и добавьте новый источник пакетов. Атрибут value тега <add> должен содержать полный URL.

<configuration>
  <packageSources>
    <add key="osa-proxy" value="https://osaproxy.example.com/nuget-repo/eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL25leHVzLnRlc3QucnUiLCJyZXBvTmFtZSI6Im51Z2V0LXJlcG8ifQ/index.json" />
  </packageSources>
  ...
</configuration>

#PyPI

Для PyPI отредактируйте файл pip.conf (Linux/macOS) или pip.ini (Windows) и установите index-url.

[global]
index-url = https://osaproxy.example.com/pypi-repo/eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL25leHVzLnRlc3QucnUiLCJyZXBvTmFtZSI6InB5cGktcmVwbyJ9/simple

#Конфигурация Maven

#Миграция URL репозитория

Сценарий использования: миграция репозитория Maven с Artifactory на OSA Proxy.

Следующая таблица содержит сводку по перенаправлению URL репозиториев для Maven. Параметры аутентификации и другие настройки, такие как имя пользователя и пароль, остаются без изменений.

#Миграция Maven репозитория

Исходный файл .m2/settings.xml:

<settings>
  <mirrors>
    <mirror>
      <id>artifactory</id>
      <mirrorOf>*</mirrorOf>
      <url>https://jfrog.host.ru/artifactory/maven-remote</url>
    </mirror>
  </mirrors>
  <servers>
    <server>
      <id>artifactory</id>
      <username>your-username</username>
      <password>your-password</password>
    </server>
  </servers>
</settings>

Следующее определение репозитория необходимо добавить в YAML-конфигурацию сервиса (файл application.yml) в секцию maven. Для применения изменений требуется перезапуск сервиса.

Конфигурация в файле application.yml

maven:
  enabled: true
  repository:
    - name: jfrog-mvn
      scan-manifest: true
      scan-package: true
      registry: https://jfrog.host.ru/artifactory/maven-remote

Обновлённый файл .m2/settings.xml:

<settings>
  <mirrors>
    <mirror>
      <id>cs-proxy</id>
      <mirrorOf>*</mirrorOf>
      <url>https://{osa-proxy-url}/jfrog-mvn</url>
    </mirror>
  </mirrors>
  <servers>
    <server>
      <id>cs-proxy</id>
      <username>your-username</username>
      <password>your-password</password>
    </server>
  </servers>
</settings>

#Конфигурация NPM

#Миграция URL репозитория

Сценарий использования: миграция репозитория npm с Artifactory на OSA Proxy.

Следующая таблица содержит сводку по перенаправлению URL репозиториев для NPM. Параметры аутентификации и другие настройки, такие как имя пользователя и пароль, остаются без изменений.

#Миграция NPM репозитория

Исходный файл .npmrc:

registry=https://artifactory.domain.ru/artifactory/api/npm/npm-remote/
//artifactory.domain.ru/artifactory/api/npm/npm-remote/:_password=1NHTGVrUnJQ
//artifactory.domain.ru/artifactory/api/npm/npm-remote/:username=asdf
//artifactory.domain.ru/artifactory/api/npm/npm-remote/:email=asdf@domain.ru
//artifactory.domain.ru/artifactory/api/npm/npm-remote/:always-auth=true

Следующее определение репозитория необходимо добавить в YAML-конфигурацию сервиса (файл application.yml) в секцию npm. Для применения изменений требуется перезапуск сервиса.

Конфигурация в файле application.yml

npm:
  enabled: true
  repository:
    - name: arti-npm
      scan-package: true
      scan-manifest: true
      registry: https://artifactory.domain.ru/artifactory/api/npm/npm-remote/

Обновлённый файл .npmrc:

registry=https://{osa-proxy-url}/arti-npm
//{osa-proxy-url}/arti-npm/:_password=1NHTGVrUnJQ
//{osa-proxy-url}/arti-npm/:username=asdf
//{osa-proxy-url}/arti-npm/:email=asdf@domain.ru
//{osa-proxy-url}/arti-npm/:always-auth=true

#Конфигурация NuGet

#Миграция URL репозитория

Сценарий использования: миграция репозитория NuGet с Artifactory на OSA Proxy.

Следующая таблица содержит сводку по перенаправлению URL репозиториев для NuGet. Параметры аутентификации и другие настройки, такие как имя пользователя и пароль, остаются без изменений.

#Миграция NuGet репозитория

Исходный файл NuGet.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="Artifactory" value="https://jfrog.host.ru/artifactory/api/nuget/v3/nuget-safe" />
  </packageSources>
  <packageSourceCredentials>
    <Artifactory>
      <add key="Username" value="your-username" />
      <add key="ClearTextPassword" value="your-password" />
    </Artifactory>
  </packageSourceCredentials>
</configuration>

Следующее определение репозитория необходимо добавить в YAML-конфигурацию сервиса (файл application.yml) в секцию nuget. Для применения изменений требуется перезапуск сервиса.

Конфигурация в файле application.yml

nuget:
  enabled: true
  repository:
    - name: arti-nuget
      scan-package: true
      registry: https://jfrog.host.ru/artifactory/api/nuget/v3/nuget-safe

Обновлённый файл NuGet.config:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="OSA-Proxy" value="https://{osa-proxy-url}/arti-nuget/nuget-api" />
  </packageSources>
  <packageSourceCredentials>
    <OSA-Proxy>
      <add key="Username" value="your-username" />
      <add key="ClearTextPassword" value="your-password" />
    </OSA-Proxy>
  </packageSourceCredentials>
</configuration>

#Конфигурация PyPI

#Миграция URL репозитория

Сценарий использования: миграция репозитория PyPI с Artifactory на OSA Proxy.

Следующая таблица содержит сводку по перенаправлению URL репозиториев для PyPI. Параметры аутентификации и другие настройки, такие как имя пользователя и пароль, остаются без изменений.

#Миграция PyPI репозитория

Исходный файл pip.conf (Linux/macOS) или pip.ini (Windows):

[global]
index-url = https://jfrog.host.ru/artifactory/api/pypi/pypi-remote/simple
trusted-host = jfrog.host.ru

Или с аутентификацией:

[global]
index-url = https://username:password@jfrog.host.ru/artifactory/api/pypi/pypi-remote/simple
trusted-host = jfrog.host.ru

Следующее определение репозитория необходимо добавить в YAML-конфигурацию сервиса (файл application.yml) в секцию pypi. Для применения изменений требуется перезапуск сервиса.

Конфигурация в файле application.yml

pypi:
  enabled: true
  repository:
    - name: jfrog-pypi
      scan-manifest: true
      scan-package: true
      registry: https://jfrog.host.ru/artifactory/api/pypi/pypi-remote
      packages-registry: https://jfrog.host.ru/artifactory/api/pypi/pypi-remote/packages

Пример настройки для GitLab в application.yml:

pypi:
  enabled: true
  repository:
    - name: python-sdk
      scan-manifest: true
      scan-package: true
      registry: https://gitlab.example.com/api/v4/projects/337/packages/pypi
      packages-registry: https://gitlab.example.com/api/v4/projects/337/packages/pypi/files

Обновлённый файл pip.conf (Linux/macOS) или pip.ini (Windows):

[global]
index-url = https://{osa-proxy-url}/jfrog-pypi
trusted-host = {osa-proxy-url}

Или с аутентификацией:

[global]
index-url = https://username:password@{osa-proxy-url}/jfrog-pypi
trusted-host = {osa-proxy-url}

#Настройка нескольких реестров пакетов

Некоторые PyPI-репозитории могут отдавать пакеты с нескольких хостов. Например, индекс download.pytorch.org содержит ссылки как на собственные CDN-хосты, так и на стандартный files.pythonhosted.org.

Для корректного проксирования таких репозиториев используется параметр additional-packages-registries — словарь, где ключ задаёт хост источника, а значение — URL реестра пакетов, на который нужно перенаправлять запросы.

Пример настройки для репозитория PyTorch:

pypi:
  enabled: true
  repository:
    - name: pytorch-pypi
      scan-manifest: true
      scan-package: true
      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

#Расположение конфигурационных файлов

• Linux/macOS: ~/.config/pip/pip.conf или ~/.pip/pip.conf
• Windows: %APPDATA%\pip\pip.ini или %HOME%\pip\pip.ini
• Для virtualenv: $VIRTUAL_ENV/pip.conf

#Конфигурация Go

#Миграция прокси для Go

Сценарий использования: миграция Go для использования OSA Proxy вместо прямого доступа или внешних публичных прокси.

Следующая таблица содержит сводку по перенаправлению URL для прокси Go. Параметры аутентификации и другие настройки (если применимы, например, для частных репозиториев, требующих специфических учетных данных) должны быть настроены отдельно в соответствии с вашими корпоративными политиками (например, через .netrc или SSH-ключи).

#Детали миграции прокси Go

#Настройка окружения до миграции

До миграции ваш GOPROXY мог быть установлен на публичный прокси Go (https://proxy.golang.org) или не задан вовсе, что приводило к использованию proxy.golang.org по умолчанию. Следующее определение репозитория необходимо добавить в YAML-конфигурацию сервиса (файл application.yml) в секцию go. Для применения изменений требуется перезапуск сервиса.

Конфигурация в файле application.yml

go:
  enabled: true
  repository:
    - name: inet-go
      scan-package: true
      scan-manifest: true
      registry: https://proxy.golang.org
      sumdb-registry: https://sum.golang.org

Пример текущей конфигурации переменных окружения (например, в файле .bashrc, .zshrc или в CI/CD пайплайне):

export GOPROXY=https://{osa-proxy-url}/inet-go

#Настройка Checksum Database

Для проксирования запросов к sum.golang.org через OSA Proxy используется переменная GOSUMDB. Её значение задаётся в формате <имя-базы> <url-прокси>, где URL строится как {osa-proxy-url}/{repo-name}/sumdb/sum.golang.org:

export GOSUMDB="sum.golang.org https://{osa-proxy-url}/inet-go/sumdb/sum.golang.org"

Полный пример запуска:

GOPROXY="https://{osa-proxy-url}/inet-go" \
GOSUMDB="sum.golang.org https://{osa-proxy-url}/inet-go/sumdb/sum.golang.org" \
go get github.com/example/module@v1.0.0

#Конфигурация Debian пакетов

#Миграция URL репозитория

Сценарий использования: миграция репозиториев Debian с прямых источников на прокси-сервер OSA Proxy.

Следующая таблица содержит сводку по перенаправлению URL репозиториев для Debian. Обратите внимание, что формат строк репозитория deb или deb-src (дистрибутив, компоненты) остается без изменений, меняется только базовый URL репозитория.

#Миграция APT репозитория

Исходный файл /etc/apt/sources.list или /etc/apt/sources.list.d/*.list:

Types: deb
URIs: https://deb.debian.org/debian
Suites: noble noble-updates noble-backports
Components: main universe restricted multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

Следующее определение репозитория необходимо добавить в YAML-конфигурацию сервиса (файл application.yml) в секцию debian. Для применения изменений требуется перезапуск сервиса.

Конфигурация в файле application.yml

debian:
  enabled: true
  repository:
    - name: debian-apt
      scan-package: true
      distro: bullseye
      registry: http://deb.debian.org/debian/

После настройки прокси-сервера и добавления его в application.yml, ваш sources.list будет выглядеть так:

Types: deb
URIs: https://{osa-proxy-url}/codescoring-debian
Suites: noble noble-updates noble-backports
Components: main universe restricted multiverse
Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg

#Конфигурация Docker Registry

#Миграция URL реестра

Сценарий использования: миграция Docker реестров с прямых источников на прокси-сервер OSA Proxy.

Следующая таблица содержит сводку по перенаправлению URL для Docker.

#Миграция Docker клиента

Следующее определение репозитория необходимо добавить в YAML-конфигурацию сервиса (файл application.yml) в секцию docker. Для применения изменений требуется перезапуск сервиса.

Конфигурация в файле application.yml

docker:
  enabled: true
  repository:
    - name: codescoring-docker
      scan-package: true
      registry: https://registry-1.docker.io
      auth-token-url: https://auth.docker.io

После настройки прокси-сервера и добавления его в application.yml, команда для загрузки образа будет выглядеть так:

docker pull {osa-proxy-url}/library/alpine:latest

#Использование поддоменов для доступа

При использовании более одного Docker-репозитория необходимо включить поддержку поддоменов. Имена поддоменов должны соответствовать именам репозиториев из конфигурации docker.repository.

В этом случае команда для загрузки образа будет выглядеть так:

docker pull codescoring-docker.osaproxyhost.ru/library/postgres

Если настроен только один репозиторий, использование поддоменов не требуется — Docker-реестр будет доступен напрямую через хост OSA Proxy:

docker pull osaproxyhost.ru/library/postgres

#Конфигурация Alpine пакетов

#Миграция URL репозитория

Сценарий использования: миграция репозиториев Alpine с прямых источников на прокси-сервер OSA Proxy.

Следующая таблица содержит сводку по перенаправлению URL репозиториев для Alpine.

#Миграция APK репозитория

Исходный файл /etc/apk/repositories:

https://dl-cdn.alpinelinux.org/alpine

Следующее определение репозитория необходимо добавить в YAML-конфигурацию сервиса (файл application.yml) в секцию alpine. Для применения изменений требуется перезапуск сервиса.

Конфигурация в файле application.yml

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

После настройки прокси-сервера и добавления его в application.yml, ваш файл репозиториев будет выглядеть так:

https://{osa-proxy-url}/codescoring-alpine

#Конфигурация RPM пакетов

#Миграция URL репозитория

Сценарий использования: миграция репозиториев RPM (YUM/DNF) с прямых источников на прокси-сервер OSA Proxy.

Следующая таблица содержит сводку по перенаправлению URL репозиториев для RPM.

#Миграция YUM/DNF репозитория

Исходный файл /etc/yum.repos.d/almalinux.repo:

[baseos]
name=AlmaLinux $releasever - BaseOS
baseurl=https://repo.almalinux.org/almalinux/$releasever/BaseOS/$basearch/os/
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-AlmaLinux-9

Следующее определение репозитория необходимо добавить в YAML-конфигурацию сервиса (файл application.yml) в секцию rpm. Для применения изменений требуется перезапуск сервиса.

Конфигурация в файле application.yml

rpm:
  enabled: true
  repository:
    - name: codescoring-rpm
      scan-package: true
      registry: https://repo.almalinux.org/almalinux

После настройки прокси-сервера и добавления его в application.yml, конфигурация репозитория будет выглядеть так:

[baseos]
name=AlmaLinux $releasever - BaseOS
baseurl=https://{osa-proxy-url}/codescoring-rpm/$releasever/BaseOS/$basearch/os/
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-AlmaLinux-9