Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to SUSE Linux Enterprise Server 11 SP4

25 Profiling Your Web Applications Using ChangeHat

A AppArmor® profile represents the security policy for an individual program instance or process. It applies to an executable program, but if a portion of the program needs different access permissions than other portions, the program can change hats to use a different security context, distinctive from the access of the main program. This is known as a hat or subprofile.

ChangeHat enables programs to change to or from a hat within a AppArmor profile. It enables you to define security at a finer level than the process. This feature requires that each application be made ChangeHat aware, meaning that it is modified to make a request to the AppArmor module to switch security domains at arbitrary times during the application execution. Two examples for ChangeHat-aware applications are the Apache Web server and Tomcat.

A profile can have an arbitrary number of subprofiles, but there are only two levels: a subprofile cannot have further sub-subprofiles. A subprofile is written as a separate profile and named as the containing profile followed by the subprofile name, separated by a ^. Subprofiles must be stored in the same file as the parent profile.

Note that the security of hats is considerably weaker than that of full profiles. That is to say, if attackers can find just the right kind of bug in a program, they may be able to escape from a hat into the containing profile. This is because the security of hats is determined by a secret key handled by the containing process, and the code running in the hat must not have access to the key. Thus change_hat is most useful in conjunction with application servers, where a language interpreter (such as PERL, PHP, or Java) is isolating pieces of code such that they do not have direct access to the memory of the containing process.

The rest of this chapter describes using change_hat in conjunction with Apache, to contain Web server components run using mod_perl and mod_php. Similar approaches can be used with any application server by providing an application module similar to the mod_apparmor described next in Section 25.2.2, “Location and Directory Directives”.

Note
Note: For More Information

For more information, see the change_hat man page.

25.1 Apache ChangeHat

AppArmor provides a mod_apparmor module (package apache2-mod-apparmor) for the Apache program (only included in SUSE Linux Enterprise Server). This module makes the Apache Web server ChangeHat aware. Install it along with Apache.

When Apache is ChangeHat aware, it checks for the following customized AppArmor security profiles in the order given for every URI request that it receives.

  • URI-specific hat. For example, ^phpsysinfo/templates/classic/images/bar_left.gif

  • DEFAULT_URI

  • HANDLING_UNTRUSTED_INPUT

Note
Note: Apache Configuration

If you install apache2-mod-apparmor, make sure the module gets loaded in Apache by executing the following command:

a2enmod apparmor

25.1.1 Managing ChangeHat-Aware Applications

As with most of the AppArmor tools, you can use two methods for managing ChangeHat, YaST or the command line interface. Managing ChangeHat-aware applications from the command line is much more flexible, but the process is also more complicated. Both methods allow you to manage the hats for your application and populate them with profile entries.

The following steps are a demonstration that adds hats to an Apache profile using YaST. In the Add Profile Wizard, the AppArmor profiling utilities prompt you to create new hats for distinct URI requests. Choosing to create a new hat allows you to create individual profiles for each URI. You can create very tight rules for each request.

If the URI that is processed does not represent significant processing or otherwise does not represent a significant security risk, safely select Use Default Hat to process this URI in the default hat, which is the default security profile.

This example creates a new hat for the URI phpsysinfo and its subsequent accesses. Using the profiling utilities, delegate what to add to this new hat. The resulting hat becomes a tight-security container that encompasses all the processing on the server that occurs when the phpsysinfo URI is passed to the Apache Web server.

