
 capsel

 Linux kernel 2.2.x/2.4.x security module version 2.0
========================================================================

Capsel module is a small but very powerful loadable Linux kernel module.
Its advanced security features allows to improve overall system security.

[+] It allows to control execve system call. This control may be used to
    restrict this system call for certain users, groups of users or programs.

[+] It works with new security model named Linux-Privs. This new security
    model splits full root privileges into separate capabilities. These
    capabilities may be altered explicitly for each process thus causing
    processes working without full root privileges. It improves system
    security by decreasing number of setuid-root binaries and daemons
    running with full root privileges. The capsel module provides easy way
    to configure and control each process's capabilities.
    
    The CAP_NET_BIND_SERVICE capability has been enhanced in the way
    that process may be restricted to bind specified TCP or UDP protected
    ports only.

[+] Its security features prevents users from taking the control over
    processes' execution. The module disables most dangerous features 
    commonly used to exploit vulnerabilities in the running software:
  
  * It clears whole environment when executing privileged programs
    (binaries that have setuid/setgid bits set or working with raised
     capability bits)
    
  * It disables dumping core of all executables.

  * It denies executing binary if some parts of the caller executable
    (i.e. file descriptors, memory, signal handlers) are shared with 
    other processes. Kernel does such a thing for setuid/setgid binaries,
    capsel does it also for all binaries that user have no read 
    permission to or are given some extra privileges by capsel.
    
  * sysctl and ptrace system calls are restricted to privileged users
    only (/proc/sys sysctl entries are still available to unprivileged
    users, I suggest using some kernel patch like Openwall).

[+] It prevents chroot-jail breaking in the way that chroot system call may
    be used only once. It means that process that have its root directory
    not equal to the file system root directory can't use chroot system call
    even if it has CAP_SYS_CHROOT / root privileges.
   
Capsel module has been tested to work under kernel versions 2.2.14 up
to 2.2.18 and 2.4.0.

Most of its features may be ported into 2.0.x kernels. Unfortunately,
Linux-Privs security model has been implemented in kernels since 2.2.x.

THE CAPSEL MODULE SHOULD BE USED BY EXPERIENCED LINUX USERS ONLY.
DO NOT FORGET TO USE YOUR MIND INSTEAD OF THIS MODULE.

If you don't know how Linux capabilities work, please read appropriate
documentation or do not use capsel at all.



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

execve
------

Execve system call is a function that does all work when any process 
want to execute other program. 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 by some program, user or group of users.
It is possible to deny all execve system calls for privileged
processes if they does not need external programs to work properly.


chroot
------

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. Capsel prevents privileged process from breaking
'chroot jail' by not allowing it to change its root directory if its
root directory has been already changed.


Linux-Privs
-----------

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



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

Module is distributed in source version only. 

In order to compile it you need Linux kernel header files properly
installed on your system.

