325 lines
9.0 KiB
Groff
325 lines
9.0 KiB
Groff
.\" $NetBSD: systrace.1,v 1.24 2003/05/21 06:23:29 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 May 21, 2003
|
|
.Dt SYSTRACE 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm systrace
|
|
.Nd generate and enforce system call policies
|
|
.Sh SYNOPSIS
|
|
.Nm systrace
|
|
.Op Fl AaitUu
|
|
.Op Fl c Ar uid:gid
|
|
.Op Fl d Ar policydir
|
|
.Op Fl f Ar file
|
|
.Op Fl g Ar gui
|
|
.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.
|
|
Its privilege elevation feature can be used to obviate the
|
|
need to run large, untrusted programs as root when only one or two
|
|
system calls require root privilege.
|
|
.Pp
|
|
The access policy can be generated interactively or obtained from a
|
|
policy file.
|
|
Interactive policy generation will be performed by the
|
|
.Dq notification user agent ,
|
|
normally
|
|
.Xr xsystrace 1 ,
|
|
unless text mode is specified via
|
|
.Fl t .
|
|
.Pp
|
|
When running in
|
|
.Dq automatic enforcement
|
|
mode, 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
|
|
Automatically generate a policy that allows every operation the
|
|
application executes.
|
|
The created policy functions as a base that can be refined.
|
|
.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 c Ar uid:gid
|
|
Specifies the
|
|
.Va uid
|
|
and
|
|
.Va gid
|
|
that the monitored application should be executed with,
|
|
which must be specified as nonnegative integers (not as names).
|
|
This is useful in conjunction with privilege elevation and requires
|
|
root privilege.
|
|
.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 f Ar file
|
|
The policies specified in
|
|
.Ar file
|
|
are added to the policies that
|
|
.Nm
|
|
knows about.
|
|
.It Fl g Ar gui
|
|
Specifies an alternative location for the notification user interface.
|
|
.It Fl i
|
|
Inherits the policy - child processes inherit policy of the parent binary.
|
|
.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 .
|
|
.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 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 .
|
|
.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 | string typeoff "re" cmdstring |
|
|
"true"
|
|
typeoff = /* empty */ | "[" number "]"
|
|
action = "permit" | "deny" | "ask"
|
|
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
|
|
.Va ask
|
|
action specifies that the user should be prompted for a decision
|
|
every time that the rule matches.
|
|
.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 .
|
|
.It re
|
|
Evaluates to true if the system call arguments matches
|
|
the specified regular expression.
|
|
.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"} {"=", "!=", "\*[Lt]", "\*[Gt]" } {number, string}
|
|
.Ed
|
|
.Pp
|
|
A rule is added to the configured policy only if its predicate
|
|
evaluates to true.
|
|
.Pp
|
|
The environment variables $HOME, $USER and $CWD are substituted in rules.
|
|
Comments, begun by an unquoted
|
|
.Sq \&#
|
|
character and continuing to the end of the line, are ignored.
|
|
.Sh PRIVILEGE ELEVATION
|
|
With
|
|
.Nm
|
|
it is possible to remove setuid or setgid binaries, and use the
|
|
privilege elevation feature instead.
|
|
Single system calls can be executed with higher privileges if
|
|
specified by the policy.
|
|
For example,
|
|
.Bd -literal -offset 4
|
|
native-bind: sockaddr eq "inet-[0.0.0.0]:22" then permit as root
|
|
.Ed
|
|
.Pp
|
|
allows an unprivileged application to bind to a reserved port.
|
|
Privilege elevation requires that the
|
|
.Nm
|
|
process is executed as root.
|
|
.Pp
|
|
The following statements can be appended after the
|
|
.Va permit
|
|
in a policy to elevate the privileges for the matching system call:
|
|
.Bd -literal -offset 4
|
|
as user
|
|
as user:group
|
|
as :group
|
|
.Ed
|
|
.Pp
|
|
The effective
|
|
.Va uid
|
|
and
|
|
.Va gid
|
|
are elevated only for the duration of the system call, and are restored
|
|
to the old values afterwards (except for the
|
|
.Va seteuid
|
|
or
|
|
.Va setegid
|
|
system calls).
|
|
.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, one per binary, with slashes in the full pathname
|
|
replaced by the underscore character.
|
|
.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-fsread: filename eq "$HOME" then permit
|
|
native-fchdir: permit
|
|
[...]
|
|
native-fsread: filename eq "/tmp" then permit
|
|
native-stat: permit
|
|
native-fsread: filename match "$HOME/*" then permit
|
|
native-fsread: filename eq "/etc/pwd.db" then permit
|
|
[...]
|
|
native-fsread: 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 ,
|
|
and then in
|
|
.\" NEXTRELEASE
|
|
.Nx 2.0 .
|
|
.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.
|