Documentation: prctl/seccomp_filter

		SECure COMPuting with filters

		=============================

Introduction

------------

A large number of system calls are exposed to every userland process

with many of them going unused for the entire lifetime of the process.

As system calls change and mature, bugs are found and eradicated.  A

certain subset of userland applications benefit by having a reduced set

of available system calls.  The resulting set reduces the total kernel

surface exposed to the application.  System call filtering is meant for

use with those applications.

Seccomp filtering provides a means for a process to specify a filter for

incoming system calls.  The filter is expressed as a Berkeley Packet

Filter (BPF) program, as with socket filters, except that the data

operated on is related to the system call being made: system call

number and the system call arguments.  This allows for expressive

filtering of system calls using a filter program language with a long

history of being exposed to userland and a straightforward data set.

Additionally, BPF makes it impossible for users of seccomp to fall prey

to time-of-check-time-of-use (TOCTOU) attacks that are common in system

call interposition frameworks.  BPF programs may not dereference

pointers which constrains all filters to solely evaluating the system

call arguments directly.

What it isn't

-------------

System call filtering isn't a sandbox.  It provides a clearly defined

mechanism for minimizing the exposed kernel surface.  It is meant to be

a tool for sandbox developers to use.  Beyond that, policy for logical

behavior and information flow should be managed with a combination of

other system hardening techniques and, potentially, an LSM of your

choosing.  Expressive, dynamic filters provide further options down this

path (avoiding pathological sizes or selecting which of the multiplexed

system calls in socketcall() is allowed, for instance) which could be

construed, incorrectly, as a more complete sandboxing solution.

Usage

-----

An additional seccomp mode is added and is enabled using the same

prctl(2) call as the strict seccomp.  If the architecture has

CONFIG_HAVE_ARCH_SECCOMP_FILTER, then filters may be added as below:

PR_SET_SECCOMP:

	Now takes an additional argument which specifies a new filter

	using a BPF program.

	The BPF program will be executed over struct seccomp_data

	reflecting the system call number, arguments, and other

	metadata.  The BPF program must then return one of the

	acceptable values to inform the kernel which action should be

	taken.

	Usage:

		prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, prog);

	The 'prog' argument is a pointer to a struct sock_fprog which

	will contain the filter program.  If the program is invalid, the

	call will return -1 and set errno to EINVAL.

	If fork/clone and execve are allowed by @prog, any child

	processes will be constrained to the same filters and system

	call ABI as the parent.

	Prior to use, the task must call prctl(PR_SET_NO_NEW_PRIVS, 1) or

	run with CAP_SYS_ADMIN privileges in its namespace.  If these are not

	true, -EACCES will be returned.  This requirement ensures that filter

	programs cannot be applied to child processes with greater privileges

	than the task that installed them.

	Additionally, if prctl(2) is allowed by the attached filter,

	additional filters may be layered on which will increase evaluation

	time, but allow for further decreasing the attack surface during

	execution of a process.

The above call returns 0 on success and non-zero on error.

Return values

-------------

A seccomp filter may return any of the following values. If multiple

filters exist, the return value for the evaluation of a given system

call will always use the highest precedent value. (For example,

SECCOMP_RET_KILL will always take precedence.)

In precedence order, they are:

SECCOMP_RET_KILL:

	Results in the task exiting immediately without executing the

	system call.  The exit status of the task (status & 0x7f) will

	be SIGSYS, not SIGKILL.

SECCOMP_RET_TRAP:

	Results in the kernel sending a SIGSYS signal to the triggering

	task without executing the system call.  The kernel will

	rollback the register state to just before the system call

	entry such that a signal handler in the task will be able to

	inspect the ucontext_t->uc_mcontext registers and emulate

	system call success or failure upon return from the signal

	handler.

	The SECCOMP_RET_DATA portion of the return value will be passed

	as si_errno.

	SIGSYS triggered by seccomp will have a si_code of SYS_SECCOMP.

SECCOMP_RET_ERRNO:

	Results in the lower 16-bits of the return value being passed

	to userland as the errno without executing the system call.

SECCOMP_RET_TRACE:

	When returned, this value will cause the kernel to attempt to

	notify a ptrace()-based tracer prior to executing the system

	call.  If there is no tracer present, -ENOSYS is returned to

	userland and the system call is not executed.

	A tracer will be notified if it requests PTRACE_O_TRACESECCOMP

	using ptrace(PTRACE_SETOPTIONS).  The tracer will be notified

	of a PTRACE_EVENT_SECCOMP and the SECCOMP_RET_DATA portion of

	the BPF program return value will be available to the tracer

	via PTRACE_GETEVENTMSG.

