seccomp

README

go-seccomp-bpf

go-seccomp-bpf is a library for Go (golang) for loading a system call filter on Linux 3.17 and later by taking advantage of secure computing mode, also known as seccomp. Seccomp restricts the system calls that a process can invoke.

The kernel exposes a large number of system calls that are not used by most processes. By installing a seccomp filter, you can limit the total kernel surface exposed to a process (principle of least privilege). This minimizes the impact of unknown vulnerabilities that might be found in the process.

The filter is expressed as a Berkeley Packet Filter (BPF) program. The BPF program is generated based on a filter policy created by you.

Requirements

• Requires Linux 3.17 because it uses the seccomp syscall in order to take advantage of the SECCOMP_FILTER_FLAG_TSYNC flag to sync the filter to all threads.

Features

• Pure Go and does not have a libseccomp dependency.
• Filters are customizable and can be written as an allowlist or blocklist.
• Supports system call argument filtering.
• Uses SECCOMP_FILTER_FLAG_TSYNC to sync the filter to all threads created by the Go runtime.
• Invokes prctl(PR_SET_NO_NEW_PRIVS, 1) to set the threads no_new_privs bit which is generally required before loading a seccomp filter.
• seccomp-profiler tool for automatically generating a allowlist policy based on the system calls that a binary uses.

Limitations

• System call tables are only implemented for 386, amd64, arm and arm64. (More system call table generation code should be added to arch/mk_syscalls_linux.go.)

Examples

• GoDoc Package Example
• sandbox example in cmd/sandbox.

Updating syscalls for new Linux releases

This package contains a list of syscall numbers that are generated from the Linux sources. Update the git tag here and then run this command to generate the code.

docker run -it --rm -v `pwd`:/go-seccomp-bpf -w /go-seccomp-bpf/arch golang:1.18 go generate

Projects Using elastic/go-seccomp-bpf

Please open a PR to submit your project.

• elastic/beats

Documentation

Overview

Package seccomp provides a way to install a syscall filter for a Linux process. It uses the seccomp (secure computing) BPF filters.

Example

package main

import (
	"fmt"

	seccomp "github.com/elastic/go-seccomp-bpf"
)

func main() {
	// Create a filter.
	filter := seccomp.Filter{
		NoNewPrivs: true,
		Flag:       seccomp.FilterFlagTSync,
		Policy: seccomp.Policy{
			DefaultAction: seccomp.ActionAllow,
			Syscalls: []seccomp.SyscallGroup{
				{
					Action: seccomp.ActionErrno,
					Names: []string{
						"fork",
						"vfork",
						"execve",
						"execveat",
					},
				},
			},
		},
	}

	// Load it. This will set no_new_privs before loading.
	if err := seccomp.LoadFilter(filter); err != nil {
		fmt.Println("failed to load filter: ", err)
		return
	}
}

Index

• Variables
• func LoadFilter(filter Filter) error
• func SetNoNewPrivs() error
• func Supported() bool
• type Action
  • func (a Action) MarshalText() ([]byte, error)
  • func (a Action) String() string
  • func (a *Action) Unpack(s string) error
• type ArgumentConditions
  • func (a ArgumentConditions) Validate() []string
• type Condition
• type Filter
• type FilterFlag
  • func (f FilterFlag) MarshalText() ([]byte, error)
  • func (f FilterFlag) String() string
• type Index
• type JumpIf
• type Label
• type NameWithConditions
• type Operation
  • func (o *Operation) Unpack(s string) error
• type Policy
  • func (p *Policy) Assemble() ([]bpf.Instruction, error)
  • func (p *Policy) Dump(out io.Writer) error
  • func (p *Policy) Validate() error
• type Program
  • func NewProgram() Program
  • func (p *Program) Assemble() ([]bpf.Instruction, error)
  • func (p *Program) JmpIf(cond bpf.JumpTest, val uint32, trueLabel Label, falseLabel Label)
  • func (p *Program) JmpIfTrue(cond bpf.JumpTest, val uint32, trueLabel Label)
  • func (p *Program) LdHi(arg uint32)
  • func (p *Program) LdLo(arg uint32)
  • func (p *Program) NewLabel() Label
  • func (p *Program) Ret(action Action)
  • func (p *Program) SetLabel(label Label)
• type SyscallGroup
  • func (g *SyscallGroup) Assemble(defaultAction Action) ([]bpf.Instruction, error)
• type SyscallWithConditions
  • func (s SyscallWithConditions) Assemble(p *Program, action Label)

