diff --git a/README.md b/README.md index 109fe12347..10bf6ce444 100644 --- a/README.md +++ b/README.md @@ -226,6 +226,7 @@ We provide several sample applications demonstrating Agent Substrate's capabilit * [Integration Repositories](docs/integration-repos.md): Where integrations live, how their repositories are named, and how fixes flow back to core. * [Observability Guide](docs/observability.md): Guide to actor logging, metrics, and distributed tracing. * [Authentication Guide](docs/authentication.md): Configure trusted JWT providers and human credentials. +* [Egress Traffic](docs/egress-traffic.md): Which protocols an Actor may reach the outside world with and which are blocked. * [Enabling man-in-the-middle (MITM) interception for Actor Egress policy](docs/egress-trust-bundle.md): Egress policies such as header injection depend on MITM interception of Actor traffic. This guide explains how an Actor should be configured to enable interception. * [Request Parking](docs/request-parking.md): How the router parks requests through transient worker-pool saturation. * [Rolling Upgrade Runbook](docs/upgrade.md): Upgrade a running substrate node by node without losing actor state. diff --git a/docs/egress-traffic.md b/docs/egress-traffic.md new file mode 100644 index 0000000000..00556c1469 --- /dev/null +++ b/docs/egress-traffic.md @@ -0,0 +1,34 @@ +This document specifies the supported egress traffic for [GA](https://github.com/agent-substrate/substrate/milestone/3). + +Actor TCP egress (except DNS traffic on port 53) is redirected to atunnel, +which opens a CONNECT tunnel to the egress gateway. Egress gateway applies policy. + +DNS-over-TCP, UDP and other traffic is filtered by nftables and never reaches the gateway. + +## TCP + +| Port | Traffic | Behavior | Path | What the actor sees when refused | +| :---- | :---- | :---- | :---- | :---- | +| any | HTTP(S) 1.1 / 2 | Supported with policy controls | atunnel -> egress gateway -> origin | `403 Forbidden` | +| any | WebSocket | Blocked | n/a | `403 Forbidden` | +| any | Standard HTTP(S) CONNECT (forward-proxy tunnel) | Blocked | n/a | `403 Forbidden` | +| 53 | DNS | Allowed via netfilter rules | nftables -> node-configured DNS | n/a | +| any | Any other TCP | Blocked | n/a | The connection is accepted and then closed with no bytes returned. There is no status code. atunnel logs the failure. | + +## UDP + + +| Port | Traffic | Behavior | Path | What the actor sees when refused | +| :---- | :---- | :---- | :---- | :---- | +| 53 | DNS | Allowed via netfilter rules | nftables -> node-configured DNS | n/a | +| any other | Any other UDP | Blocked | n/a | Packets are dropped, not rejected: no ICMP port-unreachable is sent, so the client hangs until its own timeout. | + +## Other transports + +Everything that is neither TCP nor UDP is blocked. Packets are dropped, not rejected: no ICMP port-unreachable is sent, so the client hangs until its own timeout. + +## Requesting support + +If you would like Substrate to support egress traffic that is blocked above, please +[file an issue](https://github.com/agent-substrate/substrate/issues/new) +describing your use case. \ No newline at end of file