The URI runs the application phpsysinfo (refer to http://phpsysinfo.sourceforge.net for more information). The phpsysinfo package is assumed to be installed in /srv/www/htdocs/phpsysinfo in a clean (new) installation of SUSE Linux Enterprise Server and AppArmor.

  1. Once phpsysinfo is installed, you are ready to add hats to the Apache profile. From the AppArmor GUI, select Add Profile Wizard.

  2. In Application to Profile, enter httpd2-prefork.

  3. Click Create Profile.

    Add Profile Wizard
  4. Restart Apache by entering rcapache2 restart in a terminal window.

    Restart any program you are profiling at this point.

  5. Open http://localhost/phpsysinfo/ in a Web browser window. The browser window should display network usage and system information.

    Note
    Note: Data Caching

    To ensure that this request is processed by the server and you do not review cached data in your browser, refresh the page. To do this, click the browser Refresh button to make sure that Apache processes the request for the phpsysinfo URI.

  6. Click Scan System Log for Entries to Add to Profiles. AppArmor launches the aa-logprof tool, which scans the information learned in the previous step. It begins to prompt you with profile questions.

  7. aa-logprof first prompts with Add Requested Hat or Use Default Hat because it noticed that the phpsysinfo URI was accessed. Select Add Requested Hat.

  8. Click Allow.

    Choosing Add Requested Hat in the previous step creates a new hat in the profile and specifies that the results of subsequent questions about the script's actions are added to the newly created hat rather than the default hat for this application.

    In the next screen, AppArmor displays an external program that the script executed. You can specify that the program should run confined by the phpsysinfo hat (choose Inherit), confined by a separate profile (choose Profile), or that it should run unconfined or without any security profile (choose Unconfined). For the case of the Profile option, a new profile is created for the program if one does not already exist.

    Note
    Note: Security Considerations

    Selecting Unconfined can create a significant security hole and should be done with caution.

    1. Select Inherit for the /bin/bash path. This adds /bin/bash (accessed by Apache) to the phpsysinfo hat profile with the necessary permissions.

    2. Click Allow.

  9. The remaining questions prompt you to generate new hats and add entries to your profile and its hats. The process of adding entries to profiles is covered in detail in the Section 23.1, “Adding a Profile Using the Wizard”.

    When all profiling questions are answered, click Finish to save your changes and exit the wizard.

The following is an example phpsysinfo hat.

Example 25.1: Example phpsysinfo Hat
/usr/sbin/httpd2-prefork {
  ...
  ^phpsysinfo {
    #include <abstractions/bash>
    #include <abstractions/nameservice>

    /bin/basename                        ixr,
    /bin/bash                            ixr,
    /bin/df                              ixr,
    /bin/grep                            ixr,
    /bin/mount                           Ux,
    /bin/sed                             ixr,
    /dev/bus/usb/                        r,
    /dev/bus/usb/**                      r,
    /dev/null                            w,
    /dev/tty                             rw,
    /dev/urandom                         r,
    /etc/SuSE-release                    r,
    /etc/ld.so.cache                     r,
    /etc/lsb-release                     r,
    /etc/lsb-release.d/                  r,
    /lib/ld-2.6.1.so                     ixr,
    /proc/**                             r,
    /sbin/lspci                          ixr,
    /srv/www/htdocs/phpsysinfo/**        r,
    /sys/bus/pci/**                      r,
    /sys/bus/scsi/devices/               r,
    /sys/devices/**                      r,
    /usr/bin/cut                         ixr,
    /usr/bin/getopt                      ixr,
    /usr/bin/head                        ixr,
    /usr/bin/lsb_release                 ixr,
    /usr/bin/lsscsi                      ixr,
    /usr/bin/tr                          ixr,
    /usr/bin/who                         ixr,
    /usr/lib/lib*so*                     mr,
    /usr/lib/locale/**                   r,
    /usr/sbin/lsusb                      ixr,
    /usr/share/locale/**                 r,
    /usr/share/pci.ids                   r,
    /usr/share/usb.ids                   r,
    /var/log/apache2/access_log          w,
    /var/run/utmp                        kr,
   }
}
Note
Note: Hat and Parent Profile Relationship

The profile ^phpsysinfo is only valid in the context of a process running under the parent profile httpd2-prefork.

25.1.2 Adding Hats and Entries to Hats

When you use the Edit Profile dialog (for instructions, refer to Section 23.3, “Editing Profiles”) or when you add a new profile using Manually Add Profile (for instructions, refer to Section 23.2, “Manually Adding a Profile”), you are given the option of adding hats (subprofiles) to your AppArmor profiles. Add a ChangeHat subprofile from the AppArmor Profile Dialog window as in the following.

AppArmor profile dialog
  1. From the AppArmor Profile Dialog window, click Add Entry then select Hat. The Enter Hat Name dialog box opens:

    Enter hat name
  2. Enter the name of the hat to add to the AppArmor profile. The name is the URI that, when accessed, receives the permissions set in the hat.

  3. Click Create Hat. You are returned to the AppArmor Profile Dialog screen.

  4. After adding the new hat, click Done.

Note
Note: For More Information

For an example of an AppArmor profile, refer to Example 25.1, “Example phpsysinfo Hat”.

25.2 Configuring Apache for mod_apparmor

Apache is configured by placing directives in plain text configuration files. The main configuration file is usually httpd.conf. When you compile Apache, you can indicate the location of this file. Directives can be placed in any of these configuration files to alter the way Apache behaves. When you make changes to the main configuration files, you need to start or restart Apache, so the changes are recognized.

25.2.1 Virtual Host Directives

Virtual host directives control whether requests that contain trailing pathname information following an actual filename (or that refer to a nonexistent file in an existing directory) are accepted or rejected. For Apache documentation on virtual host directives, refer to http://httpd.apache.org/docs-2.2/mod/core.html#virtualhost.

The ChangeHat-specific configuration keyword is AADefaultHatName. It is used similarly to AAHatName, for example, AADefaultHatName My_Funky_Default_Hat.

The configuration option is actually based on a server directive, which enables you to use the keyword outside of other options, setting it for the default server. Virtual hosts are considered internally within Apache to be separate servers, so you can set a default hat name for the default server as well as one for each virtual host, if desired.

When a request comes in, the following steps reflect the sequence in which mod_apparmor attempts to apply hats.

  1. A location or directory hat as specified by the AAHatName keyword

  2. A hat named by the entire URI path

  3. A default server hat as specified by the AADefaultHatName keyword

  4. DEFAULT_URI (if none of those exist, it goes back to the parent Apache hat)

25.2.2 Location and Directory Directives

Location and directory directives specify hat names in the program configuration file so the program calls the hat regarding its security. For Apache, you can find documentation about the location and directory directives at http://httpd.apache.org/docs-2.2/sections.html.

The location directive example below specifies that, for a given location, mod_apparmor should use a specific hat:

<Location /foo/> AAHatName MY_HAT_NAME </Location>

This tries to use MY_HAT_NAME for any URI beginning with /foo/ (/foo/, /foo/bar, /foo/cgi/path/blah_blah/blah, etc.).

The directory directive works similarly to the location directive, except it refers to a path in the file system as in the following example:

<Directory "/srv/www/www.immunix.com/docs"> 
  # Note lack of trailing slash 
  AAHatName immunix.com 
</Directory>

Example:  The program phpsysinfo is used to illustrate a location directive in the following example. The tarball can be downloaded from http://phpsysinfo.sourceforge.net.

  1. After downloading the tarball, install it into /srv/www/htdocs/phpsysinfo.

  2. Create /etc/apache2/conf.d/phpsysinfo.conf and add the following text to it:

    <Location "/phpsysinfo"> 
      AAHatName phpsysinfo
    </Location>

    The following hat should then work for phpsysinfo:

    /usr/sbin/httpd2-prefork {
      ...
      ^phpsysinfo {
        #include <abstractions/bash>
        #include <abstractions/nameservice>
    
        /bin/basename                        ixr,
        /bin/bash                            ixr,
        /bin/df                              ixr,
        /bin/grep                            ixr,
        /bin/mount                           Ux,
        /bin/sed                             ixr,
        /dev/bus/usb/                        r,
        /dev/bus/usb/**                      r,
        /dev/null                            w,
        /dev/tty                             rw,
        /dev/urandom                         r,
        /etc/SuSE-release                    r,
        /etc/ld.so.cache                     r,
        /etc/lsb-release                     r,
        /etc/lsb-release.d/                  r,
        /lib/ld-2.6.1.so                     ixr,
        /proc/**                             r,
        /sbin/lspci                          ixr,
        /srv/www/htdocs/phpsysinfo/**        r,
        /sys/bus/pci/**                      r,
        /sys/bus/scsi/devices/               r,
        /sys/devices/**                      r,
        /usr/bin/cut                         ixr,
        /usr/bin/getopt                      ixr,
        /usr/bin/head                        ixr,
        /usr/bin/lsb_release                 ixr,
        /usr/bin/lsscsi                      ixr,
        /usr/bin/tr                          ixr,
        /usr/bin/who                         ixr,
        /usr/lib/lib*so*                     mr,
        /usr/lib/locale/**                   r,
        /usr/sbin/lsusb                      ixr,
        /usr/share/locale/**                 r,
        /usr/share/pci.ids                   r,
        /usr/share/usb.ids                   r,
        /var/log/apache2/access_log          w,
        /var/run/utmp                        kr,
       }
    }
  3. Reload AppArmor profiles by entering rcapparmor restart at a terminal window as root.

  4. Restart Apache by entering rcapache2 restart at a terminal window as root.

  5. Enter http://hostname/phpsysinfo/ into a browser to receive the system information that phpsysinfo delivers.

  6. Locate configuration errors by going to /var/log/audit/audit.log or running dmesg and looking for any rejections in the output.

Print this page