SECCOMP_RET_ALLOW:

	Results in the system call being executed.

If multiple filters exist, the return value for the evaluation of a

given system call will always use the highest precedent value.

Precedence is only determined using the SECCOMP_RET_ACTION mask.  When

multiple filters return values of the same precedence, only the

SECCOMP_RET_DATA from the most recently installed filter will be

returned.

Pitfalls

--------

The biggest pitfall to avoid during use is filtering on system call

number without checking the architecture value.  Why?  On any

architecture that supports multiple system call invocation conventions,

the system call numbers may vary based on the specific invocation.  If

the numbers in the different calling conventions overlap, then checks in

the filters may be abused.  Always check the arch value!

Example

-------

The samples/seccomp/ directory contains both an x86-specific example

and a more generic example of a higher level macro interface for BPF

program generation.

Adding architecture support

-----------------------

See arch/Kconfig for the authoritative requirements.  In general, if an

architecture supports both ptrace_event and seccomp, it will be able to

support seccomp filter with minor fixup: SIGSYS support and seccomp return

value checking.  Then it must just add CONFIG_HAVE_ARCH_SECCOMP_FILTER

to its arch-specific Kconfig.

# Makefile for Linux samples code

obj-$(CONFIG_SAMPLES)	+= kobject/ kprobes/ tracepoints/ trace_events/ \

			   hw_breakpoint/ kfifo/ kdb/ hidraw/ rpmsg/

			   hw_breakpoint/ kfifo/ kdb/ hidraw/ rpmsg/ seccomp/

# kbuild trick to avoid linker error. Can be omitted if a module is built.

obj- := dummy.o

hostprogs-$(CONFIG_SECCOMP) := bpf-fancy dropper

bpf-fancy-objs := bpf-fancy.o bpf-helper.o

HOSTCFLAGS_bpf-fancy.o += -I$(objtree)/usr/include

HOSTCFLAGS_bpf-fancy.o += -idirafter $(objtree)/include

HOSTCFLAGS_bpf-helper.o += -I$(objtree)/usr/include

HOSTCFLAGS_bpf-helper.o += -idirafter $(objtree)/include

HOSTCFLAGS_dropper.o += -I$(objtree)/usr/include

HOSTCFLAGS_dropper.o += -idirafter $(objtree)/include

dropper-objs := dropper.o

# bpf-direct.c is x86-only.

ifeq ($(SRCARCH),x86)

# List of programs to build

hostprogs-$(CONFIG_SECCOMP) += bpf-direct

bpf-direct-objs := bpf-direct.o

endif

HOSTCFLAGS_bpf-direct.o += -I$(objtree)/usr/include

HOSTCFLAGS_bpf-direct.o += -idirafter $(objtree)/include

# Try to match the kernel target.

ifeq ($(CONFIG_64BIT),)

HOSTCFLAGS_bpf-direct.o += -m32

HOSTCFLAGS_dropper.o += -m32

HOSTCFLAGS_bpf-helper.o += -m32

HOSTCFLAGS_bpf-fancy.o += -m32

HOSTLOADLIBES_bpf-direct += -m32

HOSTLOADLIBES_bpf-fancy += -m32

HOSTLOADLIBES_dropper += -m32

endif

# Tell kbuild to always build the programs

always := $(hostprogs-y)

/*

 * Seccomp filter example for x86 (32-bit and 64-bit) with BPF macros

 *

 * Copyright (c) 2012 The Chromium OS Authors <chromium-os-dev@chromium.org>

 * Author: Will Drewry <wad@chromium.org>

 *

 * The code may be used by anyone for any purpose,

 * and can serve as a starting point for developing

 * applications using prctl(PR_SET_SECCOMP, 2, ...).

 */

#define __USE_GNU 1

#define _GNU_SOURCE 1

#include <linux/types.h>

#include <linux/filter.h>

#include <linux/seccomp.h>

#include <linux/unistd.h>

#include <signal.h>

#include <stdio.h>

#include <stddef.h>

#include <string.h>

#include <sys/prctl.h>

#include <unistd.h>

#define syscall_arg(_n) (offsetof(struct seccomp_data, args[_n]))

#define syscall_nr (offsetof(struct seccomp_data, nr))

#if defined(__i386__)

#define REG_RESULT	REG_EAX

#define REG_SYSCALL	REG_EAX

#define REG_ARG0	REG_EBX

#define REG_ARG1	REG_ECX

