Service configuration

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

Legacy Judge compatibility

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:
  url: https://codescoring.example.com
  token: "<token>"
  work-mode: strict_wait
  osa-proxy-url: https://osa-proxy.example.com
  osa-proxy-url-from-forwarded-headers: false
  enable-status-line: true
  block-on-codescoring-errors: true
  block-message: "Component download was blocked by security policy"
  append-block-url-to-message: true
  legacy-judge: false
  stage: proxy
  block-status-code: 403
  judge-concurrency: 16
  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
      remove-blocked-versions: true
      work-mode: strict_wait
    - 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
      remove-blocked-versions: true
      work-mode: strict_wait

maven:
  enabled: true
  repository:
    - name: maven
      registry: https://repo1.maven.org/maven2
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait

ivy:
  enabled: true
  repository:
    - name: ivy
      registry: https://scala.jfrog.io/artifactory/ivy-releases
      layout: sbt-default
      scan-package: true
      work-mode: strict_wait

nuget:
  enabled: true
  repository:
    - name: nuget
      registry: https://api.nuget.org
      scan-manifest: true
      scan-package: true
      remove-blocked-versions: true
      work-mode: strict_wait

npm:
  enabled: true
  repository:
    - name: npm
      registry: https://registry.npmjs.org
      scan-manifest: true
      scan-package: true
      remove-blocked-versions: true
      work-mode: strict_wait

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

ruby:
  enabled: true
  repository:
    - name: ruby
      registry: https://rubygems.org
      scan-manifest: true
      scan-package: true
      work-mode: strict_wait

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

debian:
  enabled: true
  repository:
    - name: debian
      registry: https://deb.debian.org/debian
      distro: bookworm
      scan-package: true
      work-mode: strict_wait

alpine:
  enabled: true
  repository:
    - name: alpine
      registry: https://dl-cdn.alpinelinux.org/alpine
      scan-package: true
      work-mode: strict_wait

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

docker:
  enabled: true
  repository:
    - name: docker
      registry: https://registry-1.docker.io
      auth-token-url: https://auth.docker.io/token
      scan-container: true
      codescoring-pull-through-proxy: false
      work-mode: strict_wait

admin:
  enabled: false
  address: 127.0.0.1:8081
  write-timeout: 2m
  token-hash: ""

cache:
  judge:
    enabled: false
    redis-db: 1
    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
    username: ""
    password: ""
    db: 0

configuration-store:
  enabled: false
  backend: redis
  deployment-identity: ""
  replica-identity: "osa-proxy-1"
  mode: standalone
  accept-unsafe-durability: false
  redis:
    address: ""

layouts:
  custom-layout: "[organisation]/[module]/[revision]/[type]s/[artifact]-[revision].[ext]"

webhooks:
  - name: downloads
    url: https://hooks.example.com/downloads
    token_env: WEBHOOK_DOWNLOADS_TOKEN
    events: [file_downloaded, scanned_file_downloaded, file_blocked]
    repositories: [npm, maven]
    timeout: 3s
    buffer_size: 256

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 URL used when building links and responses.
`osa-proxy-url-from-forwarded-headers`	Builds the external URL from forwarded headers instead of a static value.
`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.
`block-message`	Sets a custom block response message. If omitted or empty, OSA Proxy uses its standard block message.
`append-block-url-to-message`	Appends a link to the block reason to the custom message.
`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.

HTTP status line text

The HTTP/1.1 status line supports ASCII only. Messages containing Cyrillic or other non-ASCII characters are not passed in the status line. If Nexus or a package manager must display the block reason in the status line, use ASCII characters in block-message, for example Component download blocked by security policy.

Building URLs from forwarded headers

Use osa-proxy-url-from-forwarded-headers when one OSA Proxy instance is available through multiple external URLs, for example from two network zones:

codescoring:
  osa-proxy-url-from-forwarded-headers: true

The reverse proxy in each zone supplies its own X-Forwarded-Proto and X-Forwarded-Host. OSA Proxy uses them to build absolute package links in metadata and manifests, so clients in each zone receive links through the URL available to them. For example, requests through osa-proxy.internal.example.com produce links with that host, while requests through osa-proxy.dmz.example.com produce links with the DMZ host.

