Service configuration¶
OSA Proxy Go 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.
Configuration example¶
codescoring:
url: https://codescoring.example.com
token: "<token>"
work-mode: strict_wait
osa-proxy-url: https://osa-proxy.example.com
enable-status-line: true
block-on-codescoring-errors: true
remove-blocked-versions: true
legacy-judge: false
stage: proxy
block-status-code: 403
judge-concurrency: 10
resilience:
retry:
max-attempts: 3
wait-duration: 1s
exponential-backoff-multiplier: 2
circuit-breaker:
failure-rate-threshold: 50
minimum-number-of-calls: 10
sliding-window-size: 20
wait-duration-in-open-state: 30s
permitted-number-of-calls-in-half-open-state: 5
http:
server:
read-timeout: 2m
read-header-timeout: 5s
idle-timeout: 120s
shutdown-timeout: 10s
client:
connection-timeout: 10s
response-timeout: 30s
max-manifest-body-size: 200mb
max-idle-conns: 100
max-idle-conns-per-host: 10
idle-conn-timeout: 90s
pypi:
enabled: true
repository:
- name: pypi
registry: https://pypi.org
packages-registry: https://files.pythonhosted.org
scan-manifest: true
scan-package: true
work-mode: strict_wait
url-encoded-config: true
- name: pytorch-pypi
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
scan-manifest: true
scan-package: true
work-mode: strict_wait
url-encoded-config: true
maven:
enabled: true
repository:
- name: maven
registry: https://repo1.maven.org/maven2
scan-manifest: true
scan-package: true
work-mode: strict_wait
url-encoded-config: true
nuget:
enabled: true
repository:
- name: nuget
registry: https://api.nuget.org
scan-manifest: true
scan-package: true
work-mode: strict_wait
url-encoded-config: true
npm:
enabled: true
repository:
- name: npm
registry: https://registry.npmjs.org
scan-manifest: true
scan-package: true
work-mode: strict_wait
url-encoded-config: true
composer:
enabled: true
repository:
- name: composer
registry: https://repo.packagist.org
packages-registry: https://api.github.com
additional-packages-registries:
github.com: https://github.com
gitlab.com: https://gitlab.com
scan-manifest: true
scan-package: true
work-mode: strict_wait
url-encoded-config: true
ruby:
enabled: true
repository:
- name: ruby
registry: https://rubygems.org
scan-manifest: true
scan-package: true
work-mode: strict_wait
url-encoded-config: true
go:
enabled: true
repository:
- name: go
registry: https://proxy.golang.org
sumdb-registry: https://sum.golang.org
scan-manifest: true
scan-package: true
work-mode: strict_wait
url-encoded-config: true
debian:
enabled: true
repository:
- name: debian
registry: https://deb.debian.org/debian
distro: bookworm
scan-package: true
work-mode: strict_wait
url-encoded-config: true
alpine:
enabled: true
repository:
- name: alpine
registry: https://dl-cdn.alpinelinux.org/alpine
scan-package: true
work-mode: strict_wait
url-encoded-config: true
rpm:
enabled: true
repository:
- name: rpm
registry: https://mirror.stream.centos.org/10-stream/AppStream/x86_64/os
scan-package: true
work-mode: strict_wait
url-encoded-config: true
docker:
enabled: true
repository:
- name: docker
registry: https://registry-1.docker.io
auth-token-url: https://auth.docker.io
work-mode: strict_wait
cache:
judge:
enabled: false
ttl: 24h
refresh-after: 30m
proactive-refresh-enabled: false
proactive-refresh-interval: 2h
proactive-refresh-workers: 10
key-prefix: "cs:judge:"
redis:
address: redis:6379
password: ""
db: 0
logging:
level: info
codescoring section¶
| Parameter | Purpose |
|---|---|
url |
CodeScoring platform URL. |
token |
CodeScoring access token. |
work-mode |
Global work mode when it is not overridden at repository level. |
osa-proxy-url |
External OSA Proxy Go URL used when building links and responses. |
enable-status-line |
Adds the block reason to the HTTP/1.1 status line when the client displays it. |
block-on-codescoring-errors |
Blocks downloads on CodeScoring errors or scan errors. |
remove-blocked-versions |
Removes blocked versions from manifests. If false, versions remain marked as blocked where the format supports it. |
block-status-code |
HTTP status code for blocked downloads. The default is 403. |
judge-concurrency |
Number of parallel Judge requests. Used to limit load on Judge when checking large version lists and during background cache refresh. |
resilience.retry |
Retry settings for CodeScoring requests. |
resilience.circuit-breaker |
Circuit breaker settings for temporary degradation of external calls. |
Package manager sections¶
Each ecosystem contains the enabled flag and a repository list. The repository name becomes part of the OSA Proxy Go URL:
npm:
enabled: true
repository:
- name: company-npm
registry: https://registry.npmjs.org
scan-manifest: true
scan-package: true
work-mode: strict_wait
url-encoded-config: true
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:
cache:
judge:
enabled: true
ttl: 24h
refresh-after: 30m
proactive-refresh-enabled: false
proactive-refresh-interval: 2h
proactive-refresh-workers: 10
key-prefix: "cs:judge:"
redis:
address: redis:6379
password: ""
db: 0
Logging¶
The log level is configured with logging.level. Supported values are debug, info, warn, and error.
Parameter reference¶
Root sections¶
| Parameter | Purpose |
|---|---|
pypi |
PyPI repository settings. |
maven |
Maven repository settings. |
nuget |
NuGet repository settings. |
npm |
npm repository settings. |
composer |
Composer/Packagist repository settings. |
ruby |
RubyGems repository settings. |
go |
Go module proxy settings. |
debian |
Debian repository settings. |
alpine |
Alpine APK repository settings. |
rpm |
RPM/YUM/DNF repository settings. |
docker |
Docker Registry API v2 settings. |
codescoring |
CodeScoring connection and check behavior. |
http |
HTTP server and HTTP client timeouts and limits. |
cache |
Redis Judge verdict cache. |
logging |
Service log level. |
Common package manager parameters¶
| Parameter | Available in | Purpose |
|---|---|---|
enabled |
All package managers | Registers routes for the ecosystem. If false, repositories from this section are not served. |
repository |
All package managers | List of upstream repositories for the ecosystem. |
repository[*].name |
All package managers | Repository name. For non-Docker ecosystems it becomes the first URL segment: /{name}/.... Must be unique among enabled routes. |
repository[*].registry |
All package managers | Upstream registry URL where OSA Proxy Go proxies requests. |
repository[*].work-mode |
All package managers | Work mode for a specific repository. If empty, codescoring.work-mode is used. |
repository[*].scan-manifest |
npm, composer, maven, nuget, pypi, ruby, go |
Enables manifest/metadata checking and modification. |
repository[*].scan-package |
All except docker |
Enables checks for downloaded package files. For docker, image checks are handled by Docker Registry proxy logic. |
repository[*].url-encoded-config |
All except docker |
Enables URL-safe Base64 context in the path for Nexus/JFrog scenarios and repository-context policy application. |
repository[*].file-type-filter |
All except docker |
Limits which files are sent to package scanning by extension. If the parameter is omitted or disabled, filtering is not applied. |
Repository-specific parameters¶
| Parameter | Available in | Purpose |
|---|---|---|
packages-registry |
pypi, composer |
Base URL of a separate host used to download package files when it differs from the metadata registry. |
additional-packages-registries |
pypi, composer |
Additional host -> registry map for packages that publish artifacts on multiple domains. Useful for correct routing of external package hosts. |
sumdb-registry |
go |
Go checksum database URL, for example https://sum.golang.org, when SumDB requests should go through OSA Proxy Go. |
distro |
debian, alpine |
Distribution or branch name used when processing metadata and package paths. |
auth-token-url |
docker |
Docker Registry token service URL. For Docker Hub this is usually https://auth.docker.io; for JFrog/Nexus use the corresponding repository manager endpoint. |
file-type-filter¶
| Parameter | Purpose |
|---|---|
additional-allowed-extensions |
YAML array of strings. The presence of this field enables the filter: after that, only extensions from the built-in preset and from additional-allowed-extensions pass, while other unknown extensions are blocked. Values can be written with or without the leading dot; they are normalized to lowercase and to the dotted form. |
scanned-extensions |
YAML array of strings. Enables the filter and makes the handler treat files with these extensions as package artifacts for scanning and short-lived scan-result caching. Values can be written with or without the leading dot. |
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 Go 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 Go:
- 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:
| Ecosystem | Allowed extensions |
|---|---|
npm |
.tgz |
composer |
.zip, .tar, .tgz, .tar.gz, .tar.bz2, .tar.xz |
pypi |
.whl, .tar.gz, .tar.bz2, .tar.xz, .zip, .egg |
nuget |
.nupkg, .snupkg |
ruby |
.gem |
go |
.zip |
alpine |
.apk |
rpm |
.rpm, .drpm |
debian |
.deb, .udeb, .dsc, .orig.tar.gz, .orig.tar.xz, .orig.tar.bz2, .debian.tar.gz, .debian.tar.xz, .debian.tar.bz2, .diff.gz |
maven |
.pom, .jar, .war, .ear, .rar, .dar, .zip, .tar.gz, .aar, .apk, .aab, .nar, .hpi, .jpi, .kar, .eba, .sar, .par, .car, .mar, .har, .obr, .module |
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 Go 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:
npm:
enabled: true
repository:
- name: npm
registry: https://registry.npmjs.org
scan-package: true
file-type-filter:
additional-allowed-extensions: [tgz, license]
scanned-extensions: [tgz]
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:
npm:
enabled: true
repository:
- name: npm
registry: https://registry.npmjs.org
scan-package: true
file-type-filter: {}
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.
npm:
enabled: true
repository:
- name: npm
registry: https://registry.npmjs.org
scan-package: true
file-type-filter:
additional-allowed-extensions: []
To allow a non-standard file without sending it to package scanning, add the extension only to additional-allowed-extensions:
npm:
enabled: true
repository:
- name: npm
registry: https://registry.npmjs.org
scan-package: true
file-type-filter:
additional-allowed-extensions: [license]
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.
codescoring¶
| Parameter | Default | Purpose |
|---|---|---|
url |
Required | CodeScoring platform URL. |
token |
Required | CodeScoring API access token. |
work-mode |
Not set | Global work mode: warmup, spectator, moderate, strict, strict_wait. |
osa-proxy-url |
Not set | External OSA Proxy Go URL. Used when generating links and rewriting URLs in responses. |
enable-status-line |
false |
Adds the block reason to the HTTP/1.1 status line. Does not affect HTTP/2 or HTTP/3; Docker clients read the JSON body. |
block-on-codescoring-errors |
false |
Blocks downloads when CodeScoring returns an error or a package cannot be checked. |
remove-blocked-versions |
true |
Removes blocked versions from manifests. If false, versions remain in metadata with a block marker when the format supports it. |
legacy-judge |
false |
Enables compatibility with Judge versions before 2026.20.0. Use only for CodeScoring installations with an older Judge service version. |
stage |
Not set | Stage/context value passed to CodeScoring checks. Usually proxy. |
block-status-code |
403 |
HTTP status code returned for blocked packages. |
judge-concurrency |
10 |
Limits the number of parallel Judge requests. Lower values make OSA Proxy Go send fewer concurrent requests to Judge when checking large version lists and during background cache refresh. Versions are sent in chunks of up to 900 PURLs, so this parameter becomes visible when a single package has more than 900 versions and the check is split into multiple requests. |
resilience |
See below | Resilience settings for CodeScoring requests. |
codescoring.resilience.retry¶
| Parameter | Default | Purpose |
|---|---|---|
max-attempts |
3 |
Maximum number of request attempts. |
wait-duration |
1s |
Delay between attempts. |
exponential-backoff-multiplier |
2 |
Exponential backoff multiplier for increasing retry delays. |
codescoring.resilience.circuit-breaker¶
| Parameter | Default | Purpose |
|---|---|---|
failure-rate-threshold |
50 |
Error percentage that opens the circuit breaker. |
minimum-number-of-calls |
10 |
Minimum number of calls required to calculate the error rate. |
sliding-window-size |
20 |
Window size used for error statistics. |
wait-duration-in-open-state |
30s |
Time before moving from open to half-open state. |
permitted-number-of-calls-in-half-open-state |
5 |
Number of trial requests allowed in half-open state. |
http.server¶
| Parameter | Default | Purpose |
|---|---|---|
read-timeout |
2m |
Maximum time for reading the whole incoming request. |
read-header-timeout |
5s |
Maximum time for reading HTTP headers. |
idle-timeout |
120s |
Time to keep an idle keep-alive connection. |
shutdown-timeout |
10s |
Graceful shutdown timeout. |
http.client¶
| Parameter | Default | Purpose |
|---|---|---|
connection-timeout |
10s |
Timeout for establishing connections to upstream registries and CodeScoring. |
response-timeout |
30s |
Response wait timeout. |
max-manifest-body-size |
200mb |
Maximum manifest/metadata response body size the service will process. Values such as 200mb are supported. |
max-idle-conns |
100 |
Maximum number of idle HTTP connections. |
max-idle-conns-per-host |
10 |
Maximum number of idle HTTP connections per host. |
idle-conn-timeout |
90s |
Lifetime of an idle connection in the HTTP client. |
cache.judge¶
| Parameter | Default | Purpose |
|---|---|---|
enabled |
false |
Enables Redis cache for Judge check results. |
ttl |
24h |
Cache entry lifetime. |
refresh-after |
30m |
Entry age after which it can be refreshed in the background. |
proactive-refresh-enabled |
false |
Enables proactive background refresh for stale entries. |
proactive-refresh-interval |
2h |
Background refresh interval. |
proactive-refresh-workers |
10 |
Number of background refresh workers. |
key-prefix |
Not set | Redis key prefix, for example cs:judge:. |
cache.redis¶
| Parameter | Purpose |
|---|---|
address |
Redis address in host:port format. |
password |
Redis password. |
db |
Redis database number. |
logging¶
| Parameter | Default | Purpose |
|---|---|---|
level |
info |
Log level: debug, info, warn, warning, error. Unknown values are treated as info. |