Documentation
¶
Overview ¶
Package policy implements network policy enforcement for plexd mesh nodes.
Index ¶
- Constants
- func HandlePolicyUpdated(trigger ReconcileTrigger) api.EventHandler
- func ReconcileHandler(enforcer *Enforcer, wgMgr *wireguard.Manager, ...) reconcile.ReconcileHandler
- type Config
- type Enforcer
- type FirewallController
- type FirewallRule
- type NftablesController
- type PolicyEngine
- type ReconcileTrigger
Constants ¶
const DefaultChainName = "plexd-mesh"
DefaultChainName is the default iptables chain name for policy enforcement.
Variables ¶
This section is empty.
Functions ¶
func HandlePolicyUpdated ¶
func HandlePolicyUpdated(trigger ReconcileTrigger) api.EventHandler
HandlePolicyUpdated returns an api.EventHandler that triggers reconciliation when a policy_updated SSE event is received.
func ReconcileHandler ¶
func ReconcileHandler(enforcer *Enforcer, wgMgr *wireguard.Manager, localNodeID, localMeshIP, iface string) reconcile.ReconcileHandler
ReconcileHandler returns a reconcile.ReconcileHandler that enforces network policies. When policy or peer drift is detected it:
- Filters peers through the enforcer's policy engine.
- Applies firewall rules via the enforcer.
- Removes peers that are no longer allowed from WireGuard.
- Adds newly allowed peers to WireGuard.
Types ¶
type Config ¶
type Config struct {
// Enabled controls whether policy enforcement is active.
// Default: true (set by ApplyDefaults).
Enabled bool `yaml:"enabled"`
// ChainName is the iptables chain name for firewall rules.
ChainName string `yaml:"chain_name"`
}
Config holds the configuration for network policy enforcement.
func (*Config) ApplyDefaults ¶
func (c *Config) ApplyDefaults()
ApplyDefaults sets default values for zero-valued fields. On a zero-valued Config, Enabled defaults to true. To disable policy enforcement, set Enabled=false before or after calling ApplyDefaults.
type Enforcer ¶
type Enforcer struct {
// contains filtered or unexported fields
}
Enforcer combines a PolicyEngine with a FirewallController to enforce network policies on the local node.
func NewEnforcer ¶
func NewEnforcer(engine *PolicyEngine, firewall FirewallController, cfg Config, logger *slog.Logger) *Enforcer
NewEnforcer creates an Enforcer. The firewall parameter may be nil if no firewall backend is available; in that case only peer filtering is functional.
func (*Enforcer) ApplyFirewallRules ¶
func (e *Enforcer) ApplyFirewallRules(policies []api.Policy, localNodeID string, iface string, peersByID map[string]string) error
ApplyFirewallRules builds firewall rules from the given policies and applies them via the FirewallController. It is a no-op when enforcement is disabled or no firewall backend is available.
type FirewallController ¶
type FirewallController interface {
// EnsureChain creates the named iptables chain if it does not already exist.
EnsureChain(chain string) error
// ApplyRules replaces all rules in the named chain atomically.
ApplyRules(chain string, rules []FirewallRule) error
// FlushChain removes all rules from the named chain.
FlushChain(chain string) error
// DeleteChain deletes the named chain.
// Implementations must be idempotent: deleting a non-existent chain must return nil.
DeleteChain(chain string) error
}
FirewallController abstracts OS-level iptables operations for testability.
type FirewallRule ¶
type FirewallRule struct {
Interface string // network interface name
SrcIP string // source IP (CIDR or single IP)
DstIP string // destination IP (CIDR or single IP)
Port int // destination port (0 = any)
Protocol string // "tcp", "udp", or "" (any)
Action string // "allow" or "deny"
}
FirewallRule describes a single iptables-style packet filter rule.
func (*FirewallRule) Validate ¶
func (r *FirewallRule) Validate() error
Validate checks the rule for semantic correctness and returns an error if any field contains an invalid value.
type NftablesController ¶
type NftablesController struct {
// contains filtered or unexported fields
}
NftablesController implements FirewallController using the Linux nftables subsystem via the google/nftables netlink library. It manages a single IPv4 filter table ("plexd") and creates/destroys chains within it.
func NewNftablesController ¶
func NewNftablesController(logger *slog.Logger) *NftablesController
NewNftablesController returns a new NftablesController.
func (*NftablesController) ApplyRules ¶
func (c *NftablesController) ApplyRules(chain string, rules []FirewallRule) error
ApplyRules replaces all rules in the named chain atomically. It flushes the chain first, then adds each FirewallRule as an nftables rule with appropriate match expressions and verdict.
func (*NftablesController) DeleteChain ¶
func (c *NftablesController) DeleteChain(chain string) error
DeleteChain deletes the named chain. It is idempotent: deleting a non-existent chain returns nil.
func (*NftablesController) EnsureChain ¶
func (c *NftablesController) EnsureChain(chain string) error
EnsureChain creates the named nftables chain if it does not already exist. The chain is created as a base chain with a forward hook in the plexd filter table so that the kernel evaluates its rules for forwarded traffic.
func (*NftablesController) FlushChain ¶
func (c *NftablesController) FlushChain(chain string) error
FlushChain removes all rules from the named chain.
type PolicyEngine ¶
type PolicyEngine struct {
// contains filtered or unexported fields
}
PolicyEngine evaluates network policies to determine peer visibility and to generate firewall rules for the local node.
func NewPolicyEngine ¶
func NewPolicyEngine(logger *slog.Logger) *PolicyEngine
NewPolicyEngine creates a PolicyEngine with the given logger.
func (*PolicyEngine) BuildFirewallRules ¶
func (e *PolicyEngine) BuildFirewallRules(policies []api.Policy, localNodeID string, iface string, peersByID map[string]string) []FirewallRule
BuildFirewallRules converts policy rules into concrete FirewallRule entries for the local node. peersByID maps peer IDs to their mesh IPs. Only rules that reference localNodeID (or the wildcard "*") are included.
func (*PolicyEngine) FilterPeers ¶
func (e *PolicyEngine) FilterPeers(peers []api.Peer, policies []api.Policy, localNodeID string) []api.Peer
FilterPeers returns the subset of peers that the local node is allowed to communicate with according to the provided policies. If no policies are supplied, no peers are returned (deny-by-default).
type ReconcileTrigger ¶
type ReconcileTrigger interface {
TriggerReconcile()
}
ReconcileTrigger is satisfied by *reconcile.Reconciler.
Source Files