firewall

Documentation

Overview

Package firewall provides iptables integration for automated response actions. It wraps the coreos/go-iptables library to provide a safe, managed interface for creating and removing firewall rules in response to security detections.

Index

• Constants
• func IsValidActionType(actionType string) bool
• type ActionType
• type BlockConfig
  • func DefaultBlockConfig() *BlockConfig
• type BlockEntry
  • func (b *BlockEntry) IsExpired() bool
• type LogConfig
  • func DefaultLogConfig() *LogConfig
• type Manager
  • func NewManager(config *ManagerConfig) (*Manager, error)
  • func (m *Manager) AddToWhitelist(target string)
  • func (m *Manager) BlockCIDR(cidr string, config *BlockConfig) error
  • func (m *Manager) BlockIP(ip string, config *BlockConfig) error
  • func (m *Manager) Close() error
  • func (m *Manager) Flush() error
  • func (m *Manager) GetActiveBlocks() []*BlockEntry
  • func (m *Manager) GetStats() map[string]uint64
  • func (m *Manager) IsBlocked(ip string) bool
  • func (m *Manager) RemoveFromWhitelist(target string)
  • func (m *Manager) UnblockCIDR(cidr string) error
  • func (m *Manager) UnblockIP(ip string) error
• type ManagerConfig
  • func DefaultManagerConfig() *ManagerConfig
• type Protocol
• type RateLimitConfig
  • func DefaultRateLimitConfig() *RateLimitConfig
• type Stats

Constants

const (
	// DefaultBlockDurationConfig is the default duration for blocks if not specified.
	DefaultBlockDurationConfig = 30 * time.Minute

	// DefaultChainName is the custom chain name for netcap-managed rules.
	DefaultChainNameConst = "NETCAP"

	// DefaultCleanupIntervalConst is how often expired blocks are cleaned up.
	DefaultCleanupIntervalConst = 1 * time.Minute
)

const (
	DefaultChainName       = DefaultChainNameConst
	DefaultCleanupInterval = DefaultCleanupIntervalConst
	DefaultBlockDuration   = DefaultBlockDurationConfig
)

Type aliases for backward compatibility

Functions

func IsValidActionType

func IsValidActionType(actionType string) bool

IsValidActionType checks if an action type is valid.

Types

type ActionType

type ActionType string

ActionType represents the type of firewall action.

const (
	// ActionTypeBlock blocks traffic (DROP).
	ActionTypeBlock ActionType = "iptables_block"

	// ActionTypeReject rejects traffic with ICMP response.
	ActionTypeReject ActionType = "iptables_reject"

	// ActionTypeRateLimit rate-limits traffic.
	ActionTypeRateLimit ActionType = "iptables_rate_limit"

	// ActionTypeLog logs matching traffic.
	ActionTypeLog ActionType = "iptables_log"

	// ActionTypeAccept explicitly accepts traffic.
	ActionTypeAccept ActionType = "iptables_accept"
)

type BlockConfig

type BlockConfig struct {
	// Target specifies what to block: "source" or "destination"
	Target string

	// Duration is how long the block should last (0 = permanent until cleanup)
	Duration time.Duration

	// Chain is the iptables chain to use (INPUT, FORWARD, OUTPUT)
	// This is informational as we use a custom chain
	Chain string

	// Action is DROP or REJECT
	Action string

	// RuleName is the name of the rule that triggered this block
	RuleName string

	// Reason is a human-readable reason for the block
	Reason string
}

BlockConfig configures a block action.

func DefaultBlockConfig

func DefaultBlockConfig() *BlockConfig

DefaultBlockConfig returns a default block configuration.

type BlockEntry

type BlockEntry struct {
	// IP is the blocked IP address.
	IP string

	// CIDR is the blocked CIDR range (if blocking a range).
	CIDR string

	// CreatedAt is when the block was created.
	CreatedAt time.Time

	// ExpiresAt is when the block will automatically be removed (zero means permanent).
	ExpiresAt time.Time

	// RuleName is the netcap rule that triggered this block.
	RuleName string

	// Reason is a human-readable reason for the block.
	Reason string

	// Chain is the iptables chain where the rule was added.
	Chain string

	// Target is whether this blocks source or destination.
	Target string

	// Action is DROP or REJECT.
	Action string
}

BlockEntry represents an active firewall block.

func (*BlockEntry) IsExpired

func (b *BlockEntry) IsExpired() bool

