The SELinux Documentation Project [Request for topics]

The SELinux Documentation Project [Request for topics]

[Joshua Brindle]

As we discussed at Linux Plumbers Conference during the 'Making SELinux 
Easier to Use" talk we have some document deficiencies in the SELinux 
project.

I volunteered to start an SELinux Documentation Project. The primary 
purpose of the project would be to get as much documentation as possible 
on the selinuxproject.org wiki, organized in a fashion that users can 
understand and consume easily.

As I admitted before, we, the developers, are not always the best people 
to judge what documentation users need and therefore am requesting 
users, hopefully from different backgrounds and environments, tell us 
what documentation they feel is lacking, what questions they've been 
asked or have asked themselves and couldn't find documentation for.

I think we need basic documentation that tells about SELinux (both 
beginner and advanced), howto's for specific things (using secmark, 
using netlabel, etc) and a set of short 'recipes' to accomplish simple 
tasks.

There are documents all over the place with various information, as well 
as blog entries and mailing list archives but the effort here is to 
consolidate all those resources onto selinuxproject.org.

I'd also like to see volunteers in the community to help out with the 
documentation effort, I know quite a few people already write things 
like this on blogs, etc and it would be great to see that information 
moved/copied onto selinuxproject.org.


Users:

Please, if you are a user and have run in to lack of documentation 
respond to this thread, or privately if you aren't comfortable talking 
on list so that we can collect what the biggest deficiencies are and get 
to writing documentation as soon as possible.


Thanks.

--
This message was distributed to subscribers of the selinux mailing list.
If you no longer wish to subscribe, send mail to majordomo@tycho.nsa.gov with
the words "unsubscribe selinux" without quotes as the message.

Re: The SELinux Documentation Project

[Joshua Brindle]

Joshua Brindle wrote:
> As we discussed at Linux Plumbers Conference during the 'Making SELinux
> Easier to Use" talk we have some document deficiencies in the SELinux
> project.
>

<snip>

We have gotten some good contributions to the documentation project over 
the last couple months but there is always more to do. I've updated the 
Documentation TODO at:

<http://selinuxproject.org/page/Documentation_TODO>

with some docs we'd like written and some guidance on what the format 
should be. Use cases would be particularly appreciated.

If you haven't gone to the documentation wiki lately take a look at

<http://selinuxproject.org/page/Main_Page>

and see what's been added.

Thanks for the help of the contributors and hopefully this effort will 
go a long way toward gaining users and keeping SELinux enabled.

--
This message was distributed to subscribers of the selinux mailing list.
If you no longer wish to subscribe, send mail to majordomo@tycho.nsa.gov with
the words "unsubscribe selinux" without quotes as the message.

Re: The SELinux Documentation Project

[Dominick Grift]

