pf

package module
v0.0.0-...-5bd2d69 Latest Latest
Warning

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

 Go to latest Published: Mar 22, 2023 License: BSD-2-Clause Imports: 10 Imported by: 0

README

PF (Packet Filter)

GoDoc FreeBSD 10.3 FreeBSD 11 FreeBSD HEAD

The FreeBSD operating system has multiple packet filter build-in. One of the packet filters was ported from OpenBSD and is called pf (packetfilter).

Packet filtering restricts the types of packets that pass through network interfaces entering or leaving the host based on filter rules as described in. The packet filter can also replace addresses and ports of packets. Replacing source addresses and ports of outgoing packets is called NAT (Network Address Translation) and is used to connect an internal network (usually reserved address space) to an external one (the Internet) by making all connections to external hosts appear to come from the gateway. Replacing destination addresses and ports of incoming packets is used to redirect connections to different hosts and/or ports. A combination of both translations, bidirectional NAT, is also supported.

This go module enables easy access to the packet filter inside the kernel. The FreeBSD kernel module responsible for implementing pf is called pf.ko.

Since the kernel interface is different between the operating systems this version currently only works with FreeBSD.

The packet filter creates the pseudo-device node /dev/pf, it allows userland processes to control the behavior of the packet filter through an ioctl(2) interface. There are commands to enable and disable the filter, load rulesets, add and remove individual rules or state table entries, and retrieve statistics. The most commonly used functions are covered by this library.

Manipulations like loading a ruleset that involve more than a single ioctl(2) call require a so-called ticket, which prevents the occurrence of multiple concurrent manipulations. Tickets are modeled as transaction objects inside the library.

Working with pf directly on a remote connection can cause you to loose the connection in case of a programming error. Make sure you have a second way to access the system e.g. a serial console.

Testing

You need to be root to execute the tests.

make test

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var AllDynamicFlags = []DynamicFlag{
	DynamicFlagNetwork,
	DynamicFlagBroadcast,
	DynamicFlagPeer,
	DynamicFlagNoAlias,
}

AllDynamicFlags contains all danymic flags in usual order

View Source 
var Protocols = map[int]string{
	int(ProtocolAny):  "any",
	int(ProtocolICMP): "icmp",
	int(ProtocolTCP):  "tcp",
	int(ProtocolUDP):  "udp",
}

Default set of protocols.

Functions

This section is empty.

Types

type Action 

type Action uint8

Action that should be performed by pf 

const (
	// ActionPass Filter rule action to pass the traffic
	ActionPass Action = C.PF_PASS
	// ActionDrop Filter rule action to drop the traffic
	ActionDrop Action = C.PF_DROP

	// ActionScrub Scrub rule action to do scrubbing
	ActionScrub Action = C.PF_SCRUB
	// ActionNoScrub Srub rule action to not do scrubbing
	ActionNoScrub Action = C.PF_NOSCRUB

	// ActionNAT NAT rule action to to NAT
	ActionNAT Action = C.PF_NAT
	// ActionNoNAT NAT rule action to not do NAT
	ActionNoNAT Action = C.PF_NONAT

	// ActionBINAT NAT rule action to to BINAT
	ActionBINAT Action = C.PF_BINAT
	// ActionNoBINAT NAT rule action to not do BINAT
	ActionNoBINAT Action = C.PF_NOBINAT

	// ActionRDR RDR rule action to to RDR
	ActionRDR Action = C.PF_RDR
	// ActionNoRDR RDR rule action to not do RDR
	ActionNoRDR Action = C.PF_NORDR

	// ActionSynProxyDrop TODO
	ActionSynProxyDrop Action = C.PF_SYNPROXY_DROP

	// ActionDefer TODO is this divert?
	ActionDefer Action = C.PF_DEFER
)

func (Action) String 

func (a Action) String() string

type Address 

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

Address wraps the pf address (cgo)

func (Address) Any 

func (a Address) Any() bool

Any returns true if address represents any address

func (Address) Dynamic 

func (a Address) Dynamic() bool

Dynamic returns true if the address is dynamic based of the interface

func (Address) DynamicCount 

func (a Address) DynamicCount() int

DynamicCount returns the dynamic count

func (Address) DynamicFlag 

func (a Address) DynamicFlag(flag DynamicFlag) bool

DynamicFlag returns true if the flag is set for the address

func (Address) IPNet 

func (a Address) IPNet() *net.IPNet

IPNet returns the IPNetwork (IPv4/IPv6) of the address with mask

func (Address) IPRange 

func (a Address) IPRange() (net.IP, net.IP)

IPRange returns the start and end ip address of the range

func (Address) Interface 

func (a Address) Interface() string

Interface the name of the interface (e..g. used for dynamic address), returns an empty string if no interface is set

func (Address) Mask 

func (a Address) Mask() bool

Mask returns true if address is an ip address with mask

func (Address) NoRoute 

func (a Address) NoRoute() bool

NoRoute any address which is not currently routable

func (*Address) ParseCIDR 

