#Archived Java/Spring OSA Proxy implementation

#Overview

OSA Proxy (repo-manager-proxy) is a proxy service that acts as an intermediary between package managers and their remote repositories. It integrates with the CodeScoring platform and provides automatic scanning of downloaded components and blocking of unsafe packages according to security policies.

The service intercepts requests made by package managers, sends them to the source repositories, analyzes the received packages, modifies the responses, and manages access to components.

The service is based on an asynchronous processing model and an automatic retry mechanism for temporary errors.

#Supported package managers

OSA Proxy handles requests to the following repositories:

• 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)

#Main functionality

#Package scanning

Two scanning levels are implemented for each ecosystem:

• Manifest scanning — analyzes and excludes versions blocked by security policies from the manifest
• Package scanning — analyzes downloaded package

#Blocking insecure components

If a component violates security policy rules:

• Insecure versions are excluded from the list of available versions in the manifest;
• Downloading of corresponding archives is blocked;
• A configurable status code is returned with a message explaining the reason for the blocking.

#Response modification

OSA Proxy automatically modifies responses from original repositories:

• Redirects all URLs;
• Removes blocked versions from metadata;
• Recalculates checksums of modified manifests to maintain the correct format.

#Policy results caching

To speed up request processing and reduce platform load, policy validation results (verdicts from Judge service) are cached in Redis. Background updates of outdated records are supported.

#Work modes

Package scanning behavior is controlled by the work-mode parameter. Depending on the selected value, the scanning, waiting, and blocking logic changes. The following modes are supported:

• warmup – loads data into the CodeScoring cache without blocking components;
• spectator – loads data into the CodeScoring cache without blocking components, saving the results of component queries to the platform;
• moderate – blocks components that fail policy checks. Loading unscanned components is allowed;
• strict – blocks components that fail policy checks. Loading unscanned components is prohibited;
• strict_wait – blocks components that fail policy checks. Waiting for checks for unscanned components.

#Deployment

Following the configuration of the application.yml file, the application can be deployed and executed either within a Docker container environment or orchestrated via a Helm chart for Kubernetes (k8s) deployments.

#Docker container deployment

To instantiate the application as a Docker container, execute the following command:

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 deployment (Helm Chart)

For Kubernetes environments, the application can be deployed using the provided Helm chart, accessible at https://{REGISTRY_URL}/repository/helm/.

Installation order:

1. Create a namespace.

   kubectl create namespace codescoring

2. Create a secret to access the private Docker registry, using the address (REGISTRY_URL), login (USERNAME) and password (PASSWORD) received from the vendor.

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

3. Install Helm using your preferred method.

4. Run the following commands to add the current Helm repository to the local machine:

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

5. Create a values.yaml file with the following content:

   env:
     javaOpts: "-Xmx4g" # Optional: JVM parameters configuration
   
   config: |
     # This field must be populated with the content of the application.yml file
   
   # There's an option to create an Ingress resource
   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. Run the command to install the chart

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

#Service configuration

#Main parameters

Configuration of OSA Proxy is done via the application.yml file:

# CodeScoring parameters
codescoring:
  host: CodeScoring server URL
  token: authorization token ((with access level User or higher)
  work-mode: operation mode (applies only to package scanning)
              # warmup | Warm up scan cache without monitoring requests, no blocking
              # spectator | Warm up scan cache with request monitoring, no blocking
              # moderate | Policy-based blocking using cache results, unscanned components allowed
              # strict | Policy-based blocking using cache results, unscanned components blocked
              # strict_wait | Policy-based blocking, wait until the component is scanned
  proxy-manager-host: proxy server host
  enable-status-line: true/false (adds the block reason to the status line)
  block-status-code: status code for blocking package downloads
  block-on-codescoring-errors: block package download on 5xx status, scan_failed errors
  override-block-url: true/false (replaces URL in block reason link with the one specified in codescoring.host)
  remove-blocked-versions: true/false (default: true; when true — blocked versions are removed from the manifest; when false — they are marked as deprecated)
# PyPI settings
pypi:
  enabled: true
  repository:
    - name: internet-pypi
      scan-manifest: true
      scan-package: 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 settings
maven:
  enabled: true
  repository:
    - name: internet-mvn
      scan-manifest: true
      scan-package: 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 settings
npm:
  enabled: true
  repository:
    - name: internet-npm
      scan-package: true
      scan-manifest: 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 settings
nuget:
  enabled: true
  repository:
    - name: codescoring-nuget
      scan-package: 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 settings
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 settings
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) settings
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 settings
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 settings
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