[-- Attachment #1.1: Type: text/plain, Size: 1279 bytes --]

On 11/27/2009 09:31 PM, Joshua Brindle wrote:
> Joshua Brindle wrote:
>> As we discussed at Linux Plumbers Conference during the 'Making SELinux
>> Easier to Use" talk we have some document deficiencies in the SELinux
>> project.
>>
> 
> <snip>
> 
> We have gotten some good contributions to the documentation project over
> the last couple months but there is always more to do. I've updated the
> Documentation TODO at:
> 
> <http://selinuxproject.org/page/Documentation_TODO>
> 
> with some docs we'd like written and some guidance on what the format
> should be. Use cases would be particularly appreciated.
> 
> If you haven't gone to the documentation wiki lately take a look at
> 
> <http://selinuxproject.org/page/Main_Page>
> 
> and see what's been added.
> 
> Thanks for the help of the contributors and hopefully this effort will
> go a long way toward gaining users and keeping SELinux enabled.
> 
> -- 
> fedora-selinux-list mailing list
> fedora-selinux-list@redhat.com
> https://www.redhat.com/mailman/listinfo/fedora-selinux-list

Attached is a concept i wrote today about Locking down webapps with CGI.
This was a topic in the todo list.

Would be nice if someone could proof-read this and when
modified/accepted publish it.

[-- Attachment #1.2: Locking_down_webapps_by_using_CGI.txt --]
[-- Type: text/plain, Size: 9087 bytes --]

Locking down webapps by using CGI's (or FastCGI), separating CGI's from each other, user CGI's from system CGI's, etc 

CGI web applications operate in a seperate process. This enables us to implement SELinux policy for the process. By default two CGI web application domains are provided, additionally SElinux policy API's can be used to create new CGI webapplication domains.

The system CGI web application domain is the default CGI web application domain for system scripts. This means that if you have configured Apache to support CGI and you copy a CGI script into the default system wide location for Apache CGI web applications, usually /var/www/cgi-bin, that the script inherits the CGI web application executable type for the parent directory cgi-bin and that when Apache executes te script that the CGI web application will run in this system cgi script domain. The advantage of this domain is that the script does not have to operate with the permissions of the Apache webserver and that the CGI webapp cannot, to an extend, affect the Apache server or vice versa.

The system cgi webapp domain includes serveral types and booleans that can be used in different scenarios.

httpd_sys_script_exec_t: The system CGI web application executable file type.
I mentioned that CGI scripts that are copied to the default system CGI bin inherit the type of the CGI bin directory. The type of this directory is httpd_sys_script_exec_t. When Apache runs a executable with this type it will cause the application that is executed to run in the httpd_sys_script_t domain. To enable this behaviour you must be sure that the httpd_builtin_scripting, and httpd_enable_cgi booleans are set to on. This can be verified and toggled using the semanage command with the boolean option, followed by the parameters.

httpd_sys_script_t: The system CGI web application domain type.
The httpd_sys_script_t type is the type of a system CGI web application process. This type is used to define specific permissions for interactions were the system CGI script is the source of an interaction. Policy where a specific domain type is the source type is also refered to as a domain. A domain specifies the permissions that a process has.

httpd_sys_content_t: The system web application content file type.
The system web application content file type is a type for files that can be read by the httpd_sys_script_t domain type. When a system CGI web application wants to read web content, than this content should be labeled with this type. When you copy web content in the default system web server root, usually /var/www, this content will automatically inherit this type from the parent directory.

httpd_sys_content_ra_t: The system web application ra content file type.
The system web application ra content file type is a type for files that can be read by and appended to by the httpd_sys_script_t domain type. This type may be useful when your CGI web application has a log file that is should not be in the main Apache log location, usually /var/log/httpd. This could be useful for virtual hosts where you do not want your customers to be able to access Apache server logs but do want to provide a means for system CGI web applications to log, and the logs be accessible by your customers. By default no location is specified for files with this type. You would manually label a file that you want your CGI web application to read from and append to with for example the chcon and semanage command.

httpd_sys_content_rw_t: The system web application rw content file type.
The system web application rw content file type is a type for file that can be created and be written to by the httpd_sys_script_t domain type. A CGI web application may need to create files or write files. This file type provides this functionality. By default no location is specified for files with this type. You would either manually label a file that you want you CGI web application to write to with for example the chcon and semanage command, or you would use te appropriate command to specify a location where a CGI web application should be able to create files in. 

For your CGI web application to be able to write to files with the httpd_sys_content_rw_t or create files with the httpd_sys_content_rw_t type you must also make sure that the allow_httpd_sys_script_anon_write is set to on. You can use the set- and getsebool commands to query and toggle booleans. The semanage command with boolean option provides similar functionality.

httpd_sys_htaccess_t: The system web application htaccess file type.
The systen web application htaccess file type is a type for files that can only be read by the httpd_t domain type. This type can be used to implement safe htaccess functionality for a system  CGI web application.

The labeling of the different files and locations can be done with the chcon and semanage command used together with the restorecon command. If you have a system web root in a location that is not standard, than you can use the semanage command with fcontext option to specify what contexts the locations should have. You can base these specifications on the specifications for the /var/www/ locations which can be queried using the semanage command with fcontext option and -l parameter. You can also use the equiv option to clone the file context specifications for a location easily. Make sure that you restore the context of the locations after you have specified new contexts. The semanage command expects file contexts to be specified using Bourne shell regular expressions. Keep this in mind when you want to add specification that are complex.

The use of the chcon command is not encouraged however this command can be useful when you do not have permission to use the semanage command.

I mentioned in the first paragraph of this article that there are two CGI web application domains provided. Besides the system CGI web application domain there is also a user CGI web application domain. This domain and its types is similar to that of the system CGI application domain. All classes of types can also be used for this domain only the name slightly differs (httpd_user_script_t instead of httpd_sys_script_t). This domain is used for the confinement of user CGI web applications for example when the Apache suexec and userdir functionality is enabled.

There are a few minor differences to discus. To enable the Apache userdir functionality you must make sure that the httpd_enable_userdirs boolean is set to on. Users do not have access to the semanage command to specify custom locations for web content. Instead the must use the chcon command. File contexts specified with the chcon command are usually not persistent. When the file system contexts are restored, contexts set using the chcon command will be resetted to system wide specification for that location. On some distributions httpd user content may be an exception to this rule when th types are defined to be customizable types. In this case the restorecon command will not try to reset these types.

You may ask yourself, what is all this complexity for? The answer is that it aims to provide integrity. If you have different CGI web applications hosted on your server, you may not want one to application to be able to affect another. This is a form of privilege escalation. A cracked CGI web application might affect other CGI web application hosted on the system or even the web server itself.

With this in mind it may also be a good idea to define additional CGI web application domain types for each system CGI web application you may run. A SELinux policy API can be used to quickly define a unique set of types for a domain that has the same properties as that of the system and user domain.

Here is an example of how you can create a new set of types to be used for a CGI webapplication called mywebapp:

echo "policy_module(mywebapp, 1.0.0)" > mywebapp.te;
echo "apache_content_template(mywebapp)" >> mywebapp.te;
make -f /usr/share/selinux/devel/Makefile mywebapp.pp
sudo semodule -i mywebapp.pp

This basically clones the CGI system script domain or CGI user script domain for our webapp. It creates unique types for us to use like:
httpd_mywebapp_script_exec_t, httpd_mywebapp_script_t, httpd_mywebapp_content_t, httpd_mywebapp_content_ra_t, httpd_mywebapp_content_rw_t, httpd_mywebapp_htaccess_t.
You can use the semanage command with fcontext option to specify contexts for the location of this particular CGI web application just like we did for the CGI system and user script domain above.

By using unique types for each CGI web application you help prevent privilege escalation and help maintain the integrity of your web applications.

In conclusion i would like to point you to some useful documentation that may assist you with the configuration of above:

Fedora 11 managing confined services
Fedora 11 SELinux user guide
man setsebool
man getsebool
man semanage
man restorecon
man chcon
man matchpathcon
man httpd_selinux



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 261 bytes --]

Re: The SELinux Documentation Project

[Joshua Brindle]

Dominick Grift wrote:
> On 11/27/2009 09:31 PM, Joshua Brindle wrote:
>> Joshua Brindle wrote:
>>> As we discussed at Linux Plumbers Conference during the 'Making SELinux
>>> Easier to Use" talk we have some document deficiencies in the SELinux
>>> project.
>>>
>> <snip>
>>
>> We have gotten some good contributions to the documentation project over
>> the last couple months but there is always more to do. I've updated the
>> Documentation TODO at:
>>
>> <http://selinuxproject.org/page/Documentation_TODO>
>>
>> with some docs we'd like written and some guidance on what the format
>> should be. Use cases would be particularly appreciated.
>>
>> If you haven't gone to the documentation wiki lately take a look at
>>
>> <http://selinuxproject.org/page/Main_Page>
>>
>> and see what's been added.
>>
>> Thanks for the help of the contributors and hopefully this effort will
>> go a long way toward gaining users and keeping SELinux enabled.
>>
>> --
>> fedora-selinux-list mailing list
>> fedora-selinux-list@redhat.com
>> https://www.redhat.com/mailman/listinfo/fedora-selinux-list
>
> Attached is a concept i wrote today about Locking down webapps with CGI.
> This was a topic in the todo list.
>
> Would be nice if someone could proof-read this and when
> modified/accepted publish it.

It's a wiki :) Just put it up there and others can make modifications. 
There are actually a couple people who are decent at copy editing that 
have done some work on the wiki so if we get technical content up there 
they can do what they do to clean it up.

--
This message was distributed to subscribers of the selinux mailing list.
If you no longer wish to subscribe, send mail to majordomo@tycho.nsa.gov with
the words "unsubscribe selinux" without quotes as the message.

Re: The SELinux Documentation Project

[Serge E. Hallyn]

Quoting Joshua Brindle (method@manicmethod.com):
> Dominick Grift wrote:
> >On 11/27/2009 09:31 PM, Joshua Brindle wrote:
> >>Joshua Brindle wrote:
> >>>As we discussed at Linux Plumbers Conference during the 'Making SELinux
> >>>Easier to Use" talk we have some document deficiencies in the SELinux
> >>>project.
> >>>
> >><snip>
> >>
> >>We have gotten some good contributions to the documentation project over
> >>the last couple months but there is always more to do. I've updated the
> >>Documentation TODO at:
> >>
> >><http://selinuxproject.org/page/Documentation_TODO>
> >>
> >>with some docs we'd like written and some guidance on what the format
> >>should be. Use cases would be particularly appreciated.
> >>
> >>If you haven't gone to the documentation wiki lately take a look at
> >>
> >><http://selinuxproject.org/page/Main_Page>
> >>
> >>and see what's been added.
> >>
> >>Thanks for the help of the contributors and hopefully this effort will
> >>go a long way toward gaining users and keeping SELinux enabled.
> >>
> >>--
> >>fedora-selinux-list mailing list
> >>fedora-selinux-list@redhat.com
> >>https://www.redhat.com/mailman/listinfo/fedora-selinux-list
> >
> >Attached is a concept i wrote today about Locking down webapps with CGI.
> >This was a topic in the todo list.
> >
> >Would be nice if someone could proof-read this and when
> >modified/accepted publish it.
> 
> It's a wiki :) Just put it up there and others can make

How are we to create an account to edit a page?  The 'Log in/Create
Account' page doesn't seem to let me create an account?

I'd like to add the recipe

        useradd xa
	semanage user -a -R user_r xa
	semanage login -a -s xa xa

to lock user xa into its own selinux context to the recipes page.
If someone else is willing to post it, all the better.

> modifications. There are actually a couple people who are decent at
> copy editing that have done some work on the wiki so if we get
> technical content up there they can do what they do to clean it up.

thanks,
-serge

--
This message was distributed to subscribers of the selinux mailing list.
If you no longer wish to subscribe, send mail to majordomo@tycho.nsa.gov with
the words "unsubscribe selinux" without quotes as the message.