248 lines
6.3 KiB
Groff
248 lines
6.3 KiB
Groff
.\" $NetBSD: systrace.4,v 1.10 2003/07/16 11:35:04 wiz 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 July 14, 2003
|
|
.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 SYSTR_POLICY_ASK
|
|
Send a message on
|
|
.Pa /dev/systrace
|
|
requesting the access policy for the system call.
|
|
.It SYSTR_POLICY_PERMIT
|
|
Immediately allow the system call.
|
|
.It 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
|
|
pid_t msg_pid;
|
|
int16_t msg_policy;
|
|
union {
|
|
struct str_msg_emul msg_emul;
|
|
struct str_msg_ask msg_ask;
|
|
struct str_msg_child msg_child;
|
|
} msg_data;
|
|
};
|
|
|
|
struct str_msg_emul {
|
|
char emul[SYSTR_EMULEN];
|
|
};
|
|
|
|
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
|
|
.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
|
|
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 */
|
|
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 */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
Valid return values for
|
|
.Em stra_policy
|
|
are
|
|
SYSTR_POLICY_PERMIT, SYSTR_POLICY_ASK and 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.
|
|
.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
|