func (a *Address) ParseCIDR(address string) error

ParseCIDR parses the passed address in CIDR notation and sets the extracted addess, mask and af. Id mask is missing IP address is assumed and mask is set to 32 IPv4 or 128 IPv6. May return a parse error if the address is invalid CIDR or IP address

func (Address) Range 

func (a Address) Range() bool

Range returns true if is an address range with start and end ip addr

func (*Address) SetAny 

func (a *Address) SetAny()

SetAny will turn the address into an any IP address

func (*Address) SetDynamicFlag 

func (a *Address) SetDynamicFlag(flag DynamicFlag)

SetDynamicFlag sets the dynamic interface flag

func (*Address) SetIPNet 

func (a *Address) SetIPNet(ipn *net.IPNet)

SetIPNet updates the ip address and mask and changes the type to AddressMask

func (*Address) SetIPRange 

func (a *Address) SetIPRange(start, end net.IP)

SetIPRange sets start and end address and turns object into ip range

func (*Address) SetInterface 

func (a *Address) SetInterface(itf string) error

SetInterface turns address into dynamic interface reference, type of interface reference can be changed with flags

func (*Address) SetNoRoute 

func (a *Address) SetNoRoute()

SetNoRoute turns address into no routeable address

func (*Address) SetTableName 

func (a *Address) SetTableName(name string) error

SetTableName turns address into table reference, using given name

func (*Address) SetURPFFailed 

func (a *Address) SetURPFFailed()

SetURPFFailed see URPFFailed for details

func (Address) String 

func (a Address) String() string

func (Address) Table 

func (a Address) Table() bool

Table returns true if the address references a table

func (Address) TableCount 

func (a Address) TableCount() int

TableCount returns the table count

func (Address) TableName 

func (a Address) TableName() string

TableName returns the name of the table or an empty string if not set

func (Address) URPFFailed 

func (a Address) URPFFailed() bool

URPFFailed any source address that fails a unicast reverse path forwarding (URPF) check, i.e. packets coming in on an interface other than that which holds the route back to the packet's source address

type AddressFamily 

type AddressFamily uint8

AddressFamily that should be filtered by pf (inet / inet6) 

const (
	// AddressFamilyAny Any matches any address family
	AddressFamilyAny AddressFamily = 0
	// AddressFamilyInet IPv4
	AddressFamilyInet AddressFamily = C.AF_INET
	// AddressFamilyInet6 IPv6
	AddressFamilyInet6 AddressFamily = C.AF_INET6
)

func (AddressFamily) String 

func (af AddressFamily) String() string

type Direction 

type Direction uint8

Direction in which the traffic flows 

const (
	// DirectionIn In incoming (ingress) traffic
	DirectionIn Direction = C.PF_IN
	// DirectionOut Out outgoing (egress) traffic
	DirectionOut Direction = C.PF_OUT
	// DirectionInOut InOut any direction (ingress/egress) traffic
	DirectionInOut Direction = C.PF_INOUT
)

func (Direction) String 

func (d Direction) String() string

type DynamicFlag 

type DynamicFlag uint8

DynamicFlag can be set on an address that is derived from an interface 

const (
	// DynamicFlagNetwork translates to the network(s) attached to the interface
	DynamicFlagNetwork DynamicFlag = C.PFI_AFLAG_NETWORK
	// DynamicFlagBroadcast translates to the interface's broadcast address(es).
	DynamicFlagBroadcast DynamicFlag = C.PFI_AFLAG_BROADCAST
	// DynamicFlagPeer translates to the point-to-point interface's peer address(es).
	DynamicFlagPeer DynamicFlag = C.PFI_AFLAG_PEER
	// DynamicFlagNoAlias do not include interface aliases.
	DynamicFlagNoAlias DynamicFlag = C.PFI_AFLAG_NOALIAS
)

func (DynamicFlag) String 

func (f DynamicFlag) String() string

type FlagHeader 

type FlagHeader uint8

FlagHeader is a TCP flag header. 

const (
	FlagFIN FlagHeader = C.TH_FIN
	FlagSYN FlagHeader = C.TH_SYN
	FlagRST FlagHeader = C.TH_RST
	FlagPSH FlagHeader = C.TH_PUSH
	FlagACK FlagHeader = C.TH_ACK
	FlagURG FlagHeader = C.TH_URG
	FlagECE FlagHeader = C.TH_ECE
	FlagCWR FlagHeader = C.TH_CWR
)

func (FlagHeader) String 

func (f FlagHeader) String() string

type Flags 

type Flags struct {
	Set   FlagHeader
	OutOf FlagHeader
}

Flags specifies which TCP flags must be Set from the flags in OutOf for a rule to match. See pf.conf(5) for an explanation.

func (Flags) Any 

func (f Flags) Any() bool

Any returns whether any TCP flags are accepted.

func (Flags) Default 

func (f Flags) Default() bool

Default returns whether the default TCP flags of S/SA are set.

func (Flags) String 

func (f Flags) String() string