If X-Forwarded-Proto is absent, OSA Proxy uses https; if X-Forwarded-Host is absent, it uses the regular Host. Enable this mode only behind a trusted reverse proxy that overwrites forwarded headers instead of passing client-supplied values through.

Package manager sections

Each ecosystem contains the enabled flag and a repository list. The repository name becomes part of the OSA Proxy 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:

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

The scan-manifest and scan-package fields enable checks for manifests and downloaded artifacts. With scan-manifest: false, npm, NuGet, and PyPI metadata is not scanned, but links in responses are still rewritten to OSA Proxy. Support 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. For ivy with scan-package: true, explicitly select a layout: the built-in sbt-default or ivy-default pattern, or a custom pattern from the root layouts section. Docker supports auth-token-url, scan-container, and codescoring-pull-through-proxy.

Repository manager integration

For supported ecosystems, additional options are available for passing JFrog Artifactory repository and user context to OSA Proxy. The appropriate option depends on the Artifactory version and configuration. Vendor support provides details on request.

The artifactory and nexus sections periodically retrieve repository manager inventories and automatically create routes for selected ecosystems. Complete discovery, credentials, URL, repository context, and block response documentation is grouped into separate sections:

Verdict cache

Redis cache is disabled by default:

cache:
  judge:
    enabled: false
  redis:
    address: redis:6379

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
    tls:
      enabled: false
      ca-file: ""
      server-name: ""

Logging

The log level is configured with logging.level. Supported values are debug, info, warn, and error.

logging:
  level: info

Parameter reference

Root sections

Parameter	Purpose
`pypi`	PyPI repository settings.
`maven`	Maven-compatible repository settings for Maven and Gradle.
`ivy`	Ivy/SBT repository settings.
`nuget`	NuGet repository settings.
`npm`	npm repository settings.
`composer`	Composer/Packagist repository settings.
`cocoapods`	CocoaPods repository settings.
`swift`	Swift Package Manager repository settings.
`ruby`	RubyGems repository settings.
`conan`	Conan v2 repository settings.
`go`	Go module proxy settings.
`hex`	Hex repository settings for Elixir/Erlang.
`r`	CRAN/R repository settings.
`debian`	Debian repository settings.
`alpine`	Alpine APK repository settings.
`rpm`	RPM/YUM/DNF repository settings.
`docker`	Docker Registry API v2 settings.
`artifactory`	Automatic JFrog Artifactory repository discovery and routing.
`nexus`	Automatic Nexus Repository Manager 3 repository discovery and routing.
`codescoring`	CodeScoring connection and check behavior.
`admin`	Dedicated administration HTTP server settings (Admin API, Swagger UI).
`configuration-store`	Redis dynamic configuration storage.
`layouts`	Custom path layout templates for Ivy repositories.
`webhooks`	Outbound webhook notifications for file downloads and blocks.
`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 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`, `cocoapods`, `swift`, `ruby`, `conan`, `go`, `hex`	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`, `cocoapods`	Additional host -> registry map for packages that publish artifacts on multiple domains. For CocoaPods, it allows `source.http` URLs to be rewritten through OSA Proxy. See CocoaPods configuration.
`sumdb-registry`	`go`	Go checksum database URL, for example `https://sum.golang.org`, when SumDB requests should go through OSA Proxy.
`signing-private-key`	`hex`	Stable RSA private key in PEM format. Takes precedence over `signing-private-key-file`; the file is not read when both parameters are set.
`signing-private-key-file`	`hex`	Path to a stable RSA private key shared by all replicas. Used when `signing-private-key` is empty. One of the two parameters is required with `scan-manifest: true`.
`remove-blocked-versions`	`npm`, `nuget`, `pypi`, `swift`, `hex`	Removes blocked versions from metadata; defaults to `true`. For Swift, `false` adds `problem: 410`; for Hex, it keeps the release as `retired: security`. See Swift configuration and Hex configuration.
`distro`	`debian`, `alpine`	Distribution or branch name used when processing metadata and package paths.
`auth-token-url`	`docker`	Exact full token endpoint URL. OSA Proxy does not append `/token`; use `https://auth.docker.io/token` for Docker Hub. Omit it for registries without a Bearer token service.
`layout`	`ivy`	Layout pattern name (`sbt-default`, `ivy-default`, or a name from `layouts`). Required when `scan-package: true`.
`scan-container`	`docker`	Enables container image manifest evaluation in CodeScoring. Defaults to `true`. When `false`, manifests and layer downloads pass through without evaluation.
`codescoring-pull-through-proxy`	`docker`	Passes the proxy public URL and a short-lived bypass token to CodeScoring for reverse image pulls without recursive re-scanning. Defaults to `false`. Requires `codescoring.token`.

`file-type-filter`

Parameter	Purpose
`enabled`	Explicitly enables extension filtering. Only `true` activates it; extension lists by themselves do not.
`additional-allowed-extensions`	Adds extensions to the built-in ecosystem preset. Values can include or omit the leading dot and are normalized to lowercase.
`scanned-extensions`	Makes the handler treat files with these extensions as package artifacts for scanning and short-lived scan-result caching.

The filter applies only to non-Docker repositories. It is disabled unless enabled: true is set, including when the section is {} or either extension list is populated. When disabled, requests follow the normal handler rules.

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;
always allows checksum suffixes .sha256, .sha384, .sha512, .sha-256, .sha-384, .sha-512, .sha1, and .md5;
allows .metadata and .asc sidecars only when the base artifact is allowed;
immediately blocks all other package file requests before contacting the upstream registry or CodeScoring.

Built-in presets:

Ecosystem	Allowed extensions
`npm`	`.tgz`
`composer`, `cocoapods`	`.zip`, `.tar`, `.tgz`, `.tar.gz`, `.tar.bz2`, `.tar.xz`
`swift`	`.zip`
`pypi`	`.whl`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.zip`, `.egg`
`nuget`	`.nupkg`, `.snupkg`
`ruby`	`.gem`
`conan`	`.py`, `.tgz`
`go`	`.zip`
`hex`	`.tar`, `.tar.gz`
`r`	`.tar.gz`, `.tgz`, `.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`
`ivy`	Maven extensions plus `.tgz`, `.tar`, `.tar.bz2`, `.tar.xz`

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. It does not enable the filter or make the handler scan those files. 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:
        enabled: true
        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.

npm:
  enabled: true
  repository:
    - name: npm
      registry: https://registry.npmjs.org
      scan-package: true

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 enabled: true. For npm, only the built-in .tgz preset and applicable sidecars 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 upstream and CodeScoring are contacted.

npm:
  enabled: true
  repository:
    - name: npm
      registry: https://registry.npmjs.org
      scan-package: true
      file-type-filter:
        enabled: true

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:
        enabled: true
        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`	`strict_wait`	Global work mode: `warmup`, `spectator`, `moderate`, `strict`, `strict_wait`.
`osa-proxy-url`	Required when forwarded mode is disabled	Absolute HTTP(S) OSA Proxy URL used to generate and rewrite links.
`osa-proxy-url-from-forwarded-headers`	`false`	Builds the URL from `X-Forwarded-Proto` and `X-Forwarded-Host`. Use it when one instance is exposed through different URLs: package links in metadata and manifests will match the URL of the current network zone. Falls back to `https` and regular `Host`. Enable only behind a trusted reverse proxy.
`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`	`true`	Blocks downloads when CodeScoring returns an error or a package cannot be checked.
`block-message`	Not set	Custom block response text. If omitted or empty, OSA Proxy uses the standard message for the block reason.
`append-block-url-to-message`	`true`	Appends a link to the block reason to the custom message when CodeScoring provides one.
`legacy-judge`	`false`	Enables compatibility with Judge versions before `2026.20.0`. Use only for CodeScoring installations with an older Judge service version.
`stage`	`proxy`	Stage/context value passed to CodeScoring checks.
`block-status-code`	`403`	HTTP status code returned for blocked packages.
`judge-concurrency`	`16`	Limits parallel Judge requests. Lower values reduce simultaneous requests for large version lists and background cache refresh.
`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.
`redis-db`	Not set	Overrides `cache.redis.db` for verdict and handler caches.
`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.
`username`	Redis ACL username.
`password`	Redis password.
`db`	Redis database number.
`tls.enabled`	Enables TLS 1.2 or newer for Redis. Default is `false`; certificate verification is always enabled.
`tls.ca-file`	Optional path to an additional PEM CA bundle. Certificates are added to the system trust roots.
`tls.server-name`	Optional shared SNI and verification identity for Redis, Sentinel, and the discovered master. By default, each connection hostname is used.
`sentinel.enabled`	Enables Redis Sentinel; `address` may then be omitted.
`sentinel.master-name`	Sentinel master group name.
`sentinel.addresses`	Sentinel endpoints in `host:port` format.
`sentinel.username`	Sentinel ACL username.
`sentinel.password`	Separate Sentinel password.

Complete TLS, corporate CA, Docker Compose, and Helm configuration is documented in Redis and Caching Configuration.

`logging`

Parameter	Default	Purpose
`level`	`info`	Log level: `debug`, `info`, `warn`, `warning`, `error`. Unknown values are treated as `info`.

OSA Proxy writes JSON logs. Each inbound request produces one info completion event named http request completed with component, method, bounded route, request path without query parameters, status, status_class, outcome, and duration_ms. When tracing context is available, the event also contains trace_id and span_id.

`admin`

Parameter	Default	Purpose
`enabled`	`false`	Enables the dedicated HTTP administration listener.
`address`	`127.0.0.1:8081`	Network address and port for administrative requests.
`write-timeout`	`2m`	Write timeout for administrative responses.
`token-hash`	`""`	Lower-case hex SHA-256 hash of the administrative Bearer token. To use the `OSA_PROXY_ADMIN_TOKEN_HASH` environment variable, set this field to `${OSA_PROXY_ADMIN_TOKEN_HASH:}`.

For details, see Admin API and management.

`configuration-store`

Parameter	Default	Purpose
`enabled`	`false`	Enables the centralized dynamic configuration store in Redis.
`backend`	`redis`	Storage backend (only `redis` is currently supported).
`deployment-identity`	`""`	Cluster or deployment identifier (required when `enabled: true`).
`replica-identity`	Hostname, then generated process identity	Identity used for replica heartbeat and lease records. Helm injects the pod name through `OSA_PROXY_REPLICA_IDENTITY`.
`mode`	`standalone`	Redis operational mode: `standalone` or `sentinel`.
`accept-unsafe-durability`	`false`	Allows starting without verified Redis persistence (`noeviction` policy and persistence).
`history-limit`	`20`	Maximum number of retained configuration revisions.
`poll-interval`	`30s`	Polling interval for detecting new configuration revisions.
`operation-timeout`	`5s`	Timeout for store operations in Redis.
`heartbeat-interval`	`10s`	Replica heartbeat publication interval.
`lease-ttl`	`30s`	Replica lease duration in the active fleet registry.
`redis-db`	`null`	Logical database override when inheriting the connection from `cache.redis`.
`redis`	`{}`	Dedicated Redis connection configuration (same fields as `cache.redis`). When omitted, inherited from `cache.redis`.

For details, see Admin API and management.

`layouts`

The root layouts section contains a map of custom path layouts for Ivy (sbt) repositories. The map key is the layout name, and the value is the path pattern string:

layouts:
  custom-layout: "[organisation]/[module]/[revision]/[type]s/[artifact]-[revision].[ext]"

For details, see Ivy configuration.

`webhooks`

The webhooks section defines outbound HTTP POST event notifications:

Parameter	Default	Purpose
`name`	`""`	Human-readable subscription name.
`url`	—	HTTP(S) URL of the webhook receiver. Required parameter.
`token_env`	`""`	Name of the environment variable containing the receiver authorization token (sent in `X-CodeScoring-Authentication`).
`enabled`	`true`	Whether the subscription is active.
`events`	—	Event list: `file_downloaded`, `scanned_file_downloaded`, `file_blocked`.
`repositories`	`[]`	Repository names to filter by (empty means all non-Docker repositories).
`timeout`	`3s`	Timeout for a single POST request to the receiver.
`buffer_size`	`256`	In-memory event queue size for this subscription.

For details, see Webhook configuration.

Was this page helpful?

#Service configuration

#Configuration example

#codescoring section

#Building URLs from forwarded headers

#Package manager sections

#Ecosystem-specific options

#Repository manager integration

#Verdict cache

#Logging

#Parameter reference

#Root sections

#Common package manager parameters

#Repository-specific parameters

#file-type-filter

#npm behavior example

#codescoring

#codescoring.resilience.retry

#codescoring.resilience.circuit-breaker

#http.server

#http.client

#cache.judge

#cache.redis

#logging

#admin

#configuration-store

#layouts

#webhooks