#OSA Proxy

OSA 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 source repositories, analyzes received packages, modifies responses, and manages access to components.

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

#Supported ecosystems

OSA Proxy supports the following registry types:

• npm;
• Composer;
• Maven;
• Gradle (through Maven-compatible repositories);
• NuGet;
• PyPI;
• RubyGems;
• Conan v2;
• Go modules;
• Debian;
• Alpine;
• RPM;
• Docker Registry API v2.

#Block responses through Nexus and Artifactory

In a “remote registry → OSA Proxy → Nexus/Artifactory” setup, blocked package download responses now match repository manager plugin behavior:

• Nexus receives the status configured in codescoring.block-status-code instead of 404. With codescoring.enable-status-line: true, the block reason is included in the HTTP/1.1 status line, as with the Nexus plugin.
• Artifactory receives HTTP 403 and returns its standard response to the client without a custom status line.

If Nexus returns the correct HTTP status but the reason is missing from the status line, check any reverse proxy in front of Nexus, such as Traefik, nginx, or an ingress controller. It must not overwrite the HTTP response status line. Status lines exist only in HTTP/1.1; HTTP/2 and HTTP/3 carry only the numeric status code.

#Main functionality

#Manifest and package scanning

For supported ecosystems, two check levels are available:

• manifest scanning — analyzes package metadata/indexes and removes versions blocked by policies from responses returned to package managers;
• package scanning — checks downloaded archives, binary packages, or images before they are passed to the client.

Support depends on the ecosystem. For example, npm, Maven, NuGet, PyPI, Go, Composer, and RubyGems support metadata and package checks, while Debian, Alpine, and RPM support downloaded package checks without system index modification.

#Blocking unsafe components

If a component violates security policies, OSA Proxy can remove unsafe versions from metadata, block artifact downloads, and return a configurable block HTTP status code.

#Response modification

When manifest scanning is enabled, the service modifies upstream registry responses: removes blocked versions, rewrites download links through the proxy, and preserves the response format expected by the package manager.

#Verdict caching

To reduce CodeScoring load and speed up repeated requests, OSA Proxy supports Redis caching for Judge check results. The cache is disabled by default and configured in the cache section.

#Routes

For all ecosystems except Docker, the route name is taken from the name field in the repository section of osa-proxy.yml.

For example, an npm repository named npm is available at:

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

Docker mode uses standard Docker Registry API v2 endpoints and does not add the repository name to the path:

docker pull osa-proxy.example.com/library/alpine:latest

If several Docker repositories are enabled, use subdomains where the subdomain matches repository[*].name, for example dockerhub.osa-proxy.example.com. See Docker Configuration.

#Operational endpoints

#Work modes

The work-mode parameter controls check behavior. It can be set globally in codescoring.work-mode and overridden for a specific repository with repository[*].work-mode.

• warmup — warms up the cache without blocking components;
• spectator — warms up the cache and records request results without blocking;
• moderate — blocks by policies, but allows unscanned components;
• strict — blocks by policies and blocks unscanned components;
• strict_wait — blocks by policies and waits for checks of unscanned components.