4.6 Two Methods of Profiling

Given the syntax for AppArmor profiles in
Section 2.0, Profile Components and Syntax, you could create
profiles without using the tools. However, the effort involved would be
substantial. To avoid such a hassle, use the AppArmor tools
to automate the creation and refinement of profiles.

There are two ways to approach AppArmor profile creation.
Tools are available for both methods.

Stand-Alone Profiling

A method suitable for profiling small applications that have a finite
run time, such as user client applications like mail clients. For more
information, refer to
Section 4.6.1, Stand-Alone Profiling.

Systemic Profiling

A method suitable for profiling large numbers of programs all at once
and for profiling applications that may run for days, weeks, or
continuously across reboots, such as network server applications like
Web servers and mail servers. For more information, refer to
Section 4.6.2, Systemic Profiling.

Automated profile development becomes more manageable with the
AppArmor tools:

Decide which profiling method suits your needs.

Perform a static analysis. Run either aa-genprof or aa-autodep, depending
on the profiling method chosen.

4.6.1 Stand-Alone Profiling

Stand-alone profile generation and improvement is managed by a program
called aa-genprof. This method is easy because aa-genprof takes care of
everything, but is limited because it requires aa-genprof to run for the
entire duration of the test run of your program (you cannot reboot the
machine while you are still developing your profile).

4.6.2 Systemic Profiling

This method is called systemic profiling because it
updates all of the profiles on the system at once, rather than focusing on
the one or few targeted by aa-genprof or stand-alone profiling.
With systemic profiling, profile construction and improvement are somewhat
less automated, but more flexible. This method is suitable for
profiling long-running applications whose behavior continues after
rebooting or a large number of programs all at once.

Build an AppArmor profile for a group of applications
as follows:

Create profiles for the individual programs that make up your
application.

Although this approach is systemic, AppArmor only monitors those
programs with profiles and their children. To get AppArmor to
consider a program, you must at least have aa-autodep create an
approximate profile for it. To create this approximate profile, refer to
aa-autodep—Creating Approximate Profiles.

Put relevant profiles into learning or complain mode.

