186 lines
5.7 KiB
Groff
186 lines
5.7 KiB
Groff
.\" $NetBSD: systrace.1,v 1.3 2002/06/20 10:07:42 agc Exp $
|
|
.\" $OpenBSD: systrace.1,v 1.16 2002/06/13 00:15:00 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 aAitU
|
|
.Op Fl g Ar gui
|
|
.Op Fl f Ar file
|
|
.Op Fl p Ar pid
|
|
.Ar command ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility enforces system call policies for applications by
|
|
constraining the application's access to the system.
|
|
The policy is generated interactively.
|
|
Operations not covered by the policy raise an
|
|
alarm and allow a 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 i
|
|
Inherits the policy - child processes inherit the 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 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
|
|
.Sh POLICY
|
|
The policy is specified via the following grammar:
|
|
.Bd -literal -offset 4
|
|
filter = expression "then" action errorcode
|
|
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 "]"
|
|
.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 value
|
|
.Do
|
|
inherit
|
|
.Dc
|
|
has a special meaning when used with a
|
|
.Va permit
|
|
rule for the
|
|
.Va execve
|
|
system call.
|
|
In that case, the current policy is inherited for the new binary.
|
|
.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
|
|
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 AUTHORS
|
|
The
|
|
.Nm
|
|
utility was developed by Niels Provos.
|