How it works
Firewalls match IPs. Allowlists are domains. Egret bridges the two.
The hard part of egress control is that you want to allow github.com,
but a firewall only understands IP addresses - and CDNs rotate them
constantly. Egret closes that gap at runtime.
-
1
Default-deny egress
An nftables rule drops all outbound traffic except to a named allow set. Nothing gets out that Egret has not explicitly permitted.
-
2
A local DNS proxy
The job's resolver points at Egret. Every DNS question flows through it, so Egret sees which domain a connection is really for.
-
3
Allowlisted domain to allow set
When the build resolves an allowlisted domain, the proxy answers and inserts the resolved IPs into the nftables allow set - so the connection succeeds.
-
4
Everything else is dropped and logged
Non-allowlisted domains are refused; raw-IP connections with no prior DNS are caught by the default-deny rule. Each is recorded as a violation.
Honest limitations
The residual gaps - documented, not hidden.
Domain-allowlist egress control has known evasion paths. Egret documents them rather than pretending they don't exist, and the enforcer is reviewed against them on every change.
DoH / DoT
Encrypted DNS bypasses the proxy. Mitigated by blocking raw-IP egress; SNI inspection is future work.
Raw-IP connections
Connections with no prior DNS lookup. Caught by default-deny and blocked by block-raw-ip.
IPv6
The allow set must cover both families; IPv6 coverage is tracked toward v1.0.
CDN IP rotation
Rotating IPs are handled by the live DNS-to-IP correlation, but very short TTLs can race.
Every change to the enforcer is reviewed by an adversarial netsec-reviewer that hunts these bypass paths and verifies fail-closed teardown.
Requirements
What it needs to run.
- Linux kernel 5.8+ (CO-RE, ring buffer)
- Root, or
CAP_BPF+CAP_NET_ADMIN - To build the eBPF objects:
clang/llvm+ kernel BTF