netrules

package
v0.6.7 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 16, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source
const (
	BackendExec    = "exec"
	BackendNetlink = "netlink"

	ChainDockerUser  = "DOCKER-USER"
	ChainAerolvmUser = "AEROLVM-USER"
	// ChainAerolvmFC holds the per-guest-IP rules for Firecracker VMs (egress
	// Phase 4), apart from the container engines' chains: its FORWARD
	// accepts are scoped to the TAP subnet.
	ChainAerolvmFC = "AEROLVM-FC"
	// ChainAerolvmInput holds per-IP drops for traffic from restricted
	// sandboxes to the host itself (sandboxd API, SSH gateway, cluster port).
	// Shared by the dockerd and containerd managers: rules are keyed by
	// sandbox IP and the two bridges never share an IP.
	ChainAerolvmInput = "AEROLVM-INPUT"
)

Backend names for SB_NETRULES_BACKEND.

View Source
const ChainAerolvmFloor = "AEROLVM-FLOOR"

ChainAerolvmFloor holds the operator's node-wide deny floor (plans/egress-domain-filtering.md §5.10 PC-2): DROPs from the sandbox bridge subnet to each deny_cidrs entry, jumped from the top of the user chain so they sit above every per-sandbox ACCEPT. A chain of its own because the floor is replaced as a whole when the operator file changes, and the rule backends cannot list rules to find the old ones.

Variables

View Source
var ErrFloorUnsupported = errors.New("netrules: backend cannot manage the egress floor chain")

ErrFloorUnsupported means the rule backend cannot manage the floor chain.

Functions

func WarnIfLegacyIptables added in v0.5.6

func WarnIfLegacyIptables(backend string, logger *slog.Logger)

WarnIfLegacyIptables logs a boot-time warning when the netlink backend is selected on a host whose iptables binary runs in legacy (xtables) mode. The netlink backend writes to the nft tables, which legacy iptables cannot see — the kernel evaluates BOTH rule sets, so flipping SB_NETRULES_BACKEND with live sandboxes strands the previous backend's ACCEPT/DROP rules on recycled container IPs (TODOS.md "netrules backend switch on iptables-legacy hosts"). Best-effort: a missing binary or exec failure stays silent — no signal is not a legacy host.

Types

type Manager

type Manager struct {
	// contains filtered or unexported fields
}

func New

func New(enabled bool) (*Manager, error)

func NewWithBackend added in v0.5.5

func NewWithBackend(backend RuleBackend) *Manager

NewWithBackend builds an enabled Manager over an injected backend. Test seam only — production wiring goes through New.

func NewWithOptions added in v0.5.6

func NewWithOptions(enabled bool, backend, userChain string) (*Manager, error)

NewWithOptions builds a Manager with the chosen RuleBackend. userChain selects the filter chain for per-IP rules; empty defaults to DOCKER-USER. Unknown backend names error so misconfig is loud. Enabled backends are linux-only (see newEnabledManager); other platforms always return a disabled manager.

func (*Manager) ApplyEgressPolicy added in v0.5.4

func (m *Manager) ApplyEgressPolicy(containerIP string, allowCIDRs, denyCIDRs []string) error

ApplyEgressPolicy installs a per-container selective egress policy in DOCKER-USER, scoped by source IP and comment-tagged (see egressPolicyComment). The mode follows the shared allow-wins precedence (plans/ egress-domain-filtering.md D4):

  • allowCIDRs only → allowlist: ACCEPT each CIDR, DROP everything else.
  • denyCIDRs only → blocklist: DROP each CIDR, leave the rest to Docker's default ACCEPT.
  • both → allow wins, then deny, then default ACCEPT: ACCEPTs sit above the DROPs and there is no catch-all.