Module is distributed in tarball (gzip/tar 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. 



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

Install capsel module and configuration tool by typing:

	make install 

Before you can load your module you need to configure it.
Capsel uses one configuration file named /etc/capsel/default which will
be described later in this README.

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.

After loading capsel module type capsel command which executes
/sbin/capsel configuration tool that will parse configuration file(s)
and transfer it to the kernel module. Try capsel -h to view all possible
options. It is quite easy to use. If you want to change the configuration
edit your configuration files and then just type:

capsel

You will see all configuration files read and used.

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 or more configuration files. These files are read by
capsel configuration tool. This program reads /etc/capsel/default file (if
present) and all other files from /etc/capsel directory. These files are read
with random order.

Each configuration file contains set of rules. Rule begins with absolute
pathname to the executable file that we want to control. Basic
configuration file containing one simple rule looks like:

/bin/sh { }

and it causes capsel to do nothing.

Inside brackets we may put set of options. 

First set of options specifies a filter that is used by capsel to select
the rule and then to execute some action on the process according to
options described later.

uid
	Syntax: uid any | user_id_value
	If this option is set only process with UID equal to
	value of this option matches the rule.
	This option is disabled by default so UID is not checked.

user
	This is alias name for uid option.

euid
	Syntax: euid any | user_id_value
	If this option is set only process with EUID equal to
	value of this option matches the rule.
	This option is disabled by default so EUID is not checked.
	
gid
	Syntax: gid any | group_id_value
	If this option is set only process with GID equal to
	value of this option matches the rule.
	This option is disabled by default so GID is not checked.

group
	This is alias name for gid option.

egid
	Syntax: egid any | group_id_value
	If this option is set only process with EGID equal to
	value of this option matches the rule.
	This option is disabled by default so EGID is not checked.
	
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.
	This option is enabled by default and all supplemental group
	IDs are checked if 'gid' option is enabled.

Miscellaneous options:
log
	Syntax: log nothing | debug | security
	This defines logging level for the module. 'security' value
	is most useful and causes capsel to log only security related
	messages. 'debug' value is useless unless you are debugging
	capsel.
	Default value is 'security'.

Options described below specify how capsel controls privileges of executed
and running processes:

chkchroot
	Syntax: chkchroot yes | no
	If set to 'yes' process is allowed to use chroot system call
	only if its root directory is equal to the file system root 
	directory. No process with this option enabled may break chroot 
	jail even if it has root privileges. Remember that chroot jail
	may be broken by process that has capability to remove kernel
	modules or to make special devices, etc.
	This option is enabled by default.
	('chroot' option name is deprecated and should not be used.)

chksetuid
	Syntax: chksetuid yes | no
	If set to 'yes' process is can't call setxuid with any of the
	*uid values equal to 0 if one of its current *uid values are
	non-zero.
	The main idea is to have authorization processes working 
	with non-zero UID and with setuid/setgid capabilities enabled.
	Such a process would be able to do setuid to non-zero UIDs but
	would not be able to do setuid(0) and similar to gain root
	privileges.
	Use with caution.
	This option is disabled by default.

clrenv	
	Syntax: clrenv yes | no
	If set to 'yes' capsel will clear all environment for programs
	that have setuid/setgid bit set or for programs that have their
	capabilities modified by capsel after execve.
	This option is very usefull and may be used instead of patching
	your glibc and other libraries to disable dangerous features
	like a LD_PRELOAD environment variable (for privileged processes)
	Note, that patching a glibc still is a good idea.
	DO NOT DISABLE THIS OPTION UNLESS YOU REALLY KNOW WHAT YOU ARE
	DOING.
	This option is enabled by default.

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.
	Default value does not modify process's capabilities.

WARNING:
	Additional attention needs to be taken when creating secure 
	configuration with capsel module. If you are trying to increase
	increase privileges of some non-setuid binaries (i.e. ping)
	remeber to check their code against buffer overflows and other
	common vulnerabilities that may open security hole in your system.
	PARTICULARLY, DO _NOT_ TRY TO INCREASE PRIVILEGES OF 
	BINARIES THAT ARE NOT DESIGNED TO BE EXECUTED AS SETUID-ROOT.
	IT IS ALSO A GOOD IDEA TO PATCH YOUR GLIBC TO DISABLE FEATURES
	THAT ARE NOT ENABLED FOR SETUID BINARIES BY DEFAULT.

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 are already
	available on my home page, some of them will be created in some
	future.
	You may restore standard behavior of setxuid system calls with
	'uidcap default'.
	Default value does not modify behavior of setxuid system calls.

bindtcp
	Syntax: bind_tcp 0 | tcp_port_no
	This option allows you to restrict CAP_NET_BIND_SERVICE capability
	in the way that the process will be unable to bind to protected
	TCP ports except the one that is specified as an argument to the
	option.
	This option has no effect if process doesn't have CAP_NET_BIND_SERVICE
	capability set.
	Default value is 0 that means no restrictions at all.
	
bindudp
	Syntax: bind_udp 0 | udp_port_no
	This is similar option to the bind_tcp option but this one 
	allows binding UDP protected ports.
	Default value is 0 that means no restrictions at all.

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 improves system security
	when applied to network daemons especially if they are running
	without root privileges. It may prevent hackers from executing
	exploits locally for other buggy software.
	Default value is 'exec allow all'.

rootdir	Syntax: rootdir 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 {
		rootdir /chroot
		chkchroot 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.
	Default value does not change root directory for the executable.
	('root' option name is deprecated and should not be used.)
	
There are two special rules. First is default rule (word 'default' is
used instead of path to executable) which options are used when creating
other rules. The default rule is also used if there is no other matching 
rule. Second special rule begins with word 'any' (just like default
rule). This rule matches any executable if its UIDs/GIDs matches those
specified in the rule.

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++ */



 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-2002 Wojciech Purczynski <cliph@isec.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
========================================================================

Please send my any comments and/or suggestions.

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



 GREETINGS
========================================================================

Special thanks to Michal (lcamtuf) Zalewski for his help.
Capsel module is a result of experience and help of many people.



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

Author:		Wojciech Purczynski

e-mail: 	cliph@isec.pl

Home page:	http://cliph.linux.pl/capsel/

