gosecco

README

gosecco - a library for parsing and managing seccomp-bpf rules

gosecco is a project to provide a full stack of tools necessary for working with SECCOMP BPF rules from Golang. The primary pieces of functionality are the parser and compiler - but the project also supports a rudimentary assembler and disassembler. It also supports an emulator that can be tweaked to provide output on whether your rules actually do what you think they should do or not. None of these tools are exposed as command line tools - they are meant to be used as libraries for higher level applications and systems.

gosecco is only compatible with Linux 3.7 and above. It has only been tested with Golang 1.6, and it assumes an amd64 architecture, although that is likely to change.

The language that gosecco parses and understands is documented in https://github.com/twtiger/gosecco/blob/master/docs/seccomp-policy-language.md.

Libraries

gosecco is composed of several smaller libraries that provides different parts of the functionality. The gosecco package exposes the core functionality - see the godoc for more info: https://godoc.org/github.com/twtiger/gosecco.

The specific libraries used are these:

asm

The asm package is mostly a self contained package that can be used to generate a simple form of BPF assembler, and read the same form of assembler into and out of slices of unix.SockFilter.

checker

The checker package provides for type checking of a finished parse tree - but also makes sure that certain semantic constraints are fulfilled, such that there is not more than one rule for a specific syscall, or that all the syscalls referred actually exist.

compiler

The compiler will take a parse tree and generate optimized BPF code in the form of a slice of unix.SockFilter - the intention is that the output of the compiler should be ready to install for a running program. The compiler doesn't implement many optimizations by itself, but it does try to be clever with jump layouts and so on. Simplification and normalization of the tree will already be done before the compiler starts working.

constants

A helper package that contains many well known constants from the Linux environment, so that these are available to profiles written for seccomp.

data

This package only contains the definition for the Seccomp Working memory data set, and is a helper package for the other packages.

emulator

An emulator that takes a set of rules and an instance of working memory and executes the instructions therein. The emulation is extremely slow and obvious in order to make it easier to understand the implementation - this tool is primarily there as a basis for experiments and further evolution.

parser

The parser is divided up into a tokenizer implemented using Ragel and a very simple recursive descent parser. The language parsed is described in the document referred to above. The output will be a raw policy document where macro definitions and rule definitions appear in the order they were defined.

precompilation

The precompilation package contains some checks that make sure that everything is ready for being compiled. It doesn't provide error messages for users of packages, but for implementors. Basically speaking, if this ever triggers, it's because someone has wired something wrong.

simplifier

The simplification phase takes a tree and tries to do as much optimization as possible before hand. This means basically reducing all arithmetic expressions as much as possible based on constants. We don't do more complicated optimizations such as reorderings or inversions of mathematical operations - we simple execute as much as possible beforehand. THe assumption is that there are no free variables or calls at this stage.

tree

The tree defines the expression types and all subnodes of the AST. It also defines a Visitor that can be used to provide functionality on the AST.

unifier

The unifier takes the set of rules and zero or more lists of macro definitions and resolves all free variables in the set of rules by replacing them with their macro content. The output will be a tree that is fit for simplification, type checking and compilation.

Flow of execution

In general, this library will work by taking a file of definitions, parse it, compile it and install it. The specific flow of events looks like this:

• First, the file will be parsed
• Then, the unifier will take all the macro definitions and make sure the final tree is complete
• After that, the type checker will run to make sure everything looks correct
• Then, we use the simplifier to optimize and make everything smaller
• After simplification, the tree should be ready for compilation. The precompilation package checks that and ensures we are all good.
• Finally, the compiler takes the tree and turns it into bytecode
• Optionally, at this point we will install the bytecode into a running process using either the seccomp or the prctl system call.

The library can also check whether seccomp is supported. It supports the separation of macros and rules into several files. This composition cannot happen inside the files, but has to be done by the calling library. This allows for shared macros and rules. The language also supports default positive and negative actions, such that it's clear from the file itself whether it's a blacklist or a whitelist, for example. These default actions can also be specified programmatically. Finally, each rule can have custom positive or negative actions if needed.

Refer to the godoc for the API - we hope to have some usage examples up as soon as the library is finished.

Documentation

Index

