fix(openapi): block remote specs from declaring loopback servers (#83)

Defense in depth on top of the runtime URL revalidation that landed in
5b16e43 (GHSA-39j6-4867-gg4w). The runtime check rejects the request
once it's already on its way to the loopback interface, but the
malicious tools are still registered, still surfaced to the LLM, and
still try to fire on every invocation. Better to refuse them at
conversion time so they never enter the registry in the first place.

Rule: when an OpenAPI spec is fetched from a non-loopback URL, its
``servers[0].url`` must not be a literal loopback address. Anyone
running their own UTCP agent locally pointing at a localhost OpenAPI
spec stays unaffected — the source URL is itself loopback in that
case. And an operator who explicitly trusts a remote spec's loopback
server can still override via the call template's ``base_url`` field
(handled by the existing override-takes-precedence branch).

Added ``is_loopback_url`` helper to ``_security.py`` and four new
converter test cases covering: rejection of remote→loopback,
allowance of loopback→loopback, allowance of explicit override, and
the normal remote→remote case.

106/106 utcp-http tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: h3xxit

plugins/communication_protocols/http/src/utcp_http/_security.py

@@ -64,6 +64,35 @@ def is_secure_url(url: str) -> bool:
         return False
 
 
+def is_loopback_url(url: str) -> bool:
+    """Return True if ``url``'s host is a literal loopback address.
+
+    Used by the OpenAPI converter to detect the SSRF case where a remote spec
+    declares ``servers: [{ url: "http://127.0.0.1:..." }]`` to redirect tool
+    invocation at the host running the agent. Hostname-based — not a string
+    prefix — so ``http://localhost.evil.com`` returns False.
+    """
+    if not isinstance(url, str) or not url:
+        return False
+
+    try:
+        parsed = urlparse(url)
+    except ValueError:
+        return False
+
+    host = (parsed.hostname or "").lower()
+    if not host:
+        return False
+
+    if host in _LOOPBACK_HOSTNAMES:
+        return True
+
+    try:
+        return ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
 def ensure_secure_url(url: str, *, context: Optional[str] = None) -> None:
     """Raise ``ValueError`` if ``url`` is not safe to fetch.
 

plugins/communication_protocols/http/src/utcp_http/openapi_converter.py

@@ -27,6 +27,7 @@
 from utcp.data.utcp_manual import UtcpManual
 from utcp.data.tool import Tool, JsonSchema
 from utcp_http.http_call_template import HttpCallTemplate
+from utcp_http._security import is_loopback_url
 
 class OpenApiConverter:
     """REQUIRED
@@ -148,9 +149,40 @@ def convert(self) -> UtcpManual:
 
         # Determine base URL: override > servers > spec_url > fallback
         if self._base_url_override:
+            # Explicit override from UTCP config — caller has accepted the
+            # trust decision, no further validation here.
             base_url = self._base_url_override
         elif self.spec.get("servers"):
             base_url = self.spec["servers"][0].get("url", "/")
+
+            # Defense in depth against issue #83 / GHSA-39j6-4867-gg4w:
+            # a remote OpenAPI spec must not be allowed to redirect tool
+            # invocation at the agent's own loopback interface (cloud
+            # metadata, internal admin panels, etc.). The runtime check in
+            # call_tool already blocks the request, but rejecting at
+            # conversion time produces a clearer error and prevents the
+            # malicious tools from ever entering the registry.
+            #
+            # We only reject when the *spec was fetched from a non-loopback
+            # source*. A user pointing the converter at their own
+            # localhost OpenAPI spec is allowed to declare loopback
+            # servers, and an explicit ``base_url`` override always wins
+            # (handled above).
+            if (
+                self.spec_url
+                and not is_loopback_url(self.spec_url)
+                and is_loopback_url(base_url)
+            ):
+                raise ValueError(
+                    "Security error: OpenAPI spec fetched from "
+                    f"{self.spec_url!r} declares a loopback server URL "
+                    f"({base_url!r}). A remote spec is not allowed to "
+                    "redirect tool calls at the agent's own loopback "
+                    "interface — this is the SSRF pattern from "
+                    "GHSA-39j6-4867-gg4w. If you trust this spec, set "
+                    "the call template's ``base_url`` override "
+                    "explicitly to bypass this check."
+                )
         elif self.spec_url:
             parsed_url = urlparse(self.spec_url)
             base_url = f"{parsed_url.scheme}://{parsed_url.netloc}"

plugins/communication_protocols/http/tests/test_security.py

@@ -65,3 +65,99 @@ def test_ensure_secure_url_raises_with_context() -> None:
 def test_ensure_secure_url_passes_silently_for_valid_url() -> None:
     # Should not raise.
     ensure_secure_url("https://example.com/v1/tool", context="manual discovery")
+
+
+# --- is_loopback_url --------------------------------------------------------
+
+from utcp_http._security import is_loopback_url
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "http://localhost/x",
+        "http://localhost:9090/x",
+        "http://127.0.0.1/x",
+        "http://127.0.0.1:8080/x",
+        "http://[::1]:9090/x",
+        "https://localhost/x",
+    ],
+)
+def test_loopback_urls_detected(url: str) -> None:
+    assert is_loopback_url(url) is True
+
+
+@pytest.mark.parametrize(
+    "url",
+    [
+        "https://example.com/x",
+        "http://10.0.0.5/x",
+        "http://example.com/x",
+        # The historical hostname-prefix bypass must NOT register as loopback.
+        "http://localhost.evil.com/x",
+        "http://127.0.0.1.attacker.example/x",
+        "",
+        "not-a-url",
+    ],
+)
+def test_non_loopback_urls_rejected(url: str) -> None:
+    assert is_loopback_url(url) is False
+
+
+# --- OpenAPI converter SSRF defense -----------------------------------------
+
+from utcp_http.openapi_converter import OpenApiConverter
+
+
+def _spec_with_server(server_url: str) -> dict:
+    return {
+        "openapi": "3.0.0",
+        "info": {"title": "T"},
+        "servers": [{"url": server_url}],
+        "paths": {
+            "/x": {"get": {"operationId": "x", "responses": {"200": {"description": "ok"}}}}
+        },
+    }
+
+
+def test_converter_rejects_loopback_server_from_remote_spec() -> None:
+    """A remote (non-loopback) OpenAPI spec must not redirect at loopback."""
+    converter = OpenApiConverter(
+        _spec_with_server("http://127.0.0.1:9090"),
+        spec_url="https://attacker.example/openapi.json",
+    )
+    with pytest.raises(ValueError) as exc:
+        converter.convert()
+    assert "loopback" in str(exc.value).lower()
+    assert "GHSA-39j6-4867-gg4w" in str(exc.value)
+
+
+def test_converter_allows_loopback_server_from_loopback_spec() -> None:
+    """Local-dev case: spec from localhost can declare a localhost server."""
+    converter = OpenApiConverter(
+        _spec_with_server("http://127.0.0.1:9090"),
+        spec_url="http://localhost:8000/openapi.json",
+    )
+    manual = converter.convert()
+    assert len(manual.tools) == 1
+
+
+def test_converter_allows_explicit_base_url_override() -> None:
+    """If the user explicitly overrides base_url, we trust the user."""
+    converter = OpenApiConverter(
+        _spec_with_server("http://127.0.0.1:9090"),
+        spec_url="https://attacker.example/openapi.json",
+        base_url="http://127.0.0.1:9090",
+    )
+    manual = converter.convert()
+    assert len(manual.tools) == 1
+
+
+def test_converter_allows_remote_server_from_remote_spec() -> None:
+    """Normal case: remote spec, remote server."""
+    converter = OpenApiConverter(
+        _spec_with_server("https://api.example.com"),
+        spec_url="https://api.example.com/openapi.json",
+    )
+    manual = converter.convert()
+    assert len(manual.tools) == 1