nufftables

README

'nuff tables!

The 'nufftables go module is a thin wrapper around Google's nftables to ease reasoning over the current state of tables, chains, rules, and expressions. If you just want to setup and remove netfilter chains and rules, then @google/nftables should already be sufficient most of the time.

CLI Tool Examples

• cmd/nftdump is a simple CLI tool that fetches all netfilter tables (in the host network namespace) and then dumps the corresponding objects to stdout.

• cmd/portfinder is another simple CLI tool that fetches the IPv4 and IPv6 netfilter tables and scans them for certain port forwarding expressions, dumping the forwarded port information found to stdout. Only port forwarding expressions using port range and target DNAT expressions (with an optional IP address compare) will be detected.

Example Usage

A simplified example, without proper error handling, that reasons about netfilter port match expressions:

import (
    "github.com/google/nftables"
    "github.com/google/nftables/expr"
    "github.com/thediveo/nufftables"
)

func main() {
    conn, _ := nftables.New(nftables.AsLasting())
    defer conn.CloseLasting()

    tables := nufftables.GetFamilyTables(conn, nufftables.TableFamilyIPv4)
    for _, chain := range tables.Table("nat", nufftables.TableFamilyIPv4) {
        for _, rule := range chain.Rules {
            if _, match := nufftables.OfType[*expr.Match](rule.Expressions()); match != nil {
                fmt.Printf("port match expression: %#v\n", match)
            }
        }
    }
}

Note

'nufftables supports versions of Go that are noted by the Go release policy, that is, major versions N and N-1 (where N is the current major version).

VSCode Tasks

The included nufftables.code-workspace defines the following tasks:

• View Go module documentation task: installs pkgsite, if not done already so, then starts pkgsite and opens VSCode's integrated ("simple") browser to show the go-plugger/v2 documentation.

Aux Tasks

• pksite service: auxilliary task to run pkgsite as a background service using scripts/pkgsite.sh. The script leverages browser-sync and nodemon to hot reload the Go module documentation on changes; many thanks to @mdaverde's Build your Golang package docs locally for paving the way. scripts/pkgsite.sh adds automatic installation of pkgsite, as well as the browser-sync and nodemon npm packages for the local user.
• view pkgsite: auxilliary task to open the VSCode-integrated "simple" browser and pass it the local URL to open in order to show the module documentation rendered by pkgsite. This requires a detour via a task input with ID "pkgsite".

Make Targets

• make: lists all targets.
• make coverage: runs all tests with coverage and then updates the coverage badge in README.md.
• make pkgsite: installs x/pkgsite, as well as the browser-sync and nodemon npm packages first, if not already done so. Then runs the pkgsite and hot reloads it whenever the documentation changes.
• make report: installs @gojp/goreportcard if not yet done so and then runs it on the code base.
• make test: runs all tests, once as root and then as the invoking user.

Copyright and License

Copyright 2022 Harald Albrecht, licensed under the Apache License, Version 2.0.

Documentation

Overview

Package nufftables is a thin wrapper around Google's nftables to ease reasoning over the current state of tables, chains, rules, and expressions. If you just want to setup and remove netfilter chains and rules, then google/nftables should be sufficient most of the time.

Information Model

nufftables' information model is basically that of netfilter and Google's nftables information model in particular, but with the hierarchy added in explicitly.

• Table wraps nftables.Table and references all Chain objects belonging to this table by name.
• Chain wraps nftables.Chain and contains all Rule objects for a particular chain, sorted by their nftables.Rule.Position. It also references its containing table.
• Rule wraps nftables.Rule with its Expressions. Rules reference the Chain they are contained in.

Reasoning About Expressions

To simplify “fishing” for expressions in rules, nufftables defines a set of convenience functions:

• OfType and OfTypeFunc for finding and returning the next expression of a specific type.
• OptionalOfType and OptionalOfTypeFunc work like OfType and OfTypeFunc but don't consider failures to find matching expression types to be a failure.

For instance,

remexprs, cmp := nufftables.OptionalOfTypeFunc(
  rule.Expressions(),
  func(cmp *expr.Cmp) bool {
    return cmp.Op == expr.CmpOpEq && len(cmp.Data) == 4
  })

returns the first expr.Cmp expression, if any, that is compares with a given IPv4 address for equality (expr.CmpOpEq). The (optional) search returns either the remaining expressions after a match, or the original slice of expressions in case of no match.

In contrast,

exprs, match := nufftables.OfTypeFunc(
  exprs, func(match *expr.Match) bool {...})

either returns the first match of an expr.Match expression together with the remaining expressions, or simply a nil match with nil expressions.

These basic building blocks allow to assemble a DSL for netfilter table expression reasoning, and to finally build high-level functions on top of this all. Please see the github.com/thediveo/nufftables/dsl and github.com/thediveo/nufftables/portfinder packages for more details.

Index

• type Chain
• type ChainHook
  • func (h ChainHook) Name(fam TableFamily) string
• type Expressions
  • func OfType[E expr.Any](exprs Expressions) (Expressions, E)
  • func OfTypeFunc[E expr.Any](exprs Expressions, f func(e E) bool) (Expressions, E)
  • func OptionalOfType[E expr.Any](exprs Expressions) (Expressions, E)
  • func OptionalOfTypeFunc[E expr.Any](exprs Expressions, f func(e E) bool) (Expressions, E)
• type Rule
  • func (r *Rule) Expressions() Expressions
