Project:SELinux/Reporting policy bugs

This guide helps users to create a properly filled out bug report for SELinux policy updates.

Introduction
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.

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 security policies, much attention goes into details, but also in the many eyes paradigm to validate if a policy fix is correct or not.

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.

Short version
When reporting SELinux policy fixes based on AVC denials,


 * 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.
 * 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.
 * 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.

About
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.

Structure the denials
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.

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.

Prepare for testing
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.

Report the application failure
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.

However, denials can be cosmetic, 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).

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.

The Gentoo Hardened SELinux Handbook 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  and only then log on as user(s) to reproduce your situation. There is also a Troubleshooting SELinux section that helps you identify common bottlenecks or issues while trying to get SELinux running on your system.

Acknowledgements
We would like to thank the following authors and editors for their contributions to this guide:


 * Sven Vermeulen