Examples

• Package

Variables

var Operations = []Operation{Equal, NotEqual, GreaterThan, LessThan, GreaterOrEqual, LessOrEqual, BitsSet, BitsNotSet}

Functions

func LoadFilter

func LoadFilter(filter Filter) error

LoadFilter will install seccomp using native methods.

func SetNoNewPrivs

func SetNoNewPrivs() error

SetNoNewPrivs will use prctl to set the calling thread's no_new_privs bit to 1 (true). Once set, this bit cannot be unset.

func Supported

func Supported() bool

Supported returns true if the seccomp syscall is supported.

Types

type Action

type Action uint32

Action specifies what to do when a syscall matches during filter evaluation.

const (
	ActionKillThread  Action = unix.SECCOMP_RET_KILL_THREAD  // Kill the calling thread.
	ActionKillProcess Action = unix.SECCOMP_RET_KILL_PROCESS // Kill the process (since kernel 4.14).
	ActionTrap        Action = unix.SECCOMP_RET_TRAP         // Disallow and force a SIGSYS signal.
	ActionErrno       Action = unix.SECCOMP_RET_ERRNO        // Disallow and return an errno.
	ActionTrace       Action = unix.SECCOMP_RET_TRACE        // Pass to a tracer or disallow.
	ActionLog         Action = unix.SECCOMP_RET_LOG          // Allow after logging.
	ActionAllow       Action = unix.SECCOMP_RET_ALLOW        // Allow.
	ActionUserNotify  Action = unix.SECCOMP_RET_USER_NOTIF   // Forward to user-space supervisor.
)

List of actions. https://github.com/torvalds/linux/blob/v4.16/include/uapi/linux/seccomp.h#L32-L39

func (Action) MarshalText

func (a Action) MarshalText() ([]byte, error)

MarshalText marshals the value to text.

func (Action) String

func (a Action) String() string

String returns a string representation of the Action.

func (*Action) Unpack

func (a *Action) Unpack(s string) error

Unpack sets the Action value based on the string.

type ArgumentConditions

type ArgumentConditions []Condition

ArgumentConditions consist of a list of up to six conditions for the six arguments.

func (ArgumentConditions) Validate

func (a ArgumentConditions) Validate() []string

type Condition

type Condition struct {
	Argument  uint32    `config:"argument" default:"0" json:"position"  yaml:"position"`
	Operation Operation `config:"operation" validate:"required" json:"operation"  yaml:"operation"`
	Value     uint64    `config:"value" default:"0" json:"value"  yaml:"value"`
}

type Filter

type Filter struct {
	NoNewPrivs bool       `config:"no_new_privs" json:"no_new_privs"` // Set the process's no new privs bit.
	Flag       FilterFlag `config:"flag"         json:"flag"`         // Flag to pass to the seccomp call.
	Policy     Policy     `config:"policy"       json:"policy"`       // Policy that will be assembled into a BPF filter.
}

Filter contains all the parameters necessary to install a Linux seccomp filter for the process.

type FilterFlag

type FilterFlag uint32

FilterFlag is a flag that is passed to the seccomp. Multiple flags can be OR'ed together.

const (
	// When adding a new filter, synchronize all other threads of the calling
	// process to the same seccomp filter tree. Since Linux 3.17.
	FilterFlagTSync FilterFlag = unix.SECCOMP_FILTER_FLAG_TSYNC

	// All filter return actions except SECCOMP_RET_ALLOW should be logged.
	// Since Linux 4.14.
	FilterFlagLog FilterFlag = unix.SECCOMP_FILTER_FLAG_LOG
)

List of SECCOMP_SET_MODE_FILTER values. https://github.com/torvalds/linux/blob/v4.16/include/uapi/linux/seccomp.h#L19-L21

func (FilterFlag) MarshalText

func (f FilterFlag) MarshalText() ([]byte, error)

MarshalText marshals the value to text.

func (FilterFlag) String

func (f FilterFlag) String() string

String returns a string representation of the FilterFlag.

type Index

type Index int

Index is the concrete index of an instruction in the instruction list.

type JumpIf

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

JumpIf jumps conditionally to the true or the false label. The concrete condition is not relevant to resolve the jumps.

type Label

type Label int

Label marks a jump destination in the instruction list of the Program.

type NameWithConditions

type NameWithConditions struct {
	Name       string             `config:"name" validate:"required" json:"name"  yaml:"name"`
	Conditions ArgumentConditions `config:"arguments" validate:"required" json:"arguments"  yaml:"arguments"`
}

