config

package
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Apr 28, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	PortHTTPS      = Port{Port: 443, Protocol: ProtocolTCP}
	PortHTTP       = Port{Port: 80, Protocol: ProtocolTCP}
	PortDNS        = Port{Port: 53, Protocol: ProtocolUDP}
	PortWireServer = Port{Port: 32526, Protocol: ProtocolTCP}
	PortICMP       = Port{Port: 0, Protocol: ProtocolICMP}
)

Common port definitions for infrastructure auto-allow rules. PortICMP carries Port=0 because ICMP has no port concept; the protocol field alone drives the BPF lookup.

Functions

func ProtocolsOverlap added in v1.2.0 

func ProtocolsOverlap(a, b ProtocolType) bool

ProtocolsOverlap returns true if two protocol types can match the same traffic. ProtocolAll overlaps with everything; TCP/UDP/ICMP only overlap with themselves.

Exported for cross-package use: pkg/events relies on this to decide whether a BPF event's L4 protocol is in a configured rule's allow set. Treat as part of the package's public contract.

Types

type Action 

type Action string

Action represents a firewall action (allow or deny). 

const (
	ActionAllow Action = "allow"
	ActionDeny  Action = "deny"
)

type AutoAddedType 

type AutoAddedType string

AutoAddedType indicates why a rule was auto-added by CargoWall infrastructure. 

const (
	AutoAddedTypeNone                AutoAddedType = ""
	AutoAddedTypeDNS                 AutoAddedType = "dns"
	AutoAddedTypeAzureInfrastructure AutoAddedType = "azure_infrastructure"
	AutoAddedTypeGitHubService       AutoAddedType = "github_service"
	AutoAddedTypeCodeCargoService    AutoAddedType = "codecargo_service"
)

type FirewallConfig 

type FirewallConfig struct {
	Rules []Rule `json:"rules"`
	// DefaultAction is the default action when no Rule matches (allow/deny)
	DefaultAction Action                `json:"defaultAction"`
	SudoLockdown  *SudoLockdownSettings `json:"sudoLockdown,omitempty"`
}

FirewallConfig represents the configuration for the L4 firewall

type Manager 

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

Manager manages the firewall configuration and hostname resolution

func NewConfigManager 

func NewConfigManager() *Manager

NewConfigManager creates a new configuration manager

func (*Manager) CheckIPRuleConflict 

func (cm *Manager) CheckIPRuleConflict(ip net.IP, hostname string, hostnameAction Action, hostnamePorts []Port) (Action, bool, string)

CheckIPRuleConflict checks if an IP has conflicting rules and returns the most restrictive action Returns: (action Action, hasConflict bool, conflictingRule string)

func (*Manager) EnsureDNSAllowed 

func (cm *Manager) EnsureDNSAllowed(ips []string)

EnsureDNSAllowed adds CIDR allow rules on port 53 for the given IPs so DNS infrastructure traffic is never blocked by the firewall.

func (*Manager) EnsureHostnameAllowed 

func (cm *Manager) EnsureHostnameAllowed(hostname string, ports []Port, autoAddedType AutoAddedType)

EnsureHostnameAllowed adds an allow rule for a hostname so that it (and its subdomains) are permitted through the firewall. This is used in GitHub Actions mode to auto-allow infrastructure like the Actions service.

func (*Manager) EnsureInfraAllowed 

func (cm *Manager) EnsureInfraAllowed(ips []string, ports []Port)

EnsureInfraAllowed adds CIDR allow rules for the given IPs on the specified ports, so infrastructure traffic (e.g. Azure wireserver/IMDS) is allowed only on the ports it actually needs.

func (*Manager) FindTrackedHostname 

func (cm *Manager) FindTrackedHostname(name string) string

FindTrackedHostname checks if name exactly matches a tracked hostname or is a subdomain of one (e.g. "lb-140-82-113-22-iad.github.com" → "github.com"). Returns the tracked hostname if found, otherwise "".

func (*Manager) ForwardMatchIP 

func (cm *Manager) ForwardMatchIP(ip string) string

ForwardMatchIP checks if any tracked hostname's cached IPs match the given IP. Uses the hostname cache instead of live DNS resolution to avoid blocking.

func (*Manager) GetAutoAllowedType 

func (cm *Manager) GetAutoAllowedType(ip string, port uint16, hostname string) AutoAddedType

GetAutoAllowedType checks if a connection (ip, port, hostname) matches an auto-added rule and returns the AutoAddedType. Hostname rules are checked first, then CIDR rules. Returns AutoAddedTypeNone if no auto-added rule matches.

func (*Manager) GetAutoAllowedTypeForHostname 

func (cm *Manager) GetAutoAllowedTypeForHostname(hostname string) AutoAddedType

GetAutoAllowedTypeForHostname checks if a hostname matches a hostname-based auto-added rule, ignoring port restrictions. This is used for tagging existing connections from /proc/net/tcp where port info is lost after deduplication.

func (*Manager) GetDefaultAction 

func (cm *Manager) GetDefaultAction() Action

GetDefaultAction returns the default action

func (*Manager) GetIPToHostnameMap 

func (cm *Manager) GetIPToHostnameMap() map[string]string

GetIPToHostnameMap returns a copy of the IP to hostname mapping This is used by the DNS server to reprocess cached hostnames after config load

func (*Manager) GetResolvedRules 

func (cm *Manager) GetResolvedRules() []ResolvedRule

GetResolvedRules returns the current resolved rules

func (*Manager) GetSudoLockdown 

func (cm *Manager) GetSudoLockdown() *SudoLockdownSettings

GetSudoLockdown returns the policy-sourced sudo lockdown settings, or nil if no sudo lockdown configuration was provided.