#Additional settings

#Logging level settings

logging:
  level:
    ru:
      codescoring: info

#Viewing blocked packages in logs

To find blocked packages in the application logs, ensure the logging level for ru.codescoring is set to info or lower. The PolicyLogger component will output information about blocked packages in the following formats:

• For packages blocked by policies: Policy '<policy_name>' blocked package '<package_name>' versions: [<versions>]
• For OSA packages blocked by the platform: Policy blocked package '<purl>' for endpoint '<endpoint>': <reason>

#Logging external requests

External requests to third-party registries can be logged using the ru.codescoring.proxy.logging.RegistryRequestResponseLogger component. To do this, set its logging level to trace.

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

#Blocked version handling mode in manifests

The codescoring.remove-blocked-versions parameter controls how blocked package versions are displayed in npm, PyPI, and NuGet manifests:

• true (default) — blocked versions are fully removed from the manifest. The package manager does not see them and will not offer them to the user.
• false — blocked versions remain in the manifest but are marked as deprecated, with the name of the triggered policy included in the relevant field:
  • npm — the deprecated field of the version entry contains the policy name;
  • PyPI — the data-yanked attribute of the package link contains the policy name;
  • NuGet — the deprecation.message field of the entry contains the policy name, and listed is set to false.

codescoring:
  remove-blocked-versions: false

#Buffer size for large manifests

spring:
  http:
    codecs:
      max-in-memory-size: 150MB (this is the default setting, already included in the application; increase it if you encounter very large manifests)

#Retry policies and circuit breaker for platform requests

#Retry configuration

This configuration defines the retry policy for the codeScoringApi service. It is designed to handle temporary failures by retrying up to 3 times.

Retries use an exponential backoff strategy, starting with a 1-second delay and doubling it with each attempt. This policy applies only to certain exceptions, such as WebClientRequestException.

#Circuit breaker configuration

The circuit breaker for codeScoringApi acts as a fail-fast mechanism. It tracks failure rates, and if they reach 50% (calculated over the last 20 calls), it “opens” and prevents further requests for 30 seconds. This gives the downstream service time to recover. After the wait period, it switches to “half-open” state, allowing 5 trial calls to check if the service has recovered.

Retry and circuit breaker configuration can be overridden by setting the following properties, for example, for codeScoringApi.

#Adding truststore certificates

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

#Adding 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 and сaching сonfiguration

To improve performance and reduce load on the CodeScoring platform, caching of policy checking results (Judge service) is supported. Caching requires a Redis connection.

spring:
  data:
    redis:
      host: localhost
      port: 6379
      database: 0         # Database number (optional)
      password: password  # Optional
      timeout: 2000ms

cache:
  judge:
    enabled: true  # Enable caching (default is false)
    ttl: 24h       # Time-to-live for cache entries
    refresh-after: 30m  # Time after which an entry is considered stale and needs refresh (but can still be served from cache)
    proactive-refresh-enabled: true # Enable proactive (background) cache refresh
    proactive-refresh-interval: 2h  # Interval for background refresh task
    key-prefix: "cs:judge:" # Prefix for Redis keys

#Swagger UI

OSA Proxy provides Swagger UI for API documentation and cache management.

• URL: http://<osa-proxy-host>:<port>/api/swagger
• Available operations:
  • Clear cache by PURL
  • Clear cache by package type

#Supported protocols

This section contains data formats and response modification rules for each supported package manager in OSA Proxy.

#Maven

#Processed files

• maven-metadata.xml - version information manifest
• .jar, .war, .ear - package files