• type Table
• type TableFamily
  • func (tf TableFamily) String() string
• type TableKey
• type TableMap
  • func GetAllTables(conn *nftables.Conn) (TableMap, error)
  • func GetFamilyTables(conn *nftables.Conn, family TableFamily) (TableMap, error)
  • func (t TableMap) Table(name string, family TableFamily) *Table
  • func (t TableMap) TableChain(tablename string, family TableFamily, chainname string) *Chain

Types

type Chain

type Chain struct {
	*nftables.Chain
	Table *Table
	Rules []Rule // sorted by rule position.
}

Chain represents a nftables.Chain together with all its Rule objects. Please note that Rules are automatically sorted by their nftables.Rule.Position.

type ChainHook

type ChainHook nftables.ChainHook

ChainHook wraps nftables.ChainHook to support clear-text string representations of chain hook values.

func (ChainHook) Name

func (h ChainHook) Name(fam TableFamily) string

Name returns the name of a chain hook, based on the (table's) address family the hook is used in.

The following chain hook names are currently defined:

• PREROUTING, or INGRESS (netdev table family only)
• INPUT
• FORWARD
• OUTPUT
• POSTROUTING

type Expressions

type Expressions []expr.Any

Expressions represents a slice of a rule's expr.Any expressions.

func OfType

func OfType[E expr.Any](exprs Expressions) (Expressions, E)

OfType returns the first expression of the specified type, together with the remaining expressions after the matching expression. The type parameter must be a pointer to a concrete expression type, such as *expr.Match, et cetera. If no match could be found, then a nil expressions list is returned together with a zero matching expression (~nil).

func OfTypeFunc

func OfTypeFunc[E expr.Any](exprs Expressions, f func(e E) bool) (Expressions, E)

OfTypeFunc returns the first expression of the specified type and additionally satisfying f(exprs[i]). If no match could be found, then a nil expressions list is returned together with a zero matching expression (~nil).

func OptionalOfType

func OptionalOfType[E expr.Any](exprs Expressions) (Expressions, E)

OptionalOfType returns the first expression of the specified type if found, otherwise a zero matching expression (~nil). If a match was found, then the remaining expressions are returned, otherwise the original expressions.

func OptionalOfTypeFunc

func OptionalOfTypeFunc[E expr.Any](exprs Expressions, f func(e E) bool) (Expressions, E)

OptionalOfTypeFunc returns the first expression of the specified type and satisfying f(exprs[i]), otherwise a zero matching expression (~nil). If a match was found, then the remaining expressions are returned, otherwise the original expressions.

type Rule

type Rule struct {
	*nftables.Rule
	Chain *Chain
}

Rule is a nftables.Rule belonging to a Chain.

func (*Rule) Expressions

func (r *Rule) Expressions() Expressions

Expressions returns all expressions for this rule.

type Table

type Table struct {
	*nftables.Table
	ChainsByName map[string]*Chain
}

Table is a nftables.Table together with all its named Chain objects.

type TableFamily

type TableFamily nftables.TableFamily

TableFamily wraps nftables.TableFamily in order to implement the fmt.Stringer interface.

const (
	TableFamilyUnspecified TableFamily = TableFamily(nftables.TableFamilyUnspecified)
	TableFamilyARP         TableFamily = TableFamily(nftables.TableFamilyARP)
	TableFamilyBridge      TableFamily = TableFamily(nftables.TableFamilyBridge)
	TableFamilyINet        TableFamily = TableFamily(nftables.TableFamilyINet)
	TableFamilyIPv4        TableFamily = TableFamily(nftables.TableFamilyIPv4)
	TableFamilyIPv6        TableFamily = TableFamily(nftables.TableFamilyIPv6)
	TableFamilyNetdev      TableFamily = TableFamily(nftables.TableFamilyNetdev)
)

Reexported netfilter table family constants, for convenience.

func (TableFamily) String

func (tf TableFamily) String() string

String returns the table family name (identifier) for the given TableFamily value, such as "inet", "ip" (for IPv4), "ipv6", et cetera.

type TableKey

type TableKey struct {
	Name   string
	Family TableFamily
}

TableKey represents an index key into a TableMap. Every Table is always namespaced to a nftables.TableFamily, such as nftables.TableFamilyINet (both IPv4 and IPv6), nftables.TableFamilyIPv4, nftables.TableFamilyIPv6, et cetera.

type TableMap

type TableMap map[TableKey]*Table

TableMap indexes table names (that are always "namespaced" in a particular address family) to their corresponding Table objects. The Table objects then contain their Chain objects, and the chain objects in turn Rule objects. It's turtles all the way down.

func GetAllTables

func GetAllTables(conn *nftables.Conn) (TableMap, error)

GetAllTables returns the available netfilter tables as a TableMap using the specified conn for retrieval. The Table objects in the returned TableMap are populated with their named Chain objects, and these in turn contain their Rule objects including expressions.

func GetFamilyTables

func GetFamilyTables(conn *nftables.Conn, family TableFamily) (TableMap, error)

GetFamilyTables returns the netfiler tables for the specified netfilter family only, together with all their chains and rules.

func (TableMap) Table

func (t TableMap) Table(name string, family TableFamily) *Table

Table returns the named table of the specified family if available, otherwise nil.

func (TableMap) TableChain

func (t TableMap) TableChain(tablename string, family TableFamily, chainname string) *Chain

TableChain returns the specified named chain in the specified table and family, otherwise nil.