tags/htdocs/index.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en-US">
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta http-equiv="content-style-type" content="text/css">
<link rel="stylesheet" href="media/caitsith.css" media="all" type="text/css">
<title>CaitSith Documentation</title>
</head>
<body>

<h1>CaitSith -- A simplified access restriction module for system protection.</h1>

<p>CaitSith is an access restriction module for Linux systems. This module gives you ability to restrict access (e.g. opening files, executing programs) at the kernel level. This module is designed for ease of use.</p>

<p>Below is documentation but is partially under construction. Sorry.</p>

<hr>
<h2><a name="index">Index</a></h2>

<p><a href="#difference_with_tomoyo">1. Difference with TOMOYO (for existing TOMOYO users)</a></p>

<ul>
<li><a href="#1.1">1.1. About pathnames and management programs</a></li>
<li><a href="#1.2">1.2. About policy syntax</a></li>
<li><a href="#1.3">1.3. Why CaitSith was developed</a></li>
</ul>

<p><a href="#how_to_install">2. How to install</a></p>

<ul>
<li><a href="#2.1">2.1 How to install LKM-based LSM version</a><br>
<ul>
<li><a href="#2.1.1">2.1.1. Install dependencies</a></li>
<li><a href="#2.1.2">2.1.2. Building the kernel module</a></li>
<li><a href="#2.1.3">2.1.3. Install the userspace tools</a></li>
<li><a href="#2.1.4">2.1.4. Initializing configuration</a></li>
<li><a href="#2.1.5">2.1.5. Configuring your bootloader</a></li>
<li><a href="#2.1.6">2.1.6. Rebooting your system</a></li>
<li><a href="#2.1.7">2.1.7. How can I disable/uninstall CaitSith?</a></li>
</ul>
</li>
<li><a href="#2.2">2.2. How to install fully featured version</a><br>
<ul>
<li><a href="#2.2.1">2.2.1. Install dependencies</a></li>
<li><a href="#2.2.2">2.2.2. Download and patch the kernel</a></li>
<li><a href="#2.2.3">2.2.3. Configure the kernel</a></li>
<li><a href="#2.2.4">2.2.4. Compile and install the kernel</a></li>
<li><a href="#2.2.5">2.2.5. Install the userspace tools</a></li>
<li><a href="#2.2.6">2.2.6. Initializing configuration</a></li>
<li><a href="#2.2.7">2.2.7. Configuring your bootloader</a></li>
<li><a href="#2.2.8">2.2.8. Rebooting your system</a></li>
<li><a href="#2.2.9">2.2.9. How can I disable/uninstall CaitSith?</a></li>
</ul>
</li>
</ul>

<p><a href="#how_to_develop_policy">3. How to develop policy</a></p>

<ul>
<li><a href="#3.1">3.1. Policy file structure</a></li>
<li><a href="#3.2">3.2. Updating policy configuration</a></li>
<li><a href="#3.3">3.3. Example of simple access restriction rule</a></li>
<li><a href="#3.4">3.4. Understanding two viewpoints</a></li>
</ul>

<p><a href="#condition_list">4. List of conditions</a></p>

<ul>
<li><a href="#4.1">4.1. Using string arguments in conditions</a></li>
<li><a href="#4.2">4.2. Using numeric arguments in conditions</a></li>
<li><a href="#4.3">4.3. Using process's information in conditions</a></li>
<li><a href="#4.4">4.4. Using IP address arguments in conditions</a></li>
<li><a href="#4.5">4.5. Using command line arguments in conditions</a></li>
<li><a href="#4.6">4.6. Using environment variable arguments in conditions</a></li>
<li><a href="#4.7">4.7. Using file's DAC permissions in conditions</a></li>
<li><a href="#4.8">4.8. Using handle file's type in conditions</a></li>
<li><a href="#4.9">4.9. Using file's attributes in conditions</a></li>
</ul>

<p><a href="#syntax_list">5. List of syntaxes</a></p>

<ul>
<li><a href="#5.1">5.1. execute</a></li>
<li><a href="#5.2">5.2. read</a></li>
<li><a href="#5.3">5.3. write</a></li>
<li><a href="#5.4">5.4. append</a></li>
<li><a href="#5.5">5.5. create</a></li>
<li><a href="#5.6">5.6. unlink</a></li>
<li><a href="#5.7">5.7. getattr</a></li>
<li><a href="#5.8">5.8. mkdir</a></li>
<li><a href="#5.9">5.9. rmdir</a></li>
<li><a href="#5.10">5.10. mkfifo</a></li>
<li><a href="#5.11">5.11. mksock</a></li>
<li><a href="#5.12">5.12. truncate</a></li>
<li><a href="#5.13">5.13. symlink</a></li>
<li><a href="#5.14">5.14. mkblock</a></li>
<li><a href="#5.15">5.15. mkchar</a></li>
<li><a href="#5.16">5.16. link</a></li>
<li><a href="#5.17">5.17. rename</a></li>
<li><a href="#5.18">5.18. chmod</a></li>
<li><a href="#5.19">5.19. chown</a></li>
<li><a href="#5.20">5.20. chgrp</a></li>
<li><a href="#5.21">5.21. ioctl</a></li>
<li><a href="#5.22">5.22. chroot</a></li>
<li><a href="#5.23">5.23. mount</a></li>
<li><a href="#5.24">5.24. unmount</a></li>
<li><a href="#5.25">5.25. pivot_root</a></li>
<li><a href="#5.26">5.26. inet_stream_bind</a></li>
<li><a href="#5.27">5.27. inet_stream_listen</a></li>
<li><a href="#5.28">5.28. inet_stream_connect</a></li>
<li><a href="#5.29">5.29. inet_stream_accept</a></li>
<li><a href="#5.30">5.30. inet_dgram_bind</a></li>
<li><a href="#5.31">5.31. inet_dgram_send</a></li>
<li><a href="#5.32">5.32. inet_dgram_recv</a></li>
<li><a href="#5.33">5.33. inet_raw_bind</a></li>
<li><a href="#5.34">5.34. inet_raw_send</a></li>
<li><a href="#5.35">5.35. inet_raw_recv</a></li>
<li><a href="#5.36">5.36. unix_stream_bind</a></li>
<li><a href="#5.37">5.37. unix_stream_listen</a></li>
<li><a href="#5.38">5.38. unix_stream_connect</a></li>
<li><a href="#5.39">5.39. unix_stream_accept</a></li>
<li><a href="#5.40">5.40. unix_dgram_bind</a></li>
<li><a href="#5.41">5.41. unix_dgram_send</a></li>
<li><a href="#5.42">5.42. unix_dgram_recv</a></li>
<li><a href="#5.43">5.43. unix_seqpacket_bind</a></li>
<li><a href="#5.44">5.44. unix_seqpacket_listen</a></li>
<li><a href="#5.45">5.45. unix_seqpacket_connect</a></li>
<li><a href="#5.46">5.46. unix_seqpacket_accept</a></li>
<li><a href="#5.47">5.47. ptrace</a></li>
<li><a href="#5.48">5.48. signal</a></li>
<li><a href="#5.49">5.49. environ</a></li>
<li><a href="#5.50">5.50. modify_policy</a></li>
<li><a href="#5.51">5.51. use_netlink_socket</a></li>
<li><a href="#5.52">5.52. use_packet_socket</a></li>
<li><a href="#5.53">5.53. use_reboot</a></li>
<li><a href="#5.54">5.54. use_vhangup</a></li>
<li><a href="#5.55">5.55. set_time</a></li>
<li><a href="#5.56">5.56. set_priority</a></li>
<li><a href="#5.57">5.57. set_hostname</a></li>
<li><a href="#5.58">5.58. use_kernel_module</a></li>
<li><a href="#5.59">5.59. use_new_kernel</a></li>
<li><a href="#5.60">5.60. manual_domain_transition</a></li>
<li><a href="#5.61">5.61. auto_domain_transition</a></li>
</ul>

<p><a href="#advanced_usage">6. Advanced usage</a></p>

<hr>
<h2><a name="difference_with_tomoyo">1. Difference with TOMOYO (for existing TOMOYO users)</a></h2>

<p>CaitSith was derived from TOMOYO Linux, but usage of CaitSith would be too different to imagine that CaitSith was derived from TOMOYO Linux. If you are already using TOMOYO Linux, please read the difference described below.</p>

<hr>
<h3><a name="1.1">1.1. About pathnames and management programs</a></h3>

<p><code>/proc/ccs/domain_policy</code>, <code>/proc/ccs/exception_policy</code>, <code>/proc/ccs/profile</code>, <code>/proc/ccs/manager</code> and <code>/proc/ccs/stat</code> have been aggregated into <code>/proc/caitsith/policy</code>.</p>

<p><code>/etc/ccs/policy/current/domain_policy.conf</code>, <code>/etc/ccs/policy/current/exception_policy.conf</code>, <code>/etc/ccs/policy/current/profile.conf</code>, <code>/etc/ccs/policy/current/manager.conf</code> and <code>/etc/ccs/policy/current/stat.conf</code> have been aggregated into <code>/etc/caitsith/policy/current</code>.</p>

<p>Built-in policy files which are located under kernel source directory as <code>security/ccsecurity/policy/domain_policy.conf</code>, <code>security/ccsecurity/policy/exception_policy.conf</code>, <code>security/ccsecurity/policy/profile.conf</code>, <code>security/ccsecurity/policy/manager.conf</code> and <code>security/ccsecurity/policy/stat.conf</code> have been aggregated into <code>security/caitsith/policy/policy.conf</code>.</p>

<p>Only <code>/sbin/caitsith-init</code>, <code>/usr/sbin/caitsith-auditd</code>, <code>/usr/sbin/caitsith-loadpolicy</code>, <code>/usr/sbin/caitsith-notifyd</code>, <code>/usr/sbin/caitsith-pstree</code>, <code>/usr/sbin/caitsith-queryd</code>, <code>/usr/sbin/caitsith-savepolicy</code>, <code>/usr/lib/caitsith/audit-exec-param</code>, <code>/usr/lib/caitsith/caitsith-agent</code> and <code>/usr/lib/caitsith/init_policy</code> are provided for managing policy. (In other words, programs such as <code>/usr/sbin/ccs-editpolicy</code> and <code>/usr/sbin/ccs-setprofile</code> have been removed.)</p>

<p>Command line arguments for specifying type of policy to load/save have been removed from <code>/usr/sbin/caitsith-loadpolicy</code> and <code>/usr/sbin/caitsith-savepolicy</code>.</p>

<p>Command line arguments for specifying profile type have been removed from <code>/usr/lib/caitsith/init_policy</code>.</p>

<hr>
<h3><a name="1.2">1.2. About policy syntax</a></h3>

<p>Policy syntax has been drastically changed. TOMOYO Linux uses process's domainname as a key for grouping permissions to do some operations. In other words, TOMOYO Linux's policy is collection of "which domain can do ..." rules. On the other hand, CaitSith uses operation as a key for checking permission. In other words, CaitSith's policy is collection of "which operation can be done by ..." rules. This change is intended for allowing users to protect resources using blacklisting approach. In CaitSith, process's domainname is nothing but one of optional parameters that can be used for controlling whether to grant or deny specific operations. Users can write rules without managing domainnames unless needed.</p>

<p>Process's domainname representation has changed from space delimited multiple words (e.g. "&lt;kernel&gt; /sbin/init /etc/rc.d/rc.sysinit") to a single word (e.g. "/sbin/init").</p>

<p>Domain transitions no longer happen unless explicitly specified by policy.</p>

<p>Distinction of disabled/learning/permissive/enforcing mode has been removed.</p>

<p>"path_group" keyword has been renamed to "string_group", and "address_group" keyword has been renamed to "ip_group".</p>

<p>Representation of \ character has been changed from \\ to \134.</p>

<p>Distinction between directory's pathname and non-directory's pathname has been removed by removing trailing / character from pathname.</p>

<p>A new wildcard /\(dir\)/ has been introduced for helping converting from (e.g.) "/tmp/\{\*\}/" to "/tmp/\(\*\)/\*", for directory's pathname (except the root directory itself) no longer ends with / character which previously matched /\{\*\}/ wildcard.</p>

<p>Category keywords (i.e. "file", "network", "ipc", "misc", "capability", "task") have been removed because access control levels which was specified using profile has been removed. Some of operation keywords have been renamed (e.g. "network inet stream connect" became "inet_stream_connect", "misc env" became "environ").</p>

<p>"task auto_execute_handler" keyword has been renamed to "handler=" argument of "execute" keyword. This is intended for using execute handler for preprocessing purpose when executing specific programs rather than when executing from specific domains. "task denied_execute_handler" keyword has been removed.</p>

<p>Domain argument has been removed from permission to send signals (i.e. "signal" directive), for kill() system call accepts negative number for specifying multiple processes. It is impossible to selectively deny sending signals because it is not permitted to sleep while sending signals.</p>

<p>Restriction granularity for ptrace operation has changed from boolean (i.e. "capability SYS_PTRACE") to command number + domainname.</p>

<p>Restriction granularity for environment variables has changed from name only to both name and values.</p>

<p>Several variables for referencing file's attributes have been added.</p>

<p>Local port reserve functionality (i.e. "deny_autobind" keyword) has been removed.</p>

<hr>
<h3><a name="1.3">1.3. Why CaitSith was developed?</a></h3>

<p>Presentation slides which I used at LinuxCon North America 2012 that explain why CaitSith was developed are available.</p>

<ul>
<li><a href="http://I-love.SAKURA.ne.jp/tomoyo/CaitSith-en.pdf">English</a></li>
<li><a href="http://I-love.SAKURA.ne.jp/tomoyo/CaitSith-ja.pdf">Japanese</a></li>
</ul>

<hr>
<h2><a name="how_to_install">2. How to install</a></h2>

<p>CaitSith supports Linux kernel 2.6.27 and later.</p>

<p>There are two ways to compile CaitSith kernel module. Please choose one, but please accept that you need to choose <a href="#2.2">fully featured version</a> if you can't choose <a href="#2.1">LKM-based LSM version</a>.</p>

