Service configuration
This page describes the current OSA Proxy implementation. The archived Java/Spring implementation is available in Archived Java/Spring implementation.
OSA Proxy is configured with the osa-proxy.yml file. The example below shows a typical working configuration with several ecosystems, CodeScoring settings, HTTP client settings, Redis cache, and logging.
For CodeScoring versions earlier than 2026.20.0, set codescoring.legacy-judge: true. Versions before 2026.20.0 use the legacy Judge API, while OSA Proxy uses the current Judge API by default.
Configuration example
codescoring section
Package manager sections
Each ecosystem contains the enabled flag and a repository list. The repository name becomes part of the OSA Proxy URL:
This repository is available at:
The scan-manifest and scan-package fields enable checks for manifests and downloaded artifacts. Support for these modes depends on the ecosystem; see Supported protocols. Repository-level work-mode overrides global codescoring.work-mode.
Ecosystem-specific options
composer and pypi support packages-registry and additional-packages-registries when artifacts are downloaded from separate hosts. go uses sumdb-registry when SumDB proxying is required. Docker uses auth-token-url.
Verdict cache
Redis cache is disabled by default:
To enable caching:
Logging
The log level is configured with logging.level. Supported values are debug, info, warn, and error.
Parameter reference
Root sections
Common package manager parameters
Repository-specific parameters
file-type-filter
The filter applies only to non-Docker repositories. If the file-type-filter section is omitted or set to {}, the filter is disabled: OSA Proxy behaves as if the filter did not exist, so requests follow the normal handler rules and compatibility with previous behavior is preserved. To enable the filter, add at least one of additional-allowed-extensions / scanned-extensions. The presence of the key is what matters: for example, additional-allowed-extensions: [] enables the filter but does not add extensions beyond the built-in preset.
When the filter is enabled, OSA Proxy:
- lets metadata/manifest requests pass without extension checks;
- extracts the filename from the URL path, decodes URL-encoded characters, and compares extensions case-insensitively;
- allows a file when its extension is included in the built-in ecosystem preset or in
additional-allowed-extensions; - allows checksum and signature sidecar files (
.metadata,.sha256,.sha512,.sha1,.asc,.md5) only when the base artifact is also allowed; - immediately blocks all other package file requests before contacting the upstream registry or CodeScoring.
Built-in presets:
For Debian, source tarballs matching .orig-*.tar.gz, .orig-*.tar.xz, and .orig-*.tar.bz2 are also allowed.
additional-allowed-extensions only extends the filter allow-list. The presence of this field switches the repository to allow-list mode: OSA Proxy allows the built-in ecosystem extensions and the extensions from additional-allowed-extensions, and blocks all other unknown package file extensions. Use it when a repository contains acceptable files with non-standard extensions and the filter must not block them. This parameter does not make the handler send those files to package scanning: if the ecosystem's default strategy does not treat the extension as scannable, the request continues as normal passthrough. To make a new file type participate in package scanning, also add the extension to scanned-extensions.
scanned-extensions controls the second behavior: files with these extensions are treated as scannable package artifacts even if the ecosystem's default strategy does not recognize them. For these extensions, a short-lived scan-result cache is enabled so related files with the same base name can reuse one verdict. For example, Maven can use scanned-extensions: [.jar, .pom] so demo-1.0.0.jar and demo-1.0.0.pom are grouped by the demo-1.0.0 base name.
Example:
In this example, .tgz is allowed by the npm preset and participates in package scanning, while .license is additionally allowed by the filter but does not become a scannable artifact.
npm behavior example
Without the file-type-filter section, the filter is disabled. The npm handler follows its standard logic: the package tarball left-pad-1.0.0.tgz is sent to package scanning, while other requests are handled as metadata or passthrough depending on the route.
An empty section also keeps the filter disabled:
To enable the filter without adding new extensions, set an empty list. For npm, only the built-in .tgz preset and sidecar files for allowed artifacts are allowed. A request for left-pad-1.0.0.tgz passes and is checked, while left-pad-1.0.0.exe is blocked before the upstream registry and CodeScoring are contacted.
To allow a non-standard file without sending it to package scanning, add the extension only to additional-allowed-extensions:
With this configuration, .tgz is scanned as an npm package, .license passes the filter as an allowed file, and .exe is blocked by the filter.