#maven-metadata.xml field modifications

<metadata>
  <groupId>...</groupId>
  <artifactId>...</artifactId>
  <versioning>
    <latest>updated to latest unblocked</latest>
    <release>updated to latest unblocked</release>
    <versions>
      <version>blocked versions are removed</version>
    </versions>
  </versioning>
</metadata>

#NPM

#Files processed

• Package JSON manifest (path /{repository}/*)
• .tgz - package archives

#NPM Manifest field modifications

{
  "name": "package-name",
  "dist-tags": {
    "latest": "updated to latest unblocked version"
  },
  "versions": {
    "1.0.0": "blocked versions are removed"
  },
  "time": {
    "1.0.0": "entries for blocked versions are removed"
  }
}

#PyPI

#Files and resources

• Simple API HTML pages (path /{repository}/simple/*)
• .zip, .tar, .tgz, .tar.gz, .tar.bz2, .egg, .whl - package files

#HTML page modifications

• Elements for blocked versions are removed
• URLs are rewritten for proxy downloading

<!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

#Handled resources

• index.json - service index
• Registration index JSON
• .nupkg - package files

#Registration index modifications

{
  "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

#Processed files

• Version list (/@v/list)
• .zip — module archives

#Version list modifications

• Blocked versions are removed from the version list

#Debian

#Processed files

• .deb — package files

#Alpine

#Processed files

• .apk — package files

#RPM

#Processed files

• .rpm — package files

#Docker

#Processed files

• Manifests (v2 API)

#Manifest modification

• Digests of blocked images are removed from multi-architecture manifests (Manifest Lists).

#Behavior in case of complete package blocking

In a scenario where all available versions of a requested package are blocked by security policies, OSA Proxy returns a message indicating that all versions are blocked.

Since some package manager clients might not display this specific blocking message in the user interface, it is recommended to use the curl utility for direct diagnosis of the package status. Below are examples of curl requests to check the blocking status for various package types:

#Pip

curl http://localhost:8080/codescoring-pypi/simple/package_name

#Maven

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

#npm

curl http://localhost:8080/codescoring-npm/package_name

#NuGet

Although the NuGet client might display the reason for blocking all packages in the console, a direct curl request also allows for status confirmation:

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

#Go

curl http://localhost:8080/codescoring-go/module_name/@v/list

#Metric collection

Metrics are available in OSA Proxy at {osa-proxy-url}/actuator/metrics in JSON format, as well as in the Prometheus format {platform-url}/actuator/prometheus.

These metrics are collected for each repository type (maven, pypi, nuget, npm) and allow detailed monitoring of incoming requests to proxy repositories.

#Available metrics

• gateway_route_<package-type>_requests_seconds_count – total number of requests processed;
• gateway_route_<package-type>_requests_seconds_sum – total request processing time, used to calculate average response time;
• gateway_route_<package-type>_requests_seconds_max – maximum request processing time;
• gateway_route_<package-type>_requests_seconds_bucket – SLO (Service Level Objective) response time metrics with buckets: 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2s, 5s.

When collecting metrics, <package-type> is replaced with the corresponding repository type: maven, pypi, nuget, npm, go, debian, alpine, rpm, docker. For example, for a Maven repository, the metric will be called gateway_route_maven_requests_total.

These metrics can be filtered by the following labels:

• operation – the type of operation performed on the package;
  • scan_package – package scanning;
  • scan_manifest – manifest scanning;
  • other – other operations (e.g., transferring files not subject to analysis).
• method – HTTP request method (GET, POST, PUT, etc.);
• repository – the name of the repository to which the request was made;
• status – HTTP response status code (e.g., 200, 403, 500);
• outcome – request processing result;
  • success – request successfully processed;
  • error – an error occurred during processing (status 400 or higher, excluding the blocking code);
  • blocked_by_policies – the request was blocked by security policies.

#CodeScoring API Metrics

To monitor interaction with the CodeScoring platform, the following metrics are available:

• codescoring_api_requests_seconds_count – total number of requests to the CodeScoring API;
• codescoring_api_requests_seconds_sum – total execution time of requests to the API;
• codescoring_api_requests_seconds_max – maximum execution time of a request to the API;
• codescoring_api_requests_seconds_bucket – SLO metrics for API response time with buckets: 10ms, 25ms, 50ms, 100ms, 250ms, 500ms, 1s, 2s, 5s.

These metrics allow tracking:

• Performance of interaction with the CodeScoring platform
• Number of component scan requests
• API response time to identify connection issues
• Load on the platform from OSA Proxy

#Base64 URL Parameters

#Using Base64 URL Parameters for osa-proxy

In certain scenarios, interacting with osa-proxy requires explicitly specifying additional parameters in the URL path. This is achieved by encoding the required information in Base64 (URL-safe) format.

The primary purpose of using Base64-encoded parameters is to provide osa-proxy with the necessary context to correctly apply security policies, especially when osa-proxy acts as an intermediary for external repositories.

#Automatic Context Detection

When osa-proxy is placed between a client (package manager) and an internal repository manager (e.g., JFrog Artifactory or Nexus Repository Manager), osa-proxy can automatically extract the host and repository name from the downstream repository settings.

Example configuration where context is automatically determined:

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

#Explicit Context Specification via Base64 Parameters

In cases where osa-proxy directly interacts with external, public repositories (e.g., https://registry.npmjs.org), it cannot independently retrieve information about the internal host and repository name. In this situation, it is critical for osa-proxy to receive this data to apply linked security policies and process the request correctly.

For this purpose, a Base64-encoded string is used, which contains a JSON object with parameters such as repoManagerHost and repoName. This string is embedded directly into the request URL, allowing osa-proxy to obtain the necessary context.

Example configuration requiring explicit context specification:

npm:
  repository:
    - name: codescoring-npm
      # ...
      registry: https://registry.npmjs.org # Parameter passing is required here

#How it works:

The Base64-encoded parameter string is placed in the URL path immediately after the repository name. osa-proxy decodes this string, extracts the parameters, and uses them to perform its functions, including applying security policies associated with a specific internal repository.

General URL Structure: https://<osaproxy-host>/<repository-name>/<base64-parameters>/<rest-of-path>

#Passing Context for Correct Operation of Security Policies Linked to Nexus and Artifactory Repositories

Developer Client -> Nexus / Artifactory -> osa-proxy -> Internet

To pass contextual information, including the host and repository name of your repository manager, this data should be integrated into a Base64-encoded parameter string. It is important to strictly adhere to the rule that this Base64 string must be placed immediately after the repository name in the URL.

#Configuration Update

It is necessary to mark the repository as compatible with Base64 parameters using url-encoded-config: true.

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

#Nexus

1. Go to Server Administration -> Repositories.
2. Select the desired type (e.g., maven2 (proxy)).
3. In the Remote storage field, enter the URL of your osa-proxy instance, including the repository name and Base64-encoded parameters.

Example for a Maven proxy repository: https://osaproxy.example.com/internet-maven/eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL3JlcG8xLm1hdmVuLm9yZy9tYXZlbjIiLCJyZXBvTmFtZSI6ImludGVybmV0LW1hdmVuIn0/maven2

#Artifactory

1. Go to Administration -> Repositories -> Remote.
2. In the configuration, set the URL field to the osa-proxy URL. This URL must include the repository name and the Base64-encoded string.

Example for a remote PyPI repository: https://osaproxy.example.com/internet-pypi/eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL3B5cGkub3JnL3NpbXBsZSIsInJlcG9OYW1lIjoiaW50ZXJuZXQtcHlwaSJ9/simple

#Rule

The Base64-encoded parameter string must be placed in the URL path immediately after the repository name.

The general URL structure is as follows: https://<osaproxy-host>/<repository-name>/<base64-parameters>/<rest-of-path>

Where:

• <osaproxy-host>: The hostname of the osa-proxy instance.
• <repository-name>: The name of the repository being accessed.
• <base64-parameters>: A URL-safe Base64-encoded JSON string containing the parameters.
• <rest-of-path>: The remaining part of the path from the package manager settings.

#Example

For example, to pass the following parameters as a JSON object:

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

To do this, you should:

1. Convert the JSON object to a string.
2. Encode the string using URL-safe Base64.

The result of encoding the above JSON object in Base64: eyJyZXBvTWFuYWdlckhvc3QiOiJodHRwczovL25leHVzLnRlc3QucnUiLCJyZXBvTmFtZSI6Im5wbS1wcm94eSJ9

#Configuring Package Managers

To permanently use the URL with Base64 parameters for all requests, update your package manager's configuration file.

#NPM

For NPM, edit .npmrc file and set the registry key.

The URL should include the repository name and the Base64 encoded string.

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

#Maven

For Maven, edit settings.xml file. You can add a new <mirror> in the <mirrors> section.

The <url> tag should contain the full URL, including the repository name and the Base64 encoded string.

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

Make sure the <mirrorOf> value matches the repositories you want to proxy.

#Go

For Go, set the GOPROXY environment variable to include the repository name and the Base64-encoded string.

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

#Debian

For Debian, edit /etc/apt/sources.list or a file in /etc/apt/sources.list.d/. Update the URIs field.

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

#NuGet

For NuGet, edit NuGet.config file and add a new package source. The value attribute of the <add> tag should contain the full URL.

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

#PyPI

For PyPI, edit pip.conf (Linux/macOS) or pip.ini (Windows) file and set the index-url.

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

#Maven сonfiguration

#Repository URL migration

Use case: migrating a Maven repository from Artifactory to OSA Proxy.

The following table provides a summary of repository URL redirection for Maven. Authentication parameters and other configurations, such as username and password, remain unchanged.

#Maven registry migration

Original .m2/settings.xml file:

<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>

The following repository definition needs to be added to the service's YAML configuration (the application.yml file) under the maven section. A service restart is required to apply the changes.

Configuration in application.yml file

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

Updated .m2/settings.xml file:

<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 Configuration

#Repository URL migration

Use Case: Migrating an npm repository from Artifactory to OSA Proxy.

The following table provides a summary of repository URL redirection for NPM. Authentication parameters and other configurations, such as username and password, remain unchanged.

#NPM registry migration

Original .npmrc file:

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

The following repository definition needs to be added to the service's YAML configuration (the application.yml file) under the npm section. A service restart is required to apply the changes.

Configuration in application.yml file

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

Updated .npmrc file:

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 Configuration

#Repository URL migration

Use case: migrating a NuGet repository from Artifactory to OSA Proxy.

The following table provides a summary of repository URL redirection for NuGet. Authentication parameters and other configurations, such as username and password, remain unchanged.

#NuGet registry migration

Original NuGet.config file:

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

The following repository definition needs to be added to the service's YAML configuration (the application.yml file) under the nuget section. A service restart is required to apply the changes.

Configuration in application.yml file

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

Updated NuGet.config file:

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

#PyPI Configuration

#Repository URL migration

Use case: migrating a PyPI repository from Artifactory to OSA Proxy.

The following table provides a summary of repository URL redirection for PyPI. Authentication parameters and other configurations, such as username and password, remain unchanged.

#PyPI registry migration

Original pip.conf (Linux/macOS) or pip.ini (Windows) file:

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

[install]
trusted-host = jfrog.host.ru

Or with authentication:

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

[install]
trusted-host = jfrog.host.ru

The following repository definition needs to be added to the service's YAML configuration (the application.yml file) under the pypi section. A service restart is required to apply the changes.

Configuration in application.yml file

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 configuration example in 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

Updated pip.conf (Linux/macOS) or pip.ini (Windows) file:

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

[install]
trusted-host = {osa-proxy-url}

Or with authentication:

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

[install]
trusted-host = {osa-proxy-url}

#Multiple package registries

Some PyPI repositories may serve packages from multiple hosts. For example, the download.pytorch.org index contains links to both its own CDN hosts and the standard files.pythonhosted.org.

To correctly proxy such repositories, use the additional-packages-registries parameter — a map where the key specifies the source host and the value specifies the package registry URL to route requests to.

PyTorch configuration example:

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

#Configuration file locations

• Linux/macOS: ~/.config/pip/pip.conf or ~/.pip/pip.conf
• Windows: %APPDATA%\pip\pip.ini or %HOME%\pip\pip.ini
• Per-virtualenv: $VIRTUAL_ENV/pip.conf

#Go Configuration

#Go Proxy Migration

Use case: Migrating Go to use an OSA Proxy instead of direct access or external public proxies.

The following table summarizes URL redirection for the Go proxy. Authentication parameters and other settings (if applicable, e.g., for private repositories requiring specific credentials) should be configured separately in accordance with your corporate policies (e.g., via .netrc or SSH keys).

#Go Proxy Migration Details

#Environment Configuration Before Migration

Before migration, your GOPROXY might have been set to the public Go proxy (https://proxy.golang.org) or not set at all, which would default to using proxy.golang.org. The following repository definition needs to be added to the service's YAML configuration (the application.yml file) in the go section. A service restart is required for the changes to take effect.

Configuration in application.yml file

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

Example of current environment variable configuration (e.g., in .bashrc, .zshrc file, or in a CI/CD pipeline):

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

#Checksum Database Configuration

To proxy requests to sum.golang.org through OSA Proxy, use the GOSUMDB environment variable. Its value follows the format <db-name> <proxy-url>, where the URL is constructed as {osa-proxy-url}/{repo-name}/sumdb/sum.golang.org:

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

Full usage example:

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 Package Configuration

#Repository URL Migration

Use case: Migration of Debian repositories from direct sources to an OSA Proxy server.

The following table summarizes the redirection of repository URLs for Debian. Please note that the format of the deb or deb-src repository lines (distribution, components) remains unchanged; only the base repository URL changes.

#APT Repository Migration

Original file /etc/apt/sources.list or /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

The following repository definition needs to be added to the service's YAML configuration (the application.yml file) in the debian section. The service must be restarted for the changes to take effect.

Configuration in application.yml file

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

After configuring the proxy server and adding it to application.yml, your sources.list will look like this:

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 Configuration

#Registry URL Migration

Use case: Migration of Docker registries from direct sources to an OSA Proxy server.

The following table summarizes the redirection of URLs for Docker.

#Docker Client Migration

The following repository definition needs to be added to the service's YAML configuration (the application.yml file) in the docker section. The service must be restarted for the changes to take effect.

Configuration in application.yml file

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

After configuring the proxy server and adding it to application.yml, the command to pull an image will look like this:

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

#Using subdomains for access

If you want to use more than one Docker repository, you need to enable subdomains. The subdomain names must match the repository names specified in the docker.repository configuration.

In this case, the command to pull an image will look like this:

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

For a single repository, there is no need to add a subdomain — Docker will be available directly via the OSA Proxy host:

docker pull osaproxyhost.ru/library/postgres

#Alpine Package Configuration

#Repository URL Migration

Use case: Migration of Alpine repositories from direct sources to an OSA Proxy server.

The following table summarizes the redirection of repository URLs for Alpine.

#APK Repository Migration

Original file /etc/apk/repositories:

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

The following repository definition needs to be added to the service's YAML configuration (the application.yml file) in the alpine section. The service must be restarted for the changes to take effect.

Configuration in application.yml file

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

After configuring the proxy server and adding it to application.yml, your repositories file will look like this:

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

#RPM Package Configuration

#Repository URL Migration

Use case: Migration of RPM repositories (YUM/DNF) from direct sources to an OSA Proxy server.

The following table summarizes the redirection of repository URLs for RPM.

#YUM/DNF Repository Migration

Original file /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

The following repository definition needs to be added to the service's YAML configuration (the application.yml file) in the rpm section. The service must be restarted for the changes to take effect.

Configuration in application.yml file

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

After configuring the proxy server and adding it to application.yml, the repository configuration will look like this:

[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