
 CAPSEL Linux kernel security module version 1.5.5
========================================================================

Capsel module is a small but very powerful loadable Linux kernel module.
It is designed to improve overall system security with adding a few
security features:

1. It allows to set restrictions on execve system call witch may be used
   to limit certain users and/or programs to execute only limited set of 
   executables.

2. Limit for chroot system call that can't be used more than once which
   prevents breaking of chroot jail even for root-owned processes.

3. Allows to modify on Linux capability sets for each process which   
   may be used to decrease number of setuid-root executables and
   root-privileged processes on the system.

4. It prevents users from dumping core and ptracing executables that
   they have no permissions to read. It also prevent executing binaries
   if parts of the calling process are shared with other processes.

Capsel module is designed to work under kernel version 2.2.x. It may be
possible this module to work under kernel version 2.4.x but it hasn't
been tested. If anyone has successfully tested it please let me know.


 INTRODUCTION
========================================================================

Execve system call is a function that allows any process to execute
other processes. If this function succeeds it doesn't return and 
text, data, bss and stack of the calling process are overwritten by
that of the new program loaded. The program invoked inherits the
calling process's PID, and any open file descriptors that are not
set to close on exec. You can see execve(2) for more information.

With this module you may restrict execve system call for certain
programs. It allows you to create a set of executables that are
permitted to be executed. Because most of privileges programs doesn't
need to execute other programs it is possible to deny all execve calls.


Chroot system call may be used only by privileged processes to change
its root directory for all file system operations. If process drops all
its privileges it increases system security because there is no way to
access files outside of new root directory. It is called 'chroot jail'.
The problem is that privileged processes may use another chroot call to
break the jail. This problem may be solved by not allowing changing
root directory if it is different for file system root directory.


Linux capability system is described in doc/Linux-Privs.tar documents
by Andrew Morgan.

This module allows you to set capability bits on programs that don't
need full privileges to work correctly. It may be used to decrease
number of setuid-root binaries on system and number of processes working
with root privileges.


This module also does additional checking before executing new program.

This check is done to prevent users from ptracing or dumping core of
executables that they have no permissions to read. If you patch your
glibc to prevent users from using dangerous variables such as LD_PRELOAD
you may use executables with some capability bits raised without setting
setuid/setgid bit for fake user/group. If you don't want or don't have
patch for glibc you may set setgid bit for those executables that are
to work with raised privileges. It is very important since without this
your users may takeover your privileged programs with LD_PRELOAD trick.

Additional check is done to prevent executing binaries if calling process
shares parts of its executable (i.e. file descriptors, memory, signal 
handlers) with other processes. Kernel does this check when executing
setuid/setgid binaries, capsel does it for all binaries.


 COMPILATION
========================================================================

Module is distributed as source version only. Before it may be used it
needs to be compiled. In order to compile it you need Linux kernel
header files properly installed on your system.

Module is distributed as tar.gz compressed archive. You need to
uncompress it with command:

	tar -zxvf capsel-X.Y.Z.tar.gz

where X.Y.Z is version you have. Then go into newly created directory:

	cd capsel-X.Y.Z

Source files doesn't need to be configured before compiling. You may
just type

	make

command and after few seconds (or minutes on slow systems) module 
compilations should be completed. If it doesn't correctly compile 
check your kernel header files if they are properly installed. 
If you are unable to solve the problem please send me an e-mail.


 INSTALLATION
========================================================================

After compilation step you need to copy new object file named capsel.o
into your kernel's modules directory. You may do this by hand or with

	make install 

option. Default configuration file is copied into /etc directory 
if there is no one.

Before you can load your module you need to configure it. You may
use default configuration file if you just want to test the module.
Module can be loaded into memory with command
	
	make start

if you are in source directory or

	modprobe capsel
	
If you want to test if module has already been loaded type

	lsmod

and you should see it in the list of loaded modules if it is present
in memory.

To unload module from memory type
	
	make stop
	
