• English

    • OSA Proxy

    OSA Proxy implementation

    This page describes the current OSA Proxy implementation. The archived Java/Spring implementation is available in Archived Java/Spring implementation.

    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);
    • Ivy (sbt / Apache Ivy);
    • NuGet;
    • PyPI;
    • R (CRAN);
    • CocoaPods;
    • Swift Package Registry;
    • RubyGems;
    • Conan v2;
    • Go modules;
    • Hex;
    • Debian;
    • Alpine;
    • RPM;
    • Docker Registry API v2.
    Alternative repositories

    OSA Proxy 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.

    Artifactory and Nexus integration

    Automatic discovery, client routes, repository context, and block response behavior are documented on the JFrog Artifactory and Nexus Repository pages.

    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, CocoaPods, Swift, Go, Hex, Composer, and RubyGems support metadata and package checks, while R, 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.

    Registry typeRoute form
    npm, Composer, Maven, Ivy, NuGet, PyPI, R, CocoaPods, Swift, Ruby, Go, Hex, Debian, Alpine, RPMGET /{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

    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

    Main service listener (default 8080)

    EndpointPurpose
    GET /healthzChecks that the OSA Proxy process is alive (liveness probe).
    GET /readyzChecks that the service is ready to accept traffic (readiness probe).
    GET /metricsService metrics in Prometheus format.

    Administration listener (default 8081)

    When admin.enabled: true is configured, the protected administrative listener provides:

    EndpointPurpose
    GET /swagger/Interactive Swagger UI documentation.
    GET /openapi.jsonOpenAPI 3 JSON specification.
    GET /api/v1/statusStore status, replica synchronization, and active revision.
    GET /api/v1/runtime/repositoriesList of all active served routes (static and dynamic).
    GET /api/v1/configurationExport desired state of dynamic repository configuration.
    GET /api/v1/configuration/repositories/{package_type}Read the desired repository configuration for one package ecosystem.
    PUT /api/v1/configuration/repositories/{package_type}Replace the desired repositories for one package ecosystem (requires Configuration Store and If-Match).
    POST /api/v1/configuration/revisions/{revision}/rollbackRoll back configuration to a target revision.
    DELETE /api/v1/cache/purlsTargeted purge of verdict cache entries by PURL.
    DELETE /api/v1/cache/packages/{packageType}Purge verdict cache entries by package type and name.

    For details on configuring access tokens and calling endpoints, see Admin API and management.

    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.
    Was this page helpful?