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/devis 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/openallows 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 prefixAllowed 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 rangeDeny 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 theHostof 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 whenallowed_domainsholds*, as intektona/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 inallowed_cidrs. Port 80 carries HTTP only. Whenallowed_domainsholds*, they also reach any public address outside the deny lists. - HTTP/3 (QUIC) must name an allowed domain. An address in
allowed_cidrsdoes not reach it, and clients then fall back to HTTPS over TCP. - Denied CIDRs win on every port and protocol, under
tektona/opentoo. 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 toallowed_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.appor 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 throughallowed_cidrsor 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:
| Reference | Resolves 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.
Secrets
Store a credential once as a project secret, shared with everyone on the project. Scope it to just yourself when you need to, and Tektona keeps it encrypted and out of your sandboxes.
Egress Proxy Profiles
Attach credentials to a sandbox's outbound requests at the egress boundary so the secret never lives inside the sandbox.