How to Test Applications on Localhost from Docker Containers Using host.docker.internal with Shannon

Shannon enables testing of localhost applications from within Docker containers by utilizing the host.docker.internal DNS name, which resolves to the host machine's IP address instead of the container's internal localhost.

When running security testing agents inside Docker containers, accessing applications hosted on your local machine requires special networking configuration. The KeygraphHQ/shannon repository solves this challenge by implementing Docker's host.docker.internal DNS alias, allowing containers to reach host-bound services without exposing them to external networks.

Why Localhost Fails Inside Docker Containers

Docker containers operate within isolated networking namespaces, meaning that localhost or 127.0.0.1 references resolve to the container itself rather than the host machine. When Shannon's agents attempt to connect to localhost:3000, they target the container's internal loopback interface, not the application running on your development machine.

Configuring host.docker.internal in Shannon

Shannon leverages Docker Desktop's built-in DNS name host.docker.internal to bridge this networking gap. This hostname automatically resolves to the host's IP address within the container's network context.

Docker Compose Network Configuration

The repository's docker-compose.docker.yml file explicitly maps the host gateway to ensure DNS resolution works correctly across all containerized agents:

# docker-compose.docker.yml

services:
  shannon:
    # …

    extra_hosts:
      - "host.docker.internal:host-gateway"

This configuration, found at line 6 of the compose file, guarantees that host.docker.internal resolves to the host machine's IP address rather than failing with DNS resolution errors.

Launching Shannon Against Local Applications

According to the README.md (lines 206-212), users should substitute localhost with host.docker.internal when starting Shannon scans:

./shannon start URL=http://host.docker.internal:3000 REPO=my-app

The CLAUDE.md documentation (line 131) reinforces this pattern, ensuring consistent guidance across all Shannon documentation for testing locally-hosted applications.

Practical Implementation Examples

When Shannon agents execute tools like curl, Playwright, or PhantomJS, they automatically inherit the container's networking configuration. Here are specific implementation patterns:

HTTP Requests with curl

Inside a Shannon agent container, accessing your local API endpoint works seamlessly:

curl -s http://host.docker.internal:3000/api/health

Browser Automation with Playwright

Shannon's MCP helper for Playwright uses the same hostname pattern. The JSON payload structure for browser automation targets local applications:

{
  "tool": "mcp__playwright-agent2__browser_fill_form",
  "input": {
    "fields": [
      {
        "name": "URL field",
        "type": "textbox",
        "ref": "e7",
        "value": "http://host.docker.internal:3000/"
      }
    ]
  }
}

Security Testing Scenarios

In SSRF exploitation testing, Shannon agents inject host.docker.internal to force server-side requests to hit the host machine. An example from the benchmark audit logs demonstrates this pattern:

curl -s "http://localhost:38291/page?name=%3Czzz%20onfocus%3D%22new%20Image%28%29.src%3D%27http%3A%2F%2Fhost.docker.internal%3A9999%2Fssrf-test%27%3Balert%28%27done%27%29%22%20autofocus%3E"

This approach allows security testing of locally-hosted applications without deploying them to external servers.

Summary

• Docker containers use isolated networking namespaces, making localhost resolve to the container rather than the host machine.
• Shannon utilizes host.docker.internal as a DNS alias that resolves to the host's IP address within containers.
• Configuration requires extra_hosts mapping in docker-compose.docker.yml to ensure proper DNS resolution.
• All Shannon agents inherit this networking setup, enabling tools like curl, Playwright, and PhantomJS to access local applications seamlessly.
• This pattern supports security testing scenarios including SSRF and XSS exploitation against locally-hosted services.

Frequently Asked Questions

Why can't I use localhost to reach my host machine from Shannon's Docker containers?

Docker containers run in isolated networking namespaces where localhost and 127.0.0.1 refer to the container's own loopback interface, not the host machine. When Shannon agents attempt to connect to localhost:3000, they target the container itself, which has no service listening on that port. The host.docker.internal DNS name provides the necessary bridge to the host's network interface.

Is host.docker.internal available on all Docker platforms?

The host.docker.internal hostname works reliably on Docker Desktop for Windows and macOS. On Linux systems, this DNS name may not be available by default depending on the Docker version and configuration. Shannon addresses this by explicitly adding the extra_hosts entry in docker-compose.docker.yml, which ensures the hostname resolves correctly across all supported platforms including Linux environments.

Do I need to modify my application code to work with Shannon's Docker setup?

No application code changes are required. You only need to modify the URL you pass to Shannon when starting a scan. Replace localhost or 127.0.0.1 with host.docker.internal in the command line argument. For example, use URL=http://host.docker.internal:3000 instead of URL=http://localhost:3000. Your application continues to bind to its normal host port without any configuration changes.

Can I use this approach for security testing against local applications?

Yes, this approach is specifically designed to support security testing scenarios. Shannon's agents can target host.docker.internal to perform SSRF exploitation, XSS testing, and other vulnerability assessments against applications running on your local machine. The benchmark audit logs in the repository demonstrate real-world examples where agents inject host.docker.internal into payloads to force server-side requests back to the host machine, enabling comprehensive security testing without deploying to external servers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}