#define REG_ARG2	REG_EDX

#define REG_ARG3	REG_ESI

#define REG_ARG4	REG_EDI

#define REG_ARG5	REG_EBP

#elif defined(__x86_64__)

#define REG_RESULT	REG_RAX

#define REG_SYSCALL	REG_RAX

#define REG_ARG0	REG_RDI

#define REG_ARG1	REG_RSI

#define REG_ARG2	REG_RDX

#define REG_ARG3	REG_R10

#define REG_ARG4	REG_R8

#define REG_ARG5	REG_R9

#else

#error Unsupported platform

#endif

#ifndef PR_SET_NO_NEW_PRIVS

#define PR_SET_NO_NEW_PRIVS 38

#endif

#ifndef SYS_SECCOMP

#define SYS_SECCOMP 1

#endif

static void emulator(int nr, siginfo_t *info, void *void_context)

{

	ucontext_t *ctx = (ucontext_t *)(void_context);

	int syscall;

	char *buf;

	ssize_t bytes;

	size_t len;

	if (info->si_code != SYS_SECCOMP)

		return;

	if (!ctx)

		return;

	syscall = ctx->uc_mcontext.gregs[REG_SYSCALL];

	buf = (char *) ctx->uc_mcontext.gregs[REG_ARG1];

	len = (size_t) ctx->uc_mcontext.gregs[REG_ARG2];

	if (syscall != __NR_write)

		return;

	if (ctx->uc_mcontext.gregs[REG_ARG0] != STDERR_FILENO)

		return;

	/* Redirect stderr messages to stdout. Doesn't handle EINTR, etc */

	ctx->uc_mcontext.gregs[REG_RESULT] = -1;

	if (write(STDOUT_FILENO, "[ERR] ", 6) > 0) {

		bytes = write(STDOUT_FILENO, buf, len);

		ctx->uc_mcontext.gregs[REG_RESULT] = bytes;

	}

	return;

}

static int install_emulator(void)

{

	struct sigaction act;

	sigset_t mask;

	memset(&act, 0, sizeof(act));

	sigemptyset(&mask);

	sigaddset(&mask, SIGSYS);

	act.sa_sigaction = &emulator;

	act.sa_flags = SA_SIGINFO;

	if (sigaction(SIGSYS, &act, NULL) < 0) {

		perror("sigaction");

		return -1;

	}

	if (sigprocmask(SIG_UNBLOCK, &mask, NULL)) {

		perror("sigprocmask");

		return -1;

	}

	return 0;

}

static int install_filter(void)

{

	struct sock_filter filter[] = {

		/* Grab the system call number */

		BPF_STMT(BPF_LD+BPF_W+BPF_ABS, syscall_nr),

		/* Jump table for the allowed syscalls */

		BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, __NR_rt_sigreturn, 0, 1),

		BPF_STMT(BPF_RET+BPF_K, SECCOMP_RET_ALLOW),

#ifdef __NR_sigreturn

		BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, __NR_sigreturn, 0, 1),

		BPF_STMT(BPF_RET+BPF_K, SECCOMP_RET_ALLOW),

#endif

		BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, __NR_exit_group, 0, 1),

		BPF_STMT(BPF_RET+BPF_K, SECCOMP_RET_ALLOW),

		BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, __NR_exit, 0, 1),

		BPF_STMT(BPF_RET+BPF_K, SECCOMP_RET_ALLOW),

		BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, __NR_read, 1, 0),

		BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, __NR_write, 3, 2),

		/* Check that read is only using stdin. */

		BPF_STMT(BPF_LD+BPF_W+BPF_ABS, syscall_arg(0)),

		BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, STDIN_FILENO, 4, 0),

		BPF_STMT(BPF_RET+BPF_K, SECCOMP_RET_KILL),

		/* Check that write is only using stdout */

		BPF_STMT(BPF_LD+BPF_W+BPF_ABS, syscall_arg(0)),

		BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, STDOUT_FILENO, 1, 0),

		/* Trap attempts to write to stderr */

		BPF_JUMP(BPF_JMP+BPF_JEQ+BPF_K, STDERR_FILENO, 1, 2),

		BPF_STMT(BPF_RET+BPF_K, SECCOMP_RET_ALLOW),

		BPF_STMT(BPF_RET+BPF_K, SECCOMP_RET_TRAP),

		BPF_STMT(BPF_RET+BPF_K, SECCOMP_RET_KILL),

	};

	struct sock_fprog prog = {

		.len = (unsigned short)(sizeof(filter)/sizeof(filter[0])),

		.filter = filter,

	};

	if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) {

		perror("prctl(NO_NEW_PRIVS)");

		return 1;

	}

	if (prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, &prog)) {

		perror("prctl");

		return 1;

	}

	return 0;

}

