Documentation
¶
Index ¶
- Constants
- Variables
- func ComputeStaticIP(gateway netip.Addr, lastOctet byte) (netip.Addr, error)
- func DetectCgroupDriver(ctx context.Context, dc *docker.Client) (string, error)
- func EBPFCgroupPath(cgroupDriver, containerID string) string
- func EnsureCA(certDir string) (*x509.Certificate, *ecdsa.PrivateKey, error)
- func GenerateCorefile(rules []config.EgressRule, healthPort int) ([]byte, error)
- func GenerateDomainCert(caCert *x509.Certificate, caKey *ecdsa.PrivateKey, domain string) (certPEM, keyPEM []byte, err error)
- func GenerateEnvoyConfig(rules []config.EgressRule, ports EnvoyPorts, als ALSConfig) ([]byte, []string, error)
- func IsCanonicalContainerID(s string) bool
- func MergeRule(existing, incoming config.EgressRule) config.EgressRule
- func NewRulesStore(cfg config.Config) (*storage.Store[EgressRulesFile], error)
- func NormalizeAndDedup(rules []config.EgressRule) ([]config.EgressRule, []string)
- func NormalizeRule(r config.EgressRule) config.EgressRule
- func RegenerateDomainCerts(rules []config.EgressRule, certDir string, caCert *x509.Certificate, ...) error
- func ResolveContainerID(ctx context.Context, dc *docker.Client, ref string) (string, error)
- func RotateCA(certDir string, rules []config.EgressRule) error
- func RoutesFromRules(rules []config.EgressRule, ports EnvoyPorts) []ebpf.Route
- func RuleKey(r config.EgressRule) string
- func SeedDomainsFromRules(rules []config.EgressRule, ports EnvoyPorts) []string
- func ValidateDst(dst string) error
- func ValidateRule(r config.EgressRule) error
- type ALSConfig
- type ActionFunc
- type ActionKind
- type ActionQueue
- type ActionResult
- type BypassResult
- type ContainerResolver
- type DisableResult
- type EgressRulesFile
- type EnableResult
- type EnvoyConfig
- func (c *EnvoyConfig) AddCluster(cluster map[string]any) error
- func (c *EnvoyConfig) AddListener(listener map[string]any) error
- func (c *EnvoyConfig) Bytes() ([]byte, error)
- func (c *EnvoyConfig) ClaimPermutation(key string) bool
- func (c *EnvoyConfig) EnsureListener(name, address string, port int)
- func (c *EnvoyConfig) EnsureQUICListener(name, address string, port int)
- func (c *EnvoyConfig) EnsureRawUDPListener(name, address string, port int)
- func (c *EnvoyConfig) HasListener(name string) bool
- func (c *EnvoyConfig) SetAdmin(admin map[string]any)
- func (c *EnvoyConfig) SetListenerField(listener, key string, value any) error
- func (c *EnvoyConfig) SetUnmatchedDeny(listener string, chain map[string]any) error
- type EnvoyPorts
- type Handler
- func (h *Handler) AllResolvableDomains() []string
- func (h *Handler) CancelAllBypassTimers() int
- func (h *Handler) FirewallAddRules(ctx context.Context, req *adminv1.FirewallAddRulesRequest) (*adminv1.FirewallAddRulesResult, error)
- func (h *Handler) FirewallBypass(ctx context.Context, req *adminv1.FirewallBypassRequest) (*adminv1.FirewallBypassResult, error)
- func (h *Handler) FirewallDisable(ctx context.Context, req *adminv1.FirewallDisableRequest) (*adminv1.FirewallDisableResult, error)
- func (h *Handler) FirewallEnable(ctx context.Context, req *adminv1.FirewallEnableRequest) (*adminv1.FirewallEnableResult, error)
- func (h *Handler) FirewallInit(ctx context.Context, _ *adminv1.FirewallInitRequest) (*adminv1.FirewallInitResult, error)
- func (h *Handler) FirewallListRules(ctx context.Context, _ *adminv1.FirewallListRulesRequest) (*adminv1.FirewallListRulesResult, error)
- func (h *Handler) FirewallReload(ctx context.Context, _ *adminv1.FirewallReloadRequest) (*adminv1.FirewallReloadResult, error)
- func (h *Handler) FirewallRemove(ctx context.Context, _ *adminv1.FirewallRemoveRequest) (*adminv1.FirewallRemoveResult, error)
- func (h *Handler) FirewallRemoveRule(ctx context.Context, req *adminv1.FirewallRemoveRuleRequest) (*adminv1.FirewallRemoveRuleResult, error)
- func (h *Handler) FirewallResolveHostname(ctx context.Context, req *adminv1.FirewallResolveHostnameRequest) (*adminv1.FirewallResolveHostnameResult, error)
- func (h *Handler) FirewallRotateCA(ctx context.Context, _ *adminv1.FirewallRotateCARequest) (*adminv1.FirewallRotateCAResult, error)
- func (h *Handler) FirewallStatus(ctx context.Context, _ *adminv1.FirewallStatusRequest) (*adminv1.FirewallStatusResult, error)
- func (h *Handler) FirewallSyncRoutes(ctx context.Context, _ *adminv1.FirewallSyncRoutesRequest) (*adminv1.FirewallSyncRoutesResult, error)
- func (h *Handler) ReverseDNSDomains() []string
- type HandlerDeps
- type HealthTimeoutError
- type InitResult
- type ListRulesResult
- type NetworkInfo
- type OtelCertProvisioner
- type ResolveResult
- type Stack
- func (s *Stack) CIDR() string
- func (s *Stack) CoreDNSIP() string
- func (s *Stack) EnsureRunning(ctx context.Context) error
- func (s *Stack) EnvoyIP() string
- func (s *Stack) NetworkID() string
- func (s *Stack) NetworkInfo(ctx context.Context) (*NetworkInfo, error)
- func (s *Stack) Reload(ctx context.Context) error
- func (s *Stack) Status(ctx context.Context) (*Status, error)
- func (s *Stack) Stop(ctx context.Context) error
- func (s *Stack) WaitForHealthy(ctx context.Context) error
- type StackLifecycle
- type StackReloadResult
- type Status
- type StatusResult
- type TCPMapping
- type TeardownResult
Constants ¶
const ( ReasonCPNotRunning = "CP_NOT_RUNNING" ReasonQueueClosed = "QUEUE_CLOSED" ReasonFirewallNotInitialized = "FIREWALL_NOT_INITIALIZED" ReasonContainerGone = "CONTAINER_GONE" ReasonRuleInvalid = "RULE_INVALID" ReasonRuleStoreWrite = "RULE_STORE_WRITE" ReasonCertRegen = "CERT_REGEN" ReasonStackProbe = "STACK_PROBE" ReasonConfigRegen = "CONFIG_REGEN" ReasonEnvoyRestart = "ENVOY_RESTART" ReasonCoreDNSRestart = "COREDNS_RESTART" ReasonStackUnhealthy = "STACK_UNHEALTHY" ReasonRouteSync = "ROUTE_SYNC" )
Reason* constants are the stable wire strings carried in errdetails.ErrorInfo.Reason across the gRPC boundary. CLI code matches on these instead of Go-side sentinel identity — status.Error wrapping drops errors.Is fidelity across the wire.
const ErrorInfoDomain = "firewall.clawker.dev"
ErrorInfoDomain is the errdetails.ErrorInfo.Domain for every firewall error detail. Keeps Reason lookups scoped — future domain error catalogs pick their own domain string.
Variables ¶
var ( ErrEnvoyUnhealthy = errors.New("envoy not healthy") ErrCoreDNSUnhealthy = errors.New("coredns not healthy") ErrCPUnhealthy = errors.New("clawker-controlplane not healthy") )
Sentinel errors for firewall stack health check failures.
var ( // CLI-dial layer. ErrCPNotRunning mostly surfaces client-side from // the AdminClient dial helper; the server rarely emits it. ErrCPNotRunning = errors.New("control plane not running") ErrQueueClosed = errors.New("action queue closed or CP shutting down") // Pre-Submit layer (store unchanged on failure). ErrFirewallNotInitialized = errors.New("firewall not initialized") ErrContainerGone = errors.New("container no longer exists") ErrRuleInvalid = errors.New("invalid rule") ErrRuleStoreWrite = errors.New("rule store write failed") ErrCertRegen = errors.New("ca / per-domain cert regeneration failed") // Queued-closure layer (store already committed — partial success). ErrStackProbe = errors.New("cannot probe firewall stack state") ErrConfigRegen = errors.New("stack config regeneration failed") ErrEnvoyRestart = errors.New("envoy restart failed") ErrCoreDNSRestart = errors.New("coredns restart failed") ErrStackUnhealthy = errors.New("stack containers are not healthy") ErrRouteSync = errors.New("bpf route map sync failed") )
Sentinels surfaced through the Handler and queue. Each has a companion Reason constant for gRPC errdetails.ErrorInfo so the CLI can dispatch remediation without string-matching status messages.
Layering (see initiative memory `firewall-queue-initiative` → "Three- layer failure model"): CLI-dial sentinels fire before the queue is touched; pre-Submit sentinels fire inside the RPC handler before the store write lands; queued-closure sentinels fire on the worker after the store write has already committed — partial success by design.
var ( ErrClosed = errors.New("action queue closed") ErrNilClosure = errors.New("action queue: nil closure") ErrClosurePanic = errors.New("action closure panicked") )
Sentinels returned on an ActionResult when the queue itself rejects or cannot complete a submission. Closure-level failures use sentinels defined alongside the closure.
var CoreDNSClawkerBinary []byte
CoreDNSClawkerBinary is the pre-compiled static Linux binary for custom CoreDNS with the dnsbpf plugin (real-time BPF dns_cache population). Built by: make coredns-binary Target: GOOS=linux CGO_ENABLED=0 go build ./cmd/coredns-clawker
This binary is embedded into every clawker release binary so the custom CoreDNS container image can be built on-demand without a registry or source tree. The binary must match the Docker host's architecture (arm64 or amd64).
Functions ¶
func ComputeStaticIP ¶
ComputeStaticIP replaces the last octet of an IPv4 address with the given value. For example, gateway 172.20.0.1 with lastOctet 2 produces 172.20.0.2.
func DetectCgroupDriver ¶
DetectCgroupDriver returns the Docker daemon's cgroup driver (typically "systemd" on native Linux, "cgroupfs" on Docker Desktop). The value is stable for the daemon's lifetime; callers cache it at init. Errors propagate rather than defaulting — a silent default would produce ENOENT at eBPF attach time.
func EBPFCgroupPath ¶
EBPFCgroupPath returns the BPF-attachable cgroup v2 path for a Docker container. Any driver other than "systemd" uses the cgroupfs layout.
func EnsureCA ¶
func EnsureCA(certDir string) (*x509.Certificate, *ecdsa.PrivateKey, error)
EnsureCA creates a self-signed CA keypair if none exists under certDir, or loads the existing one.
func GenerateCorefile ¶
func GenerateCorefile(rules []config.EgressRule, healthPort int) ([]byte, error)
GenerateCorefile produces a CoreDNS Corefile from the given egress rules. healthPort is the port the CoreDNS health plugin listens on (inside the container).
Only "allow" rules with domain destinations (not IPs/CIDRs) get forward zones. Each allowed domain gets its own zone forwarding to Cloudflare malware-blocking DNS. The catch-all "." zone returns NXDOMAIN for everything else.
func GenerateDomainCert ¶
func GenerateDomainCert(caCert *x509.Certificate, caKey *ecdsa.PrivateKey, domain string) (certPEM, keyPEM []byte, err error)
GenerateDomainCert signs a per-domain certificate for TLS inspection. The certificate is signed by the given CA and has the domain as a SAN. For wildcard domains (leading-dot convention), the SAN includes both the apex (e.g., "datadoghq.com") and the wildcard ("*.datadoghq.com") so TLS inspection works for any subdomain. Returns PEM-encoded cert and key bytes.
func GenerateEnvoyConfig ¶
func GenerateEnvoyConfig(rules []config.EgressRule, ports EnvoyPorts, als ALSConfig) ([]byte, []string, error)
GenerateEnvoyConfig is the firewall's sole Envoy-config entrypoint, consumed by Stack.Reload. Signature is stable.
func IsCanonicalContainerID ¶
IsCanonicalContainerID reports whether s matches Docker's on-the-wire container ID format: exactly 64 lowercase hex characters. Exported so the host-side resolver factory in cmd/clawker-cp can apply the same validation without re-implementing the predicate.
func MergeRule ¶ added in v0.9.5
func MergeRule(existing, incoming config.EgressRule) config.EgressRule
MergeRule merges incoming into existing for the same RuleKey. Caller wins on Action; PathRules is unioned by Path with caller winning on same-path collision. Callers MUST pre-normalize via NormalizeRule so scalar defaults are populated before merge.
PathDefault is preserved from existing when incoming.PathDefault is "" so a bare CLI add (`clawker firewall add foo.com`) does not silently clear a yaml-set default on the same key. A non-empty incoming.PathDefault wins. The `string` proto field cannot distinguish "unset" from "explicitly empty" — yaml authors who want to clear a default remove the rule and re-add without it.
func NewRulesStore ¶
NewRulesStore creates a storage.Store[EgressRulesFile] for egress-rules.yaml. The store uses the firewall data subdirectory for file discovery.
func NormalizeAndDedup ¶
func NormalizeAndDedup(rules []config.EgressRule) ([]config.EgressRule, []string)
NormalizeAndDedup normalizes all rules and removes duplicates. This handles store files that contain rules with an unset port: NormalizeRule fills the proto default (e.g. https → 443) so they become duplicates of the correctly-ported entries and collapse during dedup.
Wildcard (.claude.ai) and exact (claude.ai) rules are NOT deduped against each other — they are semantically distinct. A user may want unrestricted subdomain access while restricting paths on the apex, or vice versa.
func NormalizeRule ¶
func NormalizeRule(r config.EgressRule) config.EgressRule
NormalizeRule fills in missing fields before storage so rules are explicit and unambiguous. `proto: tls` is silently translated to `proto: https` (legacy alias; "tls" was always TLS-terminated HCM-inspected HTTPS — the rename disambiguates from raw TLS proxying). Empty proto defaults to "https" (the common case). Empty action defaults to "allow". Default port is 443 for https/wss, 80 for http/ws, 22 for ssh. Existing non-zero values are never overridden. Config-side values stay present-tense (allow/deny) — the access log emits past-tense verdict values (allowed/denied) independently.
func RegenerateDomainCerts ¶
func RegenerateDomainCerts(rules []config.EgressRule, certDir string, caCert *x509.Certificate, caKey *ecdsa.PrivateKey) error
RegenerateDomainCerts generates certificates for all TLS egress rules, storing them in certDir/<domain>-cert.pem and <domain>-key.pem. Every TLS rule gets a certificate — Envoy terminates TLS for all domains to enable HTTP-level inspection (paths, methods, response codes).
Rules are deduplicated by normalized domain. If any rule for a domain uses the wildcard convention (leading dot), the cert includes both apex and wildcard SANs. This prevents a later exact-domain rule from overwriting a cert that also needs wildcard SANs.
Cert generation runs before stale cleanup so that a partial failure leaves previously-working certs intact rather than an empty directory.
func ResolveContainerID ¶
ResolveContainerID normalizes a container reference (name, short ID, or canonical long ID) to the 64-char lowercase hex long ID that EBPFCgroupPath expects. Canonical inputs skip the Docker round-trip.
func RotateCA ¶
func RotateCA(certDir string, rules []config.EgressRule) error
RotateCA regenerates the CA keypair and all domain certificates. The old CA files are overwritten. Any running containers will need the new CA injected to trust the regenerated domain certs.
func RoutesFromRules ¶
func RoutesFromRules(rules []config.EgressRule, ports EnvoyPorts) []ebpf.Route
RoutesFromRules projects a rule set into the BPF route_map entry form. Destinations are normalized before hashing so the resulting DomainHash matches whatever CoreDNS writes into dns_cache at resolve time (INV: normalizeDomain + ebpf.DomainHash form the shared hashing contract across firewall / dnsbpf / ebpf).
TLS/HTTP rules route to the main egress listener (ports.EgressPort). SSH/TCP rules route to their dedicated per-rule TCP listener port (ports.TCPPortBase + index). The TCP/SSH branch drives routes directly from TCPMappings so eBPF routes and Envoy listeners stay in lockstep: matching allow semantics (empty Action == allow), matching IP/CIDR filtering, and matching tcpDefaultPort defaulting (ssh→22, tcp→443) for rules with Port==0. Any divergence here silently misroutes traffic (e.g. SSH landing on the main TLS listener — tls_inspector sees raw TCP, no SNI match, deny chain resets).
func RuleKey ¶
func RuleKey(r config.EgressRule) string
RuleKey returns the dedup key for an egress rule: dst:proto:port. The Dst is used verbatim so that ".claude.ai" and "claude.ai" are distinct rules — a wildcard and its apex carry independent semantics (e.g., different PathRules) and must not be collapsed.
func SeedDomainsFromRules ¶ added in v0.10.2
func SeedDomainsFromRules(rules []config.EgressRule, ports EnvoyPorts) []string
SeedDomainsFromRules returns the destination strings that RoutesFromRules seeds into dns_cache as IP literals — one entry per distinct bare-IPv4 dedicated-listener mapping (TCP/SSH/UDP). These are exactly the strings whose ebpf.DomainHash equals the SeedIP routes' DomainHash, so feeding them through the netlogger ReverseDNSMap lets it attribute those seeded entries (dst_host becomes the IP literal) instead of logging them as unattributed.
CoreDNS never resolves a literal IP, so these dsts are absent from AllResolvableDomains (the Corefile zone set); the netlogger DomainSource is the union of the two (see Handler.ReverseDNSDomains). This mirrors mappingRoute's SeedIP condition in RoutesFromRules exactly — both walk TCPMappings + UDPMappings and key off net.ParseIP(dst).To4(); the TLS pass never seeds because it skips IP/CIDR destinations.
func ValidateDst ¶
ValidateDst checks that a destination is a valid lowercase domain name, wildcard domain, IP address, or CIDR block. Exported so CLI commands can pre-validate before attempting store mutations.
Domain validation is based on Go's net.isDomainName (RFC 1035 / RFC 1123 label constraints) with two deliberate deviations: uppercase is rejected to enforce normalized storage, and the root domain "." is not accepted. Underscores are allowed for SRV/DMARC compatibility.
func ValidateRule ¶ added in v0.9.8
func ValidateRule(r config.EgressRule) error
ValidateRule fully validates a single egress rule sourced from clawker.yaml (the launch path, via BootstrapServicesPreStart → FirewallAddRules) or a CLI `firewall add`. It checks destination syntax, the dynamic port spec, and every allow/deny field. A failure aborts rule ingestion — and therefore the container launch — so the CLI surfaces the bad rule to the user, instead of the rule being accepted as ADDED and then silently dropped at the later NormalizeAndDedup reconcile step.
Proto is intentionally NOT rejected: an unrecognized proto token is a deliberate soft-skip caught by the Envoy deny floor (a safety net, not a config error), so opaque L7 names for TCP pass-through stay valid.
Types ¶
type ALSConfig ¶ added in v0.9.0
ALSConfig configures the Envoy access logger's upstream cluster. MTLS=true targets the otel-collector's mTLS receiver on Port; MTLS=false omits the OTel sink + cluster (stdout-only) — infra services must never cross into the untrusted otel-collector:4317 lane reserved for agent containers.
type ActionFunc ¶
ActionFunc is the shape of every queued closure. It receives the queue's long-lived context — cancelled by Close — and returns a Result value on success or a wrapped sentinel error on failure. Closures that run for more than a few milliseconds MUST honor ctx.Done() so Close can drain in bounded time.
type ActionKind ¶
type ActionKind int
ActionKind classifies a queued action. Its Coalesces method decides whether consecutive same-kind items collapse into a single execution.
const ( ActionUnknown ActionKind = iota ActionBringup ActionTeardown ActionReconcile ActionRead ActionEnable ActionDisable ActionBypass )
func (ActionKind) Coalesces ¶
func (k ActionKind) Coalesces() bool
Coalesces reports whether consecutive submissions of this kind collapse into a single execution. Only ActionReconcile coalesces: every RPC mapped to it regenerates stack state from the current rules store, so drained submitters observe identical output. Per-container kinds (Enable, Disable, Bypass) carry distinct arguments per call and must run individually; Bringup, Teardown, and Read likewise execute one-by-one.
func (ActionKind) String ¶
func (k ActionKind) String() string
type ActionQueue ¶
type ActionQueue struct {
// contains filtered or unexported fields
}
ActionQueue serializes firewall actions behind a single worker goroutine. Items execute in strict FIFO order across kinds; consecutive items whose kind returns true from Coalesces collapse into one execution and every drained submitter receives the same result. Submit is close-safe: submissions accepted before Close was called run to completion; once Close has been called (even before it returns), further submissions receive ErrClosed. Close then blocks until the worker has drained every accepted item.
func NewActionQueue ¶
func NewActionQueue(log *logger.Logger) *ActionQueue
NewActionQueue constructs an ActionQueue and starts its worker goroutine. A nil logger is treated as logger.Nop().
func (*ActionQueue) Close ¶
func (q *ActionQueue) Close() error
Close stops accepting new submissions, waits for every submission accepted before Close returned to run to completion, and cancels the worker context so in-flight and drained closures can observe shutdown. Cancellation is published BEFORE the broadcast that wakes the worker so any item the worker subsequently pops enters execute() with an already-cancelled ctx — ctx-aware closures that short-circuit on cancellation will deliver ctx.Err() to their submitters instead of mutating stack/eBPF state mid-shutdown. Idempotent. Always returns nil — the error return matches io.Closer so callers can treat the queue as a Closer.
func (*ActionQueue) Submit ¶
func (q *ActionQueue) Submit(kind ActionKind, fn ActionFunc) <-chan ActionResult
Submit enqueues fn for execution under kind and returns a channel that will receive exactly one ActionResult. Once Close has been called, further submissions receive a pre-closed channel carrying ErrClosed; a nil fn likewise receives ErrNilClosure. Submit never panics and never waits on the worker to drain (the reply channel is buffered).
type ActionResult ¶
ActionResult is produced by a queued closure and delivered to every submitter whose action contributed to the execution. Exactly one of Value or Err is meaningful: on clean success Value carries the closure Result and Err is nil; on failure Err carries one or more wrapped sentinels and Value is nil.
type BypassResult ¶
type BypassResult struct{}
type ContainerResolver ¶
type ContainerResolver func(ctx context.Context, ref string) (id, cgroupPath string, exists bool, err error)
ContainerResolver looks up a container reference (name, short ID, or canonical long ID) against Docker and returns its canonical ID, the BPF-attachable cgroup path, and whether Docker still knows the container.
A NotFound result MUST come back as (_, _, false, nil) — a nil error with exists=false — so callers can distinguish "container is gone" from "we couldn't talk to Docker". A real Docker API failure surfaces as err.
type DisableResult ¶
type DisableResult struct{}
type EgressRulesFile ¶
type EgressRulesFile struct {
Rules []config.EgressRule `yaml:"rules" label:"Rules" desc:"Active egress firewall rules"`
}
EgressRulesFile is the top-level document type for storage.Store[T]. It persists the active set of project-level egress rules to disk.
func (EgressRulesFile) Fields ¶
func (f EgressRulesFile) Fields() storage.FieldSet
Fields implements storage.Schema for EgressRulesFile.
type EnableResult ¶
type EnableResult struct{}
type EnvoyConfig ¶ added in v0.9.8
type EnvoyConfig struct {
// contains filtered or unexported fields
}
EnvoyConfig is the growing deliverable: a generic Envoy bootstrap tree that permutations aggregate into (upsert by key), marshalled to YAML once. Storage is generic so a layer may attach any Envoy key/value; the small typed surface owns the structural invariants that, left to free-form writes, previously shipped a config Envoy rejects — cluster-name uniqueness and filter_chain_match uniqueness — failing generation CLOSED on a violation.
func NewEnvoyConfig ¶ added in v0.9.8
func NewEnvoyConfig() *EnvoyConfig
NewEnvoyConfig returns an empty accumulator.
func (*EnvoyConfig) AddCluster ¶ added in v0.9.8
func (c *EnvoyConfig) AddCluster(cluster map[string]any) error
AddCluster registers cluster, deduping by "name". An identical re-add is a no-op; a conflicting body is an error.
func (*EnvoyConfig) AddListener ¶ added in v0.9.8
func (c *EnvoyConfig) AddListener(listener map[string]any) error
AddListener stores a fully pre-built listener map (its own filter_chains baked in) under its "name" field — the listener peer of AddCluster, for a once-per-generation listener that the layer/chain machinery doesn't build (e.g. the health-check listener). listenerList emits base verbatim when no chains are attached, so the baked-in filter_chains survive. Conflicting redefinition of an existing name is an error; an identical re-add is a no-op.
func (*EnvoyConfig) Bytes ¶ added in v0.9.8
func (c *EnvoyConfig) Bytes() ([]byte, error)
Bytes assembles the bootstrap tree (listeners and clusters name-sorted) and marshals it to YAML.
func (*EnvoyConfig) ClaimPermutation ¶ added in v0.9.8
func (c *EnvoyConfig) ClaimPermutation(key string) bool
ClaimPermutation records key and reports whether it is newly seen (false on a repeat), so the orchestrator can skip a duplicate permutation.
func (*EnvoyConfig) EnsureListener ¶ added in v0.9.8
func (c *EnvoyConfig) EnsureListener(name, address string, port int)
EnsureListener returns (creating on first call, bound to address:port) the named listener. Idempotent — the first call's address wins.
func (*EnvoyConfig) EnsureQUICListener ¶ added in v0.9.8
func (c *EnvoyConfig) EnsureQUICListener(name, address string, port int)
EnsureQUICListener returns (creating on first call) the named UDP/QUIC listener, bound to address:port over UDP with quic_options. Idempotent — the first call wins. The QUIC peer of EnsureListener: filter chains attached here carry a QuicDownstreamTransport socket and an HTTP/3 HCM.
func (*EnvoyConfig) EnsureRawUDPListener ¶ added in v0.9.8
func (c *EnvoyConfig) EnsureRawUDPListener(name, address string, port int)
EnsureRawUDPListener creates (first call wins) a plain UDP listener for opaque datagram forwarding — a UDP socket_address with NO quic_options (the raw-udp peer of EnsureQUICListener). The udp_proxy listener_filter and its pinned route are attached by the terminal layer via SetListenerField; this listener carries NO filter_chains (matching examples/udp/envoy.yaml).
func (*EnvoyConfig) HasListener ¶ added in v0.9.8
func (c *EnvoyConfig) HasListener(name string) bool
HasListener reports whether the named listener has been created.
func (*EnvoyConfig) SetAdmin ¶ added in v0.9.8
func (c *EnvoyConfig) SetAdmin(admin map[string]any)
SetAdmin sets the top-level admin block (last write wins).
func (*EnvoyConfig) SetListenerField ¶ added in v0.9.8
func (c *EnvoyConfig) SetListenerField(listener, key string, value any) error
SetListenerField sets a top-level field on a listener (e.g. listener_filters).
func (*EnvoyConfig) SetUnmatchedDeny ¶ added in v0.9.8
func (c *EnvoyConfig) SetUnmatchedDeny(listener string, chain map[string]any) error
SetUnmatchedDeny installs the listener-level default_filter_chain — the terminal reached when no chain matches (the zero-layer deny). Last write wins.
type EnvoyPorts ¶
type EnvoyPorts struct {
EgressPort int // Main shared egress listener port.
TCPPortBase int // Starting port for the per-rule TCP/SSH listeners.
UDPPortBase int // Starting port for the per-rule raw-UDP (udp_proxy) listeners.
HealthPort int // Dedicated health-check listener port.
}
EnvoyPorts holds the port layout for the Envoy proxy.
func (EnvoyPorts) Validate ¶
func (p EnvoyPorts) Validate() error
Validate checks that all ports are in valid range and no two ports collide.
type Handler ¶
type Handler struct {
adminv1.UnimplementedAdminServiceServer
// contains filtered or unexported fields
}
Handler implements adminv1.AdminServiceServer for the firewall domain. Every Firewall* RPC submits its body as a closure to a single shared ActionQueue so rapid-fire calls don't collide mid-restart (see initiative memory `firewall-queue-initiative` for the full design). Rule-CRUD and rotate-CA RPCs split store-side work (pre-Submit, synchronous) from stack reconcile work (queued), so a durable rule mutation is never lost even when the subsequent reload fails.
func NewHandler ¶
func NewHandler(deps HandlerDeps) *Handler
NewHandler wires a firewall Handler. Panics on missing EBPF, Resolver, or Queue — every RPC routes through the queue and hits eBPF/Resolver, so nil there would surface as a confusing nil-deref deep inside the gRPC interceptor chain. Stack / Store / Cfg are optional at construction so tests that only exercise the ebpf-backed RPCs can skip them; calls that need them fall through to a panic at the first nil access with a clear line number.
func (*Handler) AllResolvableDomains ¶ added in v0.9.3
AllResolvableDomains returns every domain name CoreDNS will serve a zone for under the current firewall rule set — the union of allow-rule destinations (after normalization, skipping IP/CIDR destinations and deny rules) and the internal hosts CoreDNS forwards out of band (`docker.internal` + the monitoring service hostnames). The set is constructed with the same passes GenerateCorefile uses, so the returned slice and the zones in the active Corefile are identical by construction. Order is unspecified.
netlogger's reverse-DNS map calls this on its refresh timer to rebuild the `domain_hash → domain` table dnsbpf populates as it answers queries. Reads bypass the action queue: an eventually consistent view (lagging by at most one refresh interval) is fine for attribution on security telemetry; queue contention would buy nothing observable.
func (*Handler) CancelAllBypassTimers ¶
CancelAllBypassTimers stops every pending dead-man timer and clears the bypass-timers map. Part of INV-B2-007 drain-to-zero: cancelling before eBPF FlushAll stops scheduled Enables from firing against maps that are about to be emptied. A fire goroutine past timer.Stop's check will submit to the queue; after queue.Close that submission returns ErrClosed and is a harmless retry-exhausted log. Returns the count cancelled.
func (*Handler) FirewallAddRules ¶
func (h *Handler) FirewallAddRules(ctx context.Context, req *adminv1.FirewallAddRulesRequest) (*adminv1.FirewallAddRulesResult, error)
FirewallAddRules persists new egress rules then reconciles the stack. Store mutation is synchronous and pre-Submit so the rule is durable the moment the RPC accepts it; the queued closure then regenerates Envoy/CoreDNS config and restarts both. When the stack is down at queue-time the closure short-circuits to StackReloadResult{Restarted: false} — the rule is still saved, next FirewallInit picks it up.
func (*Handler) FirewallBypass ¶
func (h *Handler) FirewallBypass(ctx context.Context, req *adminv1.FirewallBypassRequest) (*adminv1.FirewallBypassResult, error)
FirewallBypass = Disable (queued) + CP dead-man timer that submits a queued Enable on expiry. The restore path reuses the same drift guard as direct FirewallEnable so enforcement returns on the container's current cgroup_id, not the one it had at bypass-time.
func (*Handler) FirewallDisable ¶
func (h *Handler) FirewallDisable(ctx context.Context, req *adminv1.FirewallDisableRequest) (*adminv1.FirewallDisableResult, error)
FirewallDisable sets the per-container BPF bypass flag. Pre-Submit resolves the target cgroup_id (or falls back to the last-known value when Docker says the container is gone); the queued closure performs the ebpf.Disable.
func (*Handler) FirewallEnable ¶
func (h *Handler) FirewallEnable(ctx context.Context, req *adminv1.FirewallEnableRequest) (*adminv1.FirewallEnableResult, error)
FirewallEnable enrolls a container. Pre-Submit resolves container_id → cgroup_path and builds the BPF container_config from CP-side state (network discovery, host-proxy resolution, egress port); the queued closure installs the resulting config via ebpf.Install and cancels any pending bypass timer.
func (*Handler) FirewallInit ¶
func (h *Handler) FirewallInit(ctx context.Context, _ *adminv1.FirewallInitRequest) (*adminv1.FirewallInitResult, error)
FirewallInit brings the firewall stack (Envoy + CoreDNS) up via a queued bringup action. BPF programs are loaded once at CP startup via ebpf.Manager.Load; this RPC is the idempotent "stack up" signal.
After the stack is healthy, Init re-enrolls every running managed agent it can find. On a cold CP start that follows a previous CP's FlushAll, container_map is empty — without re-enrollment, long-lived agents that outlived the previous CP would egress unenforced (fail-open by BPF design). Re-enrollment is in-closure so it serializes with concurrent Enable/Disable/Bypass through the same ActionBringup work unit.
func (*Handler) FirewallListRules ¶
func (h *Handler) FirewallListRules(ctx context.Context, _ *adminv1.FirewallListRulesRequest) (*adminv1.FirewallListRulesResult, error)
FirewallListRules returns the current normalized+deduped rule set. Routed through the queue under ActionRead so a read never races ahead of pending writes (read-after-write consistency).
func (*Handler) FirewallReload ¶
func (h *Handler) FirewallReload(ctx context.Context, _ *adminv1.FirewallReloadRequest) (*adminv1.FirewallReloadResult, error)
FirewallReload regenerates configs and restarts Envoy+CoreDNS without mutating the rule set. No pre-Submit work — it is a pure reconcile signal against the current store contents.
func (*Handler) FirewallRemove ¶
func (h *Handler) FirewallRemove(ctx context.Context, _ *adminv1.FirewallRemoveRequest) (*adminv1.FirewallRemoveResult, error)
FirewallRemove is global teardown. Pre-Submit: cancel pending bypass timers so they can't fire against maps that are about to be flushed. Queued closure: stop stack, flush eBPF state, delete generated config files on disk, clear storedCgroupID. Unlike the pre-queue implementation, the egress-rules file is preserved — the store is authoritative across teardown so a user's removals after `firewall down` apply to the next `firewall up`.
func (*Handler) FirewallRemoveRule ¶
func (h *Handler) FirewallRemoveRule(ctx context.Context, req *adminv1.FirewallRemoveRuleRequest) (*adminv1.FirewallRemoveRuleResult, error)
FirewallRemoveRule deletes a single rule matched by (dst, proto, port) pre-Submit then reconciles the stack. A miss on the store lookup returns Status=REMOVE_RULE_STATUS_NOT_FOUND on the result (NOT a codes.NotFound gRPC error) so a typo or wrong-proto/port surfaces as a typed outcome on the wire — the CLI renders the not-found message and exits non-zero. Genuine store-I/O failures still come back as gRPC errors. No ValidateDst here: anything that fails to match an existing key — typo, malformed hostname, or legitimate absence — collapses into the same NOT_FOUND outcome, which is exactly the behavior the CLI needs to render.
func (*Handler) FirewallResolveHostname ¶
func (h *Handler) FirewallResolveHostname(ctx context.Context, req *adminv1.FirewallResolveHostnameRequest) (*adminv1.FirewallResolveHostnameResult, error)
FirewallResolveHostname performs a DNS lookup from the CP's network namespace — used to resolve host.docker.internal during per-container enroll so the BPF container_config holds a routable address.
func (*Handler) FirewallRotateCA ¶
func (h *Handler) FirewallRotateCA(ctx context.Context, _ *adminv1.FirewallRotateCARequest) (*adminv1.FirewallRotateCAResult, error)
FirewallRotateCA regenerates the MITM CA + per-domain certs pre-Submit, then reconciles the stack so Envoy picks up the new chain. Cert regen is synchronous so the CLI sees a clean ErrCertRegen if the disk write fails, leaving the running stack on the prior certificates.
func (*Handler) FirewallStatus ¶
func (h *Handler) FirewallStatus(ctx context.Context, _ *adminv1.FirewallStatusRequest) (*adminv1.FirewallStatusResult, error)
FirewallStatus returns a health snapshot.
func (*Handler) FirewallSyncRoutes ¶
func (h *Handler) FirewallSyncRoutes(ctx context.Context, _ *adminv1.FirewallSyncRoutesRequest) (*adminv1.FirewallSyncRoutesResult, error)
FirewallSyncRoutes is a break-glass re-sync of the BPF route_map. After the queue landed, it regenerates routes from the current store (rather than trusting caller-supplied routes) — coalescing with concurrent AddRules/Reload calls would otherwise silently discard a caller's stale route set. reconcileStackClosure already syncs routes, so routing through ActionReconcile gives SyncRoutes the stronger "stack and route_map are consistent with the store" guarantee at a cost of one extra container restart.
func (*Handler) ReverseDNSDomains ¶ added in v0.10.2
ReverseDNSDomains returns every string whose ebpf.DomainHash can appear in the BPF dns_cache: the CoreDNS-served zones ([AllResolvableDomains]) plus the IP-literal seeds [SyncRoutes] writes for bare-IP routes (SeedDomainsFromRules). It is the netlogger reverse-DNS DomainSource.
AllResolvableDomains alone is incomplete: it deliberately omits IP/CIDR rules (they are not CoreDNS zones), but SyncRoutes still seeds dns_cache[ip] = DomainHash(ip) for every bare-IP rule. Sourcing the reverse map from the domain set only left each such seed permanently unattributed (event=netlogger_reverse_dns_unattributed every refresh tick) and stamped its egress records with an empty dst_host despite the destination being known. Unioning the seeds in attributes those records to the IP literal and silences the false-positive warning. Order is unspecified; the two sets never collide (an IP literal is never a domain zone).
The rule snapshot is read once and feeds both the zone derivation and the IP-seed derivation, so the two halves can never straddle a mid-flight rule mutation (and the normalize pass runs once, not twice).
type HandlerDeps ¶
type HandlerDeps struct {
EBPF ebpf.EBPFManager
Stack StackLifecycle
Store *storage.Store[EgressRulesFile]
Cfg config.Config
Resolver ContainerResolver
Log *logger.Logger
Queue *ActionQueue
// Bus is the overseer bus the handler publishes ebpf-axis lifecycle
// events on after a successful FirewallEnable. Nil-tolerant for unit
// tests that exercise the RPC surface without a running bus —
// FirewallEnable simply skips the publish when Bus is nil.
Bus *overseer.Overseer
// CertDirFn optionally overrides FirewallCertSubdir resolution —
// tests pass a temp dir so RotateCA does not touch the real data path.
// nil defaults to cfg.FirewallCertSubdir.
CertDirFn func() (string, error)
// ListAgents returns canonical container IDs of every running
// managed agent the CP knows about. FirewallInit uses it to rebuild
// per-container enforcement after a CP restart: FlushAll wipes
// container_map on shutdown, so agents that outlived the previous
// CP instance would otherwise egress unenforced until they were
// restarted. Nil means "no re-enrollment" (test wiring and flows
// that never want Init to touch agent state).
ListAgents func(ctx context.Context) ([]string, error)
}
HandlerDeps bundles the collaborators Handler needs. Using a deps struct keeps the constructor stable as future domain handlers grow.
type HealthTimeoutError ¶
HealthTimeoutError is returned when a firewall stack health wait exceeds its deadline. Err wraps one or more of the stack health sentinel errors.
func (*HealthTimeoutError) Error ¶
func (e *HealthTimeoutError) Error() string
func (*HealthTimeoutError) Unwrap ¶
func (e *HealthTimeoutError) Unwrap() error
type InitResult ¶
type InitResult struct {
EnvoyIP, CoreDNSIP, NetworkID string
}
InitResult captures the network topology EnsureRunning settled on.
type ListRulesResult ¶
type ListRulesResult struct {
Rules []config.EgressRule
}
ListRulesResult carries the normalized rule snapshot.
type NetworkInfo ¶
type NetworkInfo struct {
NetworkID string
Gateway netip.Addr
Subnet netip.Prefix
EnvoyIP string
CoreDNSIP string
CIDR string
}
NetworkInfo holds discovered state about the firewall Docker network.
func DiscoverNetwork ¶
func DiscoverNetwork(ctx context.Context, dc *docker.Client, cfg config.Config) (*NetworkInfo, error)
DiscoverNetwork inspects the firewall network and computes static IPs for Envoy and CoreDNS from the gateway address using config-defined octets.
The network must already exist — CLI `container start` ensures it via the whail EnsureNetwork container option before any firewall operation runs.
type OtelCertProvisioner ¶ added in v0.9.0
type OtelCertProvisioner interface {
// EnsureClient mints + writes per-service mTLS client material under
// the provisioner's destination directory, atomically. Re-runs
// overwrite in place. Returned paths are CP-container-FS absolute
// paths under destDir — Stack discards them and derives sibling
// Mount.Source from consts.HostFirewallOtelCertsDir, the host-FS
// twin of destDir via CP's firewall data bind-mount.
EnsureClient(svc string) (certPath, keyPath, caPath string, err error)
}
OtelCertProvisioner is the firewall-package view of the trusted-lane mTLS material provider. The concrete implementation lives in `internal/controlplane/otelcerts` (CP-level, outside the firewall package — see feedback_no_layering_violations.md). Tests pass a tiny fake; production wiring passes `*otelcerts.Service`.
May be nil — Stack tolerates a missing provisioner by skipping the mTLS material bind-mounts. Envoy omits the OTel access-log sink and the otel_collector_als cluster entirely (sender-side gate on als.MTLS in buildHTTPAccessLog / buildTCPAccessLog / buildClusters — no cross-lane emission to the untrusted otel-collector:4317 receiver that's reserved for agent containers). CoreDNS sees no CLAWKER_COREDNS_OTEL_ENDPOINT and installs noopEmitter. Stdout logs remain available via `docker logs` for triage, but the OpenSearch pipeline has no filelog receiver — the trusted OTLP push path is the only ingestion route, and it stays cold. This matches the CP-side degraded path (see cmd/clawker-cp/main.go: event= infra_issuer_unavailable).
type ResolveResult ¶
type ResolveResult struct {
Addresses []string
}
ResolveResult carries the answer set of a DNS lookup run inside the CP's netns.
type Stack ¶
type Stack struct {
// contains filtered or unexported fields
}
Stack manages the Envoy + CoreDNS container pair via Docker-outside-of- Docker from inside the control plane container. The CP container itself is created host-side by CLI bootstrap, not by Stack.
Stack is not safe for concurrent EnsureRunning + Stop calls; callers serialize via their own mutex.
func NewStack ¶
func NewStack(dc *docker.Client, cfg config.Config, log *logger.Logger, store *storage.Store[EgressRulesFile], otelCerts OtelCertProvisioner) *Stack
NewStack returns an initialized Stack. log may be nil (a Nop logger is substituted); the other dependencies are required — nil docker or cfg produces a nil Stack that panics at first use, which is preferable to silent no-ops. otelCerts may be nil — see OtelCertProvisioner.
func (*Stack) EnsureRunning ¶
EnsureRunning starts Envoy + CoreDNS if they are not already running. Idempotent: the method short-circuits per container when it finds the expected container already in the "running" state.
Ordering is fixed: ensure network → discover → write configs/certs → ensure images → ensure Envoy → ensure CoreDNS → wait healthy. CoreDNS's dnsbpf plugin opens the pinned dns_cache map at startup; the map is created by the CP's eBPF manager before Stack starts, so Stack does not touch BPF state here.
func (*Stack) EnvoyIP ¶
EnvoyIP, CoreDNSIP, NetworkID, and CIDR return the current network topology. They re-discover on every call; they are intended for display paths where the cost is negligible. On failure they return "" rather than an error — accessors never panic or block callers.
func (*Stack) NetworkInfo ¶
func (s *Stack) NetworkInfo(ctx context.Context) (*NetworkInfo, error)
NetworkInfo returns the current firewall network topology (Envoy/CoreDNS IPs, CIDR, gateway, network ID). Unlike the string accessors above it surfaces discovery errors — callers on the enforcement path (FirewallEnable) must fail loudly when topology is unknown rather than silently enrolling with zero values.
func (*Stack) Reload ¶
Reload regenerates configs and restarts Envoy + CoreDNS. Callers invoke this after rule mutations land in the store. If the stack is not currently running, Reload does nothing — the next EnsureRunning call will pick up the fresh configs.
Step-level failures are wrapped with their typed sentinel (ErrConfigRegen, ErrStackProbe, ErrEnvoyRestart, ErrCoreDNSRestart, ErrStackUnhealthy) and combined via errors.Join so the Handler's RPC wrapper (toStatus) can attach one errdetails.ErrorInfo per failed step. ErrConfigRegen short-circuits the rest — restarting against stale configs would just thrash. Envoy/CoreDNS restart failures are collected independently; WaitForHealthy runs only when both restarts succeeded (otherwise the primary signal is the restart failure, not the health probe's timeout).
func (*Stack) Status ¶
Status reports the current health of the stack plus rule count and network topology. Docker API errors propagate — callers distinguish "stack down" from "Docker unreachable".
func (*Stack) Stop ¶
Stop removes Envoy + CoreDNS. The clawker-net network and eBPF state are intentionally left intact: agent containers may still be attached to the network, and BPF links are owned by the CP's ebpf.Manager. The control plane container is owned by host-side bootstrap.
func (*Stack) WaitForHealthy ¶
WaitForHealthy polls Envoy and CoreDNS health endpoints until both return HTTP 200 or the context deadline expires. On deadline expiry the error wraps one or both of ErrEnvoyUnhealthy/ErrCoreDNSUnhealthy.
Probes hit clawker-net via internal container IPs — the CP shares the network, so host port forwarding is not required.
type StackLifecycle ¶
type StackLifecycle interface {
EnsureRunning(ctx context.Context) error
Stop(ctx context.Context) error
Reload(ctx context.Context) error
Status(ctx context.Context) (*Status, error)
NetworkInfo(ctx context.Context) (*NetworkInfo, error)
}
StackLifecycle is the subset of *Stack operations the Handler drives. Declared here rather than as a method set on *Stack alone so tests can swap in a lightweight fake — Handler orchestrates Envoy+CoreDNS lifecycle as part of FirewallInit/Remove/Reload/Status/AddRules/ RemoveRules, and unit tests should not have to spin up real containers to cover the RPC surface.
type StackReloadResult ¶
type StackReloadResult struct {
Restarted bool
}
StackReloadResult is produced by reconcileStackClosure. Restarted is true when the live Envoy+CoreDNS pair was reloaded; false when the stack was down at queue-time and only the on-disk state changed. Callers map this onto the wire field `stack_restarted`.
type Status ¶
type Status struct {
// Running is true only when every managed subsystem is up (Envoy,
// CoreDNS, control plane). Per-component booleans below disambiguate
// "partially up" from "fully down".
Running bool
// EnvoyHealth / CoreDNSHealth / CPHealth: container exists and is
// running. Deeper readiness (HTTP /healthz) is probed in WaitForHealthy.
EnvoyHealth bool
CoreDNSHealth bool
CPHealth bool
// RuleCount is the number of normalized/deduplicated egress rules
// currently loaded in the rules store.
RuleCount int
// EnvoyIP / CoreDNSIP / NetworkID: discovered network topology. Empty
// strings mean the firewall network is not yet created — not an error.
EnvoyIP string
CoreDNSIP string
NetworkID string
}
Status is the firewall-domain health snapshot returned by Stack.Status.
The field set is intentionally minimal — any new attribute must be motivated by a concrete CLI or operator-facing need so this struct does not grow into a catch-all.
type StatusResult ¶
type StatusResult struct {
Status
}
StatusResult mirrors the firewall.Status summary.
type TCPMapping ¶
TCPMapping describes a per-destination eBPF DNAT entry for non-TLS traffic; each TCP/SSH rule gets a dedicated Envoy listener port.
func TCPMappings ¶
func TCPMappings(rules []config.EgressRule, ports EnvoyPorts) []TCPMapping
TCPMappings computes TCP/SSH port mappings from egress rules. Deterministic. Consumed by the generator (listener layout) and rules_store.RoutesFromRules (eBPF DNAT route_map) — the two must stay in lockstep.
func UDPMappings ¶ added in v0.9.8
func UDPMappings(rules []config.EgressRule, ports EnvoyPorts) []TCPMapping
UDPMappings computes raw-UDP port mappings from egress rules — the udp_proxy peer of TCPMappings. Deterministic, indexed from ports.UDPPortBase. Consumed by the generator's raw-UDP listener layout AND by RoutesFromRules, which projects each mapping into an L4ProtoUDP route_map entry so the eBPF connect4/sendmsg4 SOCK_DGRAM path redirects the datagram to this dedicated udp_proxy listener (mirroring how RoutesFromRules mirrors TCPMappings).
type TeardownResult ¶
type TeardownResult struct{}
TeardownResult, EnableResult, DisableResult, BypassResult are empty markers — their RPCs report success/failure only.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package ebpf provides eBPF-based traffic routing for clawker containers.
|
Package ebpf provides eBPF-based traffic routing for clawker containers. |
|
cmd
command
ebpf-manager is the entrypoint binary for the clawker eBPF manager container.
|
ebpf-manager is the entrypoint binary for the clawker eBPF manager container. |
|
netlogger
Package netlogger drains the BPF events_ringbuf, enriches each record with userspace attribution ({container_id, agent, project, domain}), and hands the result to a Sink.
|
Package netlogger drains the BPF events_ringbuf, enriches each record with userspace attribution ({container_id, agent, project, domain}), and hands the result to a Sink. |