Summary
In pull-through cache mode, Distribution discovers token authentication endpoints by parsing WWW-Authenticate challenges from an upstream registry but fails to validate that the bearer realm URL belongs to the intended upstream host.
An attacker controlling or intercepting the upstream connection can redirect credential requests to an attacker-controlled realm URL, causing Distribution to send upstream credentials to an unauthorized server.
Affected context
This vulnerability appears in Distribution deployments configured as a pull-through cache that:
- Rely on an upstream container registry requiring token-based authentication
- Parse WWW-Authenticate headers from the upstream to discover token endpoints
- Automatically follow bearer realm URLs without constraining them to the upstream registry host
It primarily affects environments where Distribution is granted credentials for an upstream registry and where the network path to that upstream can be influenced or controlled by an attacker.
Exploit preconditions
- Attack surface: The HTTP(S) communication path between Distribution (as a pull-through cache) and its configured upstream registry.
- Required access:
- Either control over the upstream registry configuration, or
- A man-in-the-middle (MitM) position on the connection to the upstream registry.
- Trigger point:
- The upstream registry responds with a WWW-Authenticate: Bearer challenge whose
realmparameter points to an attacker-controlled URL. - Distribution subsequently contacts this realm URL and sends configured upstream credentials via basic authentication.
- Why exploitation is possible:
- The implementation trusts the
realmURL from the bearer challenge without verifying that it matches or is constrained to the expected upstream registry host or a trusted domain. - As a result, Distribution performs outbound requests with sensitive credentials to arbitrary endpoints chosen by the attacker.
Why this happens
The root cause lies in insecure handling of metadata-driven endpoint discovery for authentication.
Distribution parses WWW-Authenticate bearer challenges from the upstream registry and directly uses the realm field as the token endpoint without verifying that the host component aligns with the expected upstream registry or a trusted set of domains.
This behavior matches CWE-918: Server-Side Request Forgery (SSRF), where unvalidated user- or attacker-influenced URLs are used for server-initiated HTTP requests.
In this case, the SSRF is compounded by credential handling: the server not only reaches out to an attacker-controlled endpoint but also attaches upstream credentials, enabling credential exfiltration.
Potential impact
- Theft of upstream registry credentials, including potentially highly privileged tokens or passwords.
- Unauthorized access to container images and associated metadata hosted on the upstream registry.
- Lateral movement into other systems that trust or reuse the exfiltrated credentials.
- Abuse of stolen credentials to tamper with images (e.g., replace, delete, or push malicious images).
- Expanded attack surface for further SSRF attempts against internal services if the attacker-controlled realm URL targets private network addresses.
General mitigation guidance
Mitigation should focus on constraining where authentication and token discovery requests can be sent and reducing the privilege of any credentials involved.
Useful defensive patterns include:
- Host validation and pinning: Only accept WWW-Authenticate bearer realm URLs whose host and scheme match, or are strictly derived from, the configured upstream registry or a curated allowlist of trusted domains.
- Normalization and strict parsing: Normalize and parse realm URLs before use, rejecting malformed or unexpected schemes and ports.
- Least-privilege credentials: Configure upstream credentials with minimal required scope (read-only where possible) and avoid reusing highly privileged or long-lived tokens.
- Separation of duties: Use distinct credentials for the pull-through cache that are not shared with other automation or CI/CD components.
- Network-level controls: Apply egress filtering, DNS policies, or proxy rules so that the Distribution service cannot initiate arbitrary outbound connections, especially to untrusted or internal-only IP ranges.
- Defense-in-depth logging and monitoring: Log token discovery and outbound auth requests to detect anomalous destinations and unexpected realm hosts.
How teams detect issues like this
Effective detection involves examining both code and operational behavior:
- Static analysis and code review:
- Flag patterns where external challenge headers (e.g., WWW-Authenticate) are parsed and their URLs are used directly without host validation.
- Identify outbound HTTP client calls that accept arbitrary or header-derived URLs, especially where authentication headers or credentials are attached.
- Review authentication flows involving bearer token discovery to ensure domain pinning and scheme validation are in place.
- Configuration and policy checks:
- Enforce security policies requiring domain allowlists for all dynamic token or metadata endpoints.
- Validate that upstream registry definitions include expected token endpoints or domain constraints.
- Runtime monitoring:
- Monitor Distribution logs for outbound requests to unexpected hosts during token acquisition or authentication flows.
- Use network monitoring or egress firewalls to detect or block requests from Distribution instances to unapproved external domains.
- Automated tooling:
- Integrate SAST tools capable of recognizing SSRF patterns around HTTP client usage and header-derived URLs.
- Add CI checks that scan for use of realm or Location header values without validation.

