This directory contains the functional test suite for the LSM-based SELinux security module. Please refer to the test report available in doc/tests for complete documentation for this test suite. This README only covers a subset of that report, specifically the sections on running the tests and adding new tests. PREREQUISITES ------------- Kernel Configuration -------------------- Your kernel should have been built with the following options to test SELinux: # Minimal dependencies. CONFIG_AUDIT=y CONFIG_NET=y CONFIG_INET=y CONFIG_SECURITY=y CONFIG_SECURITY_NETWORK=y CONFIG_SECURITY_NETWORK_XFRM=y CONFIG_SECURITY_SELINUX=y CONFIG_NETLABEL=y CONFIG_IP_NF_SECURITY=m CONFIG_INET_XFRM_MODE_TRANSPORT=m CONFIG_NETWORK_SECMARK=y CONFIG_NF_CONNTRACK_SECMARK=y CONFIG_NETFILTER_XT_TARGET_CONNSECMARK=m CONFIG_NETFILTER_XT_TARGET_SECMARK=m # Filesystem security labeling support. # Only need to enable the ones for the filesystems on which you are testing. # reiserfs is not supported. CONFIG_EXT2_FS_SECURITY=y CONFIG_EXT3_FS_SECURITY=y CONFIG_EXT4_FS_SECURITY=y CONFIG_JFS_SECURITY=y CONFIG_XFS_SECURITY=y CONFIG_JFFS2_FS_SECURITY=y Do not set CONFIG_SECURITY_SELINUX_POLICYDB_VERSION_MAX; it is an option for legacy distributions (Fedora 3 and 4). Otherwise, you should not enable any other security modules in your kernel configuration unless you use the security= option to select a module at boot time. Only one primary security module may be active at a time. Userland and Base Policy ------------------------ The testsuite has the following userspace dependencies on Fedora or RHEL beyond a minimal install: perl-Test # test harness used by the testsuite perl-Test-Harness # test harness used by the testsuite perl-Test-Simple # for Test::More selinux-policy-devel # to build the test policy gcc # to build the test programs libselinux-devel # to build some of the test programs net-tools # for ifconfig, used by capable_net/test netlabel_tools # to load NetLabel configuration during inet_socket tests iptables # to load iptables SECMARK rules during inet_socket tests yum install perl-Test perl-Test-Harness perl-Test-Simple selinux-policy-devel gcc libselinux-devel net-tools netlabel_tools iptables The testsuite requires a pre-existing base policy configuration of SELinux, using either the old example policy or the reference policy as the baseline. It also requires the core SELinux userland packages (libsepol, checkpolicy, libselinux, policycoreutils, and if using modular policy, libsemanage) to be installed. The test scripts also rely upon the SELinux extensions being integrated into the coreutils package, with support for the chcon and runcon commands as well as the SELinux options to existing utilities such as ls and mkdir. If the base distribution does not include the SELinux userland, then the source code for the core SELinux userland packages can be obtained from: https://github.com/SELinuxProject/selinux/wiki/Releases If the base distribution does not include a policy configuration, then the reference policy can be obtained from: https://github.com/TresysTechnology/refpolicy/wiki/DownloadRelease RUNNING THE TESTS ----------------- Create a shell with the unconfined_r or sysadm_r role and the Linux superuser identity, e.g.: newrole -r sysadm_r # -strict or -mls policy only su Check whether the SELinux kernel is in enforcing mode by running 'getenforce'. If it is in permissive mode, toggle it into enforcing mode by running 'setenforce 1'. Ensure that expand-check = 0 in /etc/selinux/semanage.conf; if not, edit it accordingly. To run the test suite, you can just do a 'make test' from the top-level directory or you can follow these broken-out steps: 1) Load the test policy configuration as follows: make -C policy load 2) Build and run the test suite from the tests subdirectory as follows: make -C tests test 3) Unload the test policy configuration as follows: make -C policy unload The broken-out steps allow you to run the tests multiple times without loading policy each time. 4) Review the test results. As each test script is run, the name of the script will be displayed followed by a status. After running all of the test scripts, a summary of the test results will be displayed. If all tests were successful, something similar to the following summary will be displayed (the specific numbers will vary): All tests successful. Files=7, Tests=16, 2 wallclock secs ( 0.17 cusr + 0.12 csys = 0.29 CPU) Otherwise, if one or more tests failed, the script will report statistics on the number of tests that succeeded and will include a table summarizing which tests had failed. The output will be similar to the following text, which shows that a total of three tests have failed: Failed Test Status Wstat Total Fail Failed List of failed ------------------------------------------------------------------------------- entrypoint/test 2 1 50.00% 1 inherit/test 3 2 66.67% 1-2 Failed 2/7 test scripts, 71.43% okay. 3/16 subtests failed, 81.25% okay. make: *** [test] Error 255 You can also run individual test scripts by hand, e.g. running ./entrypoint/test, to see the raw output of the test script. This is particularly useful if a particular test within a given script fails in order to help identify the cause. When run by hand, the test script displays the expected number of tests, a status for each test, and any error messages from the test script or its helper programs. Please report any failures to the selinux@tycho.nsa.gov mailing list, including a copy of the test summary output, the raw output from test scripts that failed, a description of your base platform, and the particular release of SELinux that you are using. ADDING NEW TESTS ---------------- The functional test suite is not yet complete, so we still need additional tests to be written. See the test report for the current coverage. To add a new test, create a new test policy file and a new test script. The new test policy file should be added to the policy directory and should contain a set of test domains and types specifically designed for the test. For the test script, create a new subdirectory in the tests subdirectory, populate it with at least a Makefile and a test perl script and add it to the SUBDIRS definition in the Makefile file. The Makefile must contain 'all' and 'clean' targets, even if they are empty, to support the build system. The test script must run with no arguments and must comply with the perl automated test format. The simplest way to comply with the Perl automated test format is to use the Perl Test module. To do this, first include the following statement at the top of the test Perl script: use Test; Next, include a declaration that specifies how many tests the script will run; the statement to include will be similar to: BEGIN { plan tests => 2} # run two tests You can then use the 'ok' subroutine to print results ok(1); # success ok(0); # failure ok(0,1); # failure, got '0', expected '1' ok($results, 0); # success if $results == 0, failure otherwise Standard error is ignored. In general, the scripts need to know where they are located so that they can avoid hard-coded paths. Use the following line of Perl to establish a base directory (based on the path of the script executable). This won't always be accurate, but will work for this test harness/configuration. $basedir = $0; $basedir =~ s|(.*)/[^/]*|$1|;