<table border="1">
<tr><td></td><td><a href="#2.1">LKM-based LSM version</a></td><td><a href="#2.2">fully featured version</a></td></tr>
<tr><td>Advantages</td><td>No need to replace kernel package.</td><td>Complete functionality and syntax are supported.</td></tr>
<tr><td>Disadvantages</td><td>Supported functionality and syntax depend on kernel's version and kernel's configuration options.</td><td>Need to replace kernel package.</td></tr>
<tr><td>Dependency</td><td>
Kernel package must be built with below configuration options.<br>
<ul>
<li>CONFIG_SECURITY=y</li>
<li>CONFIG_KALLSYMS=y</li>
<li>CONFIG_PROC_FS=y</li>
<li>CONFIG_MODULES=y</li>
</ul>
The kernel package should be built with below configuration options in addition to above configuration options for supporting further functionality.<br>
<ul>
<li>CONFIG_SECURITY_NETWORK=y</li>
<li>CONFIG_SECURITY_PATH=y</li>
</ul>
Currently known to work on x86_32 x86_64 SH and ARM. Other architectures are not tested yet.
</td><td>
Requires patching against kernel's source and rebuilding from source.
</td></tr>
</table>

<hr>
<h2><a name="2.1">2.1. How to install LKM-based LSM version</a></h2>

<hr>
<h3><a name="2.1.1">2.1.1. Install dependencies</a></h3>

<p>These packages are required for compiling the kernel module and the userspace tools:</p>

<ul>
<li><strong>wget</strong>: to download sources</li>
<li><strong>gcc</strong>: to build the module and tools</li>
<li><strong>make</strong>: to build the module and tools</li>
<li><strong>ncurses-devel</strong> or <strong>libncurses-dev</strong>: to build the tools</li>
</ul>

<p>These can be installed with the following commands:</p>

<p><strong>RedHat distributions</strong></p>
<pre class="command">
# yum -y install wget gcc make ncurses-devel
</pre>
<p><strong>Debian distributions</strong></p>
<pre class="command">
# apt-get -y install wget gcc make libncurses-dev
</pre>
<p><strong>SUSE distributions</strong></p>
<pre class="command">
# yast -i wget gcc make ncurses-devel
</pre>

<hr>
<h3><a name="2.1.2">2.1.2. Building the kernel module</a></h3>

<p>Install the kernel development package and go to the directory that it has installed into:</p>

<p><strong>RedHat distributions</strong></p>
<pre class="command">
# VERSION=$(uname -r)
# yum -y install kernel-devel-${VERSION}
# cd /usr/src/kernels/${VERSION}*/
</pre>

<p><strong>Debian distributions</strong></p>
<pre class="command">
# VERSION=$(uname -r)
# apt-get -y install linux-headers-${VERSION}
# cd /usr/src/linux-headers-${VERSION}/
</pre>

<p><strong>SUSE distributions</strong></p>
<pre class="command">
# VERSION=$(uname -r)
# yast -i kernel-devel
# cd /lib/modules/${VERSION}/build/
</pre>

<p>Run the following commands in order to extract source code of CaitSith:</p>

<pre class="command">
# wget -O caitsith-patch-0.1-20130707.tar.gz 'http://sourceforge.jp/frs/redir.php?m=jaist&amp;f=/caitsith/55464/caitsith-patch-0.1-20130707.tar.gz'
# wget -O caitsith-patch-0.1-20130707.tar.gz.asc 'http://sourceforge.jp/frs/redir.php?m=jaist&amp;f=/caitsith/55464/caitsith-patch-0.1-20130707.tar.gz.asc'
# wget http://I-love.SAKURA.ne.jp/kumaneko-key
# gpg --import kumaneko-key
# gpg caitsith-patch-0.1-20130707.tar.gz.asc
# tar -zxf caitsith-patch-0.1-20130707.tar.gz
</pre>

<p>There are two types of CaitSith's policy configuration. The former is embedded into the kernel and the latter is saved as files on the filesystems (e.g. <code>/etc/caitsith/</code> directory). You will need to rebuild the CaitSIth kernel module whenever updating the former, but allows you to load policy without using userspace policy loader (e.g. <code>/sbin/caitsith-init</code>). The latter is loaded by executing userspace policy loader when the access control by CaitSith is about to be activated (e.g. when <code>/sbin/init</code> starts). <em>Activate without calling userspace policy loader.</em> allows you to activate access control by CaitSith as soon as the former is loaded. This option is useful when it is difficult to call policy loader (e.g. embedded systems).</p>

<p>If you want to activate CaitSith as soon as the kernel module is loaded, you can define CONFIG_CAITSITH_OMIT_USERSPACE_LOADER line in caitsith/config.h like below. (But be sure to supply built-in policy configuration located at caitsith/policy/ directory if you define CONFIG_CAITSITH_OMIT_USERSPACE_LOADER, or the system will panic as soon as the kernel module is loaded.):</p>

<p>Before:</p>
<pre>//#define CONFIG_CAITSITH_OMIT_USERSPACE_LOADER
</pre>

<p>After:</p>
<pre
>#define CONFIG_CAITSITH_OMIT_USERSPACE_LOADER
</pre>

<p>Run the following commands in order to build and install CaitSith:</p>

<pre class="command">
# make SUBDIRS=$PWD/caitsith modules
# make SUBDIRS=$PWD/caitsith modules_install
# depmod ${VERSION}
</pre>

<p>If you encountered one of errors listed below, you cannot use CaitSith for your kernel. Please jump to <a href="#2.2">2.2. How to install fully featured version</a>.
For other errors, please contact the author ( penguin-kernel@I-love.SAKURA.ne.jp ).</p>

<pre class="output">
You must choose CONFIG_SECURITY=y for building this module.
You must choose CONFIG_KALLSYMS=y for building this module.
You must choose CONFIG_PROC_FS=y for building this module.
You must choose CONFIG_MODULES=y for building this module.
</pre>

<p>Since registering CaitSith module depends on your environment, you might encounter problems. Therefore, I recommend you to confirm that CaitSith module can be loaded at this step.</p>

<p>Run the following commands in order to try to load caitsith_test.ko module:</p>

<pre class="command">
# dmesg -c &gt; /dev/null
# modprobe caitsith_test
# dmesg
</pre>
<pre class="output">
security_ops=c0c4b470
find_task_by_vpid=c04769e0
find_task_by_pid_ns=c04769c0
vfsmount_lock=c0a5a3a0
All dependent symbols have been guessed.
Please verify these addresses using System.map for this kernel (e.g. /boot/System.map-`uname -r` ).
If these addresses are correct, you can try loading CaitSith module on this kernel.
</pre>

<p>If caitsith_test.ko was loaded successfully, guessed addresses like above are printed. Therefore, please compare guessed addresses from caitsith_test.ko and actual addresses from System.map file. (Number of symbols and addresses printed depends on your environment.):</p>

<pre class="command">
# for i in c0c4b470 c04769e0 c04769c0 c0a5a3a0; do grep $i /boot/System.map-${VERSION}; done
</pre>
<pre class="output">
c0c4b470 B security_ops
c04769e0 T find_task_by_vpid
c04769c0 T find_task_by_pid_ns
c0a5a3a0 D vfsmount_lock
</pre>

<p>Please proceed if these addresses are correct. Otherwise, please contact the author since CaitSith module will not work even if you continue.</p>

<p>If caitsith_test.ko was not loaded successfully, error messages like below are printed. In this case, please contact the author since CaitSith module will not work even if you continue:</p>

<pre class="command">
# dmesg -c &gt; /dev/null
# modprobe caitsith_test
</pre>
<pre class="output">FATAL: Error inserting caitsith_test (/lib/modules/2.6.32/extra/caitsith_test.ko): Invalid argument
</pre>
<pre class="command">
# dmesg
</pre>
<pre class="output">
Sorry, I couldn't guess dependent symbols.
I need some changes for supporting your environment.
Please contact the author.
</pre>

<hr>
<h3><a name="2.1.3">2.1.3. Install the userspace tools</a></h3>

<p>Make sure the dependencies described above have been installed. Compile and install the tools with the following commands:</p>

<pre class="command">
$ wget -O caitsith-tools-0.1-20130214.tar.gz 'http://sourceforge.jp/frs/redir.php?m=jaist&amp;f=/caitsith/55465/caitsith-tools-0.1-20130214.tar.gz'
$ wget -O caitsith-tools-0.1-20130214.tar.gz.asc 'http://sourceforge.jp/frs/redir.php?m=jaist&amp;f=/caitsith/55465/caitsith-tools-0.1-20130214.tar.gz.asc'
$ gpg caitsith-tools-0.1-20130214.tar.gz.asc
$ tar -zxf caitsith-tools-0.1-20130214.tar.gz
$ cd caitsith-tools/
$ make -s USRLIBDIR=/usr/lib
$ su
# make -s USRLIBDIR=/usr/lib install
</pre>

<p>Please change USRLIBDIR=<code>/usr/lib</code> to USRLIBDIR=<code>/usr/lib64</code> (for 64bits userspace) or USRLIBDIR=<code>/usr/lib32</code> (for 32bits userspace) if needed.</p>

<p>Programs listed below are main userspace tools used for administrating CaitSith.</p>

<ul>
<li><code>/sbin/caitsith-init</code></li>
<li><code>/usr/sbin/caitsith-auditd</code></li>
<li><code>/usr/sbin/caitsith-loadpolicy</code></li>
<li><code>/usr/sbin/caitsith-notifyd</code></li>
<li><code>/usr/sbin/caitsith-pstree</code></li>
<li><code>/usr/sbin/caitsith-queryd</code></li>
<li><code>/usr/sbin/caitsith-savepolicy</code></li>
</ul>

<p>FYI: If your system has rpm-build package installed, you can make a tools RPM package with the following commands:</p>

<pre class="command">
$ rpmbuild -tb caitsith-tools-0.1-20130214.tar.gz
</pre>

<hr>
<h3><a name="2.1.4">2.1.4. Initializing configuration</a></h3>

<p>Before you can make use of CaitSith, an initialization procedure must take place. This prepares the files in which policy information will be stored. All policy files are <strong>stored in the "<code>/etc/caitsith/</code>" directory</strong>.</p>

<p>Run the following command as root user to initialize:</p>

<pre class="command">
# /usr/lib/caitsith/init_policy
</pre>
<pre class="output">
Creating policy directory... OK
Creating configuration directory... OK
Creating default policy... OK.
Creating module loader... OK.
Creating configuration file for caitsith-auditd ... OK.
Creating configuration file for caitsith-notifyd ... OK.
</pre>

<p>CaitSith can generate audit logs and allows you to read them via <code>/proc/caitsith/audit</code> interface. To save <code>/proc/caitsith/audit</code> automatically, start <code>/usr/sbin/caitsith-auditd</code> from somewhere. Default setting (specified in <code>/etc/caitsith/tools/auditd.conf</code>) sends access allowed logs to <code>/dev/null</code>, access unmatched logs to <code>/var/log/caitsith/unmatched.log</code>, access denied logs to <code>/var/log/caitsith/denied.log</code>. (The meaning and example of allowed/unmatched/denied will be explained in <a href="#3.3">Example of simple access restriction rule</a>.)</p>

<p>CaitSith can ask for your decision about access requests which will be denied unless you grant them via <code>/proc/caitsith/query</code> interface. To notify immediately the occurrence of access requests which CaitSith is about to deny, start <code>/usr/sbin/caitsith-notifyd</code> from somewhere. Default setting (specified in <code>/etc/caitsith/tools/notifyd.conf</code>) sends mails to root@localhost with subject "Notification from caitsith-notifyd" up to once per a minute.</p>

<p>Below example launches <code>/usr/sbin/caitsith-auditd</code> and <code>/usr/sbin/caitsith-notifyd</code> from <code>/etc/rc.local</code> script:</p>

<pre>
#!/bin/sh
#
# This script will be executed *after* all the other init scripts.
# You can put your own initialization stuff in here if you don't
# want to do the full Sys V style init stuff.

touch /var/lock/subsys/local
/usr/sbin/caitsith-auditd
/usr/sbin/caitsith-notifyd
</pre>

<hr>
<h3><a name="2.1.5">2.1.5. Configuring your bootloader</a></h3>

<p>Append "init=/sbin/caitsith-init" parameter to the kernel's command line options. An example for CentOS 6.4 environment is show below.</p>

<pre>
# grub.conf generated by anaconda
#
# Note that you do not have to rerun grub after making changes to this file
# NOTICE:  You do not have a /boot partition.  This means that
#          all kernel and initrd paths are relative to /, eg.
#          root (hd0,0)
#          kernel /boot/vmlinuz-version ro root=/dev/sda1
#          initrd /boot/initrd-[generic-]version.img
#boot=/dev/sda
default=0
timeout=5
splashimage=(hd0,0)/boot/grub/splash.xpm.gz
#hiddenmenu
title CentOS (2.6.32-358.2.1.el6.i686)
        root (hd0,0)
        kernel /boot/vmlinuz-2.6.32-358.2.1.el6.i686 ro root=UUID=cc8371f3-bb2c-47b4-bd8f-318124f523df rd_NO_LUKS rd_NO_LVM rd_NO_MD rd_NO_DM LANG=en_US.UTF-8 SYSFONT=latarcyrheb-sun16 KEYBOARDTYPE=pc KEYTABLE=jp106 crashkernel=auto init=/sbin/caitsith-init
        initrd /boot/initramfs-2.6.32-358.2.1.el6.i686.img
</pre>

<p>If you are using GRUB2, it is recommended that you also modify GRUB_CMDLINE_LINUX line in <code>/etc/default/grub</code> file like below in case you update kernel packages in the future:</p>

<pre>
GRUB_CMDLINE_LINUX="rd.md=0 rd.lvm=0 rd.dm=0 SYSFONT=True rd.luks=0 KEYTABLE=en LANG=en_US.UTF-8 rhgb quiet init=/sbin/caitsith-init"
</pre>

<hr>
<h3><a name="2.1.6">2.1.6. Rebooting your system</a></h3>

<p>Now you have finished all preparation. Reboot your system.</p>

<p>If everything was installed properly and the bootloader was correctly configured, the kernel should boot as normal and CaitSith should be activated:</p>

<img src="media/caitsith-lsm-activated.png" alt="caitsith-lsm-activated.png" title="CaitSith(LSM) activated" width="720" height="400">

<hr>
<h3><a name="2.1.7">2.1.7. How can I disable/uninstall CaitSith?</a></h3>