type Operation

type Operation string

const (
	Equal          Operation = "Equal"
	NotEqual       Operation = "NotEqual"
	GreaterThan    Operation = "GreaterThan"
	LessThan       Operation = "LessThan"
	GreaterOrEqual Operation = "GreaterOrEqual"
	LessOrEqual    Operation = "LessOrEqual"
	BitsSet        Operation = "BitsSet"
	BitsNotSet     Operation = "BitsNotSet"
)

func (*Operation) Unpack

func (o *Operation) Unpack(s string) error

Unpack sets the Operation value based on the string.

type Policy

type Policy struct {
	DefaultAction Action         `config:"default_action" json:"default_action" yaml:"default_action"` // Action when no syscalls match.
	Syscalls      []SyscallGroup `config:"syscalls"       json:"syscalls"       yaml:"syscalls"`       // Groups of syscalls and actions.
	// contains filtered or unexported fields
}

Policy defines the BPF seccomp filter.

func (*Policy) Assemble

func (p *Policy) Assemble() ([]bpf.Instruction, error)

Assemble assembles the policy into a list of BPF instructions. If the policy contains any unknown syscalls or invalid actions an error will be returned.

func (*Policy) Dump

func (p *Policy) Dump(out io.Writer) error

Dump writes a textual represenation of the BPF instructions to out.

func (*Policy) Validate

func (p *Policy) Validate() error

Validate validates that the configuration has both a default action and a set of syscalls.

type Program

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

The Program consists of a list of bpf.Instructions. Conditional jumps can point to different labels in the program and must be resolved by calling ResolveJumps.

NewLabel creates a new label that can be used as jump destination.

SetLabel must be used to specify the concrete instruction. Only forward jumps are supported; this means a label must not be used after setting it.

func NewProgram

func NewProgram() Program

NewProgram returns an initialized empty program.

func (*Program) Assemble

func (p *Program) Assemble() ([]bpf.Instruction, error)

Assemble resolves all jump destinations to concrete instructions using the labels. This method takes care of long jumps and resolves them by using early returns or unconditional long jumps.

func (*Program) JmpIf

func (p *Program) JmpIf(cond bpf.JumpTest, val uint32, trueLabel Label, falseLabel Label)

JmpIf inserts a conditional jump. If the condition is true, it jumps to the true label. If it is false, it jumps to the false label.

func (*Program) JmpIfTrue

func (p *Program) JmpIfTrue(cond bpf.JumpTest, val uint32, trueLabel Label)

JmpIfTrue inserts a conditional jump. If the condition is true, it jumps to the given label. If it is false, the program flow continues with the next instruction.

func (*Program) LdHi

func (p *Program) LdHi(arg uint32)

LdHi inserts an instruction to load the most significant 32-bit of the 64-bit argument.

func (*Program) LdLo

func (p *Program) LdLo(arg uint32)

LdLo inserts an instruction to load the least significant 32-bit of the 64-bit argument.

func (*Program) NewLabel

func (p *Program) NewLabel() Label

NewLabel creates a new label. It must be used with SetLabel.

func (*Program) Ret

func (p *Program) Ret(action Action)

Ret inserts a return instruction.

func (*Program) SetLabel

func (p *Program) SetLabel(label Label)

SetLabel sets the label to the latest instruction.

type SyscallGroup

type SyscallGroup struct {
	Names              []string             `config:"names"  json:"names"  yaml:"names"`                              // List of syscall names (all must exist).
	NamesWithCondtions []NameWithConditions `config:"names_with_args" json:"names_with_args"  yaml:"names_with_args"` // List of syscall with argument filters
	Action             Action               `config:"action" validate:"required" json:"action" yaml:"action"`         // Action to take upon a match.
	// contains filtered or unexported fields
}

SyscallGroup is a logical block within a Policy that contains a set of syscalls to match against and an action to take.

func (*SyscallGroup) Assemble

func (g *SyscallGroup) Assemble(defaultAction Action) ([]bpf.Instruction, error)

type SyscallWithConditions

type SyscallWithConditions struct {
	Num        uint32
	Conditions []ArgumentConditions
}

SyscallWithConditions consists of a syscall number and optional conditions.

The conditions are applied to the arguments of the syscall. So, conditions consist of a list of up to six argument conditions. This filter matches if all argument conditions match for any Conditions.

func (SyscallWithConditions) Assemble

func (s SyscallWithConditions) Assemble(p *Program, action Label)