func (*Manager) GetTrackedHostnames 

func (cm *Manager) GetTrackedHostnames() map[string]Action

GetTrackedHostnames returns a copy of the tracked hostnames map (hostname -> action). This is used to proactively resolve hostnames so the reverse lookup cache is populated.

func (*Manager) LoadConfig 

func (cm *Manager) LoadConfig(path string) error

LoadConfig loads configuration from a file

func (*Manager) LoadConfigFromCargoWall 

func (cm *Manager) LoadConfigFromCargoWall(cargoWall *cargowallv1pb.CargoWallPolicy) error

LoadConfigFromCargoWall loads configuration from a protobuf CargoWall message

func (*Manager) LoadConfigFromRules 

func (cm *Manager) LoadConfigFromRules(rules []Rule, defaultAction Action) error

LoadConfigFromRules loads configuration from rules (for testing)

func (*Manager) LoadFromEnv 

func (cm *Manager) LoadFromEnv() error

LoadFromEnv loads configuration from environment variables. Environment variables:

  • CARGOWALL_DEFAULT_ACTION: "allow" or "deny" (default: "deny")
  • CARGOWALL_ALLOWED_HOSTS: comma-separated list of allowed hostnames (supports wildcards)
  • CARGOWALL_ALLOWED_CIDRS: comma-separated list of allowed CIDR blocks
  • CARGOWALL_BLOCKED_HOSTS: comma-separated list of blocked hostnames
  • CARGOWALL_BLOCKED_CIDRS: comma-separated list of blocked CIDR blocks

func (*Manager) LookupHostnameByIP 

func (cm *Manager) LookupHostnameByIP(ip string) string

LookupHostnameByIP finds the hostname associated with an IP address

func (*Manager) MatchHostnameRule added in v1.2.0 

func (cm *Manager) MatchHostnameRule(hostname string) (Action, []Port, string)

MatchHostnameRule returns the action, ports, and identifier of the most specific configured hostname rule that matches `hostname`. All three come from the same rule so callers can keep them coherent (the rule that allows the hostname also dictates which ports are allowed) and so audit fields can faithfully report which rule fired (e.g. `*.compute-1.amazonaws.com`, not the resolved `ec2-…` subdomain).

The third return is the rule's `Value` field — the hostname for non-pattern rules, the original glob string for pattern rules.

Match types considered: exact non-pattern hostnames, parent-domain rules where `hostname` is a subdomain, and glob patterns.

Precedence:

  1. Exact non-pattern hostname match wins outright.
  2. A deny pattern match wins over a parent-domain allow ("more specific wins").
  3. Otherwise: parent-domain match if any, else first allow-pattern match.

Among parent-domain matches the longest suffix wins (e.g. `foo.example.com` beats `example.com` for `bar.foo.example.com`). Among equal-length deny or allow patterns the first in config order wins.

Returns ("", nil, "") when no hostname rule matches.

The returned ports slice is a defensive copy — callers may freely retain or mutate it without affecting the live ruleset. The cost (one small alloc per call; rules typically carry a handful of ports) is negligible relative to the single O(n) scan of resolvedRules this function already does.

func (*Manager) UpdateDNSMapping 

func (cm *Manager) UpdateDNSMapping(hostname string, ip string)

UpdateDNSMapping adds a DNS mapping from an observed DNS response

type Port 

type Port struct {
	Port     uint16       `json:"port"`
	Protocol ProtocolType `json:"protocol"`
}

Port represents a firewall Port entry

type ProtocolType 

type ProtocolType string
const (
	ProtocolAll  ProtocolType = "all"
	ProtocolTCP  ProtocolType = "tcp"
	ProtocolUDP  ProtocolType = "udp"
	ProtocolICMP ProtocolType = "icmp"
)

type ResolvedRule 

type ResolvedRule struct {
	Type          RuleType         // "hostname" or "cidr"
	Value         string           // Original value (hostname or CIDR string)
	IPs           []net.IP         // For hostnames: resolved IPs. For CIDR: empty
	IPNet         *net.IPNet       // For CIDR blocks only
	Pattern       *hostnamePattern // Non-nil for hostname rules with glob wildcards
	Ports         []Port
	Action        Action
	AutoAddedType AutoAddedType // Why this rule was auto-added (empty for user-configured rules)
}

ResolvedRule represents a Rule with resolved IP addresses or CIDR blocks

func (*ResolvedRule) MatchesHostname added in v1.1.0 

func (r *ResolvedRule) MatchesHostname(hostname string) bool

MatchesHostname returns true if the hostname matches this hostname rule via glob pattern, exact match, or parent domain (subdomain) match.

type Rule 

type Rule struct {
	// Type can be "hostname" or "cidr"
	Type RuleType `json:"type"`
	// Value is the hostname or CIDR block
	Value string `json:"value"`
	// Ports is optional list of Port (empty means all Ports on TCP and UDP)
	Ports []Port `json:"ports,omitempty"`
	// Action is "allow" or "deny"
	Action Action `json:"action"`
	// AutoAddedType indicates why this rule was auto-added (empty for user-configured rules)
	AutoAddedType AutoAddedType `json:"autoAddedType,omitempty"`
}

Rule represents a firewall Rule

type RuleType 

type RuleType string

RuleType represents the type of a firewall rule. 

const (
	RuleTypeHostname RuleType = "hostname"
	RuleTypeCIDR     RuleType = "cidr"
)

type SudoLockdownSettings 

type SudoLockdownSettings struct {
	Enabled       bool     `json:"enabled"`
	AllowCommands []string `json:"allowCommands,omitempty"`
}

SudoLockdownSettings holds policy-sourced sudo lockdown configuration.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.