Skip to main content

Legion tunnel architecture

Overview​

The Legion tunnel has two goals:

  • Let autonomous workers and pollers reach customer tools that are not accessible from the public internet. Typical cases are self-hosted internal tools, private DNS names, private IP ranges, or customer security requirements that require traffic to originate from inside the customer's network.
  • Run data masking rules inside the customer environment before responses leave the customer network, so sensitive data can be masked before Legion receives it.

Cloudflare Tunnel provides the network link between Legion and the customer network. Each customer tunnel has a public hostname at <tunnel-id>.legion-tunnel.com that is used to reach the Legion tunnel container running in the customer's network.

The tunnel has two Legion-controlled sides on either side of the Cloudflare network layer:

  • On Legion's side, each customer has a dedicated proxy VM instance in the Legion backend region. This VM runs mitmproxy proxy service on port 1380 and rewrites selected worker or poller traffic into calls to the customer's Cloudflare tunnel hostname.
  • Inside the customer's network, a Docker container runs the Legion tunnel. The container starts both cloudflared and a FastAPI proxy service. cloudflared keeps an outbound-only tunnel open to Cloudflare and forwards tunnel traffic to the FastAPI service on localhost:8080. The FastAPI service unpacks the requests from the proxy VM, forwards them to the target service and data masks the response before returning it.

Flow diagram​

Components​

Proxy configuration​

The backend stores which customer tools or domains should use a tunnel proxy. This configuration is managed through the regional proxy management page.

When a worker, poller, or API action needs to call a tool, the backend uses this configuration to decide whether the request should go directly to the public internet or through the customer's tunnel proxy VM.

Legion proxy VM​

The dedicated proxy VM is the entry point to the tunnel from inside Legion's infrastructure. Workers and pollers send selected traffic to this VM as an HTTP proxy.

The proxy VM accepts the original request, wraps the request details into the tunnel protocol, adds the Cloudflare Access authentication headers, and forwards the wrapped request to the customer's tunnel hostname. For HTTPS traffic, the proxy VM also handles certificate interception so browser and API clients can use it like a normal proxy.

Cloudflare Tunnel and Access​

Cloudflare Tunnel is the transport layer between Legion and the customer network. The customer-side tunnel container opens an outbound connection to Cloudflare, so the customer does not need to expose inbound ports to the internet.

Cloudflare Access protects each tunnel hostname so only allowed Legion traffic can reach it. Cloudflare then forwards authorized traffic over the customer's active tunnel connection to the container running in the customer network.

Customer-side container​

The customer-side Docker container contains both the Cloudflare tunnel client and the Legion proxy service.

cloudflared maintains the outbound tunnel connection to Cloudflare. The FastAPI service receives authorized traffic from cloudflared, reconstructs the original request, calls the internal target service, applies DLP masking rules to supported response bodies, and returns the masked response through the same path.

The container is configured with the Cloudflare tunnel token and a DLP rules file. Customers can optionally mount additional CA certificates or client certificates when their internal tools require custom TLS trust or mTLS.

Request flow​

For example, assume a worker needs to call https://jira.internal.company.local:

  1. The worker checks the customer's proxy configuration and sees that this tool or URL should use the customer's tunnel proxy.
  2. The worker sends the request to the customer's dedicated proxy VM instead of calling Jira directly.
  3. The proxy VM wraps the original request details, adds the Cloudflare service auth headers, and sends the wrapped request to https://<tunnel-id>.legion-tunnel.com.
  4. Cloudflare authenticates the request and forwards it over the existing outbound tunnel connection to the customer's tunnel container.
  5. cloudflared forwards the request to the FastAPI service running inside the container.
  6. The FastAPI service reconstructs the original Jira request and sends it to https://jira.internal.company.local from inside the customer network, using customer-side configuration such as custom CA certificates or client certificates when needed.
  7. When Jira responds, the FastAPI service applies the customer's data masking rules to supported response bodies.
  8. The masked response travels back through Cloudflare and the proxy VM to the worker.

The same high-level flow is used for browser traffic and API traffic.