type Protocol 

type Protocol uint8

Protocol that should be filtered by pf 

const (
	// ProtocolAny Any matches any protocol
	ProtocolAny Protocol = 0
	// ProtocolTCP TCP
	ProtocolTCP Protocol = C.IPPROTO_TCP
	// ProtocolUDP UDP
	ProtocolUDP Protocol = C.IPPROTO_UDP
	// ProtocolICMP ICMP
	ProtocolICMP Protocol = C.IPPROTO_ICMP
)

func (Protocol) String 

func (p Protocol) String() string

type Rule 

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

Rule wraps the pf rule (cgo)

func (Rule) Action 

func (r Rule) Action() Action

Action returns the action that is performed when rule matches

func (Rule) AddressFamily 

func (r Rule) AddressFamily() AddressFamily

AddressFamily returns the address family that is matched on

func (Rule) Direction 

func (r Rule) Direction() Direction

Direction returns the rule matching direction

func (Rule) Flags 

func (r Rule) Flags() Flags

Flags returns the TCP flags out of flagset that must be set for this rule to match. See pf.conf(5) for an explanation.

func (Rule) Log 

func (r Rule) Log() bool

Log returns true if matching packets are logged

func (Rule) LogAll 

func (r Rule) LogAll() bool

LogAll returns whether, for rules keeping state, all packets are logged instead of just the initial one.

func (Rule) LogIf 

func (r Rule) LogIf() uint8

LogIf returns the index of the pflog device to be used for logging.

func (*Rule) ParseDestination 

func (r *Rule) ParseDestination(dst, port string, neg bool) error

ParseDestination sets the destination (inet and inet6) based on the passed strings, if parsing failes err returned

func (*Rule) ParseSource 

func (r *Rule) ParseSource(src, port string, neg bool) error

ParseSource sets the source ip (inet and inet6) based on the passed strings, if parsing failes err is returned

func (Rule) Protocol 

func (r Rule) Protocol() Protocol

Protocol that is matched by the rule

func (Rule) Quick 

func (r Rule) Quick() bool

Quick returns true if matching packets are last to evaluate in the rule list

func (Rule) Return 

func (r Rule) Return() bool

Return returns whether TCP RST/ICMP UNREACHABLE is returned

func (*Rule) SetAction 

func (r *Rule) SetAction(a Action)

SetAction sets the action on the traffic flow

func (*Rule) SetAddressFamily 

func (r *Rule) SetAddressFamily(af AddressFamily)

SetAddressFamily sets the address family to match on

func (*Rule) SetDirection 

func (r *Rule) SetDirection(dir Direction)

SetDirection sets the direction the traffic flows

func (*Rule) SetFlags 

func (r *Rule) SetFlags(f Flags)

Flags sets the TCP flags out of flagset that must be set for this rule to match. See pf.conf(5) for an explanation.

func (*Rule) SetLog 

func (r *Rule) SetLog(enabled bool)

SetLog enables logging of packets to the log interface

func (*Rule) SetLogAll 

func (r *Rule) SetLogAll(enabled bool)

SetLogAll sets whether, for rules keeping state, all packets are logged instead of just the initial one.

func (*Rule) SetLogIf 

func (r *Rule) SetLogIf(i uint8)

SetLogIf sets the index of the pflog device to be used for logging.

func (*Rule) SetProtocol 

func (r *Rule) SetProtocol(p Protocol)

SetProtocol sets the protocol matcher of the rule if the

func (*Rule) SetQuick 

func (r *Rule) SetQuick(enabled bool)

SetQuick skips further evaluations if packet matched

func (*Rule) SetReturn 

func (r *Rule) SetReturn(t bool)

SetReturn sets whether TCP RST/ICMP UNREACHABLE is returned

func (*Rule) SetState 

func (r *Rule) SetState(s State)

SetState sets if the rule keeps state or not

func (Rule) State 

func (r Rule) State() State

State returns the state tracking configuration of the rule

func (Rule) Stats 

func (r Rule) Stats(stats *RuleStats)

Stats copies the rule statistics into the passed RuleStats struct

func (Rule) String 

func (r Rule) String() string

String returns the rule as pf.conf representation

type RuleStats 

type RuleStats struct {
	Evaluations         uint64
	PacketIn, PacketOut uint64
	BytesIn, BytesOut   uint64
}

RuleStats contains usefule pf rule statistics

type State 

type State uint8

State wether the packet filter should keep track of the packet flows (stateful packet filter) or not (stateless packet filter). 

const (
	// StateNo no state tracking with this rule
	StateNo State = 0
	// StateKeep track state inside the packet filter
	StateKeep State = C.PF_STATE_NORMAL
	// StateModulate keeps state and adds high quality random sequence numbers
	// for tcp
	StateModulate State = C.PF_STATE_MODULATE
	// StateSynproxy keeps state and creates new tcp connections to hide internals
	StateSynproxy State = C.PF_STATE_SYNPROXY
)

func (State) String 

func (s State) String() string

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.