Egress Network Policies

Control which network destinations a sandbox can reach with allow lists and deny lists.

An egress network policy controls which network destinations a sandbox can reach. Policies are enforced outside the sandbox, so an agent running inside cannot turn the policy off. What a policy blocks, and what it cannot lists the limits.

This is the gate, whether a sandbox can reach a host. It pairs with the egress proxy profile, which decides what gets attached to the requests it's allowed to make. The two are orthogonal, and a proxy rule never widens what a policy permits. See how egress injection works for how the two planes fit together.

A policy combines two kinds of rule:

  • Allow lists. The destinations a sandbox may reach (allowed_domains, allowed_cidrs).
  • Deny lists. Destinations a sandbox is blocked from reaching (denied_domains, denied_cidrs), even if an allow rule would otherwise permit them.

Built-in policies

Two system policies ship with Tektona and need no setup:

  • tektona/dev is a curated allow list for software development: package managers, git hosts, container registries, CDNs, common AI APIs, and cloud provider endpoints. This is the default. It blocks EC2 public host names (*.compute.amazonaws.com, *.compute-1.amazonaws.com). Such a name resolves to the address of any EC2 instance. Anyone can run a server behind it.
  • tektona/open allows all outbound traffic to the internet (allowed_domains: ["*"]). It does not reach private addresses; see Private networks.

Every policy, tektona/open included, always blocks link-local (169.254.0.0/16) and loopback (127.0.0.0/8) addresses. It also blocks outbound TCP to ports 25, 465 and 587 (SMTP) and 6667 (IRC).

Allow lists

An allow list is the set of hosts a sandbox may reach. A domain entry can be exact (github.com) or a wildcard suffix (*.npmjs.org, which matches any subdomain but not the apex). * alone allows every domain. An empty domain list allows no domain.

An allowed domain works on every port.

Private networks

* reaches public addresses only. It does not reach an address in a private range: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10 and fc00::/7. This also holds when a public domain resolves to a private address.

To reach a host in a private range, do one of these:

  • Add its prefix to allowed_cidrs. The sandbox then reaches every address in the prefix, on every port.
  • Name its domain in allowed_domains. The sandbox then reaches the addresses that the domain resolves to.

A domain that an egress proxy profile names for secret injection counts as named, too: HTTPS to that domain reaches the address it resolves to.

allowed_domains: ["*", "gitlab.corp.example"] # the internet, and one named host…
allowed_cidrs:   ["10.20.0.0/16"]             # …and one network prefix

Allowed CIDRs

allowed_cidrs allows destinations by IP address, on every port except the always-blocked ports and ranges above. The domain list and the CIDR list combine: a connection is allowed when either one matches. This also holds for HTTPS and HTTP. A request to a domain that is not in allowed_domains is allowed when the sandbox connects to an address inside an allowed range. Tektona then connects to that address, never to the name. Tektona blocks HTTP/3 to such an address. Clients that use HTTP/3 then fall back to HTTPS over TCP.

The sandbox's DNS resolver answers only for domains in allowed_domains. It does not answer for a domain because the domain resolves into an allowed range. To reach a host by name through a CIDR rule alone, give the sandbox the address yourself, for example in /etc/hosts.

A private destination in allowed_cidrs sees the address of the runner node, or of the NAT device behind it, as other destinations do.

Why the resolver does not answer every name

To learn whether a name resolves into an allowed range, the resolver has to send the query upstream first. Every query then leaves your network, also for names that the policy blocks. A process in the sandbox can encode data in the names it looks up (<data>.attacker.example). The query then sends that data to an outside server, even when every connection is blocked. The resolver answers only the allowed domains, so the query stays inside your network.

Deny lists

Deny rules always win over allow rules. Use them to carve specific destinations out of a broad policy without rebuilding an allow list from scratch, even under tektona/open, or when the same host is also allowed.

Denied domains

denied_domains blocks hosts by name, with the same *.suffix wildcard support as allow entries. A denied domain is blocked even when:

  • the policy is tektona/open (allowed_domains: ["*"]), or
  • the same host also appears in allowed_domains.

A denied domain also blocks every allowed name that is an alias (a DNS CNAME) of it.

For example, extend tektona/dev but deny a package mirror you don't trust, or run an otherwise-open sandbox with a handful of blocked trackers.

Denied CIDRs

denied_cidrs blocks destinations by IP address. A sandbox cannot reach any destination whose IP falls inside a denied range, even if the domain it used is allowed. This covers the case where an allowed domain resolves into a range you want to keep off-limits, for example a cloud metadata endpoint at 169.254.169.254.

