Gentoo Hardened SELinux DevelopmentDealing with Mandatory Access Control is never easy. SELinux might be available by default with Linux, enabling it can provide serious headaches - let alone developing policies for it. Within Gentoo Hardened, we strive to offer a default policy that is flexible enough to match the requirements of most of you (our users) yet remain manageable by the limited number of developers that we have. To ensure that the policy we offer is up to date, we definitely need help from end users and other developers, because developing policies requires intimate knowledge of the products they are written for. With over several thousand packages, this is just not feasible for a handful of us. Hence, this Gentoo Hardened SELinux Development guide. Within this document, we will try to explain how to set up an environment ready to build policies yourself and provide patches to Gentoo Hardened. We also cover how to deal with malfunctioning domains and even how to create your own, new domains from scratch (if we need to). Further down, we give an overview of the guidelines that we try to follow during the policy developments and finally talk about how to properly create patches and submit them to our bugzilla service. For those who want to run Gentoo Hardened with their own policies, we've also added a chapter on just that. We know that our policy does not match everyone's requirements, so we definitely want to help you run your own too. This document is a must-read for everyone willing to provide patches or develop the Gentoo Hardened SELinux policies. Other SELinux advanced users might find this document interesting as well. This document does assume prior knowledge on SELinux policies and the way the reference policy works. For those that need a quick recap, here are the highlights...
2. Setting Up Your Environment Gentoo Hardened builds its policy upon the reference policy as provided by Tresys and managed through an active community. I suggest to use two workspaces when dealing with SELinux policies for Gentoo Hardened: the hardened one for the Gentoo patched policy, and a local one in which you work and make your patches in. Of course, using a source control system like git can be helpful too. For now, Gentoo Hardened doesn't have a git repository where its policies are based from (yet). That might sound a bit dull, but it forces the developers to remain as close to upstream as possible (and contribute the changes upstream too so that newer releases include them automatically). You can definitely use a source control system yourself - the only reason we do not use it in this document is that it is easier to document without ;-) Let's create the first workspace:
As result, you now have a subdirectory called refpolicy inside dev/hardened. This directory contains all the SELinux policy rules available. Now the dev/hardened workspace is patched with the Gentoo Hardened SELinux patches applicable to the policy. Gentoo Hardened has two "flavors" of patches:
When we develop changes on the SELinux policy, we currently try to put those changes in the patchbundle as soon as possible. Currently, the selinux-base-policy package is updated fast enough to hold off module patches and wait for a new release of selinux-base-policy (after which the SELinux modules themselves can just refer to the new base policy to get their patches). However, when the selinux-base-policy is more stable, then patches might be made part of the modules themselves. In that case, a module patch is made.
If you want to or need to work on the policy of a SELinux module (rather than the base policy), check its ebuild to see if it holds any additional patches (mentioned through the POLICY_PATCH variable). If not, then you can work off the snapshot taken earlier in this guide. However, if a patch (or set of patches) is applied as well, you either need to apply those manually on the snapshot, or use the following tactics to create a snapshot just for this module:
Setting up a local workspace (where we will create changes and generate patches out of later) is easy: just copy the dev/hardened one:
Navigating the policy workspace The main location you will work with is dev/hardened/refpolicy.local/policy/modules. This location is subdivided in categories:
The categorization is arbitrary and serves no purpose other than keeping the modules a but separated. Each module must have a unique name, regardless of the category! Inside the categories, the modules are available using their three files
To build a module, go to the location where the module code is. Then, run make with the development Makefile as provided by the reference policy.
You now have a portage.pp file available which you can load (using semodule -i portage.pp). If you want to build the base policy, run make base.
The result should be a base.pp file that you can load using semodule -b base.pp. However, if you intend to do a bit more than just test this base policy quickly, it is seriously recommended to create your own Gentoo overlay for your own selinux-base-policy and install that one as installing a base policy is not only about the policy module itself, but also about the include files that will then be stored in /usr/share/selinux/strict/include. 3. A Domain Does Not Function Properly The most likely problem that you are hitting is that a domain does exist in Gentoo Hardened SELinux, but that it isn't functioning as it should. To solve this problem, it is adviseable to use the following sequence of investigations:
Make sure that the problem you are seeing is a SELinux-triggered problem. An easy way to find out is to run SELinux in permissive mode and try again:
This only works if the problem is not to do with a SELinux-aware application (unlike init or sudo which are linked to the libselinux library). SELinux-aware applications might alter their behavior if SELinux is set on the system regardless of it running in permissive mode or not. A prime example is vixie-cron (as can be seen in bug #257111). But for applications that are not SELinux aware, this is the easiest method to find out if SELinux is to blame or not. If running your system in permissive mode works around the problem, read on. If it doesn't, check the regular permissions (strace'ing the application might be a good idea too). Assuming that we now know that SELinux is to blame, we need to make sure that we get the proper AVC denials. Either locate the proper denials in /var/log/avc.log (or audit.log) around the time that you encountered the issue, or run tail -f /var/log/avc.log and reproduce the problem.
Analyzing the meaning of the AVC denial is covered by Looking at the AVC Log in the Gentoo Hardened SELinux handbook. The denial should give you a pointer where to look for. However, it is possible that no denial is occurring, or at least no relevant ones. A first step to get potentially more denials is to switch the gentoo_try_dontaudit boolean off. This boolean is used by the Gentoo Hardened SELinux developers to hide denials which they assume are cosmetic. As these developers are known to have a human side (as well), they are known to make mistakes ;-)
Retry getting the proper AVC denials. If it still doesn't work, you can disable all dontaudit statements:
Retry getting the proper AVC denials. The moment you get the denials you are looking for, isolate them and then undo the changes you made earlier:
If you still do not see any denials, then check out the dmesg output for other problems. It is possible that SELinux is not even getting to the point of the policy, which you will not notice by looking at the AVC denials alone. However, the chance of this to happen is very slim - most of the time, you'll find the AVC denials you are looking for. Deducing the correct security contexts The next step is to see if we are dealing with the right security contexts. This does require a bit of insight in how both the application (that is failing) and the policy relate to each other. In essence, you want to make sure that the process is running in the right domain and is trying to work on the right target type. Say you are having issues with SELinux (re)labeling and you notice the following AVC denial:
In this case, setfiles is running in the sysadm_t domain even though it should run in setfiles_t. So check the security context of the setfiles binary as well as the transition rules:
In the above (forced) situation, the problem is with the security context of the binary - it should have been setfiles_exec_t instead of bin_t. Usually, entry points are named similarly (like portage_exec_t or sudo_exec_t). If you are not certain about which domain it should be, use sesearch
The sesearch utility is extremely powerful to query the SELinux policy (which is currently in memory). I also advise you to use the -C switch to see which rules are trigged by certain SELinux booleans:
In the above example, the named_t domain only has write privileges on files labeled named_zone_t if the named_write_master_zones boolean is set (which it currently isn't, otherwise the line would stat with ET instead of DT). To gain a bit of insight in the various, available domains, use seinfo:
To gain a bit of insight in the (current) file context rules, use semanage:
Most of the time, fixing domain issues is a matter of relabeling files (or updating the configuration to match the contexts already defined - both work). Intra-module permissions are missing It is possible that you get a denial between correct security contexts, but that the permission is just never granted. In this case, you can choose between two things:
In both cases you will need to edit the module files (most likely the .te file), build the module, load it, perhaps even relabel the files or the package and retry. It is also a good idea to take a look at upstream (latest refpolicy repository or the repositories of Fedora and co) and see if they have already solved this problem or not. Granting additional permissions between existing domains is the easiest, but might introduce additional problems: if this permission is only needed in a particular case yet you grant it for all files and resources related to those domains, then you are opening up the policy beyond what is necessary. Often, creating an additional domain or type can be beneficial. A noticeable example is Portage' support for CVS/SVN/GIT ebuilds (the so-called live ebuilds). These ebuilds get their repository and store it in the distfiles/svn+src location, which was by default labeled portage_ebuild_t with only read-access for the portage_sandbox_t domain. However, with those live ebuilds, the portage_sandbox_t domain also needs write privileges to this location. Rather than allowing portage_sandbox_t write privileges to portage_ebuild_t, a new type was created called portage_svnsrc_t for just this location and the rights are transferred towards type. Inter-module permissions are needed If the solution for the problem requires permissions between modules, then you need to create the proper interface functions in the target domain and call these functions from the source domain. Interface functions are the APIs that a module provides towards other SELinux modules when they need to interact with the domains. For instance, the mysql module provides, amongst other functions, the mysql_stream_connect interface:
The interface declares that the domain passed on as its first (and only) argument gets the rights offered by stream_connect_pattern, which is a macro (defined in policy/support/ipc_patterns.spt that looks like so:
Modules that need to interact with MySQL through a Unix domain stream socket (/var/run/mysqld/mysqld.sock) will need the proper permissions to work with the target type (mysqld_var_run_t). Modules cannot just set allow statements towards mysqld_var_run_t as they do not know this type. Instead, they call the mysql_stream_connect interface, like the postfix.te file does:
If the change you need is adding existing interface calls to the module (in the .te file) then you should be able to test it easily by building the changed module and loading it. However, if you need to change the interface of your module itself (in the .if file) you will eventually need to rebuild the base policy and even provide and install a new sec-policy/selinux-base-policy package as the interfaces are placed in /usr/share/selinux/strict/include. This is one of the reasons why the sec-policy/selinux-base-policy package in Gentoo Hardened has a high revision number (and many updates). If you are facing problems because you run an application which has no domain itself (and hence is probably running in the user_t, staff_t or sysadm_t domains - or even tries to run in the initrc_t domain), you will need to create one. But before we do that, it might be possible that the application can work within the domain definition of a different application. One example here is lighttpd. This lightweight HTTPd service "uses" the definitions offered by the apache module. By marking its executable file httpd_exec_t it runs in the httpd_t domain and uses the same policy like Apache. By labeling the files according to the apache.fc definitions (but now for lighttpd) it might Just Work ™ Reusing existing domains requires that you at least consider the following aspects:
(Do Not) Copy from existing domains If reusing existing domains introduces too many risks, you'll need to create a new domain for the application. Many people would be inclined to copy the domain definition of a similar application and work from there. Although this is a viable approach, it is considered a bad practice because you start by providing privileges to the domain that are never needed, and removing privileges from a domain later is very difficult. Even more, if you are not the author of the modules, most developers will not even try to remove them as they assume that the author of the domain had a good reason to add it in the first place. This is one of the reasons why upstream takes great care in accepting patches - they must be properly documented before they are accepted. Instead, create a domain from scratch but take a close eye on the domain you belief is very similar. Issues that arise during the module development might be quickly resolved by looking at how the original domain is defined. To start the development of a new module from scratch, first identify the domain(s) you want to have. An application that, in its entire lifespan only constitutes of a single process, will most likely only have one domain. For instance, the Skype client will have just skype_t. However, applications that have multiple processes running might need multiple domains too. For instance, the Postfix application runs a master (postfix_master_t), queue manager (postfix_qmgr_t) and pickup service (postfix_pickup_t), but depending on the commands you execute, it will also have (short-lived) processes running as postfix_cleanup_t, postfix_bounce_t, etc.) It is considered a best practice to start with a fine-grained model for domains and only later decide if merging multiple domains into one is beneficial. Splitting domains later is more difficult. Don't forget to look at the client-side aspect too! Next, define the types that each domain interacts with. This of course includes the binary (like skype_exec_t) but do not forget resources like
Also, try to separate types that are used by other domains as well. This way, the other domains can only interact with those files or resources that are labeled accordingly, rather than interact with a broad spectrum of files. The distinction that the apache module makes between system-provided content (like phpmyadmin files) and user-provided content (in the public_html directory in the users' home directories) seems (and is) very logical, but one could wrongly say that for Apache itself, the access controls are the same. Although that might be true, both types are clearly used in different ways so this mandates the use of different domains. Once you have defined those types too, start writing down the intra-domain permissions. Right now is a good time to look at other modules to see how they do things. Start with defining the accesses towards the domains.
This small snippet defines many things. The first two lines just mention the new types (the spamassassin_t domain and spamassassin_exec_t type). The application_domain interface marks spamassassin_t as an application domain type (it gets the application_domain_type and domain attributes and a few default permissions (like allowing that it sends SIGCHLD and SIGNULL to init). It also marks spamassassin_exec_t as an applications' executable type (application_exec_type and exec_type attributes) so that it can be executed by regular users (these domains have execute rights against all resources that have the application_exec_type attribute set. Finally, it marks the spamassassin_t domain as a constrained domain for user-based access controls. In other words, if SELinux users user_u and staff_u launch the application in spamassassin_t domains, then the domains are segregated from each other (the intra-domain rules inside spamassassin_t are only valid for communication within the same SELinux user, not between SELinux users). Attributes are an important aspect in SELinux policy development. They make managing the domains easier, but you should always consider the implications when you add an attribute to one of your types. It usually means that a whole lot of permissions are suddenly granted between other domains and yours. Next, set the proper intra-domain permissions. For instance, allow your domain to read its configuration files as well as more access inside its own /var/lib location:
The majority of work in developing SELinux policy modules is using and choosing the right interfaces. Having a few functions available to browse through all the available information is always interesting, so you might want to use the following function definitions (definitely not mandatory - this is only to help people skim through the policy definitions):
These functions can then be used to find the information / interfaces you are looking for. For instance, you need the application to read the postfix configuration files:
Same thing if you want to look for the correct macro definition (usually, if you notice something but you cannot find it as an interface, then it is most likely a macro):
As we strive to bring most of our patches upstream, please do consider the contribution guidelines of the reference policy project. The project has a documented style guide, naming convention and an online API reference (for the various interfaces). Note that, the moment you create a new module, you'll need to create the proper role interfaces (if it is an application that is directly called from a user domain). Take a look at tvtime_role and how it is used in the staff.te and sysadm.te role definitions. When you test your application, test it in as many ways as possible. If your application is a command-line application, run it both from a regular terminal (tty) as well as a virtual one (in an xterm). See if it still works if you run it in a screen session. Try out all functions and features that the application supports. This rigorous testing is necessary because SELinux denies everything that isn't explicitly allowed. If you do not test certain features, chances are that the module does not provide the necessary permissions and as such, users will be impacted. To test out a new module, load it (semodule -i modulename.pp) and relabel the files affiliated with the application (either through rlpkg or using restorecon). Consider the following testing activities if applicable (not all domains are interactive domains, so please read the activities with your domain definition in mind):
When working on policy modules, you'll notice that the application is trying to do things which are denied, but have no obvious effect on the applications functionality. This is to be expected: many applications do not handle file descriptors properly (file descriptor leaks are common) or applications read attributes of files but don't do anything with it. You'll notice that you learn a lot from the application while writing its policy ;-) Gentoo Hardened's idea here is to only allow what is actually needed by the application. Cosmetic denials are to be dontaudit'ed. Gentoo Hardened uses the gentoo_try_dontaudit boolean for this:
Gentoo Hardened SELinux policy To streamline the policy development efforts, Gentoo Hardened as a SELinux Policy document explaining the principles used during policy development and the implementation guidelines we strive to follow during development. Such a policy is important because we want to have a consistent security policy that users and developers can relate to. By following the policy, we hope that other developers can quickly jump in and work on it further. If you are able to fix a problem by adding the proper file contexts (using semanage fcontext -a), please consider the following:
If you believe that the change is needed for everyone using Gentoo Hardened with SELinux, create a bugreport and assign it to selinux@gentoo.org. In the bugreport, mention the file context you think is necessary and why. Module patches with changes that are intra-module (and have no effect outside) are best generated from the policy/modules location:
Attach this patch to the bugreport explaining why it is needed. If you think the patch itself is not obvious, make sure that the necessary comments are in place inside the patch for future reference. Please have a separate patch file per module (do not combine multiple modules in a single patch). If a patch extends a single module, or it includes interface changes on a module, you'll need to create a patch for the base policy. In this case, the patch is best made from the upper location.
Attach this patch to the bugreport explaining why it is needed. If you think the patch itself is not obvious, make sure that the necessary comments are in place inside the patch for future reference. Please have a separate patch file per major change (do not combine multiple unrelated changes in a single patch). If you want to use your own policy rather than Gentoo's, we seriously recommend to use a local overlay which uses the same package names and constructs. This allows your policy to integrate properly with the other Gentoo packages (which might depend on the SELinux packages). For instance, when you install openldap, it will still properly depend on the sec-policy/selinux-ldap package even if you provide it completely. To do so, first create a local overlay and copy the content of the sec-policy category inside it.
Next, tell Portage to not synchronise the sec-policy category of the main tree anymore. To do so, create the file /etc/portage/rsync_excludes with the following content:
Finally, add your current overlay by editing /etc/make.conf:
From now onwards, Gentoo Portage will only use your local overlay (you can remove /usr/portage/sec-policy if you don't want Portage to even reuse the current set of packages. To create or update a module package, you can use the following skeleton for the ebuilds:
The patch(es) that you can put in the files/ location (and referred to in the POLICY_PATCH) should be made as defined earlier in this document. You can put multiple patches in this variable if you want. Don't forget to run repoman manifest with every change, and run repoman scan to check for potential mistakes. To provide updates on the base policy, it is recommended to keep all patches you made centrally in a directory (say dev/hardened/base-patches). When you want to create a new sec-policy/selinux-base-policy release, create a patchbundle from your patch directory, put the bundle in the files location, create the updated ebuild and try it out.
Don't forget to run repoman manifest and repoman scan. You can then install sec-policy/selinux-base-policy-2.20110726-r4 and test it out. The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply. |
|