251 lines
7.1 KiB
Groff
251 lines
7.1 KiB
Groff
.\" $NetBSD: systrace.1,v 1.13 2002/09/25 15:18:43 wiz Exp $
|
|
.\" $OpenBSD: systrace.1,v 1.27 2002/08/05 23:27:53 provos Exp $
|
|
.\"
|
|
.\" Copyright 2002 Niels Provos <provos@citi.umich.edu>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by Niels Provos.
|
|
.\" 4. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" Manual page, using -mandoc macros
|
|
.\"
|
|
.Dd June 3, 2002
|
|
.Dt SYSTRACE 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm systrace
|
|
.Nd generates and enforces system call policies
|
|
.Sh SYNOPSIS
|
|
.Nm systrace
|
|
.Op Fl aAituU
|
|
.Op Fl d Ar policydir
|
|
.Op Fl g Ar gui
|
|
.Op Fl f Ar file
|
|
.Op Fl p Ar pid
|
|
.Ar command ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility monitors and controls an application's access to the system by
|
|
enforcing access policies for system calls.
|
|
The
|
|
.Nm
|
|
utility might be used to trace an untrusted application's access to
|
|
the system.
|
|
Alternatively, it might be used to protect the system
|
|
from software bugs (such as buffer overflows) by constraining a
|
|
daemon's access to the system.
|
|
.Pp
|
|
The access policy can be generated interactively or obtained from a
|
|
policy file.
|
|
Operations not covered by the policy raise an alarm and
|
|
allow an user to refine the currently configured policy.
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width Dfxfile
|
|
.It Fl a
|
|
Enables automatic enforcement of configured policies.
|
|
An operation not covered by policy is denied and logged via
|
|
.Xr syslog 3 .
|
|
.It Fl A
|
|
Automatically generate a policy that allows every operation the
|
|
application executes.
|
|
The created policy functions as a base that can be refined.
|
|
.It Fl u
|
|
Do not perform aliasing on system call names.
|
|
Aliasing is enabled by default to group similar system calls into a
|
|
single compound name.
|
|
For example, system calls that read from the file system like
|
|
.Fn lstat
|
|
and
|
|
.Fn access
|
|
are translated to
|
|
.Fn fsread .
|
|
.It Fl i
|
|
Inherits the policy - child processes inherit policy of the parent binary.
|
|
.It Fl t
|
|
Uses text mode to ask for interactive policy generation.
|
|
.It Fl U
|
|
Ignore user configured policies and use only global system policies.
|
|
.It Fl d Ar policydir
|
|
Specifies an alternative location for the user's directory from
|
|
which policies are loaded and to which changed policies are stored.
|
|
.It Fl g Ar gui
|
|
Specifies an alternative location for the notification user interface.
|
|
.It Fl f Ar file
|
|
The policies specified in
|
|
.Ar file
|
|
are added to the policies that
|
|
.Nm
|
|
knows about.
|
|
.It Fl p Ar pid
|
|
Specifies the pid of a process that
|
|
.Nm
|
|
should attach to.
|
|
The full path name of the corresponding binary has to be specified
|
|
as
|
|
.Ar command .
|
|
.El
|
|
.Ss POLICY
|
|
The policy is specified via the following grammar:
|
|
.Bd -literal -offset 4
|
|
filter = expression "then" action errorcode logcode
|
|
expression = symbol | "not" expression | "(" expression ")" |
|
|
expression "and" expression | expression "or" expression
|
|
symbol = string typeoff "match" cmdstring |
|
|
string typeoff "eq" cmdstring | string typeoff "neq" cmdstring |
|
|
string typeoff "sub" cmdstring | string typeoff "nsub" cmdstring |
|
|
string typeoff "inpath" cmdstring | "true"
|
|
typeoff = /* empty */ | "[" number "]"
|
|
action = "permit" | "deny"
|
|
errorcode = /* empty */ | "[" string "]"
|
|
logcode = /* empty */ | "log"
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Va cmdstring
|
|
is an arbitrary string enclosed with quotation marks.
|
|
The
|
|
.Va errorcode
|
|
is used to return an
|
|
.Xr errno 2
|
|
value to the system call when using a
|
|
.Va deny
|
|
action.
|
|
The values
|
|
.Do
|
|
inherit
|
|
.Dc
|
|
and
|
|
.Do
|
|
detach
|
|
.Dc
|
|
have special meanings when used with a
|
|
.Va permit
|
|
rule for the
|
|
.Va execve
|
|
system call.
|
|
When using
|
|
.Do
|
|
inherit,
|
|
.Dc
|
|
the current policy is inherited for the new binary.
|
|
With
|
|
.Do
|
|
detach,
|
|
.Dc
|
|
.Nm
|
|
detaches from a process after successfully
|
|
completing
|
|
the
|
|
.Va execve
|
|
system call.
|
|
.Pp
|
|
The filter operations have the following meaning:
|
|
.Bl -hang -width Dinpath -offset AAA
|
|
.It match
|
|
Evaluates to true if file name globbing according to
|
|
.Xr fnmatch 3
|
|
succeeds.
|
|
.It eq
|
|
Evaluates to true if the system call argument matches
|
|
.Va cmdstring
|
|
exactly.
|
|
.It neq
|
|
This is the logical negation of
|
|
.Va eq .
|
|
.It sub
|
|
Performs a substring match on the system call argument.
|
|
.It nsub
|
|
This is the logical negation of
|
|
.Va sub .
|
|
.It inpath
|
|
Evaluates to true if the system call argument is a subpath of
|
|
.Va cmdstring .
|
|
.El
|
|
.Pp
|
|
By appending the
|
|
.Va log
|
|
statement to a rule, a matching system call and its arguments
|
|
is logged to
|
|
.Xr syslog 3 .
|
|
This is useful, for example, to log all invocations of the
|
|
.Va execve
|
|
system call.
|
|
.Pp
|
|
Policy entries may contain an appended predicate.
|
|
Predicates have the following format:
|
|
.Bd -literal -offset 4
|
|
", if" {"user", "group"} {"=", "!="} string
|
|
.Ed
|
|
.Pp
|
|
A rule is added to the configured policy only if its predicate
|
|
evaluates to true.
|
|
.Sh FILES
|
|
.Bl -tag -width xHOME/xsystrace -compact
|
|
.It Pa /dev/systrace
|
|
systrace device
|
|
.It Pa /etc/systrace
|
|
global systrace policies
|
|
.It Pa $HOME/.systrace
|
|
user specified policies
|
|
.El
|
|
.Sh EXAMPLES
|
|
An excerpt from a sample
|
|
.Xr ls 1
|
|
policy might look as follows:
|
|
.Bd -literal -offset 4
|
|
Policy: /bin/ls, Emulation: native
|
|
[...]
|
|
native-open: filename eq "$HOME" and oflags sub "ro" then permit
|
|
native-fchdir: permit
|
|
[...]
|
|
native-open: filename eq "/tmp" and oflags sub "ro" then permit
|
|
native-stat: permit
|
|
native-open: filename match "$HOME/*" and oflags sub "ro" then permit
|
|
native-open: filename eq "/etc/pwd.db" and oflags sub "ro" then permit
|
|
[...]
|
|
native-open: filename eq "/etc" then deny[eperm], if group != wheel
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr systrace 4
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility first appeared in
|
|
.Ox 3.2 .
|
|
It appeared in
|
|
.Nx 1.7 .
|
|
.Sh AUTHORS
|
|
The
|
|
.Nm
|
|
utility was developed by Niels Provos.
|
|
.Sh BUGS
|
|
Applications that use clone()-like system calls to share the complete
|
|
address space between processes may be able to replace system call
|
|
arguments after they have been evaluated by
|
|
.Nm
|
|
and escape policy enforcement.
|