syscallfilter

Documentation

Overview

Package syscallfilter supports filtering child process events by system call or strace event. Strace events include SyscallEnter, SyscallExit, SignalExit, Exit, SignalStop, and NewChild. System call events are for an explicit system call, and can be a regexp. They follow the naming pattern of the u-root strace package (which came from gvisor, which came from the plan 9 "ratrace" command, described in https://www.osti.gov/biblio/1028390), i.e. Esyscallname means system call entry; Xsyscallname means system call exit. Thus you can, if you wish, allow the system call to run but force an error return by specifying Xsyscall, or force the entry to fail immediately by specifying Esyscall.

For each event, an action can be specified. These actions can in principle be set up at any time, although, currently, the package only supports setting them up before the process is started.

Actions are specified as a triple: event,action,value. For example, if we wish to block any kind of fork, we would specify the action:

NewChild,error,-1

which would cause a -1 to be returned from any action that causes a new child to be created. If we wish to block all reads, we might specify

E.*read,error,-1

Index

• type Cmd
  • func Command(name string, args ...string) *Cmd
  • func (c *Cmd) AddActions(actions ...string) error
  • func (c *Cmd) Run() error

Types

type Cmd

type Cmd struct {
	*exec.Cmd
	// if Log is non-nil, actions take are written to it.
	Log io.Writer
	// contains filtered or unexported fields
}

Cmd contains a command and a filter. The filter is allowed to be empty.

func Command

func Command(name string, args ...string) *Cmd

Command creates a new Cmd, with a context, embedding an exec.Cmd, with an empty set of events.

func (*Cmd) AddActions

func (c *Cmd) AddActions(actions ...string) error

AddActions creates an []event as defined by a possibly empty set of actions, and installs it in the Cmd. The action is a string, with comma-separated fields, designed to be convenient to be used on a command line.

Actions have 3 fields.

The first is a regexp to match against the system call name, e.g., E.*imeofday. The first character, E or X, indicates Entry or eXit.

The second parameter indications an action to take. Currently there are only two: error, and log.

The third value indicates a value to return. It can be empty. For the error action, the third parameter indicates the error to return. For the log action, the third parameter is currently unused.

func (*Cmd) Run

func (c *Cmd) Run() error

Run implements cmd.Run, filtering strace events as created by AddActions. The slice can be empty, in which case the command runs as normal.