at source directory or just type

	rmmod capsel

If you want to reload module you need to unload it from memory and then
load it again into memory.


 CONFIGURATION
========================================================================

Module uses one configuration file named /etc/capsel.conf. This file is
read while loading module into memory. If it can't be read module fails
to load. All syntax errors are reported via printk to system logs.

Configuration file contains set of rules. Rule begins with absolute pathname
to the executable file that we want to control. Simple rule looks like:

/bin/sh { }

and it does nothing.

Inside brackets we may put set of options. First type of options specify 
a filter which process must match:

uid
	Syntax: uid any | user_id_value
	If this option is set only process with UID or EUID equal to
	value of this option matches the rule.
	
gid
	Syntax: gid any | group_id_value
	If this option is set only process with GID or EGID equal to
	value of this option matches the rule.

groups
	Syntax: groups yes | no
	If set to 'yes' process's supplemental group IDs are checked 
	against the 'gid' option value. 
	If 'gid' option has value of 'any' this option has no effect.

Miscellaneous options:
log
	Syntax: log nothing | debug | security
	This defines logging level for the module.
	
ignore
	Syntax: ignore yes | no
	If this option is enabled all restrictions (cap, uidcap, exec, 
	chroot, root) are ignored. Useful for debugging and while 
	creating new configuration.

Options that allow to control privileges of running processes:

chroot	
	Syntax: chroot yes | no
	If set to 'yes' process is restricted to use chroot system call
	only if its root directory is equal to file system root directory.
	In this case no process may break chroot jail even with root
	privileges.

cap 	
	Syntax: cap [ effective ] [ permitted ] [ inheritable ]
		    [ set | raise | lower | mask | default ]
		    full | empty | ( { list_of_capabilities... } ) ]
	This option allows to modify process's capability bits just after
	starting it.
	Process may have some capability bits raised and some bits
	cleared. Three arguments defines what capability sets are
	modified: 'effective', 'permitted' or 'inheritable'. If no
	such arguments are specified all three capability sets may be
	changed. It is followed by one of 'set', 'raise', 'lower' or
	'mask' word (default is 'set') which determines operation done
	on capability bits:
	'set'	-listed capability bits are raised and all non-listed
		 capability bits are cleared
		 This is default for 'cap' option.
	'raise' -listed capability bits are raised and all non-listed
		 capability bits are left unchanged
	'lower' -listed capability bits are cleared and all non-listed
		 capability bits are left unchanged
	'mask'	-listed capability bits are left unchanged and all 
		 non-listed capability bits are cleared
		 This is default for 'uidcap' option.
	'default'-restores default behavior of capabilities inheritance
	         after execve and setuid system calls.
	'set' is useful in adding capability bits to non-privileged
	programs which need some privileges to do its work (ex. ping)
	'mask' is useful in 'uidcap' option described below.
	'raise' and 'lower' are useful if we use inheritance of 
	capabilities.
	'empty'/'full' arguments mean empty/full capability set.
	This option may be specified multiple times and its values
	are combined together, i.e.:
	cap raise { bind }
	cap lower { setuid }
	results in raising bind capability and clearing setuid capability.
	Last specified 'cap' option has highest priority.

WARNING:
	Additional attention needs to be taken when creating secure 
	configuration with capsel module that would increase privileges 
	for some non-setuid binaries (i.e. ping) that no user can take 
	the control over their execution (with LD_PRELOAD or ptrace stuff)
	and then takeover their privileges. A lot of them needs to be 
	checked against buffer overflows and other vulnerabilities that 
	may open a security hole in your system. Particularly, do _not_
	try to increase privileges for binaries that are not designed
	to be executed as setuid-root.

