                                                                        README

This is the README file for suidcontrol 0.1.


suidcontrol is an experimental utility for managing suid/sgid policy
under FreeBSD.  The primary intent is to allow system managers to
generate scripts to apply to new FreeBSD installations so that they
can minimize risk associated with the plethora of tools requiring
additional privilege to run.

Please read the LICENSE file as well as the BUGS and WARNINGS sections
before proceeding, as this is DEVELOPMENTAL software.  As it is
experimental, it should not currently be applied to production
machines unless you are absolutely sure.  Needless to say, the license
covers my absolute lack of responsibility for any problems you incur
by not heeding this warning.

	Robert Watson



TABLE OF CONTENTS
-----------------

0. LICENSE
1. BUILDING
2. USING
3. BUGS
4. WARNINGS
5. POSSIBLE USES

0. LICENSE
----------

This software is available under a BSD-style license.  Please read the
LICENSE file included with this software and documentation.

1. BUILDING
-----------

This software should build almost cleanly under both -CURRENT and
-STABLE.  However, as these are moving targets, there may be problems.
Also, due to a prototyping problem, the lex generated code will cause
some warnings when compiling.  These may safely be ignored.

No per-version configuration is needed.  You can simply run

make

in the suidcontrol directory.

2. USING
--------

suidcontrol provides a dialog-based interface (similar to sysinstall)
allowing the selection of a "policy" to apply to sets of related
binaries.  A typical invocation of suidcontrol provides a reference to
a setuid binary policy description file (for example, policy-stable),
and to an implementation file -- that is, the location where a
description of the selected policy options can be written.  This
implementation file may then be passed to an implementation utility
that generates an sh shell script that actually implements the
selected policy on a default FreeBSD install.

A typical invocation might be:

./suidcontrol -c policy-stable -i implementation

A dialog-based interface pops up, providing a list of sets of suid
utilities along with a brief description of each.  When a set is
selected using the space bar, a list of possible policies for the set
is presented.  "default" represents the default FreeBSD installation
permissions.  The remaining options depend on the utility in question,
and whether it makes use of setuid or setgid flags.  If a non-empty
implementation file was provided, these settings are read in as the
defaults.  Usually, the options consist of:

	disabled	Disables the utility for all users
	root-only	Restricts execution to root
	wheel-only	Restricts execution to the wheel group

The space bar may be used to select the policy choice.  As with
syscontrol (and as required by the dialog package), Enter either saves
or cancels the setting.  When you are done defining the policy to use,
press Enter at the main menu either over Save or Cancel.  You will be
prompted for further behavior.  Saving may be wise if you like your
changes.

applysuid allows you to generate a script file implementing the policy
from a combination of the policy file and the implementation file.  A
typical invocation of applysuid looks a lot like the suidcontrol
invocation:

./applysuid -c policy-stable -i implementation -a out.sh

Any problems will be reported with error messages.

statfile is a utility to generate the "default" entries in the policy
file.  Pass a set of /-prefixed paths to statfile and it will generate
the prototype policy file for you.  This is useful for generating
policy files for specific packages, or new platforms.  This software
has not been extensively tested.

3. BUGS
-------

Only a -stable policy file is provided.  A -current file should be
provided.  Also, policy files for specific RELEASE versions of FreeBSD
should be provided.

Dialog contains bugs.  Also, this use of dialog may be buggy.  This
results in incorrect rendering in some environments.  For example,
under xterm under 3.0-CURRENT, the main menu is not correctly redrawn
when returning from a particular set configuration menu.  Any patches
that fix this would be welcomed.

This software does not correctly deal with the system immutable flag.
This should be fixed, and currently results in errors during application
of the implementation script if you attempt to modify the permissions
of an immutable file.  This software should both know how to correctly
deal with these permissions, and manage these permissions.  Currently
it knows only about owners and permissions, not about extended file
flags.

4. WARNINGS
-----------

You can disable a perfectly functional system by hitting enter a few
times and running the script generated.  BEWARE!

The policy file for -stable is believed to be correct.  However, it
may not be, and as such, might not be able to correctly restore your
permissions if you change your mind.  Similarly, while the
descriptions of various policies are believed to be correct, all
permutations HAVE NOT BEEN TESTED.  Similarly, the descriptions may
not be entirely accurate.

suidcontrol cannot control permissions on files that are not described
in its policy file.  As such, it will not provide any control over the
ssh binary that is setuid root.

5. POSSIBLE USES
----------------

Easily disable UUCP, which you probably do not use.  UUCP access can
be considered equivilent to root access under FreeBSD, and the UUCP
code may contain serious security flaws.

Easily disable multicast setuid programs that you probably do not use.

Easily disable ppp software that you may not use.

Easily restrict execution of network debugging programs that most
users may not need.

Easily disable setuid printer support programs that many installations
do not need.

6. CONTACT INFORMATION
----------------------

FreeBSD related questions: robert+freebsd@cyrus.watson.org
General suidcontrol related questions: robert+suidcontrol@cyrus.watson.org
Personal email: robert@fledge.watson.org

FreeBSD Hardening Project: http://www.watson.org/fbsd-hardening/

Thanks to:
	Jan Koum - discussion of FreeBSD security and freebsd-sec HOW-TO
	TISLabs NetSec and Wrappers research groups

$Id: README,v 1.2 1998/08/23 15:01:44 robert Exp $