<p>If your system becomes unable to boot during the course of this guide or any time in the future, it may be due to policy configuration or something related to CaitSith. If this is the case, it is possible that the kernel can still be booted by disabling CaitSith. This can be done by removing "init=/sbin/caitsith-init" from the kernel's command line options.</p>

<p>CaitSith fortunately does not require the modification of any existing Linux binaries, libraries or applications. Thus, uninstalling CaitSith is very easy. It is simply a matter of removing "init=/sbin/caitsith-init" from the kernel's command line options and userspace tools that you installed above.</p>

<hr>
<h2><a name="2.2">2.2. How to install fully featured version</a></h2>

<hr>
<h3><a name="2.2.1">2.2.1. Install dependencies</a></h3>

<p>These packages are required for compiling the kernel and the userspace tools:</p>

<ul>
<li><strong>wget</strong>: to download sources</li>
<li><strong>patch</strong>: to patch the kernel</li>
<li><strong>gcc</strong>: to build the kernel and tools</li>
<li><strong>make</strong>: to build the kernel and tools</li>
<li><strong>ncurses-devel</strong> or <strong>libncurses-dev</strong>: to build the tools</li>
</ul>

<p>These can be installed with the following commands:</p>

<p><strong>RedHat distributions</strong></p>
<pre class="command">
# yum -y install wget patch gcc make ncurses-devel
</pre>
<p><strong>Debian distributions</strong></p>
<pre class="command">
# apt-get -y install wget patch gcc make libncurses-dev
</pre>
<p><strong>SUSE distributions</strong></p>
<pre class="command">
# yast -i wget patch gcc make ncurses-devel
</pre>

<hr>
<h3><a name="2.2.2">2.2.2. Download and patch the kernel</a></h3>

<p>Download the kernel source from <a href="http://www.kernel.org/pub/linux/kernel/v2.6/">linux-2.6</a> or <a href="http://www.kernel.org/pub/linux/kernel/v3.0/">linux-3</a>.<br>
Linux kernel 2.6.27 and later are supported from the linux-2.6 tree.<br>
Linux kernel 3.0 and later are supported from the linux-3 tree.</p>

<p>Extract the kernel source and go to the extracted directory.<br>
In the operations below, "$VERSION" should be replaced with appropriate kernel version. For example "3.8" if using Linux kernel 3.8.6, "2.6.27" if using Linux kernel 2.6.27.62.<br>
Also, there are several patches which can be applied to distributor's latest kernels. For example "2.6.32-centos-6.4" if using CentOS 6.4's latest kernel:</p>

<pre class="command">
$ wget -O caitsith-patch-0.1-20130707.tar.gz 'http://sourceforge.jp/frs/redir.php?m=jaist&amp;f=/caitsith/55464/caitsith-patch-0.1-20130707.tar.gz'
$ wget -O caitsith-patch-0.1-20130707.tar.gz.asc 'http://sourceforge.jp/frs/redir.php?m=jaist&amp;f=/caitsith/55464/caitsith-patch-0.1-20130707.tar.gz.asc'
$ wget http://I-love.SAKURA.ne.jp/kumaneko-key
$ gpg --import kumaneko-key
$ gpg caitsith-patch-0.1-20130707.tar.gz.asc
$ tar -zxf caitsith-patch-0.1-20130707.tar.gz
$ sed -i -e 's/CCSECURITY/CAITSITH/g' -e 's/ccsecurity/caitsith/g' -e 's/ccs_domain_info/cs_domain_info/g' -e 's/ccs_flags/cs_flags/g' -- patches/ccs-patch-*.diff
$ patch -sp1 &lt; patches/ccs-patch-$VERSION.diff
</pre>

<hr>
<h3><a name="2.2.3">2.2.3. Configure the kernel</a></h3>

<pre class="command">
$ make -s menuconfig
</pre>

<p>Choose the following options in "Security options" section:</p>

<ul>
<li>[*] CaitSith support</li>
<li>[ ] &nbsp;&nbsp;Compile as loadable kernel module</li>
<li>[ ] &nbsp;&nbsp;Disable by default</li>
<li>[ ] &nbsp;&nbsp;Do not modify 'struct task_struct' in order to keep KABI</li>
<li>[ ] &nbsp;&nbsp;Activate without calling userspace policy loader.</li>
<li>(<code>/sbin/caitsith-init</code>) Location of userspace policy loader</li>
<li>(<code>/sbin/init</code>) Trigger for calling userspace policy loader</li>
<li>[*] &nbsp;&nbsp;Enable readdir operation restriction.</li>
<li>[*] &nbsp;&nbsp;Enable getattr operation restriction.</li>
<li>[*] &nbsp;&nbsp;Enable socket operation restriction.</li>
<li>[*] &nbsp;&nbsp;Enable non-POSIX capability operation restriction.</li>
<li>[*] &nbsp;&nbsp;Enable ptrace operation restriction.</li>
<li>[*] &nbsp;&nbsp;Enable kill operation restriction.</li>
<li>[*] &nbsp;&nbsp;Enable environment variable names/values restriction.</li>
<li>[*] &nbsp;&nbsp;Enable execute handler functionality.</li>
<li>[*] &nbsp;&nbsp;Enable domain transition without program execution request.</li>
<li>[*] &nbsp;&nbsp;Enable automatic domain transition.</li>
</ul>

<p><em>"Compile as loadable kernel module"</em> is useful when there is a file size limitation for vmlinux (e.g. embedded systems).</p>

<p><em>"Disable by default"</em> will enable CaitSith only when "caitsith=on" is passed to the kernel's command line options. If this option is not selected, "caitsith=off" will disable CaitSith.</p>

<p><em>"Do not modify 'struct task_struct' in order to keep KABI"</em> will manage "struct task_struct" variables outside "struct task_struct" in order to avoid Kernel Application Binary Interface (KABI) breakage. Choose this option if wanting to patch against distributor's kernels without breaking KABI. However, since "struct caitsith_operations" must be exported to loadable kernel modules (LKMs) in order to allow them to call CaitSith's functions, build scripts may still print warning messages.</p>

<p>There are two types of CaitSith's policy configuration. The former is embedded into the kernel and the latter is saved as files on the filesystems (e.g. <code>/etc/caitsith/</code> directory). You will need to rebuild the kernel whenever updating the former, but allows you to load policy without using userspace policy loader (e.g. <code>/sbin/caitsith-init</code>). The latter is loaded by executing userspace policy loader when the access control by CaitSith is about to be activated (e.g. when <code>/sbin/init</code> starts). <em>Activate without calling userspace policy loader.</em> allows you to activate access control by CaitSith as soon as the former is loaded. This option is useful when it is difficult to call policy loader (e.g. embedded systems).</p>

<p><em>Location of userspace policy loader</em> is available only when <em>Activate without calling userspace policy loader.</em> is not selected. This option specifies the default pathname of the userspace policy loader. You can override this setting via the "CS_loader=" kernel command-line option.</p>

<p><em>Trigger for calling userspace policy loader</em> is available only when <em>Activate without calling userspace policy loader.</em> is not selected. This option specifies the default pathname of the activation trigger. You can override this setting via the "CS_trigger=" kernel command-line option. For example, if you pass "init=<code>/bin/systemd</code>" option, you may also want to pass "CS_trigger=<code>/bin/systemd</code>" option.</p>

<hr>
<h3><a name="2.2.4">2.2.4. Compile and install the kernel</a></h3>

<p>The policy configuration which will be embedded into the kernel needs to exist as <code>security/caitsith/policy/policy.conf</code>. But you can proceed without creating that file because you don't have the policy configuration to embed as of this step. (You may come back here after you developed policy configuration to embed.)</p>

<p>Once the kernel has been configured, compile and install the kernel with the following commands:</p>

<pre class="command">
$ make -s
$ su
# make -s modules_install install
</pre>

<p>Create initrd/initramfs if required.</p>

<hr>
<h3><a name="2.2.5">2.2.5. Install the userspace tools</a></h3>

<p>Make sure the dependencies described above have been installed. Compile and install the tools with the following commands:</p>

<pre class="command">
$ wget -O caitsith-tools-0.1-20130214.tar.gz 'http://sourceforge.jp/frs/redir.php?m=jaist&amp;f=/caitsith/55465/caitsith-tools-0.1-20130214.tar.gz'
$ wget -O caitsith-tools-0.1-20130214.tar.gz.asc 'http://sourceforge.jp/frs/redir.php?m=jaist&amp;f=/caitsith/55465/caitsith-tools-0.1-20130214.tar.gz.asc'
$ gpg caitsith-tools-0.1-20130214.tar.gz.asc
$ tar -zxf caitsith-tools-0.1-20130214.tar.gz
$ cd caitsith-tools/
$ make -s USRLIBDIR=/usr/lib
$ su
# make -s USRLIBDIR=/usr/lib install
</pre>

<p>Please change USRLIBDIR=<code>/usr/lib</code> to USRLIBDIR=<code>/usr/lib64</code> (for 64bits userspace) or USRLIBDIR=<code>/usr/lib32</code> (for 32bits userspace) if needed.</p>

<p>Programs listed below are main userspace tools used for administrating CaitSith.</p>

<ul>
<li><code>/sbin/caitsith-init</code></li>
<li><code>/usr/sbin/caitsith-auditd</code></li>
<li><code>/usr/sbin/caitsith-loadpolicy</code></li>
<li><code>/usr/sbin/caitsith-notifyd</code></li>
<li><code>/usr/sbin/caitsith-pstree</code></li>
<li><code>/usr/sbin/caitsith-queryd</code></li>
<li><code>/usr/sbin/caitsith-savepolicy</code></li>
</ul>

<p>FYI: If your system has rpm-build package installed, you can make a tools RPM package with the following commands:</p>

<pre class="command">
$ rpmbuild -tb caitsith-tools-0.1-20130214.tar.gz
</pre>

<hr>
<h3><a name="2.2.6">2.2.6. Initializing configuration</a></h3>

<p>Before you can make use of CaitSith, an initialization procedure must take place. This prepares the files in which policy information will be stored. All policy files are <strong>stored in the "<code>/etc/caitsith/</code>" directory</strong>.</p>

<p>Run the following command as root user to initialize:</p>

<pre class="command">
# /usr/lib/caitsith/init_policy
</pre>
<pre class="output">
Creating policy directory... OK
Creating configuration directory... OK
Creating default policy... OK.
Creating module loader... OK.
Creating configuration file for caitsith-auditd ... OK.
Creating configuration file for caitsith-notifyd ... OK.
</pre>

<p>CaitSith can generate audit logs and allows you to read them via <code>/proc/caitsith/audit</code> interface. To save <code>/proc/caitsith/audit</code> automatically, start <code>/usr/sbin/caitsith-auditd</code> from somewhere. Default setting (specified in <code>/etc/caitsith/tools/auditd.conf</code>) sends access allowed logs to <code>/dev/null</code>, access unmatched logs to <code>/var/log/caitsith/unmatched.log</code>, access denied logs to <code>/var/log/caitsith/denied.log</code>. (The meaning and example of allowed/unmatched/denied will be explained in <a href="#3.3">Example of simple access restriction rule</a>.)</p>

<p>CaitSith can ask for your decision about access requests which will be denied unless you grant them via <code>/proc/caitsith/query</code> interface. To notify immediately the occurrence of access requests which CaitSith is about to deny, start <code>/usr/sbin/caitsith-notifyd</code> from somewhere. Default setting (specified in <code>/etc/caitsith/tools/notifyd.conf</code>) sends mails to root@localhost with subject "Notification from caitsith-notifyd" up to once per a minute.</p>

<p>Below example launches <code>/usr/sbin/caitsith-auditd</code> and <code>/usr/sbin/caitsith-notifyd</code> from <code>/etc/rc.local</code> script:</p>

<pre>
#!/bin/sh
#
# This script will be executed *after* all the other init scripts.
# You can put your own initialization stuff in here if you don't
# want to do the full Sys V style init stuff.

touch /var/lock/subsys/local
/usr/sbin/caitsith-auditd
/usr/sbin/caitsith-notifyd
</pre>

<hr>
<h3><a name="2.2.7">2.2.7. Configuring your bootloader</a></h3>

<p>Now edit your bootloader (e.g. GRUB) to include the kernel you have just compiled. If the <em>"Disable by default"</em> option was selected during kernel configuration, remember to include "caitsith=on" in the kernel boot options. Consult the documentation for your distribution and bootloader to find out how to boot your CaitSith kernel.</p>

<p>CaitSith supports the kernel boot option "CS_trigger". This is useful for systems that run a program other than <code>/sbin/init</code> on startup, for example when booting using systemd which uses <code>/bin/systemd</code>. In this case, you should include "CS_trigger=<code>/bin/systemd</code>" in the kernel boot options.</p>

<pre>
# grub.conf generated by anaconda
#
# Note that you do not have to rerun grub after making changes to this file
# NOTICE:  You do not have a /boot partition.  This means that
#          all kernel and initrd paths are relative to /, eg.
#          root (hd0,0)
#          kernel /boot/vmlinuz-version ro root=/dev/sda1
#          initrd /boot/initrd-[generic-]version.img
#boot=/dev/sda
default=1
timeout=5
splashimage=(hd0,0)/boot/grub/splash.xpm.gz
#hiddenmenu
title CentOS (3.8.6-caitsith)
        root (hd0,0)
        kernel /boot/vmlinuz-3.8.6-caitsith ro root=UUID=cc8371f3-bb2c-47b4-bd8f-318124f523df rd_NO_LUKS rd_NO_LVM rd_NO_MD rd_NO_DM LANG=en_US.UTF-8 SYSFONT=latarcyrheb-sun16 KEYBOARDTYPE=pc KEYTABLE=jp106 crashkernel=auto
        initrd /boot/initramfs-3.8.6-caitsith.img
title CentOS (2.6.32-358.2.1.el6.i686)
        root (hd0,0)
        kernel /boot/vmlinuz-2.6.32-358.2.1.el6.i686 ro root=UUID=cc8371f3-bb2c-47b4-bd8f-318124f523df rd_NO_LUKS rd_NO_LVM rd_NO_MD rd_NO_DM LANG=en_US.UTF-8 SYSFONT=latarcyrheb-sun16 KEYBOARDTYPE=pc KEYTABLE=jp106 crashkernel=auto
        initrd /boot/initramfs-2.6.32-358.2.1.el6.i686.img