allowed_domains: ["*"]              # open egress…
denied_domains:  ["*.tracker.net"]  # …minus a few hosts
denied_cidrs:    ["169.254.0.0/16"] # …and the metadata range

Deny always wins

When a destination matches both an allow rule and a deny rule, the deny rule wins. Precedence is the whole point of deny lists: start broad, then subtract.

What a policy blocks, and what it cannot

The gateway checks every connection that leaves a sandbox. It does not read encrypted data. These lists state the limits.

The policy blocks or checks:

  • HTTPS and HTTP on every TCP port except 25, 53, 465, 587 and 6667 must name an allowed domain, unless the address is in allowed_cidrs. HTTPS names the domain in the TLS server name. HTTP names the domain in the Host of every request.
  • An address that an allowed domain shares with other sites, for example a CDN address, does not reach those sites.
  • A TLS handshake without a server name reaches only an address in allowed_cidrs, or any public address when allowed_domains holds *, as in tektona/open.
  • Other TCP protocols, such as SSH or databases, reach addresses that an allowed domain resolved to, or an address in allowed_cidrs. On port 443 they reach only addresses in allowed_cidrs. Port 80 carries HTTP only. When allowed_domains holds *, they also reach any public address outside the deny lists.
  • HTTP/3 (QUIC) must name an allowed domain. An address in allowed_cidrs does not reach it, and clients then fall back to HTTPS over TCP.
  • Denied CIDRs win on every port and protocol, under tektona/open too. Denied domains win for TCP, HTTP/3 and DNS.
  • A denied domain also blocks each allowed name that is an alias (CNAME) of it.
  • The gateway blocks known DNS-over-HTTPS resolvers by name, also under *. To use one, add its host name to allowed_domains. A deny entry still wins.
  • DNS goes through the platform resolver. It answers only allowed domains.
  • The gateway refuses malformed or ambiguous TLS handshakes and HTTP requests.
  • A sandbox holds at most 1024 open TCP connections through the gateway. The gateway closes a new connection above that number at once.
  • A policy edit reaches the sandboxes that use the policy within about 5 seconds. The gateway then closes each connection that the new policy blocks. An edit that removes anything also closes SSH and other non-HTTP connections that reach an address only through a DNS answer. The client must resolve the name again before it connects.

The policy cannot block:

  • Requests inside an encrypted connection to an allowed domain. A client can name an allowed site in the handshake. It can then ask the same CDN for another site (domain fronting). The gateway checks the handshake, not the encrypted requests. Hosts that an egress proxy rule binds, on a port that the rule lists, are the exception, because the gateway decrypts them.
  • A real site name that Encrypted Client Hello hides. This needs an ECH configuration that the client already holds.
  • Data that a sandbox sends to an allowed domain that hosts user content, for example *.vercel.app or object storage. Keep the allow list narrow.
  • UDP outside ports 53 and 443, and ICMP. These pass by address, not by name. A denied domain does not block them. Under *, they reach a private address only through allowed_cidrs or an allowed domain.
  • Data in the name of a DNS query for an allowed domain. The resolver answers only allowed domains, which limits this.
  • Cleartext HTTP/2 (h2c, such as cleartext gRPC) on any port except 80. The gateway treats it like other non-HTTP TCP traffic.

Custom policies

You can define your own egress network policies at the organization or project scope, and optionally extends a system policy to inherit its allow and deny lists and add your own (the lists are merged). Set an org's default policy and the set of policies its sandboxes may use from the org's sandbox settings. A project can override the default for its own sandboxes.

Manage policies from the Egress Network Policies page in the Tektona console, with the tektona egress-network-policy commands, or via the egress-network-policy endpoints in the API reference for automation. tektona egress-network-policy info <name> prints a policy's allow and deny lists.

Referencing a policy

When you attach a policy at sandbox create with --egress-network-policy, the prefix is a scope keyword — not an org or project name:

ReferenceResolves to
tektona/<name>A system policy (e.g. tektona/dev, tektona/open).
org/<name>A policy in the sandbox's organization.
project/<name>A policy in the sandbox's project.
<name> (bare)The same as project/<name> — the project scope.

A bare name always means the project scope; use org/<name> to reach an org-scoped policy. There is no automatic org fallback.

Address rules are strict, name checks stop at the handshake

Unless allowed_domains holds *, a sandbox reaches an IP address by HTTPS or HTTP only when the address is in allowed_cidrs. Under *, this rule holds for private addresses. HTTP/3 never reaches a bare IP address. Other TCP protocols also reach addresses that an allowed domain resolved to, except on port 443.

Denied CIDRs are blocked on every port.

Name checks read the handshake and the Host header, not encrypted requests. To decrypt and check the requests to a host, bind it to an Egress Proxy Profile rule.

On this page