Merge pull request #50 from MaazAhmed47/codex/outbound-destination-guard-phase1

fix: harden outbound destination validation

Author: MaazAhmed47

.env.example

@@ -56,7 +56,8 @@
 # ENABLE_API_DOCS=false
 
 # SSRF-oriented outbound URL checks for MCP discovery/calls and SIEM tests.
-# Defaults on in production. Keep private outbound disabled for shared hosted demos.
+# Defaults on in production and whenever a supported hosted marker is present.
+# Keep private outbound disabled for shared hosted demos.
 # INTERLOCK_PROTECT_OUTBOUND_URLS=true
 # INTERLOCK_ALLOW_PRIVATE_OUTBOUND=false
 

README.md

@@ -1165,7 +1165,10 @@ Production/hosted deployments should set:
 - `INTERLOCK_ENV=production`
 - explicit `ALLOWED_ORIGINS` for the dashboard origin; `*` is rejected in production
 - `ENABLE_API_DOCS=false` unless the API docs are intentionally gated elsewhere
-- default outbound URL protection enabled; only set `INTERLOCK_ALLOW_PRIVATE_OUTBOUND=true` for controlled local/private deployments
+- outbound URL protection is mandatory in production; private destinations are rejected
+- the bundled offline Compose proof uses a narrow `mcp-mock` allowance and does not enable a general private-destination override
+- enforce a production egress proxy or firewall because application-level hostname checks are not a complete DNS-rebinding defense
+- guarded HTTP clients ignore ambient proxy variables; a production proxy must be an explicit future design or a transparent enforced network boundary
 
 Secrets hygiene:
 
@@ -1202,17 +1205,35 @@ Common variables:
 | `DATABASE_URL` | Optional Postgres connection string for hosted/production deployments. |
 | `REDIS_URL` | Optional Redis connection string for shared rate limits across workers/pods. |
 | `FIREWALL_DB_PATH` | Local SQLite path; defaults to `data/firewall.db`. |
-| `INTERLOCK_ENV` | Set to `production` for hosted deployments; local/dev keeps permissive defaults. |
+| `INTERLOCK_ENV` | Set to `production` for hosted deployments; local/dev is permissive only when no supported hosted-platform marker is present. |
 | `ALLOWED_ORIGINS` | Required in production; comma-separated dashboard origins for CORS. |
 | `ENABLE_API_DOCS` | Defaults to off in production and on in local/dev. |
-| `INTERLOCK_PROTECT_OUTBOUND_URLS` | Enables SSRF-oriented outbound URL checks; defaults on in production. |
-| `INTERLOCK_ALLOW_PRIVATE_OUTBOUND` | Override for controlled private/local outbound URLs; avoid on shared hosted deployments. |
+| `INTERLOCK_PROTECT_OUTBOUND_URLS` | Enables outbound URL checks in local/dev; protection is mandatory in production and hosted-platform environments. |
+| `INTERLOCK_ALLOW_PRIVATE_OUTBOUND` | Legacy local-only compatibility setting; it cannot disable the shared guard or permit private production egress. |
+| `INTERLOCK_OFFLINE_DEMO` | Enables the non-production Compose proof profile, including only the exact `mcp-mock` outbound allowance. |
 | `MCP_UPSTREAM_AUTH_ALLOWED_ENV_VARS` | Comma-separated allowlist of environment-variable names that registered MCP servers may use for upstream auth; default deny. |
 | `SHADOW_SCAN_ENABLED` | Opt-in background shadow MCP probing. |
 | `SHADOW_SCAN_INTERVAL` | Shadow scan interval in seconds. |
 
 ---
 
+### Outbound destination limitation
+
+Interlock rejects non-global literal addresses and any hostname whose checked
+A/AAAA answer includes a non-global address when outbound protection is active.
+The check fails closed on resolution errors and covers configurable MCP, probe,
+readback, webhook, SIEM, shadow-scan, and JWKS destinations.
+
+hostname resolution rejection is a partial mitigation; DNS rebinding requires connection pinning or an enforced egress proxy/firewall.
+
+The current HTTP transports resolve hostnames again when connecting. Production
+deployments must therefore enforce destination policy at the network boundary;
+see [Outbound destination security](docs/outbound-destination-security.md).
+Guarded clients use `trust_env=False`, so ambient `HTTP_PROXY`, `HTTPS_PROXY`,
+`ALL_PROXY`, and `NO_PROXY` settings are unsupported for these paths.
+
+---
+
 ## Current State
 
 Interlock is pre-release and intended for self-hosted or isolated non-production evaluation.

config.py

@@ -256,15 +256,19 @@ def cors_allowed_origins() -> list[str]:
 
 def protect_outbound_urls() -> bool:
     """Enable SSRF-oriented outbound URL validation."""
+    if is_production() or is_hosted():
+        return True
     raw = os.getenv("INTERLOCK_PROTECT_OUTBOUND_URLS")
     if raw is not None:
         return _truthy(raw)
-    return is_production()
+    return False
 
 
 def allow_private_outbound_urls() -> bool:
-    """Emergency/local override for private outbound URLs."""
-    return _truthy(os.getenv("INTERLOCK_ALLOW_PRIVATE_OUTBOUND"))
+    """Legacy local-only switch; never permits private production egress."""
+    return not is_production() and _truthy(
+        os.getenv("INTERLOCK_ALLOW_PRIVATE_OUTBOUND")
+    )
 
 
 def offline_demo_enabled() -> bool:

core/admin.py

@@ -15,11 +15,13 @@
 from typing import Optional, List, Dict, Any, Set
 
 import jwt
+import httpx
 
 from fastapi import APIRouter, Header, HTTPException
 from pydantic import BaseModel, Field
 
 from core import db
+from core.url_security import OutboundUrlRejected, ensure_safe_outbound_url
 
 logger = logging.getLogger("interlock.admin")
 router = APIRouter(prefix="/admin", tags=["admin"])
@@ -46,6 +48,38 @@
 _OIDC_LAST_CONFIG_ERROR_AT = 0.0
 
 
+class _GuardedPyJWKClient(jwt.PyJWKClient):
+    """PyJWT key selection with Interlock-controlled HTTP behavior."""
+
+    def fetch_data(self):
+        jwk_set = None
+        try:
+            canonical_url = ensure_safe_outbound_url(self.uri, context="OIDC JWKS")
+            with httpx.Client(
+                timeout=self.timeout,
+                follow_redirects=False,
+                trust_env=False,
+            ) as client:
+                response = client.get(canonical_url, headers=self.headers)
+                if response.is_redirect:
+                    raise jwt.exceptions.PyJWKClientConnectionError(
+                        "OIDC JWKS redirect was rejected"
+                    )
+                response.raise_for_status()
+                jwk_set = response.json()
+        except jwt.exceptions.PyJWKClientConnectionError:
+            raise
+        except (OutboundUrlRejected, httpx.HTTPError, ValueError) as exc:
+            raise jwt.exceptions.PyJWKClientConnectionError(
+                "OIDC JWKS fetch failed"
+            ) from exc
+        else:
+            return jwk_set
+        finally:
+            if self.jwk_set_cache is not None:
+                self.jwk_set_cache.put(jwk_set)
+
+
 @dataclass(frozen=True)
 class AdminContext:
     auth_type: str
@@ -129,9 +163,10 @@ def _enforce_oidc_principal_allowlist(claims: Dict[str, Any]) -> None:
 
 def _get_oidc_signing_key(token: str):
     global _OIDC_JWKS_CLIENT, _OIDC_JWKS_CLIENT_URL
-    if _OIDC_JWKS_CLIENT is None or _OIDC_JWKS_CLIENT_URL != OIDC_JWKS_URL:
-        _OIDC_JWKS_CLIENT = jwt.PyJWKClient(OIDC_JWKS_URL)
-        _OIDC_JWKS_CLIENT_URL = OIDC_JWKS_URL
+    canonical_url = ensure_safe_outbound_url(OIDC_JWKS_URL, context="OIDC JWKS")
+    if _OIDC_JWKS_CLIENT is None or _OIDC_JWKS_CLIENT_URL != canonical_url:
+        _OIDC_JWKS_CLIENT = _GuardedPyJWKClient(canonical_url)
+        _OIDC_JWKS_CLIENT_URL = canonical_url
     return _OIDC_JWKS_CLIENT.get_signing_key_from_jwt(token).key
 
 

core/ci_boundary_review.py

@@ -66,7 +66,7 @@
 from core.mcp_drift import ACTION_BY_SEVERITY, SEVERITY_ORDER
 from core.mcp_drift import classify_server_drift, classify_tool_drift
 from core.mcp_gateway import fetch_candidate_tool_surface
-from core.url_security import OutboundUrlRejected, ensure_safe_outbound_url
+from core.url_security import OutboundUrlRejected, ensure_safe_outbound_url_async
 
 logger = logging.getLogger("interlock.ci_boundary_review")
 
@@ -340,14 +340,16 @@ async def _observe(
         "mutated_state": False,
     }
     try:
-        ensure_safe_outbound_url(server.get("url") or "", context="MCP discovery")
+        server_url = await ensure_safe_outbound_url_async(
+            server.get("url") or "", context="MCP discovery"
+        )
     except OutboundUrlRejected:
         observation["error_class"] = "registry_url_rejected"
         return observation, None, []
 
     try:
         result = await fetch_candidate_tool_surface(
-            server["url"],
+            server_url,
             timeout=boundary_review_timeout_seconds(),
             server_id=server_id,
             max_response_bytes=caps["max_response_bytes"],

core/effect_readback.py

@@ -22,7 +22,7 @@
 from core import db
 from core import drift_evidence
 from core.effect_drift import build_effect_profile
-from core.url_security import OutboundUrlRejected, ensure_safe_outbound_url
+from core.url_security import OutboundUrlRejected, ensure_safe_outbound_url_async
 
 SCHEMA_ID = "interlock.readback-effect-drift-record"
 SCHEMA_VERSION = "1"
@@ -400,7 +400,7 @@ async def _call_upstream_tool(
     )
 
     try:
-        server_url = ensure_safe_outbound_url(
+        server_url = await ensure_safe_outbound_url_async(
             server["url"], context="MCP readback probe"
         )
         headers = _resolve_upstream_auth_headers(server)
@@ -410,7 +410,9 @@ async def _call_upstream_tool(
             "method": "tools/call",
             "params": {"name": tool_name, "arguments": arguments or {}},
         }
-        async with httpx.AsyncClient(timeout=30.0) as client:
+        async with httpx.AsyncClient(
+            timeout=30.0, follow_redirects=False, trust_env=False
+        ) as client:
             resp = await client.post(server_url, **_mcp_post_kwargs(payload, headers))
             status = getattr(resp, "status_code", None)
             body: Optional[Dict[str, Any]] = None

core/effective_permission.py

@@ -16,7 +16,7 @@
 
 from core import db
 from core import drift_evidence
-from core.url_security import OutboundUrlRejected, ensure_safe_outbound_url
+from core.url_security import OutboundUrlRejected, ensure_safe_outbound_url_async
 
 EXPECTED_OUTCOMES = {"denied", "allowed"}
 OBSERVED_OUTCOMES = {
@@ -390,7 +390,9 @@ async def _call_upstream_for_observation(
     )
 
     try:
-        server_url = ensure_safe_outbound_url(server["url"], context="MCP probe")
+        server_url = await ensure_safe_outbound_url_async(
+            server["url"], context="MCP probe"
+        )
         headers = _resolve_upstream_auth_headers(server)
         payload = {
             "jsonrpc": "2.0",
@@ -401,7 +403,9 @@ async def _call_upstream_for_observation(
                 "arguments": probe.get("arguments") or {},
             },
         }
-        async with httpx.AsyncClient(timeout=30.0) as client:
+        async with httpx.AsyncClient(
+            timeout=30.0, follow_redirects=False, trust_env=False
+        ) as client:
             resp = await client.post(server_url, **_mcp_post_kwargs(payload, headers))
             body: Optional[Dict[str, Any]] = {}
             try:

core/ema_auth.py

@@ -20,6 +20,7 @@
 from jwt.algorithms import RSAAlgorithm
 
 from core.ema_config import EMASettings, HMACKeyRing
+from core.url_security import ensure_safe_outbound_url_async
 
 _BASE64URL_RE = re.compile(r"^[A-Za-z0-9_-]*$")
 _KID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
@@ -196,13 +197,17 @@ async def _refresh(self) -> None:
             pool=self.settings.jwks_connect_timeout_seconds,
         )
         try:
+            jwks_uri = await ensure_safe_outbound_url_async(
+                self.settings.jwks_uri, context="EMA JWKS"
+            )
             async with httpx.AsyncClient(
                 transport=self._transport,
                 timeout=timeout,
                 follow_redirects=False,
+                trust_env=False,
             ) as client:
                 body = await asyncio.wait_for(
-                    self._read_jwks_response(client),
+                    self._read_jwks_response(client, jwks_uri),
                     timeout=self.settings.jwks_total_timeout_seconds,
                 )
             document = json.loads(body)
@@ -223,10 +228,12 @@ async def _refresh(self) -> None:
             if key_id in keys:
                 self._negative.pop(key_id, None)
 
-    async def _read_jwks_response(self, client: httpx.AsyncClient) -> bytes:
+    async def _read_jwks_response(
+        self, client: httpx.AsyncClient, jwks_uri: str
+    ) -> bytes:
         async with client.stream(
             "GET",
-            self.settings.jwks_uri,
+            jwks_uri,
             headers={"Accept": "application/json"},
         ) as response:
             if response.is_redirect or response.status_code != 200:

core/mcp_gateway.py

@@ -9,7 +9,7 @@
 from typing import Optional, Dict, Any
 from models.schemas import ScanResult, ThreatLevel
 from core.metadata_policy import evaluate_metadata_policy
-from core.url_security import OutboundUrlRejected, ensure_safe_outbound_url
+from core.url_security import OutboundUrlRejected, ensure_safe_outbound_url_async
 from core.tool_inspector import inspect_tool_call
 from core.tool_metadata import normalize_tool_metadata
 from core import db
@@ -768,7 +768,9 @@ async def _fetch_tool_list_payload(
     """
     profile = MCP_UPSTREAM_LEGACY_PROFILE
     try:
-        server_url = ensure_safe_outbound_url(server_url, context="MCP discovery")
+        server_url = await ensure_safe_outbound_url_async(
+            server_url, context="MCP discovery"
+        )
         registered = (
             db.lookup_mcp_server(server_id)
             if server_id
@@ -780,7 +782,9 @@ async def _fetch_tool_list_payload(
         auth_headers = _resolve_upstream_auth_headers(registered)
         profile = _upstream_protocol_profile(registered)
 
-        async with httpx.AsyncClient(timeout=timeout, follow_redirects=False) as client:
+        async with httpx.AsyncClient(
+            timeout=timeout, follow_redirects=False, trust_env=False
+        ) as client:
 
             async def send(method: str) -> Dict[str, Any]:
                 request_id = uuid.uuid4().hex
@@ -1705,9 +1709,13 @@ async def proxy_mcp_tool_call(
 
     # 5. Forward to actual MCP server
     try:
-        server_url = ensure_safe_outbound_url(server["url"], context="MCP server")
+        server_url = await ensure_safe_outbound_url_async(
+            server["url"], context="MCP server"
+        )
         auth_headers = _resolve_upstream_auth_headers(server)
-        async with httpx.AsyncClient(timeout=30.0, follow_redirects=False) as client:
+        async with httpx.AsyncClient(
+            timeout=30.0, follow_redirects=False, trust_env=False
+        ) as client:
             request_id = uuid.uuid4().hex
             payload, protocol_headers = _upstream_request(
                 profile,

core/router.py

@@ -235,7 +235,9 @@ async def forward_to_provider(
 
     # Make request
     try:
-        async with httpx.AsyncClient(timeout=120.0) as client:
+        async with httpx.AsyncClient(
+            timeout=120.0, follow_redirects=False, trust_env=False
+        ) as client:
             resp = await client.post(url, json=body, headers=headers)
             data = resp.json()