• Constants
• func CheckSupport() error
• func Compile(path string, enforce bool) ([]unix.SockFilter, error)
• func CompileBlacklist(path string, enforce bool) ([]unix.SockFilter, error)
• func Install(bpf []unix.SockFilter) error
• func InstallBlacklist(bpf []unix.SockFilter) error
• func Load(bpf []unix.SockFilter) error
• func LockedLoad(bpf []unix.SockFilter) error
• func Prepare(path string, s SeccompSettings) ([]unix.SockFilter, error)
• func PrepareSource(source parser.Source, s SeccompSettings) ([]unix.SockFilter, error)
• type SeccompSettings

Constants

const InlineMarker = "{inline}"

InlineMarker is the marker a string should start with in order to specify it should be parsed as an inline string, not a path.

Functions

func CheckSupport

func CheckSupport() error

CheckSupport checks for the required seccomp support in the kernel.

func Compile

func Compile(path string, enforce bool) ([]unix.SockFilter, error)

Compile provides the compatibility interface for gosecco - it has the same signature as Compile from the go-seccomp package and should provide the same behavior. However, the modern interface is through the Prepare function

func CompileBlacklist

func CompileBlacklist(path string, enforce bool) ([]unix.SockFilter, error)

CompileBlacklist provides the compatibility interface for gosecco, for blacklist mode It has the same signature as CompileBlacklist from Subgraphs go-seccomp and should provide the same behavior. However, the modern interface is through the Prepare function

func Install

func Install(bpf []unix.SockFilter) error

Install will install the given policy filters into the kernel

func InstallBlacklist

func InstallBlacklist(bpf []unix.SockFilter) error

InstallBlacklist makes the necessary system calls to install the Seccomp-BPF filter for the current process (all threads). Install can be called multiple times to install additional filters.

func Load

func Load(bpf []unix.SockFilter) error

Load makes the seccomp system call to install the bpf filter for all threads (with tsync). Most users of this library should use Install instead of Load, since Install ensures that prctl(set_no_new_privs, 1) has been called

func LockedLoad

func LockedLoad(bpf []unix.SockFilter) error

LockedLoad will run Load with the arguments given while locking the current OS thread. The existing Load can't do that, since LockOSThread is not nestable at the moment

func Prepare

func Prepare(path string, s SeccompSettings) ([]unix.SockFilter, error)

Prepare will take the given path and settings, parse and compile the given data, combined with the settings - and returns the bytecode If path starts with the special marker InlineMarker, the rest of the string will be interpreted as an inline definition, not a path. Prepare is now deprecated, and PrepareSource should be used instead

func PrepareSource

func PrepareSource(source parser.Source, s SeccompSettings) ([]unix.SockFilter, error)

PrepareSource will take the given source and settings, parse and compile the given data, combined with the settings - and returns the bytecode

Types

type SeccompSettings

type SeccompSettings struct {
	// ExtraDefinitions contains paths to files with extra definitions to parse
	// These files should only contain variables/macros - rules will not be picked
	// up.
	// If the path starts with the special marker InlineMarker, the rest of the string will
	// be interpreted as an inline definition, not a path.
	// ExtraDefinitions is softly deprecated - you should probably use parser.CombineSources instead
	ExtraDefinitions []string
	// DefaultPositiveAction is the action to take when a syscall is matched, and the expression returns a positive result - and the rule
	// doesn't have any specified custom actions.  It can be specified as one of "trap", "kill", "allow" or "trace". It can also be a number
	// - this will be treated as an errno. You can also use the pre- defined classical names for errors instead of the number - such as
	// EACCES.
	DefaultPositiveAction string
	// DefaultNegativeAction is the action to take when a syscall is matched, the expression returns a negative result and the rule doesn't
	// have any custom actions defined. The action can be specified using the same syntax as described for DefaultPositiveAction.
	DefaultNegativeAction string
	// DefaultPolicyAction is the action to take when the syscall is not matched. The action can be specified using the same syntax as
	// described for DefaultPositiveAction.
	DefaultPolicyAction string
	// ActionOnX32 is the action to take if the syscall is a 32-bit ABI compatibility syscall. If no action is specified, this case will not
	// be considered. The actions are specified using the same syntax as described for DefaultPositiveAction.
	ActionOnX32 string
	// ActionOnAuditFailure is the action to take if the policy is running on the wrong architecture compared to what it was compiled
	// for. If not specified, it will default to "kill". The actions are specified using the same syntax as described for
	// DefaultPositiveAction.
	ActionOnAuditFailure string
}

SeccompSettings contains the extra settings necessary to tweak the behavior of the compilation process