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

The allow_private_registry_fetch flag is all-or-nothing: enabling it lifts
the registry SSRF guard for every non-routable range at once, including the
169.254.169.254 cloud-metadata endpoint. Enabling it for a localhost dev
registry therefore also re-opens the cloud-metadata SSRF vector.

Document this sharp edge in the config doc comment, docs/configuration.md,
and docs/registries.md, plus note the flag only takes effect on daemon
(re)start / config reload.

Related #745
Related MCP-3206

Author: Dumbris

docs/configuration.md

@@ -985,6 +985,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):

docs/registries.md

@@ -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": "…" }`.

internal/config/config.go

@@ -212,8 +212,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.

oas/docs.go

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