feat(fetch): add allowed_domains and blocked_domains filters

Lets operators restrict the fetch tool to a curated set of hosts (or

deny a few sensitive ones), mirroring Anthropic's web-fetch tool and

Claude Code's WebFetch permission model. Patterns match the host and

any subdomain by default; a leading dot restricts to strict subdomains.

The check runs before any network call (including robots.txt) so blocked

URLs never leak DNS or TCP traffic.

Assisted-By: docker-agent

Author: dgageot

agent-schema.json

@@ -1319,6 +1319,28 @@
           "description": "Timeout in seconds for the fetch tool",
           "minimum": 1
         },
+        "allowed_domains": {
+          "type": "array",
+          "description": "Allow-list of domains the fetch tool is permitted to fetch (only valid for type 'fetch'). A pattern matches the host exactly (case-insensitive) and any of its subdomains; e.g. 'example.com' matches 'example.com' and 'docs.example.com' but not 'badexample.com'. A leading dot ('.example.com') restricts the match to strict subdomains. Mutually exclusive with 'blocked_domains'.",
+          "items": {
+            "type": "string"
+          },
+          "examples": [
+            ["docker.com", "docs.docker.com"],
+            ["github.com", "raw.githubusercontent.com"]
+          ]
+        },
+        "blocked_domains": {
+          "type": "array",
+          "description": "Deny-list of domains the fetch tool is forbidden to fetch (only valid for type 'fetch'). Uses the same matching rules as 'allowed_domains'. Mutually exclusive with 'allowed_domains'.",
+          "items": {
+            "type": "string"
+          },
+          "examples": [
+            ["internal.example.com"],
+            ["169.254.169.254"]
+          ]
+        },
         "url": {
           "type": "string",
           "description": "URL for the a2a or openapi tool",

docs/tools/fetch/index.md

@@ -28,9 +28,21 @@ toolsets:
 
 ### Options
 
-| Property  | Type | Default | Description                                                       |
-| --------- | ---- | ------- | ----------------------------------------------------------------- |
-| `timeout` | int  | `30`    | Default request timeout in seconds (overridable per tool call).   |
+| Property          | Type           | Default | Description                                                                                                                                                                                                                                                                                                                  |
+| ----------------- | -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `timeout`         | int            | `30`    | Default request timeout in seconds (overridable per tool call).                                                                                                                                                                                                                                                              |
+| `allowed_domains` | array[string]  | _none_  | Allow-list of hosts the tool may fetch. When set, every URL whose host is **not** in the list is rejected before any network call is made. Mutually exclusive with `blocked_domains`.                                                                                                                                        |
+| `blocked_domains` | array[string]  | _none_  | Deny-list of hosts the tool must not fetch. URLs whose host matches one of these patterns are rejected before any network call (including `robots.txt`) is made. Mutually exclusive with `allowed_domains`.                                                                                                                  |
+
+### Domain matching
+
+Domain patterns in `allowed_domains` and `blocked_domains` use the following rules (case-insensitive):
+
+- **Bare domain** — `example.com` matches the host `example.com` _and_ any subdomain such as `docs.example.com`. It does **not** match unrelated hosts that share a suffix (e.g. `badexample.com`).
+- **Leading dot** — `.example.com` matches **only** strict subdomains (`docs.example.com`, `a.b.example.com`), not the apex `example.com`.
+- **IP literal** — IP addresses are matched exactly (`169.254.169.254`).
+
+The lists are mutually exclusive: a single fetch toolset may set either `allowed_domains` or `blocked_domains`, but not both.
 
 ### Custom Timeout
 
@@ -40,6 +52,27 @@ toolsets:
     timeout: 60
 ```
 
+### Restrict to specific domains
+
+```yaml
+toolsets:
+  - type: fetch
+    allowed_domains:
+      - docker.com          # docker.com and *.docker.com
+      - github.com          # github.com and *.github.com
+      - .githubusercontent.com  # only subdomains, e.g. raw.githubusercontent.com
+```
+
+### Block sensitive hosts
+
+```yaml
+toolsets:
+  - type: fetch
+    blocked_domains:
+      - 169.254.169.254       # cloud metadata endpoint
+      - internal.example.com  # internal corporate hostnames
+```
+
 ## Tool Interface
 
 The toolset exposes a single tool, `fetch`, with the following parameters:

examples/fetch_domain_filtering.yaml

@@ -0,0 +1,41 @@
+#!/usr/bin/env docker agent run
+
+# Demonstrates domain filtering for the fetch tool. The agent is only allowed
+# to fetch URLs whose host matches one of the entries in `allowed_domains`
+# (the host itself or any subdomain). Use `blocked_domains` instead to keep
+# fetch open by default while denying specific hosts.
+
+agents:
+  root:
+    model: anthropic/claude-sonnet-4-5
+    description: An agent restricted to Docker and GitHub documentation.
+    instruction: |
+      You are a documentation assistant. You may only fetch pages from the
+      docker.com and github.com families of domains. If asked about an
+      external resource, politely refuse and suggest a search instead.
+    toolsets:
+      - type: fetch
+        # Each entry matches the bare host AND any subdomain.
+        # Example: "docker.com" matches docker.com AND docs.docker.com.
+        # Use ".github.com" to match strict subdomains only.
+        allowed_domains:
+          - docker.com
+          - github.com
+          - raw.githubusercontent.com
+
+  # Alternative: keep fetch open but deny specific hosts (e.g. cloud
+  # metadata endpoints, internal services). Switch the active agent to
+  # `safe_fetch` with `-a safe_fetch` to try this variant.
+  safe_fetch:
+    model: anthropic/claude-sonnet-4-5
+    description: An agent that can fetch the open web except a few sensitive hosts.
+    instruction: |
+      You are a research assistant. Use the fetch tool to gather information
+      from the public web. Some hosts are blocked for safety; if a fetch is
+      rejected, do not retry and explain the situation to the user.
+    toolsets:
+      - type: fetch
+        blocked_domains:
+          - 169.254.169.254     # cloud instance metadata
+          - 100.100.100.200     # alibaba/oracle metadata
+          - metadata.google.internal

pkg/config/latest/types.go

@@ -816,6 +816,18 @@ type Toolset struct {
 	// For the `fetch` tool
 	Timeout int `json:"timeout,omitempty"`
 
+	// For the `fetch` tool - allow-list of domains the tool is permitted to fetch.
+	// A pattern matches the host exactly (case-insensitive) and any of its subdomains;
+	// e.g. "example.com" matches "example.com" and "docs.example.com" but not
+	// "badexample.com". A leading dot (".example.com") restricts the match to
+	// strict subdomains. Mutually exclusive with `blocked_domains`.
+	AllowedDomains []string `json:"allowed_domains,omitempty" yaml:"allowed_domains,omitempty"`
+
+	// For the `fetch` tool - deny-list of domains the tool is forbidden to fetch.
+	// Uses the same matching rules as `allowed_domains`. Mutually exclusive with
+	// `allowed_domains`.
+	BlockedDomains []string `json:"blocked_domains,omitempty" yaml:"blocked_domains,omitempty"`
+
 	// For the `rag` tool
 	RAGConfig *RAGConfig `json:"rag_config,omitempty" yaml:"rag_config,omitempty"`
 

pkg/config/latest/validate.go

@@ -79,6 +79,15 @@ func (t *Toolset) validate() error {
 	if len(t.FileTypes) > 0 && t.Type != "lsp" {
 		return errors.New("file_types can only be used with type 'lsp'")
 	}
+	if len(t.AllowedDomains) > 0 && t.Type != "fetch" {
+		return errors.New("allowed_domains can only be used with type 'fetch'")
+	}
+	if len(t.BlockedDomains) > 0 && t.Type != "fetch" {
+		return errors.New("blocked_domains can only be used with type 'fetch'")
+	}
+	if len(t.AllowedDomains) > 0 && len(t.BlockedDomains) > 0 {
+		return errors.New("allowed_domains and blocked_domains are mutually exclusive")
+	}
 	if len(t.Models) > 0 && t.Type != "model_picker" {
 		return errors.New("models can only be used with type 'model_picker'")
 	}

pkg/config/latest/validate_test.go

@@ -217,6 +217,106 @@ agents:
 	}
 }
 
+func TestToolset_Validate_Fetch_Domains(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name    string
+		config  string
+		wantErr string
+	}{
+		{
+			name: "fetch with allowed_domains",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: fetch
+        allowed_domains:
+          - docker.com
+          - github.com
+`,
+			wantErr: "",
+		},
+		{
+			name: "fetch with blocked_domains",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: fetch
+        blocked_domains:
+          - 169.254.169.254
+`,
+			wantErr: "",
+		},
+		{
+			name: "fetch with both is rejected",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: fetch
+        allowed_domains:
+          - docker.com
+        blocked_domains:
+          - example.com
+`,
+			wantErr: "allowed_domains and blocked_domains are mutually exclusive",
+		},
+		{
+			name: "allowed_domains on non-fetch toolset is rejected",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: shell
+        allowed_domains:
+          - docker.com
+`,
+			wantErr: "allowed_domains can only be used with type 'fetch'",
+		},
+		{
+			name: "blocked_domains on non-fetch toolset is rejected",
+			config: `
+version: "8"
+agents:
+  root:
+    model: "openai/gpt-4"
+    toolsets:
+      - type: shell
+        blocked_domains:
+          - docker.com
+`,
+			wantErr: "blocked_domains can only be used with type 'fetch'",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			var cfg Config
+			err := yaml.Unmarshal([]byte(tt.config), &cfg)
+
+			if tt.wantErr != "" {
+				require.Error(t, err)
+				require.Contains(t, err.Error(), tt.wantErr)
+			} else {
+				require.NoError(t, err)
+			}
+		})
+	}
+}
+
 func TestToolset_Validate_MCP_RemoteOAuth_CallbackRedirectURL(t *testing.T) {
 	t.Parallel()
 

pkg/teamloader/registry.go

@@ -291,6 +291,12 @@ func createFetchTool(_ context.Context, toolset latest.Toolset, _ string, _ *con
 		timeout := time.Duration(toolset.Timeout) * time.Second
 		opts = append(opts, builtin.WithTimeout(timeout))
 	}
+	if len(toolset.AllowedDomains) > 0 {
+		opts = append(opts, builtin.WithAllowedDomains(toolset.AllowedDomains))
+	}
+	if len(toolset.BlockedDomains) > 0 {
+		opts = append(opts, builtin.WithBlockedDomains(toolset.BlockedDomains))
+	}
 	return builtin.NewFetchTool(opts...), nil
 }