IsExpired returns true if the block has expired.

type LogConfig

type LogConfig struct {
	// Target specifies what to log: "source" or "destination"
	Target string

	// Prefix is the log prefix for identifying netcap logs
	Prefix string

	// Level is the log level (0-7)
	Level int

	// RuleName is the name of the rule that triggered this log
	RuleName string
}

LogConfig configures logging actions.

func DefaultLogConfig

func DefaultLogConfig() *LogConfig

DefaultLogConfig returns a default log configuration.

type Manager

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

Manager handles iptables rule management with automatic cleanup.

func NewManager

func NewManager(config *ManagerConfig) (*Manager, error)

NewManager creates a new firewall manager.

func (*Manager) AddToWhitelist

func (m *Manager) AddToWhitelist(target string)

AddToWhitelist adds an IP or CIDR to the whitelist.

func (*Manager) BlockCIDR

func (m *Manager) BlockCIDR(cidr string, config *BlockConfig) error

BlockCIDR adds an iptables rule to block a CIDR range.

func (*Manager) BlockIP

func (m *Manager) BlockIP(ip string, config *BlockConfig) error

BlockIP adds an iptables rule to block an IP address.

func (*Manager) Close

func (m *Manager) Close() error

Close cleans up all netcap-managed iptables rules and stops the cleanup goroutine.

func (*Manager) Flush

func (m *Manager) Flush() error

Flush removes all rules from the NETCAP chain.

func (*Manager) GetActiveBlocks

func (m *Manager) GetActiveBlocks() []*BlockEntry

GetActiveBlocks returns all currently active blocks.

func (*Manager) GetStats

func (m *Manager) GetStats() map[string]uint64

GetStats returns current statistics.

func (*Manager) IsBlocked

func (m *Manager) IsBlocked(ip string) bool

IsBlocked checks if an IP is currently blocked.

func (*Manager) RemoveFromWhitelist

func (m *Manager) RemoveFromWhitelist(target string)

RemoveFromWhitelist removes an IP or CIDR from the whitelist.

func (*Manager) UnblockCIDR

func (m *Manager) UnblockCIDR(cidr string) error

UnblockCIDR removes a block for a CIDR range.

func (*Manager) UnblockIP

func (m *Manager) UnblockIP(ip string) error

UnblockIP removes a block for an IP address.

type ManagerConfig

type ManagerConfig struct {
	// ChainName is the custom chain name (default: NETCAP).
	ChainName string

	// EnableIPv4 enables IPv4 iptables (default: true).
	EnableIPv4 bool

	// EnableIPv6 enables IPv6 ip6tables (default: true).
	EnableIPv6 bool

	// CleanupInterval is how often to check for expired blocks.
	CleanupInterval time.Duration

	// DefaultDuration is the default block duration if not specified.
	DefaultDuration time.Duration

	// Whitelist is a list of IPs/CIDRs that should never be blocked.
	Whitelist []string

	// DryRun if true, logs actions but doesn't execute them.
	DryRun bool

	// Verbose enables verbose logging.
	Verbose bool
}

ManagerConfig holds configuration for the firewall manager.

func DefaultManagerConfig

func DefaultManagerConfig() *ManagerConfig

DefaultManagerConfig returns a sane default configuration.

type Protocol

type Protocol int

Protocol represents the IP protocol version.

const (
	// ProtocolIPv4 represents IPv4.
	ProtocolIPv4 Protocol = iota
	// ProtocolIPv6 represents IPv6.
	ProtocolIPv6
)

type RateLimitConfig

type RateLimitConfig struct {
	// Target specifies what to rate limit: "source" or "destination"
	Target string

	// Rate is the rate limit (e.g., "10/minute", "100/second")
	Rate string

	// Burst is the initial burst allowance
	Burst int

	// Duration is how long the rate limit should last
	Duration time.Duration

	// Chain is the iptables chain to use
	Chain string

	// RuleName is the name of the rule that triggered this rate limit
	RuleName string
}

RateLimitConfig configures rate limiting.

func DefaultRateLimitConfig

func DefaultRateLimitConfig() *RateLimitConfig

DefaultRateLimitConfig returns a default rate limit configuration.

type Stats

type Stats struct {
	BlocksCreated  uint64
	BlocksRemoved  uint64
	BlocksExpired  uint64
	DuplicatesSkip uint64
	WhitelistSkip  uint64
	Errors         uint64
}

Stats tracks firewall manager statistics.