uidcap
	Syntax:	uidcap [ effective ] [ permitted ] [ inheritable ]
		       [ set | raise | lower | mask | default ]
		       full | empty | ( { list_of_capabilities... } ) ]
	This option has the same syntax as cap. It is used to define
	operation done on capability bits after changing process's xUID
	with setuid, setreuid and setresuid system calls from UID specified
	in 'uid' option.
	If 'uid' option has value of 'any' this option has no effect.
	It is very useful to use 'uidcap' with 'mask' argument that
	allows you to define set of capability bits that are not cleared
	while dropping all other privileges. It may be used in most
	network daemons (such as sendmail or wu-ftpd). Unfortunately,
	most of them needs to be patched. Some patches will be soon 
	available on my home page.
	You may restore standard behavior of setxuid system calls with
	'uidcap default'.

exec
	Syntax:	exec [ allow | deny ] all | 
		       ( { list_of_executables... } )
	This option allows you to specify set of executables that this
	process may or may not execute. This may improve system	security 
	when applied to network daemons especially if they are running 
	without root privileges. It may prevent hackers from executing 
	exploits for other local buggy software.

root	Syntax: root default | root_directory
	This useful option may be used to force new root directory for 
	all file system operations for miscellaneous executables even 
	for those executed without any privileges. This option may be
	useful to create chroot jail for many networking programs like 
	IRC clients, lynx and so on. Here is example of	secure and not 
	so much restricted configuration:
	/usr/bin/lynx {
		root /chroot
		chroot yes
		exec deny all
	}
	Although /chroot should be mounted on separate partition with 
	at least nodev,nosuid and noexec options, it may have writable
	directories that allows users downloading miscellaneous files.
	

There are two special rules. First is default rule (word 'default' is
used instead of path to executable) which options are used when creating
standard rule. This rule is also used if there is no other matching
option. Second special rule begins with word 'any' (just like default
rule) and is very similar to default rule but its options are not used
when creating standard rule. They both may be used multiple times.

Comments may be used in configuration file.
# Comments started with # character to the end of line
// Comments started with // to the end of line just like in C++
/* All text between '/*' and '*/' just like in C and C++ */
Remember, that # // /* and */ must have be separated by white space
(space, tab, newline) from other words.

 LOGS
========================================================================

Module generates various messages while running. These messages are
written in human readable format using printk kernel function. It is
possible to log all messages  Module uses kernel printk function to log
messages. Log level may be altered in configuration file.


 FAQ
========================================================================

There is no Frequently Asked Question document available yet. 
If you have some question please ask me directly via e-mail.


 COPYING
========================================================================

 Copyright (C) 1999-2000 Wojciech Purczynski <wp@elzabsoft.pl>

 THIS PROGRAM IS FREE SOFTWARE; YOU CAN REDISTRIBUTE IT AND/OR MODIFY
 IT UNDER THE TERMS OF THE GNU GENERAL PUBLIC LICENSE AS PUBLISHED BY
 THE FREE SOFTWARE  FOUNDATION;  EITHER  VERSION 2 OF THE LICENSE, OR
 (AT YOUR OPTION) ANY LATER VERSION.

 THIS PROGRAM IS DISTRIBUTED IN THE HOPE THAT IT WILL BE USEFUL,
 BUT WITHOUT ANY WARRANTY; WITHOUT EVEN THE IMPLIED  WARRANTY OF
 MERCHANTABILITY OR FITNESS  FOR A PARTICULAR  PURPOSE.  SEE THE
 GNU GENERAL PUBLIC LICENSE FOR MORE DETAILS.


 MY NOTES
========================================================================

If you feel it useful please let me know.
Please send my any comments and/or suggestions.

I hope this software will let you have secure and stable Linux system.


 CONTACT
========================================================================

Author:		Wojciech Purczynski

Address:	Baczynskiego 2/10
		41-813 Zabrze
		Poland

Phone:		+48604432981

e-mail: 	wp@elzabsoft.pl

Home page:	http://www.elzabsoft.pl/~wp/capsel.html

Download:	http://www.elzabsoft.pl/~wp/capsel.tgz
		ftp://ftp.elzabsoft.pl/capsel/capsel.tgz
