From 90e534ef96c2e67c19ecce98e84845ce17c77e2b Mon Sep 17 00:00:00 2001 From: Haiyan Meng Date: Fri, 18 Sep 2026 13:58:57 -0400 Subject: [PATCH] Document the egress traffic supported for GA Record which egress protocols are allowed, which are allowed only under policy controls, and which are blocked, along with the data path each one takes. Having this written down gives users a single place to check what Substrate lets an actor reach, and gives us a checklist to implement and test against before GA. Point readers at the issue tracker so that requests for traffic we do not yet support arrive with a use case attached. --- README.md | 1 + docs/egress-traffic.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 docs/egress-traffic.md 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