Skip to content

docs: clarify allow_private_registry_fetch is a blanket SSRF opt-out (MCP-3206) #751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Dumbris wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify allow_private_registry_fetch is a blanket SSRF opt-out (MCP-3206) #751

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -942,6 +942,15 @@ intentionally run a trusted registry mirror on an internal/private address:
{ "allow_private_registry_fetch": true }
```

> ⚠️ **The opt-out is blanket (all-or-nothing).** Setting it `true` lifts the
> guard for **every** non-routable range at once — loopback, RFC1918/CGNAT
> private, link-local **and** the `169.254.169.254` cloud-metadata endpoint.
> There is no way to allow only loopback: enabling it for a localhost dev
> registry also re-opens the cloud-metadata SSRF vector (e.g.
> `registry add-source https://169.254.169.254/...` will then succeed). Enable
> it only for trusted local/dev use, ideally on hosts with no cloud-metadata
> exposure. The flag takes effect only on daemon (re)start / config reload.
Default `false` (secure). See [Registries Documentation](registries.md#adding-your-own-registry-source).

**Default Registries** (shipped built-in, no configuration required):
Expand Down
9 changes: 9 additions & 0 deletions docs/registries.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,15 @@ into a request-forgery vector against internal services:
rebinding. The official protocol's cursor-follow pagination is also pinned to
the configured host so a hostile `nextCursor` cannot redirect the request.

The top-level `allow_private_registry_fetch` flag (default `false`) is a **blanket
opt-out**: setting it `true` disables this guard for **every** non-routable range
at once — loopback, RFC1918/CGNAT private, link-local **and** the
`169.254.169.254` cloud-metadata endpoint. It cannot be scoped to loopback only,
so enabling it for a localhost dev registry also re-opens the cloud-metadata SSRF
vector; enable it only for trusted local/dev use, ideally on hosts with no
cloud-metadata exposure. The change takes effect on daemon (re)start / config
reload. See [Configuration](configuration.md#registries).

Equivalent surfaces:

- **REST:** `POST /api/v1/registries` with `{ "url": "https://…", "protocol": "…", "id": "…", "name": "…" }`.
Expand Down
12 changes: 10 additions & 2 deletions internal/config/config.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,8 +182,16 @@ type Config struct {
// resolves to — a non-routable address (loopback, RFC1918/CGNAT private,
// link-local incl. the 169.254.169.254 cloud-metadata endpoint), so a
// malicious or typo'd registry source cannot turn the daemon into a
// request-forgery vector against internal services. Set true ONLY when you
// intentionally run a trusted registry mirror on an internal/private address.
// request-forgery vector against internal services.
//
// This opt-out is BLANKET (all-or-nothing): setting it true disables the
// guard for EVERY non-routable range at once — loopback, RFC1918/CGNAT
// private, link-local AND the 169.254.169.254 cloud-metadata endpoint. There
// is no way to allow only loopback; enabling it for a localhost dev registry
// also re-opens the cloud-metadata SSRF vector. Set true ONLY when you
// intentionally run a trusted registry mirror on an internal/private address,
// ideally on a host with no cloud-metadata exposure. The change takes effect
// only on daemon (re)start or config reload.
AllowPrivateRegistryFetch bool `json:"allow_private_registry_fetch,omitempty" mapstructure:"allow-private-registry-fetch"`

// Deprecated: Features flags are unused and have no runtime effect. Kept for backward compatibility.
Expand Down
2 changes: 1 addition & 1 deletion oas/docs.go
View file
Open in desktop

Large diffs are not rendered by default.

12 changes: 10 additions & 2 deletions oas/swagger.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,16 @@ components:
resolves to — a non-routable address (loopback, RFC1918/CGNAT private,
link-local incl. the 169.254.169.254 cloud-metadata endpoint), so a
malicious or typo'd registry source cannot turn the daemon into a
request-forgery vector against internal services. Set true ONLY when you
intentionally run a trusted registry mirror on an internal/private address.
request-forgery vector against internal services.

This opt-out is BLANKET (all-or-nothing): setting it true disables the
guard for EVERY non-routable range at once — loopback, RFC1918/CGNAT
private, link-local AND the 169.254.169.254 cloud-metadata endpoint. There
is no way to allow only loopback; enabling it for a localhost dev registry
also re-opens the cloud-metadata SSRF vector. Set true ONLY when you
intentionally run a trusted registry mirror on an internal/private address,
ideally on a host with no cloud-metadata exposure. The change takes effect
only on daemon (re)start or config reload.
type: boolean
allow_server_add:
type: boolean
Expand Down
Loading