diff options
author | Sven Vermeulen <sven.vermeulen@siphos.be> | 2011-11-22 21:05:18 +0100 |
---|---|---|
committer | Sven Vermeulen <sven.vermeulen@siphos.be> | 2011-11-22 21:05:18 +0100 |
commit | cf4aaf2bf53d3dd358a54e3253796d23a0f33395 (patch) | |
tree | 8cf8d983cb799df47a29a920a88ac941892fdba1 | |
parent | Updating information on module policy development aspects (diff) | |
download | hardened-docs-cf4aaf2bf53d3dd358a54e3253796d23a0f33395.tar.gz hardened-docs-cf4aaf2bf53d3dd358a54e3253796d23a0f33395.tar.bz2 hardened-docs-cf4aaf2bf53d3dd358a54e3253796d23a0f33395.zip |
Adding SELinux bugreporting guide
-rw-r--r-- | xml/selinux-bugreporting.xml | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/xml/selinux-bugreporting.xml b/xml/selinux-bugreporting.xml new file mode 100644 index 0000000..bfc13ad --- /dev/null +++ b/xml/selinux-bugreporting.xml @@ -0,0 +1,171 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> +<!-- $Header$ --> + +<guide link="/proj/en/hardened/selinux-policy.xml" lang="en"> +<title>Gentoo Hardened SELinux Development Policy</title> + +<author title="Author"> + <mail link="swift"/> +</author> + +<abstract> +This guide helps users to create a properly filled out bug report for SELinux +policy updates. +</abstract> + +<!-- The content of this document is licensed under the CC-BY-SA license --> +<!-- See http://creativecommons.org/licenses/by-sa/2.5 --> +<license/> + +<version>1</version> +<date>2011-11-22</date> + +<chapter> +<title>So you got a bug?</title> +<section> +<title>Introduction</title> +<body> + +<p> +When working with a SELinux-enabled system, you will notice that some policies +are far from perfect. That is to be expected, since there are a lot more +policies and SELinux policy modules than we can thoroughly test. That is why bug +reports are very important for us as they give us much-needed feedback on the +state of the policies. Also, since we follow the reference policy closely, +patches are also sent upstream so that other distributions can benefit from the +updates. +</p> + +<p> +However, debugging and fixing SELinux policies also means that we need to +identify a proper policy failure, find the root cause of this failure and have +an optimal solution. Since we are talking about <e>security</e> policies, much +attention goes into details, but also in the <e>many eyes</e> paradigm to +validate if a policy fix is correct or not. +</p> + +<p> +That is one of the reasons why we created this bugreport as it helps you, as the +feedback-providing user, to both properly figure out why a failure occurs and +how to fix it, but also why we are quite strict in the acceptance of patches. +</p> + +</body> +</section> +<section> +<title>Short version</title> +<body> + +<p> +When reporting SELinux policy fixes based on AVC denials, +</p> + +<ul> + <li> + structure the denials and try to create one bug report per logically + coherent set of denials. Don't push all your AVC denials onto us. + </li> + <li> + make sure you can reproduce the issue and that you have the ability to + reproduce while we work on the fix. We cannot test all policies ourselves. + </li> + <li> + report the application failure output as well, not only the AVC denial. We + need to know what the application is trying to do (and failing to do) to fix + the problem. + </li> +</ul> + +</body> +</section> +</chapter> + +<chapter> +<title>Bugs related to AVC denials (and non-functional applications)</title> +<section> +<title>About</title> +<body> + +<p> +In this section, we'll go into the details of creating a helpful bug report for +SELinux policies in case you have an AVC denial (which means SELinux is +prohibiting a certain privilege request) that results in the failure of the +application. +</p> + +</body> +</section> +<section> +<title>Structure the denials</title> +<body> + +<p> +When you get one or more AVC denials, try to structure them into logically +coherent sets. We cannot easily deal with several dozen denials. Most of the +time, you either get multiple denials of the same cause, or the denials are not +truely related. +</p> + +<p> +When we need to fix the SELinux policy, nine out of ten times we focus on one or +a few related denials and come up with a proper fix. When there is an abundance +of AVC denials, we need to skim through them (which we usually then do one at a +time) which puts a lot of stress on you (the reporter) as we will ask you +hundred-and-one questions and requests for testing. +</p> + +</body> +</section> +<section> +<title>Prepare for testing</title> +<body> + +<p> +When you report a SELinux policy related bug, make sure you are ready to test +the results that we want to put in. We cannot test out all applications +ourselves. Sometimes, a failure is even only reproducable on a specific setup. +</p> + +</body> +</section> +<section> +<title>Report the application failure</title> +<body> + +<p> +More than once, we get bug reports on SELinux policy denials where the user is +still running in permissive mode. He is reporting the denials because he is +afraid that he will not be able to run it in enforcing mode without the denials +being fixed. +</p> + +<p> +However, denials can be <e>cosmetic</e>, in which case we should actually hide +the denials rather than allow their requests. Also, when you run in permissive +mode, it is very much possible that the denials would never be reached when +running in enforcing mode because of earlier denials (which, coincidentally, +might be wrongly hidden from your logs). +</p> + +<p> +For this reason, we urge you to give us not only the AVC denial information, but +also the application failure log output when running in enforcing mode. +</p> + +<p> +The <uri link="selinux/selinux-handbook.xml">Gentoo Hardened SELinux +Handbook</uri> will guide you through the process of migrating from a permissive +system into an enforcing mode. If you believe that booting in enforcing is not +possible yet, just boot in permissive, log on as root, run <c>setenforce 1</c> +and only then log on as user(s) to reproduce your situation. There is also a +<uri link="selinux/selinux-handbook.xml?part=2&chap=2">Troubleshooting +SELinux</uri> section that helps you identify common bottlenecks or issues while +trying to get SELinux running on your system. +</p> + +</body> +</section> +</chapter> + +</guide> |