</pre>

<p>In Fedora 17, <code>/sbin/init</code> exists as a symlink to <code>/usr/lib/systemd/systemd</code> . However, since <code>/init</code> script in the initramfs tries to execute <code>/usr/lib/systemd/systemd</code> (the pathname printed by <code>readlink</code> command) rather than <code>/sbin/init</code> (the pathname passed to <code>readlink</code> command), the trigger for activating CaitSith is <code>/usr/lib/systemd/systemd</code> rather than <code>/sbin/init</code> :</p>

<pre>
# By the time we get here, the root filesystem should be mounted.
# Try to find init.
for i in "$(getarg real_init=)" "$(getarg init=)" $(getargs rd.distroinit=) /sbin/init; do
    [ -n "$i" ] || continue

    __p=$(readlink -f "${NEWROOT}/${i}")
    if [ -x "$__p" ]; then
        INIT="$i"
        break
    fi
done
</pre>

<p>Therefore, in Fedora 17, you need to include "CS_trigger=<code>/usr/lib/systemd/systemd</code>" in the kernel boot options if you didn't specify <code>/usr/lib/systemd/systemd</code> at <a href="#2.2.3">2.2.3. Configure the kernel</a>. You may directly edit <code>/boot/grub2/grub.cfg</code> file. But it is recommended that you also modify GRUB_CMDLINE_LINUX line in <code>/etc/default/grub</code> file like below in case you update kernel packages in the future:</p>

<pre>
GRUB_CMDLINE_LINUX="rd.md=0 rd.lvm=0 rd.dm=0 SYSFONT=True rd.luks=0 KEYTABLE=en LANG=en_US.UTF-8 rhgb quiet CS_trigger=/usr/lib/systemd/systemd"
</pre>

<hr>
<h3><a name="2.2.8">2.2.8. Rebooting your system</a></h3>

<p>Now you have finished all preparation. Reboot your system and choose the entry with CaitSith kernel at the GRUB screen, or at whatever other bootloader you have installed:</p>

<img src="media/grub-screen.png" alt="grub-screen.png" title="Select CaitSith enabled kernel" width="640" height="480">

<p>If everything was installed properly and the bootloader was correctly configured, the kernel should boot as normal and CaitSith should be activated:</p>

<img src="media/caitsith-activated.png" alt="caitsith-activated.png" title="CaitSith activated" width="720" height="400">

<hr>
<h3><a name="2.2.9">2.2.9. How can I disable/uninstall CaitSith?</a></h3>

<p>If your system becomes unable to boot during the course of this guide or any time in the future, it may be due to policy configuration or something related to CaitSith. If this is the case, it is possible that the kernel can still be booted by disabling CaitSith. This can be done by appending "caitsith=off" at the kernel's command line options.</p>

<p>CaitSith fortunately does not require the modification of any existing Linux binaries, libraries or applications. Thus, uninstalling CaitSith is very easy. It is simply a matter of uninstalling the kernel and userspace tools that you installed above. You can reboot with the kernel provided by your distribution and then remove the entry from your bootloader.</p>

<hr>
<h2><a name="how_to_develop_policy">3. How to develop policy</a></h2>

<hr>
<h3><a name="3.1">3.1. Policy file structure</a></h3>

<p>CaitSith's policy file consists with "Header part" and "ACL part".</p>

<h4><a name="3.1.1">3.1.1. Header part of policy file</a></h4>

<p>Header part consists with below lines.</p>

<pre>
POLICY_VERSION=20120401
stat $stat_name $stat_value
quota memory policy $max_byte_for_policy
quota memory audit $max_byte_for_audit_logs
quota memory query $max_byte_for_query
quota audit[$audit_index] allowed=$max_logs_for_allowed_request unmatched=$max_logs_for_unmatched_request denied=$max_logs_for_denied_request
string_group $string_group_name $string_group_member
number_group $number_group_name $number_group_member
ip_group $ip_group_name $ip_group_member
</pre>

<ul>
<li>POLICY_VERSION line defines policy version.</li>
<li>stat lines are for showing statistics information such as memory usage. $stat_name and $stat_value are simply ignored.</li>
<li>$max_byte_for_policy is max amount of memory in byte which can be allocated for policy. Default is unlimited.</li>
<li>$max_byte_for_audit_logs is max amount of memory in byte which can be allocated for audit logs. Default is unlimited. $max_byte_for_audit_logs=16777216 should be sufficient.</li>
<li>$max_byte_for_query is max amount of memory in byte which can be allocated for interactive enforcement. Default is unlimited. $max_byte_for_audit_logs=1048576 should be sufficient.</li>
<li>quota audit[$audit_index] lines (0 &lt;= $audit_index &lt;= 255) are max number of audit logs which can be held in the kernel space. $max_logs_for_allowed_request is for allowed requests. $max_logs_for_unmatched_request is for unmatched requests. $max_logs_for_denied_request is for denied requests. Default is 0. Unless you have special reasons, you should set 0 to $max_logs_for_allowed_request. Regarding $max_logs_for_unmatched_request and $max_logs_for_denied_request, 1024 should be sufficient.</li>
<li>string_group $string_group_name lines define group of strings. $string_group_member is a member for $string_group_name group.</li>
<li>number_group $number_group_name lines define group of numbers. $number_group_member is a member for $number_group_name group.</li>
<li>ip_group $ip_group_name lines define group of IP addresses. $ip_group_member is a member for $ip_group_name group.</li>
</ul>

<h4><a name="3.1.2">3.1.2. ACL part of policy file</a></h4>

<p>ACL part consists with 0 or more repetitions of below block.</p>

<pre>
$acl_priority acl $operation $conditions_to_filter
    audit $audit_index
    $cond_priority $decision $conditions_to_allow_or_deny
</pre>

<ul>
<li>A block which starts with $acl_priority determines whether to evaluate rules in this block or not.</li>
<li>Blocks which start with $acl_priority can be defined as many as you need.</li>
<li>$acl_priority is a priority (an integer between 0 and 65535) which controls which block should be evaluated first (among all blocks defined in the policy).</li>
<li>Blocks are evaluated from smaller $acl_priority values to larger $acl_priority values.</li>
<li>If two blocks have same $acl_priority value, the block which is defined first is evaluated first.</li>
<li>$operation is "operation".</li>
<li>$conditions_to_filter is "conditional expressions" which can be applied to "operation". Omit $conditions_to_filter to evaluate this block unconditionally.</li>
<li>Access requests will be denied if one of deny lines (among all blocks defined in the policy) matches.</li>
</ul>

<p>$decision lines in a block is evaluated only when the block's $acl_priority line matched.</p>

<ul>
<li>A line which starts with $cond_priority determines whether to grant the access request or not.</li>
<li>Lines which start with $cond_priority can be defined as many as you need.</li>
<li>$cond_priority is a priority (an integer between 0 and 65535) which controls which line should be checked first (among all lines defined in the block).</li>
<li>Lines are checked from smaller $cond_priority values to larger priority values.</li>
<li>If two lines have same $cond_priority value, the line which is defined first is checked first.</li>
<li>$decision is either allow or deny.</li>
<li>$conditions_to_allow_or_deny is "conditional expressions" which can be applied to "operation". Omit $conditions_to_allow_or_deny to match this line unconditionally.</li>
</ul>

<p>Checking of $decision lines in a block lasts until it matches a $decision line or it reaches to the end of block.</p>

<ul>
<li>If $conditions_to_allow_or_deny of a deny line matches, the access request is denied. At the same time, access denied log is generated if memory used for audit logs is smaller than $max_byte_for_audit_logs bytes and number of denied logs which is in the kernel is smaller than $max_logs_for_denied_request of quota audit[$audit_index] line where $audit_index is specified by audit line of this block.</li>
<li>If $conditions_to_allow_or_deny of an allow line matches, the evaluation of this block ends and proceeds to next block. At the same time, access allowed log is generated if memory used for audit logs is smaller than $max_byte_for_audit_logs bytes and number of allowed logs which is in the kernel is smaller than $max_logs_for_allowed_request of quota audit[$audit_index] line where $audit_index is specified by audit line of this block.</li>
<li>If none of $conditions_to_allow_or_deny matches, the evaluation of this block ends and proceeds to next block. At the same time, access unmatched log is generated if memory used for audit logs is smaller than $max_byte_for_audit_logs bytes and number of unmatched logs which is in the kernel is smaller than $max_logs_for_unmatched_request of quota audit[$audit_index] line where $audit_index is specified by audit line of this block.</li>
</ul>

<p>Access requests will be denied only when "deny" line of "acl" block matched. (There are two exceptions. Regarding permission to change domains manually (i.e. <a href="#5.60">acl manual_domain_transition</a> blocks) and permission to change domains automatically (i.e. <a href="#5.61">acl auto_domain_transition</a> blocks), access requests will be granted only when "allow" line of all blocks match, in order to avoid unintended domain transition.)</p>

<p>$acl_priority and $cond_priority values are used for two purposes. One is for selectively deny operations using "deny" lines. For example,</p>

<pre>
10 acl read path.fsmagic=0x9FA0
    audit 0
    10 deny path="proc:/cmdline"
    20 allow
</pre>

