339 lines
8.8 KiB
Groff
339 lines
8.8 KiB
Groff
.\" $NetBSD: systrace.4,v 1.15 2007/03/07 00:41:16 dogcow Exp $
|
|
.\" $OpenBSD: systrace.4,v 1.2 2002/06/03 15:44:17 mpech Exp $
|
|
.\"
|
|
.\" Copyright (c) 2002 CubeSoft Communications, Inc.
|
|
.\" 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. Redistribution of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Neither the name of CubeSoft Communications, nor the names of its
|
|
.\" contributors may 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.
|
|
.\"
|
|
.Dd June 30, 2005
|
|
.Dt SYSTRACE 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm systrace
|
|
.Nd enforce and generate policies for system calls
|
|
.Sh SYNOPSIS
|
|
.Cd "options SYSTRACE"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
kernel facility provides a mechanism to manipulate and enforce access
|
|
policies for system calls.
|
|
Using the
|
|
.Nm
|
|
facility it is possible to monitor and control a process's access to
|
|
the kernel through system calls.
|
|
.Pp
|
|
Access to the
|
|
.Nm
|
|
facility is provided to userland processes, such as
|
|
.Xr systrace 1 ,
|
|
through an
|
|
.Xr ioctl 2
|
|
interface on the pseudo-device
|
|
.Pa /dev/systrace .
|
|
This interface allows messages to be sent from the kernel to the
|
|
userland process to request confirmation of an access policy.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
facility can assign the following policies to system calls for a
|
|
specific process:
|
|
.Bl -tag -offset indent -width "XXXXXX"
|
|
.It Dv SYSTR_POLICY_ASK
|
|
Send a message on
|
|
.Pa /dev/systrace
|
|
requesting the access policy for the system call.
|
|
.It Dv SYSTR_POLICY_PERMIT
|
|
Immediately allow the system call.
|
|
.It Dv SYSTR_POLICY_NEVER
|
|
Immediately deny the system call and return an error code.
|
|
.El
|
|
.Sh SYSTRACE MESSAGES
|
|
A
|
|
.Xr read 2
|
|
operation on the
|
|
.Nm
|
|
pseudo-device will block if there are no pending messages, or
|
|
return the following structure:
|
|
.Bd -literal
|
|
struct str_message {
|
|
int32_t msg_type;
|
|
#define SYSTR_MSG_ASK 1
|
|
#define SYSTR_MSG_RES 2
|
|
#define SYSTR_MSG_EMUL 3
|
|
#define SYSTR_MSG_CHILD 4
|
|
#define SYSTR_MSG_UGID 5
|
|
#define SYSTR_MSG_POLICYFREE 6
|
|
#define SYSTR_MSG_EXECVE 7
|
|
#define SYSTR_MSG_SCRIPTNAME 8
|
|
pid_t msg_pid;
|
|
uint16_t msg_seqnr; /* answer has to match seqnr */
|
|
int16_t msg_policy;
|
|
union {
|
|
struct str_msg_emul msg_emul;
|
|
struct str_msg_ugid msg_ugid;
|
|
struct str_msg_ask msg_ask;
|
|
struct str_msg_child msg_child;
|
|
struct str_msg_execve msg_execve;
|
|
} msg_data;
|
|
};
|
|
|
|
struct str_msg_emul {
|
|
char emul[SYSTR_EMULEN];
|
|
};
|
|
|
|
struct str_msg_ugid {
|
|
uid_t uid;
|
|
gid_t gid;
|
|
};
|
|
|
|
struct str_msg_execve {
|
|
char path[MAXPATHLEN];
|
|
};
|
|
|
|
struct str_msg_ask {
|
|
int32_t code;
|
|
int32_t argsize;
|
|
register_t args[SYSTR_MAXARGS];
|
|
register_t rval[2];
|
|
int32_t result;
|
|
};
|
|
|
|
struct str_msg_child {
|
|
pid_t new_pid;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
These messages are all sent to the userland control process.
|
|
.Bl -tag -width SYSTR_MSG_XXXXXXXXXX
|
|
.It Dv SYSTR_MSG_ASK
|
|
This message is sent whenever the kernel does not have a cached simple
|
|
policy for system call number
|
|
.Ar code
|
|
within the currently set emulation.
|
|
.It Dv SYSTR_MSG_RES
|
|
This message is sent whenever a system call is flagged with
|
|
.Dv SYSTR_FLAGS_RESULT .
|
|
.It Dv SYSTR_MSG_EMUL
|
|
This message is sent whenever a process gains a child.
|
|
.It Dv SYSTR_MSG_UGID
|
|
This message is sent whenever the effective UID or GID has changed
|
|
during the execution of a system call.
|
|
.It Dv SYSTR_MSG_POLICYFREE
|
|
This message is sent whenever the kernel frees the policy identified by
|
|
.Va msg_policy .
|
|
.It Dv SYSTR_MSG_EXECVE
|
|
This message is sent whenever, before a call to
|
|
.Xr execve 2
|
|
a process is privileged (technically, the process has the
|
|
,Dv P_SUGID
|
|
flag set),
|
|
but after the call these privileges have been dropped.
|
|
The new image name is specified in the
|
|
.Ar path
|
|
argument.
|
|
.El
|
|
.Sh IOCTL INTERFACE
|
|
The
|
|
.Nm
|
|
facility supports the following
|
|
.Xr ioctl 2
|
|
operations:
|
|
.Bl -tag -width "XXXXXX"
|
|
.It Dv STRIOCATTACH Fa "pid_t"
|
|
Attach to the process with the specified process ID.
|
|
This operation will fail under the following conditions:
|
|
.Pp
|
|
.Bl -enum -offset indent -compact -width 2n
|
|
.It
|
|
The process is trying to attach to itself.
|
|
.It
|
|
The process is a system process.
|
|
.It
|
|
The process is being traced already.
|
|
.It
|
|
You do not own the process and you are not root.
|
|
.It
|
|
The process is
|
|
.Xr init 8 ,
|
|
and the
|
|
kernel was not compiled with
|
|
.Cd option INSECURE .
|
|
.El
|
|
.It Dv STRIOCDETACH Fa "pid_t"
|
|
Wake up the process if it is waiting for an answer, and detach from
|
|
it.
|
|
.It Dv STRIOCANSWER Fa "struct systrace_answer"
|
|
Notify the
|
|
.Nm
|
|
facility in response to a
|
|
.Dv SYSTR_MSG_ASK
|
|
message what to do with a system call that was assigned a policy of
|
|
.Dv SYSTR_POLICY_ASK .
|
|
.Bd -literal
|
|
struct systrace_answer {
|
|
pid_t stra_pid; /* PID of process being traced */
|
|
uint16_t stra_seqnr;
|
|
int16_t reserved;
|
|
uid_t stra_seteuid;
|
|
gid_t stra_setegid;
|
|
int32_t stra_policy; /* Policy to assign */
|
|
int32_t stra_error; /* Return value of denied syscall
|
|
(will return EPERM if zero) */
|
|
int32_t stra_flags;
|
|
#define SYSTR_FLAGS_RESULT 0x0001 /* Report syscall result */
|
|
#define SYSTR_FLAGS_SETEUID 0x002
|
|
#define SYSTR_FLAGS_SETEGID 0x004
|
|
};
|
|
.Ed
|
|
.Pp
|
|
Valid return values for
|
|
.Em stra_policy
|
|
are
|
|
.Dv SYSTR_POLICY_PERMIT ,
|
|
.Dv SYSTR_POLICY_ASK ,
|
|
and
|
|
.Dv SYSTR_POLICY_NEVER .
|
|
.It Dv STRIOCIO Fa "struct systrace_io"
|
|
Copy data in/out of the process being traced.
|
|
.Bd -literal
|
|
struct systrace_io {
|
|
pid_t strio_pid; /* PID of process being traced */
|
|
int32_t strio_ops;
|
|
#define SYSTR_READ 1
|
|
#define SYSTR_WRITE 2
|
|
void *strio_offs;
|
|
void *strio_addr;
|
|
size_t strio_len;
|
|
};
|
|
.Ed
|
|
.It Dv STRIOCPOLICY Fa "struct systrace_policy"
|
|
Manipulate the set of policies.
|
|
.Bd -literal
|
|
struct systrace_policy {
|
|
int strp_op;
|
|
#define SYSTR_POLICY_NEW 1 /* Allocate a new policy */
|
|
#define SYSTR_POLICY_ASSIGN 2 /* Assign policy to process */
|
|
#define SYSTR_POLICY_MODIFY 3 /* Modify an entry */
|
|
int32_t strp_num;
|
|
union {
|
|
struct {
|
|
int16_t code;
|
|
#define SYSTR_POLICY_ASK 0
|
|
#define SYSTR_POLICY_PERMIT 1
|
|
#define SYSTR_POLICY_NEVER 2
|
|
int16_t policy;
|
|
} assign;
|
|
pid_t pid;
|
|
int32_t maxents;
|
|
} strp_data;
|
|
#define strp_pid strp_data.pid
|
|
#define strp_maxents strp_data.maxents
|
|
#define strp_code strp_data.assign.code
|
|
#define strp_policy strp_data.assign.policy
|
|
};
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Dv SYSTR_POLICY_NEW
|
|
operation allocates a new policy with all entries initialized to
|
|
.Dv SYSTR_POLICY_ASK ,
|
|
and returns the new policy number into
|
|
.Va strp_num .
|
|
The
|
|
.Dv SYSTR_POLICY_ASSIGN
|
|
operation attaches the policy identified by
|
|
.Va strp_num
|
|
to
|
|
.Va strp_pid ,
|
|
with a maximum of
|
|
.Va strp_maxents
|
|
entries.
|
|
The
|
|
.Dv SYSTR_POLICY_MODIFY
|
|
operation changes the entry indexed by
|
|
.Va strp_code
|
|
to
|
|
.Va strp_policy .
|
|
.It Dv STRIOCGETCWD Fa "pid_t"
|
|
Set the working directory of the current process to that of the
|
|
specified process.
|
|
.It Dv STRIOCRESCWD
|
|
Restore the working directory of the current process.
|
|
.It Dv STRIOCREPORT Fa "pid_t *"
|
|
Report the current emulation a process is using inside the
|
|
.Vt msg_emul
|
|
structure.
|
|
.It Dv STRIOCREPLACE Fa "struct systrace_replace *"
|
|
Arrange for system call arguments to be replaced by arguments supplied
|
|
by the monitoring process.
|
|
.Bd -literal
|
|
struct systrace_replace {
|
|
pid_t strr_pid;
|
|
uint16_t strr_seqnr;
|
|
int16_t reserved;
|
|
int32_t strr_nrepl; /* # of arguments to replace */
|
|
void *strr_base; /* Base user memory */
|
|
size_t strr_len; /* Length of memory */
|
|
int32_t strr_argind[SYSTR_MAXARGS]; /* Argument indexes */
|
|
size_t strr_off[SYSTR_MAXARGS]; /* Argumen offsets */
|
|
size_t strr_offlen[SYSTR_MAXARGS]; /* Argument sizes */
|
|
int32_t strr_flags[SYSTR_MAXARGS];
|
|
};
|
|
.Ed
|
|
.It Dv STRIOCSCRIPTNAME Fa "struct systrace_scriptname *"
|
|
Set the path of executed scripts to
|
|
.Va sn_scriptname .
|
|
.Bd -literal
|
|
struct systrace_scriptname {
|
|
pid_t sn_pid;
|
|
char sn_scriptname[MAXPATHLEN];
|
|
};
|
|
.Ed
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width "/dev/systrace" -compact
|
|
.It Pa /dev/systrace
|
|
system call tracing facility
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr systrace 1 ,
|
|
.Xr ioctl 2 ,
|
|
.Xr read 2 ,
|
|
.Xr options 4 ,
|
|
.Xr init 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
facility first appeared in
|
|
.Ox 3.2 ,
|
|
and then in
|
|
.Nx 2.0 .
|
|
.\" .Sh BUGS
|
|
.Sh CAVEATS
|
|
When creating new policies, if
|
|
.Va strp_maxents
|
|
is not large enough to accommodate any system calls needed for
|
|
fundamental process operations, the traced process will block
|
|
forever.
|