fix: bind to loopback by default instead of all interfaces (#391)

* fix: bind to loopback by default instead of all interfaces

The test agent created its HTTP, OTLP HTTP, OTLP gRPC, and Web UI
listeners with no host argument, so aiohttp/grpc bound to all
interfaces (0.0.0.0 and [::]). Under `lapdog` those servers carry
captured Claude Code / Codex / Pi session content (prompts, responses,
traces, and the Web UI that renders them), so anyone on the same
network could read local AI session data. The plain test agent was
exposed too.

Make the bind host configurable via --host (env HOST) and default it
to 127.0.0.1 (loopback) so the agent is safe out of the box. Exposure
is now explicit opt-in: the Docker images set HOST=0.0.0.0 so their
published ports keep working, and anyone running over the network
passes --host 0.0.0.0. The gRPC server preserves its dual-stack [::]
bind when 0.0.0.0 is requested.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* add release note for loopback bind default

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: alexisdps-dd

Dockerfile

@@ -3,6 +3,10 @@ FROM python:3.13-slim
 WORKDIR /src
 EXPOSE 8126
 
+# The agent binds to loopback by default. In a container the published port
+# (EXPOSE 8126 / -p 8126:8126) is only reachable if the agent binds all
+# interfaces, so opt in explicitly here.
+ENV HOST=0.0.0.0
 ENV SNAPSHOT_CI=1
 ENV LOG_LEVEL=INFO
 ENV SNAPSHOT_DIR=/snapshots

Dockerfile.windows

@@ -4,6 +4,10 @@ FROM python:3.13-windowsservercore
 WORKDIR /src
 EXPOSE 8126
 
+# The agent binds to loopback by default. In a container the published port
+# (EXPOSE 8126 / -p 8126:8126) is only reachable if the agent binds all
+# interfaces, so opt in explicitly here.
+ENV HOST=0.0.0.0
 ENV SNAPSHOT_CI=1
 ENV LOG_LEVEL=INFO
 ENV SNAPSHOT_DIR=C:\snapshots

README.md

@@ -24,6 +24,10 @@ The test agent can be installed from PyPI:
     # HTTP on port 8126, OTLP HTTP on port 4318, OTLP GRPC on port 4317, with the web-ui enabled
     ddapm-test-agent --port=8126 --otlp-http-port=4318 --otlp-grpc-port=4317 --web-ui-port=8080
 
+The agent binds to `127.0.0.1` (loopback) by default. To accept connections from
+other hosts, pass `--host 0.0.0.0` or set `HOST=0.0.0.0`. The Docker image sets
+this for you so its published ports work.
+
 or from Docker:
 
     # Run the test agent and mount the snapshot directory

ddapm_test_agent/agent.py

@@ -1994,7 +1994,9 @@ async def otlp_store_request_middleware(request: Request, handler: _Handler) ->
     return app
 
 
-async def make_otlp_grpc_server_async(agent: Agent, http_port: int, grpc_port: int) -> Any:
+async def make_otlp_grpc_server_async(
+    agent: Agent, http_port: int, grpc_port: int, host: str = "127.0.0.1"
+) -> Any:
     """Create and start a separate GRPC server for OTLP endpoints that forwards to HTTP server."""
     # Define the servicer class only when GRPC is available
     server = grpc_aio.server()
@@ -2011,8 +2013,15 @@ async def make_otlp_grpc_server_async(agent: Agent, http_port: int, grpc_port: i
     traces_servicer = OTLPTracesGRPCServicer(http_port)
     add_TraceServiceServicer_to_server(traces_servicer, server)
 
-    # Setup and start the server
-    listen_addr = f"[::]:{grpc_port}"
+    # Setup and start the server. Preserve the historical dual-stack
+    # all-interfaces bind for the default; otherwise bind the requested host,
+    # wrapping IPv6 literals in brackets.
+    if host == "0.0.0.0":
+        listen_addr = f"[::]:{grpc_port}"
+    elif ":" in host:
+        listen_addr = f"[{host}]:{grpc_port}"
+    else:
+        listen_addr = f"{host}:{grpc_port}"
     server.add_insecure_port(listen_addr)
     await server.start()
 
@@ -2351,6 +2360,16 @@ def main(args: Optional[List[str]] = None) -> None:
         help="Print version info and exit.",
     )
     parser.add_argument("-p", "--port", type=int, default=int(os.environ.get("PORT", 8126)))
+    parser.add_argument(
+        "--host",
+        type=str,
+        default=os.environ.get("HOST"),
+        help=(
+            "Host/interface to bind all servers to. Defaults to 127.0.0.1 "
+            "(loopback only). Set to 0.0.0.0 to accept connections from other "
+            "hosts, e.g. when running in a container with a published port."
+        ),
+    )
     parser.add_argument(
         "--otlp-http-port",
         type=int,
@@ -2543,6 +2562,13 @@ def main(args: Optional[List[str]] = None) -> None:
     parsed_args = parser.parse_args(args=args)
     logging.basicConfig(level=parsed_args.log_level)
 
+    # Bind to loopback by default so the agent is not exposed on the network.
+    # Deployments that must accept off-host traffic (the Docker image, CI)
+    # opt in explicitly via --host/HOST (the published Dockerfile sets
+    # HOST=0.0.0.0).
+    if parsed_args.host is None:
+        parsed_args.host = "127.0.0.1"
+
     if parsed_args.version:
         print(_get_version())
         sys.exit(0)
@@ -2663,21 +2689,21 @@ async def run_servers():
 
         # Start GRPC server if available (async creation)
         otlp_grpc_server = await make_otlp_grpc_server_async(
-            agent, parsed_args.otlp_http_port, parsed_args.otlp_grpc_port
+            agent, parsed_args.otlp_http_port, parsed_args.otlp_grpc_port, host=parsed_args.host
         )
 
         # Create sites for both apps
         if apm_sock:
             apm_site = web.SockSite(apm_runner, apm_sock)
         else:
-            apm_site = web.TCPSite(apm_runner, port=parsed_args.port)
+            apm_site = web.TCPSite(apm_runner, host=parsed_args.host, port=parsed_args.port)
 
-        otlp_http_site = web.TCPSite(otlp_http_runner, port=parsed_args.otlp_http_port)
+        otlp_http_site = web.TCPSite(otlp_http_runner, host=parsed_args.host, port=parsed_args.otlp_http_port)
 
         # Create Web UI site if enabled
         web_ui_site = None
         if web_ui_runner is not None:
-            web_ui_site = web.TCPSite(web_ui_runner, port=parsed_args.web_ui_port)
+            web_ui_site = web.TCPSite(web_ui_runner, host=parsed_args.host, port=parsed_args.web_ui_port)
 
         # Start servers concurrently
         sites_to_start = [apm_site.start(), otlp_http_site.start()]

releasenotes/notes/bind-loopback-by-default-981134f62dc0508f.yaml

@@ -0,0 +1,20 @@
+---
+security:
+  - |
+    The test agent now binds to ``127.0.0.1`` (loopback) by default instead of
+    all network interfaces. Previously the HTTP, OTLP HTTP, OTLP gRPC, and Web
+    UI servers were reachable from any host on the network, which could expose
+    captured data (including ``lapdog`` Claude Code / Codex / Pi session
+    content) to other machines on the same network.
+features:
+  - |
+    Added a ``--host`` command-line argument (and ``HOST`` environment
+    variable) to control the interface all servers bind to. Defaults to
+    ``127.0.0.1``.
+upgrade:
+  - |
+    The default bind host is now ``127.0.0.1`` instead of all interfaces. To
+    accept connections from other hosts (for example when running outside of a
+    container and pointing a remote tracer at the agent), pass ``--host
+    0.0.0.0`` or set ``HOST=0.0.0.0``. The published Docker images set
+    ``HOST=0.0.0.0`` automatically, so their published ports keep working.