Skip to content

OSA Proxy Go

OSA Proxy Go is the Go version of the proxy service for package registries with CodeScoring OSA checks. The service accepts package manager requests, proxies them to upstream registries, checks manifests and downloaded artifacts, blocks forbidden components, and exposes operational endpoints for health checks, metrics, Swagger UI, and cache administration.

Supported ecosystems

OSA Proxy Go supports the following registry types:

  • npm;
  • Composer;
  • Maven;
  • NuGet;
  • PyPI;
  • RubyGems;
  • Go modules;
  • Debian;
  • Alpine;
  • RPM;
  • Docker Registry API v2.

Alternative repositories

OSA Proxy Go can work not only with public registries, but also with repository managers that implement the corresponding ecosystem protocols, for example Sonatype Nexus Repository, JFrog Artifactory, or CodeScoring.Save.

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

Registry type Route form
npm, Composer, Maven, NuGet, PyPI, Ruby, Go, Debian, Alpine, RPM GET /{repository-name}/{path...}
Docker /v2/{path...} and GET /token

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

Operational endpoints

Endpoint Purpose
GET /healthz Checks that the OSA Proxy Go process is running.
GET /metrics Prometheus metrics.
GET /api/v3/api-docs OpenAPI JSON.
GET /api/swagger/ Swagger UI.
DELETE /api/cache/purls Deletes specific PURLs from the verdict cache.
DELETE /api/cache/packages/{packageType} Deletes cache records by package type, package name, or repository context.

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.