#define payload(_c) (_c), sizeof((_c))

int main(int argc, char **argv)

{

	char buf[4096];

	ssize_t bytes = 0;

	if (install_emulator())

		return 1;

	if (install_filter())

		return 1;

	syscall(__NR_write, STDOUT_FILENO,

		payload("OHAI! WHAT IS YOUR NAME? "));

	bytes = syscall(__NR_read, STDIN_FILENO, buf, sizeof(buf));

	syscall(__NR_write, STDOUT_FILENO, payload("HELLO, "));

	syscall(__NR_write, STDOUT_FILENO, buf, bytes);

	syscall(__NR_write, STDERR_FILENO,

		payload("Error message going to STDERR\n"));

	return 0;

}

/*

 * Seccomp BPF example using a macro-based generator.

 *

 * Copyright (c) 2012 The Chromium OS Authors <chromium-os-dev@chromium.org>

 * Author: Will Drewry <wad@chromium.org>

 *

 * The code may be used by anyone for any purpose,

 * and can serve as a starting point for developing

 * applications using prctl(PR_ATTACH_SECCOMP_FILTER).

 */

#include <linux/filter.h>

#include <linux/seccomp.h>

#include <linux/unistd.h>

#include <stdio.h>

#include <string.h>

#include <sys/prctl.h>

#include <unistd.h>

#include "bpf-helper.h"

#ifndef PR_SET_NO_NEW_PRIVS

#define PR_SET_NO_NEW_PRIVS 38

#endif

int main(int argc, char **argv)

{

	struct bpf_labels l;

	static const char msg1[] = "Please type something: ";

	static const char msg2[] = "You typed: ";

	char buf[256];

	struct sock_filter filter[] = {

		/* TODO: LOAD_SYSCALL_NR(arch) and enforce an arch */

		LOAD_SYSCALL_NR,

		SYSCALL(__NR_exit, ALLOW),

		SYSCALL(__NR_exit_group, ALLOW),

		SYSCALL(__NR_write, JUMP(&l, write_fd)),

		SYSCALL(__NR_read, JUMP(&l, read)),

		DENY,  /* Don't passthrough into a label */

		LABEL(&l, read),

		ARG(0),

		JNE(STDIN_FILENO, DENY),

		ARG(1),

		JNE((unsigned long)buf, DENY),

		ARG(2),

		JGE(sizeof(buf), DENY),

		ALLOW,

		LABEL(&l, write_fd),

		ARG(0),

		JEQ(STDOUT_FILENO, JUMP(&l, write_buf)),

		JEQ(STDERR_FILENO, JUMP(&l, write_buf)),

		DENY,

		LABEL(&l, write_buf),

		ARG(1),

		JEQ((unsigned long)msg1, JUMP(&l, msg1_len)),

		JEQ((unsigned long)msg2, JUMP(&l, msg2_len)),

		JEQ((unsigned long)buf, JUMP(&l, buf_len)),

		DENY,

		LABEL(&l, msg1_len),

		ARG(2),

		JLT(sizeof(msg1), ALLOW),

		DENY,

		LABEL(&l, msg2_len),

		ARG(2),

		JLT(sizeof(msg2), ALLOW),

		DENY,

		LABEL(&l, buf_len),

		ARG(2),

		JLT(sizeof(buf), ALLOW),

		DENY,

	};

	struct sock_fprog prog = {

		.filter = filter,

		.len = (unsigned short)(sizeof(filter)/sizeof(filter[0])),

	};

	ssize_t bytes;

	bpf_resolve_jumps(&l, filter, sizeof(filter)/sizeof(*filter));

	if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) {

		perror("prctl(NO_NEW_PRIVS)");

		return 1;

	}

	if (prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, &prog)) {

		perror("prctl(SECCOMP)");

		return 1;

	}

	syscall(__NR_write, STDOUT_FILENO, msg1, strlen(msg1));

	bytes = syscall(__NR_read, STDIN_FILENO, buf, sizeof(buf)-1);

	bytes = (bytes > 0 ? bytes : 0);

	syscall(__NR_write, STDERR_FILENO, msg2, strlen(msg2));

	syscall(__NR_write, STDERR_FILENO, buf, bytes);

	/* Now get killed */

	syscall(__NR_write, STDERR_FILENO, msg2, strlen(msg2)+2);

	return 0;

}