<p>denies opening <code>/proc/cmdline</code> on the proc filesystem (proc filesystem's magic number is 0x9FA0) for reading while allowing opening all other files.</p>

<p>The other is for controlling which "transition=" and "handler=" arguments should be used when these arguments matched more than once. This will be explained in <a href="#advanced_usage">advanced usage</a>.</p>

<h4><a name="3.1.3">3.1.3. An example policy file</a></h4>

<p>Below is an example of <code>/etc/caitsith/policy/current</code> file on CentOS. The content of this file varies depending on environments you are using, and will be updated as you develop policy.</p>

<pre>
POLICY_VERSION=20120401

quota memory audit 16777216
quota memory query 1048576
quota audit[1] allowed=0 denied=1024 unmatched=1024

10000 acl execute
    audit 0
    10 allow path="/sbin/modprobe" transition="/sbin/modprobe"
    10 allow path="/sbin/init" transition="/sbin/init"
    10 allow path="/sbin/mingetty" transition="/sbin/mingetty"
    10 allow path="/sbin/udevd" transition="/sbin/udevd"
    10 allow path="/usr/sbin/anacron" transition="/usr/sbin/anacron"
    10 allow path="/usr/sbin/crond" transition="/usr/sbin/crond"
    10 allow path="/usr/sbin/httpd" transition="/usr/sbin/httpd"
    10 allow path="/usr/sbin/logrotate" transition="/usr/sbin/logrotate"
    10 allow path="/usr/sbin/nmbd" transition="/usr/sbin/nmbd"
    10 allow path="/usr/sbin/smbd" transition="/usr/sbin/smbd"
    10 allow path="/usr/sbin/sshd" transition="/usr/sbin/sshd"
    10 allow path="/etc/rc.d/init.d/ntpd" transition="/etc/rc.d/init.d/ntpd"
    10 allow path="/etc/rc.d/init.d/single" transition="/etc/rc.d/init.d/single"
    10 allow path="/etc/rc.d/init.d/killall" transition="/etc/rc.d/init.d/killall"
    10 allow path="/etc/rc.d/init.d/ip6tables" transition="/etc/rc.d/init.d/ip6tables"
    10 allow path="/etc/rc.d/init.d/halt" transition="/etc/rc.d/init.d/halt"
    10 allow path="/etc/rc.d/init.d/netfs" transition="/etc/rc.d/init.d/netfs"
    10 allow path="/etc/rc.d/init.d/messagebus" transition="/etc/rc.d/init.d/messagebus"
    10 allow path="/etc/rc.d/init.d/sandbox" transition="/etc/rc.d/init.d/sandbox"
    10 allow path="/etc/rc.d/init.d/rsyslog" transition="/etc/rc.d/init.d/rsyslog"
    10 allow path="/etc/rc.d/init.d/smb" transition="/etc/rc.d/init.d/smb"
    10 allow path="/etc/rc.d/init.d/sshd" transition="/etc/rc.d/init.d/sshd"
    10 allow path="/etc/rc.d/init.d/cgconfig" transition="/etc/rc.d/init.d/cgconfig"
    10 allow path="/etc/rc.d/init.d/udev-post" transition="/etc/rc.d/init.d/udev-post"
    10 allow path="/etc/rc.d/init.d/firstboot" transition="/etc/rc.d/init.d/firstboot"
    10 allow path="/etc/rc.d/init.d/ntpdate" transition="/etc/rc.d/init.d/ntpdate"
    10 allow path="/etc/rc.d/init.d/crond" transition="/etc/rc.d/init.d/crond"
    10 allow path="/etc/rc.d/init.d/restorecond" transition="/etc/rc.d/init.d/restorecond"
    10 allow path="/etc/rc.d/init.d/httpd" transition="/etc/rc.d/init.d/httpd"
    10 allow path="/etc/rc.d/init.d/rdisc" transition="/etc/rc.d/init.d/rdisc"
    10 allow path="/etc/rc.d/init.d/postfix" transition="/etc/rc.d/init.d/postfix"
    10 allow path="/etc/rc.d/init.d/saslauthd" transition="/etc/rc.d/init.d/saslauthd"
    10 allow path="/etc/rc.d/init.d/netconsole" transition="/etc/rc.d/init.d/netconsole"
    10 allow path="/etc/rc.d/init.d/network" transition="/etc/rc.d/init.d/network"
    10 allow path="/etc/rc.d/init.d/avahi-daemon" transition="/etc/rc.d/init.d/avahi-daemon"
    10 allow path="/etc/rc.d/init.d/auditd" transition="/etc/rc.d/init.d/auditd"
    10 allow path="/etc/rc.d/init.d/nmb" transition="/etc/rc.d/init.d/nmb"
    10 allow path="/etc/rc.d/init.d/iptables" transition="/etc/rc.d/init.d/iptables"
    10 allow path="/etc/rc.d/init.d/cgred" transition="/etc/rc.d/init.d/cgred"

0 acl modify_policy
    audit 1
    1 deny task.uid!=0
    1 deny task.euid!=0
    100 allow task.exe="/usr/sbin/caitsith-loadpolicy"
    100 allow task.exe="/usr/sbin/caitsith-queryd"
    10000 deny
</pre>

<hr>
<h3><a name="3.2">3.2. Updating policy configuration</a></h3>

<p>There are two ways to update policy configuration.</p>

<p>One is to use <code>/sbin/caitsith-init</code> which is automatically called when <code>/sbin/init</code> starts. <code>/sbin/caitsith-init</code> reads policy from <code>/etc/caitsith/policy/current</code> and writes to <code>/proc/caitsith/policy</code> interface. Therefore, you can update policy configuration by updating <code>/etc/caitsith/policy/current</code> and rebooting your system.</p>

<p>The other is to use <code>/usr/sbin/caitsith-loadpolicy</code> which is defined for loading policy after your system has booted. <code>/usr/sbin/caitsith-loadpolicy</code> reads policy from standard input and writes to <code>/proc/caitsith/policy</code> interface. Therefore, you can update policy configuration without updating <code>/etc/caitsith/policy/current</code> and rebooting your system. For example, if you want to append a "string_group mygroup1 /" line to <code>/proc/caitsith/policy</code> interface, run below command:</p>

<pre class="command">
# echo 'string_group mygroup1 /' | /usr/sbin/caitsith-loadpolicy
</pre>

<p>If you want to delete the "string_group mygroup1 /" line from <code>/proc/caitsith/policy</code> interface, run below command:</p>

<pre class="command">
# echo 'delete string_group mygroup1 /' | /usr/sbin/caitsith-loadpolicy
</pre>

<p>The contents in <code>/proc/caitsith/policy</code> will be lost when your system shuts down or reboots. To save <code>/proc/caitsith/policy</code> as <code>/etc/caitsith/policy/current</code>, run below command:</p>

<pre class="command">
# /usr/sbin/caitsith-savepolicy
</pre>

<hr>
<h3><a name="3.3">3.3. Example of simple access restriction rule</a></h3>

<p>Let's experience how CaitSith restricts access using simple examples.</p>

<h4><a name="3.3.1">3.3.1. Telling CaitSith which access requests should be checked</a></h4>

<p>By default, CaitSith does not deny access requests. To restrict access requests, you need to tell CaitSith which access requests should be denied.</p>

<p>Below rule will check access requests which open <code>/tmp/file1</code> for reading.</p>

<pre>
100 acl read path="/tmp/file1"
    audit 1
</pre>

<p>Append above rule using <code>/usr/sbin/caitsith-loadpolicy</code>. Since <code>/usr/sbin/caitsith-loadpolicy</code> reads policy from standard input, you can use ^D (Ctrl-D) to indicate end of input:</p>

<pre class="command">
# /usr/sbin/caitsith-loadpolicy
</pre>
<pre>
100 acl read path="/tmp/file1"
    audit 1
^D
</pre>

<p>You may use a temporary file if you worry typos.</p>

<pre class="command">
# cat &gt; ~/policy.tmp
</pre>
<pre>
100 acl read path="/tmp/file1"
    audit 1
^D
</pre>
<pre class="command">
# /usr/sbin/caitsith-loadpolicy &lt; ~/policy.tmp
# rm ~/policy.tmp
</pre>

<p>You can confirm that above rule is appended to <code>/proc/caitsith/policy</code> by reading <code>/proc/caitsith/policy</code>.</p>

<pre class="command">
# cat /proc/caitsith/policy
</pre>
<pre>
POLICY_VERSION=20120401
stat Policy updated: 7 (Last: 2012/04/08 04:56:45)
stat Requests denied: 0
stat Memory used by policy: 6048
stat Memory used by audit: 0
stat Memory used by query: 0
quota memory audit 16777216
quota memory query 1048576
quota audit[1] allowed=0 denied=1024 unmatched=1024

10000 acl execute
    audit 0
    10 allow path="/sbin/modprobe" transition="/sbin/modprobe"
    10 allow path="/sbin/init" transition="/sbin/init"
    10 allow path="/sbin/mingetty" transition="/sbin/mingetty"
    10 allow path="/sbin/udevd" transition="/sbin/udevd"
    10 allow path="/usr/sbin/anacron" transition="/usr/sbin/anacron"
    10 allow path="/usr/sbin/crond" transition="/usr/sbin/crond"
    10 allow path="/usr/sbin/httpd" transition="/usr/sbin/httpd"
    10 allow path="/usr/sbin/logrotate" transition="/usr/sbin/logrotate"
    10 allow path="/usr/sbin/nmbd" transition="/usr/sbin/nmbd"
    10 allow path="/usr/sbin/smbd" transition="/usr/sbin/smbd"
    10 allow path="/usr/sbin/sshd" transition="/usr/sbin/sshd"
    10 allow path="/etc/rc.d/init.d/ntpd" transition="/etc/rc.d/init.d/ntpd"
    10 allow path="/etc/rc.d/init.d/single" transition="/etc/rc.d/init.d/single"
    10 allow path="/etc/rc.d/init.d/killall" transition="/etc/rc.d/init.d/killall"
    10 allow path="/etc/rc.d/init.d/ip6tables" transition="/etc/rc.d/init.d/ip6tables"
    10 allow path="/etc/rc.d/init.d/halt" transition="/etc/rc.d/init.d/halt"
    10 allow path="/etc/rc.d/init.d/netfs" transition="/etc/rc.d/init.d/netfs"
    10 allow path="/etc/rc.d/init.d/messagebus" transition="/etc/rc.d/init.d/messagebus"
    10 allow path="/etc/rc.d/init.d/sandbox" transition="/etc/rc.d/init.d/sandbox"
    10 allow path="/etc/rc.d/init.d/rsyslog" transition="/etc/rc.d/init.d/rsyslog"
    10 allow path="/etc/rc.d/init.d/smb" transition="/etc/rc.d/init.d/smb"
    10 allow path="/etc/rc.d/init.d/sshd" transition="/etc/rc.d/init.d/sshd"
    10 allow path="/etc/rc.d/init.d/cgconfig" transition="/etc/rc.d/init.d/cgconfig"
    10 allow path="/etc/rc.d/init.d/udev-post" transition="/etc/rc.d/init.d/udev-post"
    10 allow path="/etc/rc.d/init.d/firstboot" transition="/etc/rc.d/init.d/firstboot"
    10 allow path="/etc/rc.d/init.d/ntpdate" transition="/etc/rc.d/init.d/ntpdate"
    10 allow path="/etc/rc.d/init.d/crond" transition="/etc/rc.d/init.d/crond"
    10 allow path="/etc/rc.d/init.d/restorecond" transition="/etc/rc.d/init.d/restorecond"
    10 allow path="/etc/rc.d/init.d/httpd" transition="/etc/rc.d/init.d/httpd"
    10 allow path="/etc/rc.d/init.d/rdisc" transition="/etc/rc.d/init.d/rdisc"
    10 allow path="/etc/rc.d/init.d/postfix" transition="/etc/rc.d/init.d/postfix"
    10 allow path="/etc/rc.d/init.d/saslauthd" transition="/etc/rc.d/init.d/saslauthd"
    10 allow path="/etc/rc.d/init.d/netconsole" transition="/etc/rc.d/init.d/netconsole"
    10 allow path="/etc/rc.d/init.d/network" transition="/etc/rc.d/init.d/network"
    10 allow path="/etc/rc.d/init.d/avahi-daemon" transition="/etc/rc.d/init.d/avahi-daemon"
    10 allow path="/etc/rc.d/init.d/auditd" transition="/etc/rc.d/init.d/auditd"
    10 allow path="/etc/rc.d/init.d/nmb" transition="/etc/rc.d/init.d/nmb"
    10 allow path="/etc/rc.d/init.d/iptables" transition="/etc/rc.d/init.d/iptables"
    10 allow path="/etc/rc.d/init.d/cgred" transition="/etc/rc.d/init.d/cgred"

100 acl read path="/tmp/file1"
    audit 1

0 acl modify_policy
    audit 1
    1 deny task.uid!=0
    1 deny task.euid!=0
    100 allow task.exe="/usr/sbin/caitsith-loadpolicy"
    100 allow task.exe="/usr/sbin/caitsith-queryd"
    10000 deny
</pre>

<h4><a name="3.3.2">3.3.2. Access requests which will be implicitly allowed by CaitSith</a></h4>

<p>Make sure that <code>/usr/sbin/caitsith-auditd</code> is running.</p>

<pre class="command">
# pidof caitsith-auditd
</pre>
<pre>
3627
</pre>

<p>Now, create <code>/tmp/file1</code> file.</p>

<pre class="command">
# touch /tmp/file1
</pre>

<p>Then, open <code>/tmp/file1</code> for reading.</p>

<pre class="command">
# cat /tmp/file1
</pre>

<p>Check <code>/var/log/caitsith/unmatched.log</code> for access unmatched log of this access request. You will find an entry like below:</p>

<pre class="command">
# grep /tmp/file1 /var/log/caitsith/unmatched.log
</pre>
<pre>
#2012/04/08 04:58:40# global-pid=3678 result=unmatched priority=100 / read path="/tmp/file1" task.pid=3678 task.ppid=3653 task.uid=0 task.gid=0 task.euid=0 task.egid=0 task.suid=0 task.sgid=0 task.fsuid=0 task.fsgid=0 task.type!=execute_handler task.exe="/bin/cat" task.domain="/usr/sbin/sshd" path.uid=0 path.gid=0 path.ino=2113451 path.major=8 path.minor=1 path.perm=0644 path.type=file path.fsmagic=0xEF53 path.parent.uid=0 path.parent.gid=0 path.parent.ino=2097153 path.parent.major=8 path.parent.minor=1 path.parent.perm=01777 path.parent.type=directory path.parent.fsmagic=0xEF53
</pre>

<p>Note the <strong>result=unmatched</strong> part of the entry. This indicates that access request was checked but matched neither "allow" nor "deny" rule.</p>

<p>Note the <strong>priority=100</strong> part of the entry. This indicates that this entry was generated by rules which have 100 as priority.</p>

<p>Note the <strong>read path="<code>/tmp/file1</code>"</strong> part of the entry. This indicates that this entry was generated by access request of opening <code>/tmp/file1</code> for reading.</p>

<h4><a name="3.3.3">3.3.3. Access requests which will be explicitly denied by CaitSith</a></h4>

<p>Now, let's add a rule to explicitly deny this request.</p>

<pre>
100 acl read path="/tmp/file1"
    1000 deny
</pre>

<p>Append above rule using <code>/usr/sbin/caitsith-loadpolicy</code>:</p>

<pre class="command">
# /usr/sbin/caitsith-loadpolicy
</pre>
<pre>
100 acl read path="/tmp/file1"
    1000 deny
^D
</pre>

<p>Rules that have same priority (in this rule, 100) and same operation (in this rule, read) and same condition (in this rule, path="<code>/tmp/file1</code>") are automatically merged. Therefore, you will find</p>

<pre>
100 acl read path="/tmp/file1"
    audit 1
    1000 deny
</pre>

<p>rather than</p>

<pre>
100 acl read path="/tmp/file1"
    audit 1

100 acl read path="/tmp/file1"
    1000 deny
</pre>

<p>when you read <code>/proc/caitsith/policy</code>.</p>

<p>Then, open <code>/tmp/file1</code> for reading.</p>

<pre class="command">
# cat /tmp/file1
</pre>
<pre>
cat: /tmp/file1: Operation not permitted
</pre>

<p>This time, access request was denied by CaitSith.</p>

<p>Check <code>/var/log/caitsith/denied.log</code> for access denied log of this access request. You will find an entry like below:</p>

<pre class="command">
# grep /tmp/file1 /var/log/caitsith/denied.log
</pre>
<pre>
#2012/04/08 04:59:53# global-pid=3682 result=denied priority=100 / read path="/tmp/file1" task.pid=3682 task.ppid=3653 task.uid=0 task.gid=0 task.euid=0 task.egid=0 task.suid=0 task.sgid=0 task.fsuid=0 task.fsgid=0 task.type!=execute_handler task.exe="/bin/cat" task.domain="/usr/sbin/sshd" path.uid=0 path.gid=0 path.ino=2113451 path.major=8 path.minor=1 path.perm=0644 path.type=file path.fsmagic=0xEF53 path.parent.uid=0 path.parent.gid=0 path.parent.ino=2097153 path.parent.major=8 path.parent.minor=1 path.parent.perm=01777 path.parent.type=directory path.parent.fsmagic=0xEF53
</pre>

<p>Note the <strong>result=denied</strong> part of the entry. This indicates that access request was checked and matched "deny" rule.</p>

<p>If <code>/usr/sbin/caitsith-notifyd</code> is running, you will receive a notification mail. The content is same with access denied logs.</p>

<pre class="command">
# mail
</pre>
<pre>
Heirloom Mail version 12.4 7/29/08.  Type ? for help.
"/var/spool/mail/root": 1 message 1 new
&gt;N  1 root                  Sun Apr  8 13:59  20/1231  "Notification from caitsith-notifyd"
&amp;
Message  1:
From root@ccsecurity.localdomain  Sun Apr  8 13:59:53 2012
Return-Path: &lt;root@ccsecurity.localdomain&gt;
X-Original-To: root@localhost
Delivered-To: root@localhost.localdomain
Date: Sun, 08 Apr 2012 13:59:53 +0900
To: root@localhost.localdomain
Subject: Notification from caitsith-notifyd
User-Agent: Heirloom mailx 12.4 7/29/08
Content-Type: text/plain; charset=us-ascii
From: root@caitsith.localdomain (root)
Status: R

Q0-0
#2012/04/08 04:59:53# global-pid=3682 result=denied priority=100 / read path="/tmp/file1" task.pid=3682 task.ppid=3653 task.uid=0 task.gid=0 task.euid=0 task.egid=0 task.suid=0 task.sgid=0 task.fsuid=0 task.fsgid=0 task.type!=execute_handler task.exe="/bin/cat" task.domain="/usr/sbin/sshd" path.uid=0 path.gid=0 path.ino=2113451 path.major=8 path.minor=1 path.perm=0644 path.type=file path.fsmagic=0xEF53 path.parent.uid=0 path.parent.gid=0 path.parent.ino=2097153 path.parent.major=8 path.parent.minor=1 path.parent.perm=01777 path.parent.type=directory path.parent.fsmagic=0xEF53
</pre>

<p>Now, let's remove a rule to explicitly deny this request.</p>

<pre>
100 acl read path="/tmp/file1"
    delete 1000 deny
</pre>

<p>Append above rule using <code>/usr/sbin/caitsith-loadpolicy</code>:</p>

<pre class="command">
# /usr/sbin/caitsith-loadpolicy
</pre>
<pre>
100 acl read path="/tmp/file1"
    delete 1000 deny
^D
</pre>

<p>You will find</p>

<pre>
100 acl read path="/tmp/file1"
    audit 1
</pre>

<p>rather than</p>

<pre>
100 acl read path="/tmp/file1"
    audit 1
    1000 deny
    delete 1000 deny
</pre>

<p>when you read <code>/proc/caitsith/policy</code>.</p>

<h4><a name="3.3.4">3.3.4. Filtering audit logs</a></h4>

<p>Now, open <code>/tmp/file1</code> for reading.</p>

<pre class="command">
# cat /tmp/file1
</pre>

<p>Check <code>/var/log/caitsith/unmatched.log</code> for access unmatched log of this access request. You will find entries like below:</p>

<pre class="command">
# grep /tmp/file1 /var/log/caitsith/unmatched.log
</pre>
<pre>
#2012/04/08 04:58:40# global-pid=3678 result=unmatched priority=100 / read path="/tmp/file1" task.pid=3678 task.ppid=3653 task.uid=0 task.gid=0 task.euid=0 task.egid=0 task.suid=0 task.sgid=0 task.fsuid=0 task.fsgid=0 task.type!=execute_handler task.exe="/bin/cat" task.domain="/usr/sbin/sshd" path.uid=0 path.gid=0 path.ino=2113451 path.major=8 path.minor=1 path.perm=0644 path.type=file path.fsmagic=0xEF53 path.parent.uid=0 path.parent.gid=0 path.parent.ino=2097153 path.parent.major=8 path.parent.minor=1 path.parent.perm=01777 path.parent.type=directory path.parent.fsmagic=0xEF53
#2012/04/08 05:01:00# global-pid=3695 result=unmatched priority=100 / read path="/tmp/file1" task.pid=3695 task.ppid=3653 task.uid=0 task.gid=0 task.euid=0 task.egid=0 task.suid=0 task.sgid=0 task.fsuid=0 task.fsgid=0 task.type!=execute_handler task.exe="/bin/cat" task.domain="/usr/sbin/sshd" path.uid=0 path.gid=0 path.ino=2113451 path.major=8 path.minor=1 path.perm=0644 path.type=file path.fsmagic=0xEF53 path.parent.uid=0 path.parent.gid=0 path.parent.ino=2097153 path.parent.major=8 path.parent.minor=1 path.parent.perm=01777 path.parent.type=directory path.parent.fsmagic=0xEF53
</pre>

<p>The former entry was generated before adding explicit "deny" rule. The latter entry was generated after removing explicit "deny" rule. You might want to filter the output using tail command:</p>

<pre class="command">
# grep /tmp/file1 /var/log/caitsith/unmatched.log | tail -n 1
</pre>
<pre>
#2012/04/08 05:01:00# global-pid=3695 result=unmatched priority=100 / read path="/tmp/file1" task.pid=3695 task.ppid=3653 task.uid=0 task.gid=0 task.euid=0 task.egid=0 task.suid=0 task.sgid=0 task.fsuid=0 task.fsgid=0 task.type!=execute_handler task.exe="/bin/cat" task.domain="/usr/sbin/sshd" path.uid=0 path.gid=0 path.ino=2113451 path.major=8 path.minor=1 path.perm=0644 path.type=file path.fsmagic=0xEF53 path.parent.uid=0 path.parent.gid=0 path.parent.ino=2097153 path.parent.major=8 path.parent.minor=1 path.parent.perm=01777 path.parent.type=directory path.parent.fsmagic=0xEF53
</pre>

<h4><a name="3.3.5">3.3.5. Access requests which will be explicitly allowed by CaitSith</a></h4>

<p>Next, let's see audit logs with explicitly matching "allow" rules.</p>

<p>By default CaitSith does not generate audit logs with explicitly matching "allow" rules. Change policy configuration to generate such logs.</p>

<pre>
quota audit[1] allowed=1024
</pre>

<p>Append above rule using <code>/usr/sbin/caitsith-loadpolicy</code>:</p>

<pre class="command">
# echo 'quota audit[1] allowed=1024' | /usr/sbin/caitsith-loadpolicy
</pre>

<p>Preferences that have same name (in this rule, audit[1]) are automatically merged. Therefore, you will find</p>

<pre>
quota audit[1] allowed=1024 denied=1024 unmatched=1024
</pre>

<p>rather than</p>

<pre>
quota audit[1] allowed=0 denied=1024 unmatched=1024
quota audit[1] allowed=1024
</pre>

<p>when you read <code>/proc/caitsith/policy</code>.</p>

<pre>
100 acl read path="/tmp/file1"
    1000 allow
</pre>

<p>Append above rule using <code>/usr/sbin/caitsith-loadpolicy</code>:</p>

<pre class="command">
# /usr/sbin/caitsith-loadpolicy
</pre>
<pre>
100 acl read path="/tmp/file1"
    1000 allow
^D
</pre>

<p>Since audit logs with explicitly matching "allow" rules tend to grow rapidly, by default <code>/usr/sbin/caitsith-auditd</code> discards such logs by writing to <code>/dev/null</code> (specified in <code>/etc/caitsith/tools/auditd.conf</code>).
Therefore, temporarily stop <code>/usr/sbin/caitsith-auditd</code> process in order to read audit logs from <code>/proc/caitsith/audit</code> interface.</p>

<pre class="command">
# killall -KILL caitsith-auditd
</pre>

<p>Then, open <code>/tmp/file1</code> for reading.</p>

<pre class="command">
# cat /tmp/file1
</pre>

<p>Check <code>/proc/caitsith/audit</code> for audit log of this access request. This time, you will find an entry like below:</p>

<pre class="command">
# cat -v /proc/caitsith/audit
</pre>
<pre>
#2012/04/08 05:03:03# global-pid=3720 result=allowed priority=100 / read path="/tmp/file1" task.pid=3720 task.ppid=3653 task.uid=0 task.gid=0 task.euid=0 task.egid=0 task.suid=0 task.sgid=0 task.fsuid=0 task.fsgid=0 task.type!=execute_handler task.exe="/bin/cat" task.domain="/usr/sbin/sshd" path.uid=0 path.gid=0 path.ino=2113451 path.major=8 path.minor=1 path.perm=0644 path.type=file path.fsmagic=0xEF53 path.parent.uid=0 path.parent.gid=0 path.parent.ino=2097153 path.parent.major=8 path.parent.minor=1 path.parent.perm=01777 path.parent.type=directory path.parent.fsmagic=0xEF53
^@
</pre>

<p>Note the <strong>result=allowed</strong> part of the entry. This indicates that access request was checked and matched "allow" rule.</p>

<p>Restart <code>/usr/sbin/caitsith-auditd</code> process.</p>

<pre class="command">
# /usr/sbin/caitsith-auditd
</pre>

<p>Also, restore the audit logs configuration:</p>

<pre>
quota audit[1] allowed=0
</pre>

<p>Append above rule using <code>/usr/sbin/caitsith-loadpolicy</code>:</p>

<pre class="command">
# echo 'quota audit[1] allowed=0' | /usr/sbin/caitsith-loadpolicy
</pre>

<hr>
<h3><a name="3.4">3.4. Understanding two viewpoints</a></h3>

<p>CaitSith supports writing access restriction rules from two viewpoints. One is from the point of view of "subject" (a resource which requests access on object). The other is from the point of view of "object" (a resource which subject requests access).</p>

<p>The advantage of the former approach is that the rules clearly explains and restricts what each subject is allowed to access which object.
This approach is powerful when you can afford identifying all possible subjects and defining the rules for each subject.
But the disadvantage is that it is difficult to identify all possible subjects and define the rules for each subject.
Therefore, in reality, this approach tends to restrict only specific subjects.
If one of subjects which is not restricted by this approach is cracked or misbehaved, nothing can protect objects you want to protect.</p>

<p>The advantage of the latter approach is that the rules clearly explains and restricts what object might be accessed by which subject.
This approach is powerful when you can afford identifying objects you want to protect and defining rules for each object.
This approach can compensate for the disadvantage of the former approach because this approach can restrict access even when it is difficult to
identify all possible subjects and define the rules for each possible subjects.</p>

<h4><a name="3.4.1">3.4.1. Writing access restriction rules from the point of view of "subject".</a></h4>

<p>Below entry is an example of restricting programs which can be executed from <code>/usr/sbin/httpd</code> program.</p>

<pre>
0 acl execute task.exe="/usr/sbin/httpd"
    audit 1
    1 allow path="/var/www/cgi-bin/counter.cgi"
    100 deny
</pre>

<p>The <strong>0 acl execute task.exe="<code>/usr/sbin/httpd</code>"</strong> line means check rules for executing programs from <code>/usr/sbin/httpd</code> program. Since <strong>task.exe="<code>/usr/sbin/httpd</code>"</strong> is specified in this line, this line tells CaitSith <strong>check rules for executing programs only if current thread's program name is <code>/usr/sbin/httpd</code></strong>.</p>

<p>The line <strong>1 allow path="<code>/var/www/cgi-bin/counter.cgi</code>"</strong> means that allow if the pathname of the program to execute is <code>/var/www/cgi-bin/counter.cgi</code>. This line tells CaitSith "allow execution of <code>/var/www/cgi-bin/counter.cgi</code>".</p>

<p>The line <strong>100 deny</strong> means deny unconditionally. This tells CaitSith "unconditionally deny execution of programs".</p>

<p>Since the line starting with <strong>1 allow</strong> has higher priority than the line starting with <strong>100 deny</strong>, CaitSith will allow execution of <code>/var/www/cgi-bin/counter.cgi</code>.</p>

<p>To summarize this rule, <code>/usr/sbin/httpd</code> can execute <strong>only</strong> <code>/var/www/cgi-bin/counter.cgi</code>.</p>

<p>The line <strong>audit 1</strong> means that use audit rules defined in the <strong>quota audit[1]</strong> line. This line tells CaitSith generate audit logs up to entries defined in the <strong>quota audit[1]</strong> line. The default configuration generated by executing <code>/usr/lib/caitsith/init_policy</code> command is</p>

<pre>
quota audit[1] allowed=0 denied=1024 unmatched=1024
</pre>

<p>which means do not generate audit logs if matched an "allow" line and generate audit logs up to 1024 entries if matched a "deny" line and generate audit logs up to 1024 lines if matched neither an "allow" line nor a "deny" line. Though, since the block starting with <strong>0 acl execute task.exe="<code>/usr/sbin/httpd</code>"</strong> is terminated with explicit <strong>100 deny</strong> line, this block shall match either an "allow" line or a "deny" line.</p>

<h4><a name="3.4.2">3.4.2. Writing access restriction rules from the point of view of "object".</a></h4>

<p>Below entry is default configuration generated by executing <code>/usr/lib/caitsith/init_policy</code> command.</p>

<pre>
0 acl modify_policy
    audit 1
    1 deny task.uid!=0
    1 deny task.euid!=0
    100 allow task.exe="/usr/sbin/caitsith-loadpolicy"
    100 allow task.exe="/usr/sbin/caitsith-queryd"
    10000 deny
</pre>

<p>The <strong>0 acl modify_policy</strong> line means check rules for modifying policy configuration via <code>/proc/caitsith/policy</code> interface. Since no additional conditions are specified in this line, this line tells CaitSith <strong>unconditionally check</strong> rules for modifying policy configuration via <code>/proc/caitsith/policy</code> interface.</p>

<p>The line <strong>1 deny task.uid!=0</strong> means that deny if current thread's user ID is not 0. This line tells CaitSith "deny modification of policy configuration via <code>/proc/caitsith/policy</code> interface if current thread's user ID is not 0".</p>

<p>The line <strong>1 deny task.euid!=0</strong> means that deny if current thread's effective user ID is not 0. This line tells CaitSith "deny modification of policy configuration via <code>/proc/caitsith/policy</code> interface if current thread's effective user ID is not 0".</p>

<p>Note the difference between</p>

<pre>
    1 deny task.uid!=0
    1 deny task.euid!=0
</pre>

<p>and</p>

<pre>
    1 deny task.uid!=0 task.euid!=0
</pre>

<p>. The former conditions tell CaitSith "deny if current thread's user ID is not 0 <strong>or</strong> current thread's effective user ID is not 0", while the latter conditions tell CaitSith "deny if current thread's user ID is not 0 <strong>and</strong> current thread's effective user ID is not 0".</p>

<p>The line <strong>100 allow task.exe="<code>/usr/sbin/caitsith-loadpolicy</code>"</strong> means that allow if current thread's program name is <code>/usr/sbin/caitsith-loadpolicy</code>. This tells CaitSith finish evaluation of this block starting with the <strong>0 acl modify_policy</strong> line if current thread's program name is <code>/usr/sbin/caitsith-loadpolicy</code>. If there are more blocks, CaitSith will evaluate them. If there are no more blocks, CaitSith will allow modifying policy configuration via <code>/proc/caitsith/policy</code> interface.</p>

<p>The line <strong>100 allow task.exe="<code>/usr/sbin/caitsith-queryd</code>"</strong> means that allow if current thread's program name is <code>/usr/sbin/caitsith-queryd</code>. This tells CaitSith finish evaluation of this block starting with the <strong>0 acl modify_policy</strong> line if current thread's program name is <code>/usr/sbin/caitsith-queryd</code>. The usage of <code>/usr/sbin/caitsith-queryd</code> will be explained later.</p>

<p>The line <strong>10000 deny</strong> means deny unconditionally. This tells CaitSith "unconditionally deny modification of policy configuration via <code>/proc/caitsith/policy</code> interface".</p>

<p>Since lines starting with <strong>1 deny</strong> have higher priority than lines starting with <strong>100 allow</strong>, CaitSith will deny modifying policy configuration via <code>/proc/caitsith/policy</code> interface if current thread's user ID is not 0 or current thread's effective user ID is not 0. In other words, only root user (where current thread's user ID and effective user ID are both 0) can modify policy configuration via <code>/proc/caitsith/policy</code> interface.</p>

<p>Since lines starting with <strong>100 allow</strong> have higher priority than a line starting with <strong>10000 deny</strong>, CaitSith will allow modifying policy configuration via <code>/proc/caitsith/policy</code> interface if current thread's program name is <code>/usr/sbin/caitsith-loadpolicy</code> or current thread's program name is <code>/usr/sbin/caitsith-queryd</code>. In other words, other programs such as <code>/bin/sh</code>, <code>/bin/echo</code>, <code>/bin/cat</code> are not allowed to modify policy configuration via <code>/proc/caitsith/policy</code> interface.</p>

<p>To summarize this rule, only <code>/usr/sbin/caitsith-loadpolicy</code> or <code>/usr/sbin/caitsith-queryd</code> command running as root user can modify policy configuration via <code>/proc/caitsith/policy</code> interface.</p>

<p>Note the difference between</p>

<pre>
0 acl execute task.exe="/usr/sbin/httpd"
    audit 1
    1 allow path="/var/www/cgi-bin/counter.cgi"
    100 deny
</pre>

<p>and</p>

<pre>
0 acl execute path="/var/www/cgi-bin/counter.cgi"
    audit 1
    1 allow task.exe="/usr/sbin/httpd"
    100 deny
</pre>

<p>. The former means "<code>/usr/sbin/httpd</code> can execute <strong>only</strong> <code>/var/www/cgi-bin/counter.cgi</code>", while the latter means "<strong>only</strong> <code>/usr/sbin/httpd</code> can execute <code>/var/www/cgi-bin/counter.cgi</code>".</p>

<p>CaitSith supports restricting other arguments such as command line arguments and environment variables. Syntax for restricting other arguments will be explained later.</p>

<h4><a name="3.4.3">3.4.3. Writing access restriction rules from the point of view of both "subject" and "object".</a></h4>

<p>It is possible to write access restriction rules like</p>

<pre>
0 acl execute task.exe="/usr/sbin/httpd" path="/var/www/cgi-bin/counter.cgi"
    audit 1
    1 allow task.uid!=0
    100 deny
</pre>

<p>and</p>

<pre>
0 acl execute task.uid!=0
    audit 1
    1 allow task.exe="/usr/sbin/httpd" path="/var/www/cgi-bin/counter.cgi"
    100 deny
</pre>

<p>. The former means "<code>/usr/sbin/httpd</code> is allowed to execute <code>/var/www/cgi-bin/counter.cgi</code> only if current thread's user ID is not 0", while the latter means "only execution of <code>/var/www/cgi-bin/counter.cgi</code> from <code>/usr/sbin/httpd</code> is allowed if current thread's user ID is not 0".</p>

<p>Also, it is possible to write access restriction rules like</p>

<pre>
0 acl execute
    audit 1
    1 allow task.exe="/usr/sbin/httpd" path="/var/www/cgi-bin/counter.cgi"
    100 deny
</pre>

<p>which means "any execute requests other than execution of <code>/var/www/cgi-bin/counter.cgi</code> from <code>/usr/sbin/httpd</code> are denied" (DO NOT TRY THIS EXAMPLE, or you will no longer be able to run any commands).</p>

<hr>
<h2><a name="condition_list">4. List of conditions</a></h2>

<hr>
<h3><a name="4.1">4.1. Using string arguments in conditions</a></h3>

<p>Arguments such as file's pathnames and command line arguments and environment variables are handled as string argument.</p>

<h4><a name="4.1.1">4.1.1. About string argument representation rule</a></h4>

<p>All ASCII printable characters other than \ character (i.e. from 33 to 91 and from 93 to 126) are represented as is.</p>

<p>All other characters (i.e. from 0 to 32, 92 and from 127 to 255) are represented using \ooo style octal form.</p>

<table border="1">
<tr>
<td>
<table><tr><td></td><td>Lower 4 bits</td></tr><tr><td>Upper 4 bits</td><td></td></tr></table>
</td>
<th><p>0x0</p></th>
<th><p>0x1</p></th>
<th><p>0x2</p></th>
<th><p>0x3</p></th>
<th><p>0x4</p></th>
<th><p>0x5</p></th>
<th><p>0x6</p></th>
<th><p>0x7</p></th>
<th><p>0x8</p></th>
<th><p>0x9</p></th>
<th><p>0xA</p></th>
<th><p>0xB</p></th>
<th><p>0xC</p></th>
<th><p>0xD</p></th>
<th><p>0xE</p></th>
<th><p>0xF</p></th>
</tr>
<tr>
<th><p>0x0</p></th>
<td><p>\000</p></td>
<td><p>\001</p></td>
<td><p>\002</p></td>
<td><p>\003</p></td>
<td><p>\004</p></td>
<td><p>\005</p></td>
<td><p>\006</p></td>
<td><p>\007</p></td>
<td><p>\010</p></td>
<td><p>\011</p></td>
<td><p>\012</p></td>
<td><p>\013</p></td>
<td><p>\014</p></td>
<td><p>\015</p></td>
<td><p>\016</p></td>
<td><p>\017</p></td>
</tr>
<tr>
<th><p>0x1</p></th>
<td><p>\020</p></td>
<td><p>\021</p></td>
<td><p>\022</p></td>
<td><p>\023</p></td>
<td><p>\024</p></td>
<td><p>\025</p></td>
<td><p>\026</p></td>
<td><p>\027</p></td>
<td><p>\030</p></td>
<td><p>\031</p></td>
<td><p>\032</p></td>
<td><p>\033</p></td>
<td><p>\034</p></td>
<td><p>\035</p></td>
<td><p>\036</p></td>
<td><p>\037</p></td>
</tr>
<tr>
<th><p>0x2</p></th>
<td><p>\040</p></td>
<td><p>!</p></td>
<td><p>"</p></td>
<td><p>#</p></td>
<td><p>$</p></td>
<td><p>%</p></td>
<td><p>&amp;</p></td>
<td><p>'</p></td>
<td><p>(</p></td>
<td><p>)</p></td>
<td><p>*</p></td>
<td><p>+</p></td>
<td><p>,</p></td>
<td><p>-</p></td>
<td><p>.</p></td>
<td><p>/</p></td>
</tr>
<tr>
<th><p>0x3</p></th>
<td><p>0</p></td>
<td><p>1</p></td>
<td><p>2</p></td>
<td><p>3</p></td>
<td><p>4</p></td>
<td><p>5</p></td>
<td><p>6</p></td>
<td><p>7</p></td>
<td><p>8</p></td>
<td><p>9</p></td>
<td><p>:</p></td>
<td><p>;</p></td>
<td><p>&lt;</p></td>
<td><p>=</p></td>
<td><p>&gt;</p></td>
<td><p>?</p></td>
</tr>
<tr>
<th><p>0x4</p></th>
<td><p>@</p></td>
<td><p>A</p></td>
<td><p>B</p></td>
<td><p>C</p></td>
<td><p>D</p></td>
<td><p>E</p></td>
<td><p>F</p></td>
<td><p>G</p></td>
<td><p>H</p></td>
<td><p>I</p></td>
<td><p>J</p></td>
<td><p>K</p></td>
<td><p>L</p></td>
<td><p>M</p></td>
<td><p>N</p></td>
<td><p>O</p></td>
</tr>
<tr>
<th><p>0x5</p></th>
<td><p>P</p></td>
<td><p>Q</p></td>
<td><p>R</p></td>
<td><p>S</p></td>
<td><p>T</p></td>
<td><p>U</p></td>
<td><p>V</p></td>
<td><p>W</p></td>
<td><p>X</p></td>
<td><p>Y</p></td>
<td><p>Z</p></td>
<td><p>[</p></td>
<td><p>\134</p></td>
<td><p>]</p></td>
<td><p>^</p></td>
<td><p>_</p></td>
</tr>
<tr>
<th><p>0x6</p></th>
<td><p>`</p></td>
<td><p>a</p></td>
<td><p>b</p></td>
<td><p>c</p></td>
<td><p>d</p></td>
<td><p>e</p></td>
<td><p>f</p></td>
<td><p>g</p></td>
<td><p>h</p></td>
<td><p>i</p></td>
<td><p>j</p></td>
<td><p>k</p></td>
<td><p>l</p></td>
<td><p>m</p></td>
<td><p>n</p></td>
<td><p>o</p></td>
</tr>
<tr>
<th><p>0x7</p></th>
<td><p>p</p></td>
<td><p>q</p></td>
<td><p>r</p></td>
<td><p>s</p></td>
<td><p>t</p></td>
<td><p>u</p></td>
<td><p>v</p></td>
<td><p>w</p></td>
<td><p>x</p></td>
<td><p>y</p></td>
<td><p>z</p></td>
<td><p>{</p></td>
<td><p>|</p></td>
<td><p>}</p></td>
<td><p>~</p></td>
<td><p>\177</p></td>
</tr>
<tr>
<th><p>0x8</p></th>
<td><p>\200</p></td>
<td><p>\201</p></td>
<td><p>\202</p></td>
<td><p>\203</p></td>
<td><p>\204</p></td>
<td><p>\205</p></td>
<td><p>\206</p></td>
<td><p>\207</p></td>
<td><p>\210</p></td>
<td><p>\211</p></td>
<td><p>\212</p></td>
<td><p>\213</p></td>
<td><p>\214</p></td>
<td><p>\215</p></td>
<td><p>\216</p></td>
<td><p>\217</p></td>
</tr>
<tr>
<th><p>0x9</p></th>
<td><p>\220</p></td>
<td><p>\221</p></td>
<td><p>\222</p></td>
<td><p>\223</p></td>
<td><p>\224</p></td>
<td><p>\225</p></td>
<td><p>\226</p></td>
<td><p>\227</p></td>
<td><p>\230</p></td>
<td><p>\231</p></td>
<td><p>\232</p></td>
<td><p>\233</p></td>
<td><p>\234</p></td>
<td><p>\235</p></td>
<td><p>\236</p></td>
<td><p>\237</p></td>
</tr>
<tr>
<th><p>0xA</p></th>
<td><p>\240</p></td>
<td><p>\241</p></td>
<td><p>\242</p></td>
<td><p>\243</p></td>
<td><p>\244</p></td>
<td><p>\245</p></td>
<td><p>\246</p></td>
<td><p>\247</p></td>
<td><p>\250</p></td>
<td><p>\251</p></td>
<td><p>\252</p></td>
<td><p>\253</p></td>
<td><p>\254</p></td>
<td><p>\255</p></td>
<td><p>\256</p></td>
<td><p>\257</p></td>
</tr>
<tr>
<th><p>0xB</p></th>
<td><p>\260</p></td>
<td><p>\261</p></td>
<td><p>\262</p></td>
<td><p>\263</p></td>
<td><p>\264</p></td>
<td><p>\265</p></td>
<td><p>\266</p></td>
<td><p>\267</p></td>
<td><p>\270</p></td>
<td><p>\271</p></td>
<td><p>\272</p></td>
<td><p>\273</p></td>
<td><p>\274</p></td>
<td><p>\275</p></td>
<td><p>\276</p></td>
<td><p>\277</p></td>
</tr>
<tr>
<th><p>0xC</p></th>
<td><p>\300</p></td>
<td><p>\301</p></td>
<td><p>\302</p></td>
<td><p>\303</p></td>
<td><p>\304</p></td>
<td><p>\305</p></td>
<td><p>\306</p></td>
<td><p>\307</p></td>
<td><p>\310</p></td>
<td><p>\311</p></td>
<td><p>\312</p></td>
<td><p>\313</p></td>
<td><p>\314</p></td>
<td><p>\315</p></td>
<td><p>\316</p></td>
<td><p>\317</p></td>
</tr>
<tr>
<th><p>0xD</p></th>
<td><p>\320</p></td>
<td><p>\321</p></td>
<td><p>\322</p></td>
<td><p>\323</p></td>
<td><p>\324</p></td>
<td><p>\325</p></td>
<td><p>\326</p></td>
<td><p>\327</p></td>
<td><p>\330</p></td>
<td><p>\331</p></td>
<td><p>\332</p></td>
<td><p>\333</p></td>
<td><p>\334</p></td>
<td><p>\335</p></td>
<td><p>\336</p></td>
<td><p>\337</p></td>
</tr>
<tr>
<th><p>0xE</p></th>
<td><p>\340</p></td>
<td><p>\341</p></td>
<td><p>\342</p></td>
<td><p>\343</p></td>
<td><p>\344</p></td>
<td><p>\345</p></td>
<td><p>\346</p></td>
<td><p>\347</p></td>
<td><p>\350</p></td>
<td><p>\351</p></td>
<td><p>\352</p></td>
<td><p>\353</p></td>
<td><p>\354</p></td>
<td><p>\355</p></td>
<td><p>\356</p></td>
<td><p>\357</p></td>
</tr>
<tr>
<th><p>0xF</p></th>
<td><p>\360</p></td>
<td><p>\361</p></td>
<td><p>\362</p></td>
<td><p>\363</p></td>
<td><p>\364</p></td>
<td><p>\365</p></td>
<td><p>\366</p></td>
<td><p>\367</p></td>
<td><p>\370</p></td>
<td><p>\371</p></td>
<td><p>\372</p></td>
<td><p>\373</p></td>
<td><p>\374</p></td>
<td><p>\375</p></td>
<td><p>\376</p></td>
<td><p>\377</p></td>
</tr>
</table>

<p>Some examples are shown below.</p>

<pre>
/bin/sh
/home/demo/Documents\040and\040Settings
</pre>

<h4><a name="4.1.2">4.1.2. Grouping string arguments using wildcard expressions.</a></h4>

<p>It is possible to use wildcards listed below in order to match string patterns.</p>

<table border="1">
<tr>
<th><p>Wildcard</p></th>
<th><p>Pattern match</p></th>
<th><p>Examples</p></th>
</tr>
<tr>
<td><p>\*</p></td>
<td><p>0 or more repetitions of characters other than "/"</p></td>
<td><p>/var/log/samba/\*</p></td>
</tr>
<tr>
<td><p>\@</p></td>
<td><p>0 or more repetitions of characters other than "/" or "."</p></td>
<td><p>/var/www/html/\@.html</p></td>
</tr>
<tr>
<td><p>\?</p></td>
<td><p>1 byte character other than "/"</p></td>
<td><p>/tmp/mail.\?\?\?\?\?\?</p></td>
</tr>
<tr>
<td><p>\$</p></td>
<td><p>1 or more repetitions of decimal digits</p></td>
<td><p>/proc/\$/cmdline</p></td>
</tr>
<tr>
<td><p>\+</p></td>
<td><p>1 decimal digit</p></td>
<td><p>/var/tmp/my_work.\+</p></td>
</tr>
<tr>
<td><p>\X</p></td>
<td><p>1 or more repetitions of hexadecimal digits</p></td>
<td><p>/var/tmp/my-work.\X</p></td>
</tr>
<tr>
<td><p>\x</p></td>
<td><p>1 hexadecimal digit</p></td>
<td><p>/tmp/my-work.\x</p></td>
</tr>
<tr>
<td><p>\A</p></td>
<td><p>1 or more repetitions of alphabet characters</p></td>
<td><p>/var/log/my-work/\$-\A-\$.log</p></td>
</tr>
<tr>
<td><p>\a</p></td>
<td><p>1 alphabet character</p></td>
<td><p>/home/users/\a/\*/public_html/\*.html</p></td>
</tr>
<tr>
<td><p>\-</p></td>
<td><p>Pathname subtraction operator (negative match)</p></td>
<td>
<p>/\*\-proc\-sys</p>
<p>This will match /\* except "/proc" and "/sys".</p>
</td>
</tr>
<tr>
<td><p>/\{dir\}/</p></td>
<td><p>Recursive directory matching operator.</p>
<p>Matches "/" and 1 or more repetitions of "dir/".</p></td>
<td>
<p>/var/www/html/\{\*\}/\*.html</p>
<p>This will match all *.html files in subdirectories under /var/www/html/ directory. Note that /var/www/html/\*.html will not match.</p>
</td>
</tr>
<tr>
<td><p>/({dir\)/</p></td>
<td><p>Recursive directory matching operator.</p>
<p>Matches "/" and 0 or more repetitions of "dir/".</p></td>
<td>
<p>/var/www/html/\(\*\)/\*.html</p>
<p>This will match all *.html files under /var/www/html/ directory. Note that /var/www/html/\*.html will match.</p>
</td>
</tr>
</table>

<h4><a name="4.1.3">4.1.3. Grouping string arguments using string_group keyword.</a></h4>

<p>It is possible to define groups of string arguments using string_group keyword followed by $string_group_name and $string_group_member.</p>

<pre>
string_group TMPDIR /tmp
string_group TMPDIR /tmp/\(\*\)/\*
</pre>

<h4><a name="4.1.4">4.1.4. Example of conditions that use string arguments.</a></h4>

<p>When string argument is specified in condition part, it is quoted by " character in order to clarify that the argument is a string argument rather than name of variable.</p>

<table border="1">
<tr><td>Conditions example</td><td>Value of variable "path"</td><td>Comparison result</td></tr>
<tr><td rowspan="5">path="/tmp/\*"</td>
<td>/</td><td>Does not match</td></tr>
<tr><td>/tmp</td><td>Does not match</td></tr>
<tr><td>/tmp/</td><td>Matches</td></tr>
<tr><td>/tmp/rt6bh84t</td><td>Matches</td></tr>
<tr><td>/tmp/349gy08t/y8024fgf</td><td>Does not match</td></tr>
<tr><td rowspan="5">path!="/tmp/\*"</td>
<td>/</td><td>Matches</td></tr>
<tr><td>/tmp</td><td>Matches</td></tr>
<tr><td>/tmp/</td><td>Does not match</td></tr>
<tr><td>/tmp/rt6bh84t</td><td>Does not match</td></tr>
<tr><td>/tmp/349gy08t/y8024fgf</td><td>Matches</td></tr>
</table>

<p>When string_group argument is specified in condition part, it is prefixed by @ character in order to clarify that the argument is a string_group argument rather than name of variable.</p>

<table border="1">
<tr><td>Conditions example</td><td>Value of variable "path"</td><td>Values in TMPDIR group</td><td>Comparison result</td></tr>
<tr><td rowspan="4">path=@TMPDIR</td>
<td>/</td><td rowspan="4">/tmp<br>/tmp/\(\*\)/\*</td><td>Does not match</td></tr>
<tr><td>/tmp</td><td>Matches</td></tr>
<tr><td>/tmp/rt6bh84t</td><td>Matches</td></tr>
<tr><td>/tmp/349gy08t/y8024fgf</td><td>Matches</td></tr>
<tr><td rowspan="4">path!=@TMPDIR</td>
<td>/</td><td rowspan="4">/tmp<br>/tmp/\(\*\)/\*</td><td>Matches</td></tr>
<tr><td>/tmp</td><td>Does not match</td></tr>
<tr><td>/tmp/rt6bh84t</td><td>Does not match</td></tr>
<tr><td>/tmp/349gy08t/y8024fgf</td><td>Does not match</td></tr>
</table>

<p>List of name of variables which reference string data is explained later.</p>

<hr>
<h3><a name="4.2">4.2. Using numeric arguments in conditions</a></h3>

<p>Arguments such as user ID and process ID are handled as numeric argument.</p>

<h4><a name="4.2.1">4.2.1. About numeric argument representation rule</a></h4>

<p>Decimal form, octal form and hexadecimal form are supported. Octal form is prefixed with 0 and Hexadecimal form is prefixed with 0x. For example, 010 in octal form is equivalent with 8 in decimal form, 0x10 in hexadecimal form is equivalent with 16 in decimal form.</p>

<p>Since numeric data is handled using C language's "unsigned long" type, minimal value is 0 and maximal value is 0xFFFFFFFF (for 32 bit environments) or 0xFFFFFFFFFFFFFFFF (for 64 bit environments).</p>

<p>It is possible to specify numeric data ranges in $min_value-$max_value form. If specifying in range, $min_value has to be smaller or equals to $max_value. For example, 0-100 is valid but 100-0 is invalid.</p>

<p>Some examples are shown below.</p>

<pre>
0
100
0xFFFF
0777
500-1000
0x0-0xFFFFFFFF
00-07777
</pre>

<h4><a name="4.2.2">4.2.2. Grouping numeric arguments using number_group keyword.</a></h4>

<p>It is possible to define groups of numeric arguments using number_group keyword followed by $number_group_name and $number_group_member.</p>

<pre>
number_group ID_GROUP 100
number_group ID_GROUP 200-500
</pre>

<h4><a name="4.2.3">4.2.3. Example of conditions that use numeric arguments.</a></h4>

<p>Comparison with numeric value is defined as below.</p>

<table border="1">
<tr><td>Conditions example</td><td>Value of variable "task.uid"</td><td>Comparison result</td></tr>
<tr><td rowspan="3">task.uid=0</td>
<td>0</td><td>Matches</td></tr>
<tr><td>100</td><td>Does not match</td></tr>
<tr><td>500</td><td>Does not match</td></tr>
<tr><td rowspan="3">task.uid!=0</td>
<td>0</td><td>Does not match</td></tr>
<tr><td>100</td><td>Matches</td></tr>
<tr><td>500</td><td>Matches</td></tr>
</table>

<p>Comparison with numeric value range is defined as below.</p>

<table border="1">
<tr><td>Conditions example</td><td>Value of variable "task.gid"</td><td>Comparison result</td></tr>
<tr><td rowspan="3">task.gid=0-100</td>
<td>0</td><td>Matches</td></tr>
<tr><td>100</td><td>Matches</td></tr>
<tr><td>500</td><td>Does not match</td></tr>
<tr><td rowspan="3">task.gid!=0-100</td><td>0</td><td>Does not match</td></tr>
<tr><td>100</td><td>Does not match</td></tr>
<tr><td>500</td><td>Matches</td></tr>
</table>

<p>It is possible to compare one variable which references numeric value with another variable which references numeric value.</p>

<table border="1">
<tr><td>Conditions example</td><td>Value of variable "task.uid"</td><td>Value of variable "task.gid"</td><td>Comparison result</td></tr>
<tr><td rowspan="4">task.uid=task.gid</td>
<td>0</td><td>0</td><td>Matches</td></tr>
<tr><td>0</td><td>100</td><td>Does not match</td></tr>
<tr><td>100</td><td>0</td><td>Does not match</td></tr>
<tr><td>100</td><td>100</td><td>Matches</td></tr>
<tr><td rowspan="4">task.uid!=task.gid</td>
<td>0</td><td>0</td><td>Does not match</td></tr>
<tr><td>0</td><td>100</td><td>Matches</td></tr>
<tr><td>100</td><td>0</td><td>Matches</td></tr>
<tr><td>100</td><td>100</td><td>Does not match</td></tr>
</table>

<p>When number_group argument is specified in condition part, it is prefixed by @ character in order to clarify that the argument is a number_group argument rather than name of variable.</p>

<table border="1">
<tr><td>Conditions example</td><td>Value of variable "task.uid"</td><td>Values in ID_GROUP group</td><td>Comparison result</td></tr>
<tr><td rowspan="4">task.uid=@ID_GROUP</td>
<td>0</td><td rowspan="4">100<br>200-500</td><td>Does not match</td></tr>
<tr><td>100</td><td>Matches</td></tr>
<tr><td>500</td><td>Matches</td></tr>
<tr><td>1000</td><td>Does not match</td></tr>
<tr><td rowspan="4">task.uid!=@ID_GROUP</td>
<td>0</td><td rowspan="4">100<br>200-500</td><td>Matches</td></tr>
<tr><td>100</td><td>Does not match</td></tr>
<tr><td>500</td><td>Does not match</td></tr>
<tr><td>1000</td><td>Matches</td></tr>
</table>

<p>List of name of variables which reference numeric data is explained later.</p>

<hr>
<h3><a name="4.3">4.3. Using process's information in conditions</a></h3>

<p>By using current thread's attributes as part of conditions, you can write complicated access restriction rules.</p>

<h4><a name="4.3.1">4.3.1. About available variables</a></h4>

<p>Below variables are available for referring current thread's attributes.</p>

<table border="1">
<tr><td>Variable's name</td><td>Comparison method</td><td>Meaning</td><td></td></tr>
<tr><td>task.uid</td><td><a href="#4.2">Numeric</a></td><td>Current thread's user ID</td></tr>
<tr><td>task.gid</td><td><a href="#4.2">Numeric</a></td><td>Current thread's group ID</td></tr>
<tr><td>task.euid</td><td><a href="#4.2">Numeric</a></td><td>Current thread's effective user ID</td></tr>
<tr><td>task.egid</td><td><a href="#4.2">Numeric</a></td><td>Current thread's effective group ID</td></tr>
<tr><td>task.suid</td><td><a href="#4.2">Numeric</a></td><td>Current thread's saved user ID</td></tr>
<tr><td>task.sgid</td><td><a href="#4.2">Numeric</a></td><td>Current thread's saved group ID</td></tr>
<tr><td>task.fsuid</td><td><a href="#4.2">Numeric</a></td><td>Current thread's filesystem user ID</td></tr>
<tr><td>task.fsgid</td><td><a href="#4.2">Numeric</a></td><td>Current thread's filesystem group ID</td></tr>
<tr><td>task.pid</td><td><a href="#4.2">Numeric</a></td><td>Current thread's process ID </td></tr>
<tr><td>task.ppid</td><td><a href="#4.2">Numeric</a></td><td>Process ID of current thread's parent process</td></tr>
<tr><td>task.exe</td><td><a href="#4.1">String</a></td><td>Current thread's program name (the content of <code>/proc/self/exe</code>)</td></tr>
<tr><td>task.domain</td><td><a href="#4.1">String</a></td><td>Current thread's domainname (the content of <code>/proc/caitsith/self_domain</code>)</td></tr>
<tr><td>task.type</td><td>Literal</td><td>Matches execute_handler if running as an execute handler, does not match execute_handler otherwise</td></tr>
</table>

<p>Details of task.domain and task.type are explained later.</p>

<hr>
<h3><a name="4.4">4.4. Using IP address arguments in conditions</a></h3>

<p>Any operation which handles IPv4/IPv6 network address can check IP address.</p>

<h4><a name="4.4.1">4.4.1. About IP address argument representation rule</a></h4>

<p>It is possible to handle IPv4 address and IPv6 address. IPv4 address (32 bit) is represented using dot separated decimal form. and IPv6 address (128 bit) is represented using forms defined in RFC 2373.</p>

<p>It is possible to specify IP address ranges in $min_address-$max_address form. If specifying in range, $min_address has to be smaller or equals to $max_address. For example, 1.2.3.4-5.6.7.8 is valid but 5.6.7.8-1.2.3.4 is invalid.</p>

<p>Some examples are shown below.</p>

<pre>
127.0.0.1
10.0.0.0-10.255.255.255
::1
fd00::-fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
</pre>

<h4><a name="4.4.2">4.4.2. Grouping IP address arguments using ip_group keyword.</a></h4>

<p>It is possible to define groups of IP address arguments using ip_group keyword followed by $ip_group_name and $ip_group_member.</p>

<pre>
ip_group PRIVATE_ADDRESS 10.0.0.0-10.255.255.255
ip_group PRIVATE_ADDRESS 172.16.0.0-172.31.255.255
ip_group PRIVATE_ADDRESS 192.168.0.0-192.168.255.255
ip_group PRIVATE_ADDRESS fd00::-fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
</pre>

<h4><a name="4.4.3">4.4.3. Example of conditions that use IP address arguments.</a></h4>

<p>Comparison with IP address value is defined as below. Note that comparison between an IPv4 address and an IPv6 address does not match.</p>

<table border="1">
<tr><td>Conditions example</td><td>Value of variable "ip"</td><td>Comparison result</td></tr>
<tr><td rowspan="4">ip=127.0.0.1</td><td>127.0.0.1</td><td>Matches</td></tr>
<tr><td>0.0.0.0</td><td>Does not match</td></tr>
<tr><td>::1</td><td>Does not match</td></tr>
<tr><td>::ffff:127.0.0.1</td><td>Does not match</td></tr>
<tr><td rowspan="4">ip!=127.0.0.1</td><td>127.0.0.1</td><td>Does not match</td></tr>
<tr><td>0.0.0.0</td><td>Matches</td></tr>
<tr><td>::1</td><td>Does not match</td></tr>
<tr><td>::ffff:127.0.0.1</td><td>Does not match</td></tr>
<tr><td rowspan="4">ip=::1</td><td>127.0.0.1</td><td>Does not match</td></tr>
<tr><td>0.0.0.0</td><td>Does not match</td></tr>
<tr><td>::1</td><td>Matches</td></tr