.\" $Id: manifest.man,v 1.3 2012/09/07 15:08:11 ksb Exp $
.\" by Kevin Braunsdorf
.\" $Compile: Display%h
.\" $Display: ${groff:-groff} -Tascii -man %f | ${PAGER:-less}
.\" $Display(*): ${groff:-groff} -T%s -man %f
.\" $Install: %b -mDeinstall %o %f && cp %f $DESTDIR/usr/local/man/man7/manifest.7
.\" $Deinstall: ${rm-rm} -f $DESTDIR/usr/local/man/[cm]a[nt]7/manifest.7*
.TH MANIFEST 7 LOCAL
.SH NAME
manifest - check a proposed escalation program against a list
.SH SYNOPSIS
.ds PN "manifest
\fI\*(PN\fP [\fB\-P\fP\~\fIpid\fP] [\fB\-C\fP\~config] [\fB\-f\fP\~\fIfile\fP] [\fB\-g\fP\~\fIgroup\fP] [\fB\-R\fP\~\fIroot\fP] [\fB\-u\fP\~\fIuser\fP] \fImnemonic\fP \fIprogram\fP \fIeuid\fP:\fIegid\fP \fIcred_type\fP:\fIcred\fP
.br
\fI\*(PN\fP \fB\-h\fP|\fB\-H\fP
.br
\fI\*(PN\fP \fB\-V\fP

.SH DESCRIPTION
This helmet is intended to allow a list of approved commands (or scripts)
to be grouped under a single \fBop\fP \fImnemonic\fP.  A file provided
to the helmet contains a list of the allowed commands, each non-comment
line contains a \fBperl\fP regular expression, possible prefixed by
an exit code.  If that RE matches the proposed \fPprogram\fP, then
the proposed exit code represents the exit status of \fI\*(PN\fP.
.P
As either the escalated login's or the client's home directory may
differ across instances, the REs list allows the replacement of
2 special leading strings.
A leading tilde slash (\fB~/\fP) is replaced by the proposed \fIeuid\fP's
home directory prefixed with a circumflex (\fB^\fP).
A leading dot slash (\fB./\fP) is replaced by the escalated uid's
home directory prefixed with a circumflex (\fB^\fP).  This allows
a match against files which may be rooted at different places on
various client machines.
.P
In the list of REs leading hash (\fB#\fP) to end of line comments are
ignored.  This allows revision identification and \fBmk\fP markup
within each file.  Blank lines are also ignored.

.SH OPTIONS
This program takes all the \fBop\fP provided options, but actually
doesn't look at any of them (other than \fB\-P\fP, and the program path).
It does sanity check them, just the same.

.SH ENVIRONMENT
Like any helmet, most of the configuration is passed from \fBop\fP
via the environment.
.TP
.nf
\fBMANIFEST_LIST\fP\fIname\fP=\fIpath\fP
.fi
Every \fIpath\fP listed as a value of a matching environment variable
is searched for a matching RE.  The files are consulted in lexical
order of the \fIname\fP's.
.TP
.nf
\fBMANIFEST_WARN\fP\fIname\fP=\fIsorry\fP
.fi
The warning message to replace the common "Sorry" denial message.  If
there is not a matching \fIname\fP, then the empty \fIname\fP is
consulted as a better default.
.TP
.nf
\fBMANIFEST_REVEAL\fP=\fIprefix\fP
.fi
The standard reveal logic, see \fBop-jacket\fP(7).

.P
All of these are deleted from each \fIcmd\fP's environment:
\fB$IFS\fP, \fB$CDPATH\fP, \fB$ENV\fP, \fB$BASH_ENV\fP to prevent
\fBperl\fP(1) from refusing to run any commands.  There is no way
to set them, but we do not \fBfork\fP any processes.

.SH EXAMPLES
These are example from the command-line:
.TP
.nf
/usr/local/libexec/jacket/manifest \-V
.fi
Output the version of the program.
.TP
.nf
/usr/local/libexec/jacket/manifest \-H
.fi
Output a summary of the environment expected.

.P
All of these are snips from the \fBop\fP \fIaccess.cf\fP file.
Note that you \fBmust\fP allow any referenced environment variables
into the escalated environment, and it is a really good idea to
include a \fB$PATH\fP.
.sp
.PD 0
.TP
.nf
jacket=/usr/local/libexec/jacket/manifest
.fi
.TP
.nf
$MANIFEST_LIST=~/.allowed
.fi
Consult the proposed login's home directory for an allowed list
(which starts with a dot to hide it from \fBls\fP).
.sp
.TP
.nf
jacket=/usr/local/libexec/jacket/manifest
.fi
.TP
.nf
$MANIFEST_LIST=./allow/$l
.fi
Consult the escalated login's home directory for an allow list based
on the client login's user name.
.sp
.TP
.nf
jacket=/usr/local/libexec/jacket/manifest
.fi
With no in-scope manifest list this helmet always fails.
.sp
.TP
.nf
jacket=/usr/local/libexec/jacket/manifest
.fi
.TP
.nf
$MANIFEST_LIST=/etc/shells
.fi
Allow any system shell, since the \fB/etc/shells\fP file happens
to look just like a list of expressions to this program.
.PD

.SH NOTES
The regular expression list to allow 2 harmless commands, and forbid
the \fBdate\fP command:
.RS
.nf
# $Id... revision control markup $
^/bin/true$
^/bin/false$
# date can set the system clock, never allow that --ksb
73=^/bin/date$
.fi
.RE
The \fBdate\fP program is excluded with the  code CANTCREAT (\fB73\fP),
which is a good one for \*(lqyou are not the superuser\*(rq, since we
do not want escalated mortals setting the system clock.
.P
There is a hackish way to set the default exit code:  use a negative
number with an empty RE.  For example \fB-63=\fP sets the code for
any unmatched \fBprogram\fP to 63 (which is in the range of
an application specific meanings).

.SH BUGS
This jacket trusts that the \fBop\fP configuration won't allow a
malicious shell command in of the regular expression lists.  Since
those lists could be writable by others than the superuser, you
should take care to audit and protect them.
.P
We do not check the options to the command.  It is possible to
code another helmet for that purpose.  More often a fixed parameter
list is provided to each listed script (or shell).
.P
Always allow the internal \fBecho\fP command, if that is a possible match.
(Note that is it \fBnot\fP prefixeed with a slash, as it is not really
an executable file.)

.SH AUTHOR
K S Braunsdorf, from the Non-Player Character Guild
.br
op at-not-a-spammer ksb dot npcguild.org.nopinks

.SH "SEE ALSO"
.hlm 0
op(1l), op-jacket(7l), stampctl(8l), getpeereid(3), perl(1), shells(5)