Activate learning or complain mode for all profiled programs by entering
aa-complain /etc/apparmor.d/* in a terminal window
while logged in as root. This functionality is also available
through the YaST Profile Mode module, described in Section 3.6.2, Changing the Mode of Individual Profiles.

When in learning mode, access requests are not blocked even if the
profile dictates that they should be. This enables you to run through
several tests (as shown in
Step 3) and learn the access
needs of the program so it runs properly. With this information, you can
decide how secure to make the profile.

Run your application and exercise its functionality. How much to
exercise the program is up to you, but you need the program to access
each file representing its access needs. Because the execution is not
being supervised by aa-genprof, this step can go on for days or weeks
and can span complete system reboots.

Analyze the log.

In systemic profiling, run aa-logprof directly instead of letting
aa-genprof run it (as in stand-alone profiling). The general form of
aa-logprof is:

This generates optimum profiles. An iterative approach captures
smaller data sets that can be trained and reloaded into the policy
engine. Subsequent iterations generate fewer messages and run
faster.

Edit the profiles.

You might want to review the profiles that have been generated. You can
open and edit the profiles in /etc/apparmor.d/
using vim.

Return to enforce mode.

This is when the system goes back to enforcing the rules of the
profiles, not just logging information. This can be done manually by
removing the flags=(complain) text from the profiles
or automatically by using the aa-enforce command,
which works identically to the aa-complain command,
except it sets the profiles to enforce mode. This functionality is also
available through the YaST Profile Mode module, described in Section 3.6.2, Changing the Mode of Individual Profiles.

To ensure that all profiles are taken out of complain mode and put into
enforce mode, enter aa-enforce /etc/apparmor.d/*.

Rescan all profiles.

To have AppArmor rescan all of the profiles and change the enforcement mode
in the kernel, enter rcapparmor restart.

4.6.3 Summary of Profiling Tools

All of the AppArmor profiling utilities are provided by the
apparmor-utils RPM package and are stored
in /usr/sbin. Each tool has a different purpose.

aa-autodep—Creating Approximate Profiles

This creates an approximate profile for the program or application
selected. You can generate approximate profiles for binary executables and
interpreted script programs. The resulting profile is called
approximate because it does not necessarily contain all of
the profile entries that the program needs to be properly confined by
AppArmor. The minimum aa-autodep approximate profile has at least a base
include directive, which contains basic profile entries needed by most
programs. For certain types of programs, aa-autodep generates a more
expanded profile. The profile is generated by recursively calling
ldd(1) on the executables listed on the command line.

To generate an approximate profile, use the aa-autodep program. The
program argument can be either the simple name of the program, which
aa-autodep finds by searching your shell's path variable, or it can be a
fully qualified path. The program itself can be of any type (ELF binary,
shell script, Perl script, etc.). aa-autodep generates an approximate
profile to improve through the dynamic profiling that follows.

The resulting approximate profile is written to the
/etc/apparmor.d directory using the AppArmor profile
naming convention of naming the profile after the absolute path of the
program, replacing the forward slash (/) characters in
the path with period (.) characters. The general form
of aa-autodep is to enter the following in a terminal window when logged
in as root:

aa-autodep [ -d /path/to/profiles ] [program1program2...]

If you do not enter the program name or names, you are prompted for them.
/path/to/profiles overrides the default
location of /etc/apparmor.d, should you keep profiles
in a location other than the default.

To begin profiling, you must create profiles for each main executable
service that is part of your application (anything that might start
without being a child of another program that already has a profile).
Finding all such programs depends on the application in question.
Here are several strategies for finding such programs:

Directories

If all the programs to profile are in one directory and
there are no other programs in that directory, the simple command
aa-autodep
/path/to/your/programs/* creates
basic profiles for all programs in that directory.

ps command

You can run your application and use the standard Linux
ps command to find all processes running. Then
manually hunt down the location of these programs and run the
aa-autodep for each one. If the programs are in your
path, aa-autodep finds them for you. If they are not in your path, the
standard Linux command find might be helpful in
finding your programs. Execute find / -name
'my_application' -print to
determine an application's path
(my_application being an example
application). You may use wild cards if appropriate.

aa-complain—Entering Complain or Learning Mode

The complain or learning mode tool (aa-complain) detects violations of
AppArmor profile rules, such as the profiled program accessing files not
permitted by the profile. The violations are permitted, but also logged.
To improve the profile, turn complain mode on, run the program through a
suite of tests to generate log events that characterize the program's
access needs, then postprocess the log with the AppArmor tools to transform
log events into improved profiles.

Manually activating complain mode (using the command line) adds a
flag to the top of the profile so that /bin/foo
becomes /bin/foo flags=(complain). To use complain
mode, open a terminal window and enter one of the following lines as
root:

If the example program (program1) is in your
path, use:

aa-complain [program1program2 ...]

If the program is not in your path, specify the entire path as
follows:

aa-complain /sbin/program1

If the profiles are not in /etc/apparmor.d, use
the following to override the default location:

aa-complain /path/to/profiles/program1

Specify the profile for program1 as
follows:

aa-complain /etc/apparmor.d/sbin.program1

Each of the above commands activates the complain mode for the profiles or
programs listed. If the program name does not include its entire path,
aa-complain searches $PATH for the program. For
instance, aa-complain /usr/sbin/* finds profiles
associated with all of the programs in /usr/sbin and
puts them into complain mode. aa-complain
/etc/apparmor.d/* puts all of the profiles in
/etc/apparmor.d into complain mode.

aa-enforce—Entering Enforce Mode

The enforce mode detects violations of AppArmor profile
rules, such as the profiled program accessing files not permitted by the
profile. The violations are logged and not permitted.
The default is for enforce mode to be enabled. To log the violations
only, but still permit them, use complain mode. Enforce toggles with
complain mode.

Manually activating enforce mode (using the command line) adds a flag to
the top of the profile so that /bin/foo becomes
/bin/foo flags=(enforce). To use enforce mode, open a
terminal window and enter one of the following lines as root.

If the example program (program1) is in your
path, use:

aa-enforce [program1program2 ...]

If the program is not in your path, specify the entire path, as
follows:

aa-enforce /sbin/program1

If the profiles are not in /etc/apparmor.d,
use the following to override the default location:

aa-enforce /path/to/profiles/program1

Specify the profile for program1 as follows:

aa-enforce /etc/apparmor.d/sbin.program1

Each of the above commands activates the enforce mode for the
profiles and programs listed.

If you do not enter the program or profile names, you are prompted to
enter one. /path/to/profiles overrides the
default location of /etc/apparmor.d.

The argument can be either a list of programs or a list of profiles. If
the program name does not include its entire path, aa-enforce searches
$PATH for the program.

aa-genprof—Generating Profiles

aa-genprof is AppArmor's profile generating utility. It
runs aa-autodep on the specified program, creating an approximate profile
(if a profile does not already exist for it), sets it to complain mode,
reloads it into AppArmor, marks the log, and prompts the user to execute
the program and exercise its functionality. Its syntax is as follows:

aa-genprof [ -d /path/to/profiles ] program

To create a profile for the the Apache Web server program
httpd2-prefork, do the following as root:

Enter rcapache2 stop.

Next, enter aa-genprof httpd2-prefork.

Now aa-genprof does the following:

Resolves the full path of httpd2-prefork using your shell's path
variables. You can also specify a full path. On openSUSE, the default full path is
/usr/sbin/httpd2-prefork.

When prompted by the tool, run the application to profile in
another terminal window and perform as many of the application
functions as possible. Thus, the learning mode can log the files and
directories to which the program requires access in order to function
properly. For example, in a new terminal window, enter
rcapache2 start.

Select from the following options that are available in the aa-logprof
terminal window after you have executed the program function:

S runs aa-logprof on the system log from where
it was marked when aa-genprof was started and reloads the profile. If
system events exist in the log, AppArmor parses the learning mode log
files. This generates a series of questions that you must answer to
guide aa-genprof in generating the security profile.

A resource is requested by a profiled program that is not in the
profile (see Example 4-1).

A program is executed by the profiled program and the security
domain transition has not been defined (see Example 4-2).

Each of these categories results in a series of questions that you must
answer to add the resource or program to the profile. Example 4-1 and Example 4-2 provide examples of each one. Subsequent steps
describe your options in answering these questions.

Dealing with execute accesses is complex. You must decide how to proceed
with this entry regarding which execute permission type to grant to this
entry:

The child inherits the parent's profile, running with the same access
controls as the parent. This mode is useful when a confined program
needs to call another confined program without gaining the
permissions of the target's profile or losing the permissions of the
current profile. This mode is often used when the child program is a
helper application, such as the
/usr/bin/mail client using less
as a
pager or the Mozilla* Web browser using Adobe Acrobat* to display
PDF files.

Profile (px)

The child runs using its own profile, which must be loaded into the
kernel. If the profile is not present, attempts to execute the child
fail with permission denied. This is most useful if the parent
program is invoking a global service, such as DNS lookups or sending
mail with your system's MTA.

Choose the profile with clean exec (Px) option to
scrub the environment of environment variables that could modify
execution behavior when passed to the child process.

Unconfined (ux)

The child runs completely unconfined without any AppArmor profile applied
to the executed resource.

Choose the unconfined with clean exec (Ux) option
to scrub the environment of environment variables that could modify
execution behavior when passed to the child process. This option
introduces a security vulnerability that could be used to exploit
AppArmor. Only use it as a last resort.

mmap (m)

This permission denotes that the program running under the
profile can access the resource using the mmap system call with the
flag PROT_EXEC. This means that the data mapped in it can
be executed. You are prompted to include this permission if it is
requested during a profiling run.

Deny

Prevents the program from accessing the specified directory path
entries. AppArmor then continues to the next event.

AppArmor provides one or more paths or includes. By entering the option
number, select the desired options then proceed to the next
step.

NOTE:
All of these options are not always presented in the AppArmor menu.

#include

This is the section of an AppArmor profile that refers to
an include file, which procures access permissions for programs. By
using an include, you can give the program access to directory paths
or files that are also required by other programs. Using includes
can reduce the size of a profile. It is good practice to select
includes when suggested.

This is the literal path to which the program needs access so that
it can run properly.

After you select the path or include,
process it as an entry into the AppArmor profile by
selecting Allow or Deny. If you
are not satisfied with the directory path entry as it is displayed, you
can also Glob it.

The following options are available to process the learning mode
entries and build the profile:

Prevents the program from accessing the specified directory path
entries. AppArmor then continues to the next event.

New

Prompts you to enter your own rule for this event, allowing you
to specify a regular expression. If the
expression does not actually satisfy the event that
prompted the question in the first place, AppArmor
asks for confirmation and lets you reenter the expression.

Glob

Select a specific path or create a general rule using wild
cards that match a broader set of paths. To select any of
the offered paths, enter the number that is printed in front of
the path then decide how to proceed with the selected
item.

This modifies the original directory path while retaining
the filename extension. For example,
/etc/apache2/file.ext becomes
/etc/apache2/*.ext, adding the wild card
(asterisk) in place of the filename. This allows the program to
access all files in the suggested directory that end with the
.ext extension.

Closes aa-logprof, saving all rule changes entered so far and
modifying all profiles.

To view and edit your profile using vim, enter vim
/etc/apparmor.d/profilename in a
terminal window.

Restart AppArmor and reload the profile set including the newly created
one using the rcapparmor restart
command.

Like the graphical front-end for building AppArmor profiles, the YaST
Add Profile Wizard, aa-genprof also supports the use of the local profile
repository under
/etc/apparmor/profiles/extras and the remote AppArmor profile
repository.

To use a profile from the local repository, proceed as
follows:

Start aa-genprof as described above.

If aa-genprof finds an inactive local profile, the following lines
appear on your terminal window:

If you want to just use this profile, hit U
(Use Profile) and follow the profile generation
procedure outlined above.

If you want to examine the profile before activating it, hit
V (View Profile).

If you want to ignore the existing profile, hit C
(Create New Profile) and follow the profile
generation procedure outlined above to create the profile from
scratch.

Leave aa-genprof by hitting F
(Finish) when you are done and save the
profile.

If you opted for uploading your profile, provide a short change
log and push it to the repository.

aa-logprof—Scanning the System Log

aa-logprof is an interactive tool used to review the learning or complain
mode output found in the log entries in
/var/log/audit/audit.log or
/var/log/messages (if auditd is not running) and
generate new entries in AppArmor security profiles.

When you run aa-logprof, it begins to scan the log files produced in
learning or complain mode and, if there are new security events that are
not covered by the existing profile set, it gives
suggestions for modifying the profile. The learning or complain mode
traces program behavior and enters it in the log. aa-logprof uses this
information to observe program behavior.

If a confined program forks and executes another program, aa-logprof sees
this and asks the user which execution mode should be used when launching
the child process. The execution modes ix,
px, Px, ux,
and Ux are options for starting the child process. If
a separate profile exists for the child process, the default selection is
px. If one does not exist, the profile defaults to
ix. Child processes with separate profiles have
aa-autodep run on them and are loaded into AppArmor, if it is running.

When aa-logprof exits, profiles are updated with the changes. If the
AppArmor module is running, the updated profiles are reloaded and, if
any processes that generated security events are still running in the
null-complain-profile, those processes are set to run under their
proper profiles.

To run aa-logprof, enter aa-logprof into a terminal
window while logged in as root. The following options can be used
for aa-logprof:

aa-logprof -d /path/to/profile/directory/

Specifies the full path to the location of the profiles if the
profiles are not located in the standard directory,
/etc/apparmor.d/.

aa-logprof -f /path/to/logfile/

Specifies the full path to the location of the log file if the log file
is not located in the default directory,
/var/log/audit/audit.log or
/var/log/messages (if auditd is not running).

aa-logprof -m "string marker in logfile"

Marks the starting point for aa-logprof to look in the system log.
aa-logprof ignores all events in the system log before the specified
mark. If the mark contains spaces, it must be surrounded by
quotes to work correctly. For example:

aa-logprof -m"17:04:21"

or

logprof -m e2ff78636296f16d0b5301209a04430d

aa-logprof scans the log, asking you how to handle each logged event. Each
question presents a numbered list of AppArmor rules that can be added by
pressing the number of the item on the list.

By default, aa-logprof looks for profiles in
/etc/apparmor.d/ and scans the log in
/var/log/messages. In many cases, running
aa-logprof as root is enough to create the
profile.

However, there might be times when you need to search archived log files,
such as if the program exercise period exceeds the log rotation window
(when the log file is archived and a new log file is
started). If this is the case, you can enter
zcat -f `ls -1tr /var/log/messages*` | aa-logprof -f -.

aa-logprof Example 1

The following is an example of how aa-logprof addresses httpd2-prefork
accessing the file /etc/group. []
indicates the default option.

In this example, the access to /etc/group is part of
httpd2-prefork accessing name services. The appropriate response is
1, which includes a predefined set of AppArmor rules.
Selecting 1 to #include the name
service package resolves all of the future questions pertaining to DNS
lookups and also makes the profile less brittle in that any changes to
DNS configuration and the associated name service profile package can be
made just once, rather than needing to revise many profiles.

Prevents the program from accessing the specified directory path
entries. AppArmor then continues to the next event.

New

Prompts you to enter your own rule for this event, allowing you to
specify whatever form of regular expression you want. If the
expression entered does not actually satisfy the event that
prompted the question in the first place, AppArmor asks
for confirmation and lets you reenter the expression.

Glob

Select either a specific path or create a general rule using wild
cards that matches on a broader set of paths. To select any of
the offered paths, enter the number that is printed in front of
the paths then decide how to proceed with the selected
item.

This modifies the original directory path while retaining
the filename extension. For example,
/etc/apache2/file.ext becomes
/etc/apache2/*.ext, adding the wild card
(asterisk) in place of the filename. This allows the program to
access all files in the suggested directory that end with the
.ext extension.

aa-logprof Example 2

Several items of interest appear in this question. First, note that
vsftpd is asking for a path entry at the top of the tree, even though
vsftpd on openSUSE serves FTP files from
/srv/ftp by default. This is because httpd2-prefork
uses chroot and, for the portion of the code inside the chroot jail, AppArmor
sees file accesses in terms of the chroot environment rather than the
global absolute path.

The second item of interest is that you might want to grant FTP read
access to all JPEG files in the directory, so you could use
Glob w/Ext and use the suggested path of
/*.jpg. Doing so collapses all previous rules granting
access to individual .jpg files and forestalls any
future questions pertaining to access to .jpg files.

Finally, you might want to grant more general access to FTP files. If you
select Glob in the last entry, aa-logprof replaces the
suggested path of /y2k.jpg with
/*. Alternatively, you might want to grant even
more access to the entire directory tree, in which case you could use the
New path option and enter /**.jpg
(which would grant access to all .jpg files in the
entire directory tree) or /** (which would grant
access to all files in the directory tree).

These items deal with read accesses. Write accesses are similar, except
that it is good policy to be more conservative in your use of regular
expressions for write accesses. Dealing with execute accesses is more
complex. Find an example in Example 4-1.

In the following example, the /usr/bin/mail mail
client is being profiled and aa-logprof has
discovered that /usr/bin/mail executes
/usr/bin/less as a helper
application to page long mail messages. Consequently, it
presents this prompt:

HINT:
The actual executable file for /usr/bin/mail turns
out to be /usr/bin/nail, which is not a
typographical error.

The program /usr/bin/less appears to be a simple one
for scrolling through text that is more than one screen long and that is
in fact what /usr/bin/mail is using it for. However,
less is actually a large and powerful program that makes use of many
other helper applications, such as tar and rpm.

HINT:
Run less on a tar file or an RPM file and it shows
you the
inventory of these containers.

You do not want to run rpm automatically when reading
mail
messages (that leads directly to a Microsoft* Outlook–style virus
attack,
because rpm has the power to install and modify system programs),
so, in this case, the best choice is to use Inherit.
This results in the less program executed from this context running under
the profile for /usr/bin/mail. This has two
consequences:

You need to add all of the basic file accesses for
/usr/bin/less to the profile for
/usr/bin/mail.

You can avoid adding the helper applications, such as tar and rpm, to
the /usr/bin/mail profile so that when
/usr/bin/mail runs
/usr/bin/less in this context, the less
program is far less dangerous than it would be without AppArmor protection.

In other circumstances, you might instead want to use the
Profile option. This has two effects on aa-logprof:

The rule written into the profile uses px, which forces the transition
to the child's own profile.

aa-logprof constructs a profile for the child and starts building it,
in the same way that it built the parent profile, by assigning
events for the child process to the child's profile and asking
the aa-logprof user questions.

If a confined program forks and executes another program, aa-logprof
sees this and asks the user which execution mode should be used when
launching the child process. The execution modes of inherit, profile,
unconfined or an option to deny the execution are presented.

If a separate profile exists for the child process, the default
selection is profile. If a profile does not exist, the default is inherit.
The inherit option, or ix, is described in Section 2.1.3, File Permission Access Modes.

The profile option indicates that the child program should run in its
own profile—a secondary question asks whether to sanitize the
environment that the child program inherits from the parent. If you choose
to sanitize the environment, this places the execution modifier
Px in your AppArmor profile. If you select not to sanitize,
px is placed in the profile and no environment
sanitizing occurs. The default for the execution mode is
px if you select profile execution mode.

The unconfined execution mode is not recommended and should only be
used in cases where there is no other option to generate a profile for a
program reliably. Selecting unconfined opens a warning dialog asking for
confirmation of the choice. If you are sure and choose
Yes, a second dialog ask whether to sanitize the
environment. Choosing Yes uses the execution mode
Ux in your profile. Choosing No uses
the execution mode ux for your profile. The default
value selected is Ux for unconfined execution mode.

IMPORTANT: Running Unconfined

Choosing ux is very dangerous and provides no
enforcement of policy from a security perspective of resulting execution
behavior of the child program.

aa-unconfined—Identifying Unprotected Processes

The aa-unconfined command examines open network ports
on your system, compares that to the set of profiles loaded on your
system, and reports network services that do not have AppArmor profiles. It
requires root privileges and that it not be confined by an AppArmor
profile.

aa-unconfined must be run as root to retrieve the process executable
link from the /proc file system. This program is
susceptible to the following race conditions:

An unlinked executable is mishandled

A process that dies between netstat(8) and
further checks is mishandled

NOTE:
This program lists processes using TCP and UDP only. In short, this
program is unsuitable for forensics use and is provided only as an
aid to profiling all network-accessible processes in the lab.