"allow + deny 0.0.0.0/0" is the portable allowlist spelling (E2B's allowOut + denyOut all): normalizeLists maps it to allow-only here, in the one place every apply and clear goes through, so a clear from the stored row always mirrors what the apply installed.

Re-apply is idempotent: every rule is Exists-checked before Insert, so the start/reconcile reapply paths can call this repeatedly without duplicating.

func (*Manager) BlockAllEgress

func (m *Manager) BlockAllEgress(containerIP string) error

BlockAllEgress installs a DROP rule for traffic originating from containerIP. The rule lives in DOCKER-USER, the chain Docker explicitly reserves for operator-defined firewall rules. DOCKER-USER is jumped from FORWARD *before* DOCKER-FORWARD, so our DROP fires before Docker's blanket "iifname docker0 accept" rule that would otherwise short-circuit any rule appended directly to FORWARD. This works on iptables-legacy and on Docker 28+/iptables-nft (which writes through to nftables) alike.

func (*Manager) BlockAllEgressReport added in v0.5.6

func (m *Manager) BlockAllEgressReport(containerIP string) (bool, error)

BlockAllEgressReport is BlockAllEgress with the idempotency outcome surfaced: inserted is true only when the rule was genuinely absent and had to be re-installed. Reconcile reapplies unconditionally (the Exists guard below is what makes that safe), so "we called Apply" is a constant rate and useless as a signal — "the rule was missing when we looked" is the actual isolation-drift event worth counting. Disabled manager and empty IP report inserted=false: nothing was installed, so nothing drifted.

func (*Manager) BlockAllIngress added in v0.1.7

func (m *Manager) BlockAllIngress(containerIP string) error

BlockAllIngress installs a DROP rule for traffic destined for containerIP, the mirror of BlockAllEgress on the destination axis. Used by the network quota enforcer when net_bytes_in_limit is crossed. The honest caveat (also documented in plans/network-usage-tracking.md): host-side ingress is counted after the NIC has accepted the packet, so the meter is "what the container would have seen" rather than "bytes spent on the wire." Same chain (DOCKER-USER) and idempotency check pattern as the egress mirror.

func (*Manager) BridgeSubnet added in v0.6.6

func (m *Manager) BridgeSubnet() netip.Prefix

BridgeSubnet returns the subnet set by SetBridgeSubnet (the containerd CNI bridge), or the zero prefix.

func (*Manager) ClearBlockAllEgress

func (m *Manager) ClearBlockAllEgress(containerIP string) error

func (*Manager) ClearBlockAllIngress added in v0.1.7

func (m *Manager) ClearBlockAllIngress(containerIP string) error

func (*Manager) ClearEgressPolicy added in v0.5.4

func (m *Manager) ClearEgressPolicy(containerIP string, allowCIDRs, denyCIDRs []string) error

ClearEgressPolicy removes the rules ApplyEgressPolicy would have installed for the same (containerIP, allowCIDRs, denyCIDRs). The caller passes the policy persisted on the sandbox row so cleanup is exact and comment-scoped — the blanket BlockAllEgress DROP (no comment) is left untouched.

func (*Manager) ClearHoldEgress added in v0.6.6

func (m *Manager) ClearHoldEgress(containerIP string) error

ClearHoldEgress removes the hold DROP. Only a successful attach lifts a hold; callers enforce that.

func (*Manager) Enabled

func (m *Manager) Enabled() bool

func (*Manager) EnsureChain added in v0.5.6

func (m *Manager) EnsureChain() error

EnsureChain bootstraps the filter user chain and its FORWARD jump once per Manager lifetime. Idempotent and latched like EnsureLayer4Ready: concurrent callers single-flight through chainMu; success sets chainReady.

func (*Manager) HoldEgress added in v0.6.6

func (m *Manager) HoldEgress(containerIP string) error

HoldEgress installs the hold DROP for containerIP. Idempotent.

func (*Manager) ReassertChain added in v0.5.6

func (m *Manager) ReassertChain() error

ReassertChain re-runs the chain + FORWARD-jump bootstrap WITHOUT the latch, so a caller (e.g. the containerd netns reconcile ticker) can re-assert the jump after a dockerd restart flushes/reorders FORWARD and drops it. Both steps are idempotent; a no-op when disabled or the backend cannot bootstrap.

func (*Manager) ResetChainLatch added in v0.5.6

func (m *Manager) ResetChainLatch()

ResetChainLatch clears the bootstrap latch. Test-only seam.

func (*Manager) SetBridgeSubnet added in v0.5.6

func (m *Manager) SetBridgeSubnet(subnet string)

SetBridgeSubnet records the sandbox bridge subnet whose forwarded traffic EnsureChain/ReassertChain must ACCEPT (below any per-IP DROP). Empty = no-op.

func (*Manager) SetFloor added in v0.6.6

func (m *Manager) SetFloor(subnet netip.Prefix, cidrs []netip.Prefix) error

SetFloor replaces the node-wide deny floor for sandboxes on subnet. An empty cidrs list clears it. The flush and refill are separate steps, so the floor is briefly empty while it is replaced; the egress gateway's own copy of the floor (its deny_floor set) stays in place throughout.

type RuleBackend added in v0.5.5

type RuleBackend interface {
	Exists(table, chain string, rulespec ...string) (bool, error)
	Insert(table, chain string, pos int, rulespec ...string) error
	Delete(table, chain string, rulespec ...string) error
}

RuleBackend is the subset of iptables operations the Manager drives. Production always wraps *go-iptables' IPTables; tests substitute an in-memory backend so rule-state semantics (which rules survive an adopt, a clear, a reapply) are assertable without root or a linux host.

func NewNetlinkBackend added in v0.5.6

func NewNetlinkBackend() (RuleBackend, error)

NewNetlinkBackend wires the per-operation nftables connection factory. Callers must be on linux; non-linux builds use the stub that always errors.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL