mirrors/apparmor
1
0
Fork 0
mirror of https://gitlab.com/apparmor/apparmor.git synced 2025-03-04 08:24:42 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
apparmor/parser/apparmor.d.pod
John Johansen cd79c1ac77 update copyright dates
2007-04-11 08:12:51 +00:00

456 lines
15 KiB
Text
Raw Blame History

# $Id$
# ----------------------------------------------------------------------
# Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007
# NOVELL (All rights reserved)
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of version 2 of the GNU General Public
# License published by the Free Software Foundation.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, contact Novell, Inc.
# ----------------------------------------------------------------------
=pod
=head1 NAME
apparmor.d - syntax of security profiles for AppArmor.
=head1 DESCRIPTION
AppArmor profiles describe mandatory access rights granted to given
programs and are fed to the AppArmor policy enforcement module using
apparmor_parser(8). This man page describes the format of the AppArmor
configuration files; see apparmor(7) for an overview of AppArmor.
=head1 FORMAT
The following is a BNF-style description of AppArmor policy
configuration files; see below for an example AppArmor policy file.
AppArmor configuration files are line-oriented; B<#> introduces a
comment, similar to shell scripting languages. The exception to this
rule is that B<#include> will I<include> the contents of a file inline
to the policy; this behaviour is modelled after cpp(1).
=over 4
B<INCLUDE> = '#include' ( I<ABS PATH> | I<MAGIC PATH> )
B<ABS PATH> = '"' path '"' (the path is passed to open(2))
B<MAGIC PATH> = '<' relative path '>' (the path is relative to F</etc/apparmor.d/>)
B<COMMENT> = '#' I<TEXT>
B<TEXT> = any characters
B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] I<PROGRAM> [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> ) ... ] '}'
B<SUBPROFILE> = [ I<COMMENT> ... ] I<PROGRAMHAT> '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'
B<CAPABILITY> = (lowercase capability name without 'CAP_' prefix; see
capabilities(7))
B<PROGRAM> = (non-whitespace characters except for '^', must start with '/')
B<PROGRAMHAT> = '^' (non-whitespace characters; see change_hat(2) for a description of how this "hat" is used.)
B<RESOURCE RULE> = ( I<FILE RULE> | I<NETWORK RULE> ) ','
B<FILE RULE> = ( I<FILENAME> | I<FILEGLOB> ) I<ACCESS>
B<FILENAME> = (non-whitespace characters except for B<?*[]{}^>, must start with '/'. May include I<VARIABLE>.)
B<FILEGLOB> = (non-whitespace characters, must start with '/', B<?*[]{}^> have special meanings; see below. May include I<VARIABLE>.)
B<ACCESS> = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'm' ) [ I<ACCESS> ... ] (not all combinations are allowed; see below.)
B<VARIABLE> = '@{' I<ALPHA> [ I<ALPHANUMERIC> ... ] '}'
B<VARIABLE ASSIGNMENT> = I<VARIABLE> ('=' | '+=') (space separated values)
B<ALPHA> = ('a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
B<ALPHANUMERIC> = ('1', '2', '3', ... '9', 'a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
=back
All resources and programs need a full path. There may be any number
of subprofiles ("hats") in a profile, limited only by kernel memory.
Subprofile names are limited to 974 characters.
Not all profiles benefit from subprofiles
--- applications must either be written or modified to use change_hat(2)
to take advantage of subprofiles. (An Apache module, mod_apparmor(5)
has been provided to use change_hat(2).)
=head2 Access Modes
File permission access modes consists of combinations of the following
modes:
=over 8
=item B<r> - read
=item B<w> - write
=item B<ux> - unconstrained execute
=item B<Ux> - unconstrained execute -- scrub the environment
=item B<px> - discrete profile execute
=item B<Px> - discrete profile execute -- scrub the environment
=item B<ix> - inherit execute
=item B<m> - allow PROT_EXEC with mmap(2) calls
=item B<l> - link
=back
=head2 Access Modes Details
=over 4
=item B<r - Read mode>
Allows the program to have read access to the file. Read access is
required for shell scripts and other interpreted content, and determines
if an executing process can core dump or be attached to with ptrace(2).
(ptrace(2) is used by utilities such as strace(1), ltrace(1), and
gdb(1).)
=item B<w - Write mode>
Allows the program to have write access to the file. Files must have
this permission if they are to be unlinked (removed.)
=item B<ux - Unconstrained execute mode>
Allows the program to execute the program without any AppArmor profile
being applied to the program.
This mode is useful when a confined program needs to be able to perform
a privileged operation, such as rebooting the machine. By placing the
privileged section in another executable and granting unconstrained
execution rights, it is possible to bypass the mandatory constraints
imposed on all confined processes. For more information on what is
constrained, see the apparmor(7) man page.
B<WARNING> 'ux' should only be used in very special cases. It enables the
designated child processes to be run without any AppArmor protection.
'ux' does not scrub the environment of variables such as LD_PRELOAD;
as a result, the calling domain may have an undue amount of influence
over the callee. Use this mode only if the child absolutely must be
run unconfined and LD_PRELOAD must be used. Any profile using this mode
provides negligible security. Use at your own risk.
Incompatible with 'Ux', 'px', 'Px', 'ix'.
=item B<Ux - unconstrained execute -- scrub the environment>
'Ux' allows the named program to run in 'ux' mode, but AppArmor
will invoke the Linux Kernel's B<unsafe_exec> routines to scrub
the environment, similar to setuid programs. (See ld.so(8) for some
information on setuid/setgid environment scrubbing.)
B<WARNING> 'Ux' should only be used in very special cases. It enables the
designated child processes to be run without any AppArmor protection.
Use this mode only if the child absolutely must be run unconfined. Use
at your own risk.
Incompatible with 'ux', 'px', 'Px', 'ix'.
=item B<px - Discrete Profile execute mode>
This mode requires that a discrete security profile is defined for a
program executed and forces an AppArmor domain transition. If there is
no profile defined then the access will be denied.
B<WARNING> 'px' does not scrub the environment of variables such as
LD_PRELOAD; as a result, the calling domain may have an undue amount of
influence over the callee.
Incompatible with 'Ux', 'ux', 'Px', 'ix'.
=item B<Px - Discrete Profile execute mode -- scrub the environment>
'Px' allows the named program to run in 'px' mode, but AppArmor
will invoke the Linux Kernel's B<unsafe_exec> routines to scrub
the environment, similar to setuid programs. (See ld.so(8) for some
information on setuid/setgid environment scrubbing.)
Incompatible with 'Ux', 'ux', 'px', 'ix'.
=item B<ix - Inherit execute mode>
Prevent the normal AppArmor domain transition on execve(2) when the
profiled program executes the named program. Instead, the executed resource
will inherit the current profile.
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. There is no
version to scrub the environment because 'ix' executions don't change
privileges.
Incompatible with 'Ux', 'ux', 'Px', 'px'. Implies 'm'.
=item B<m - Allow executable mapping>
This mode allows a file to be mapped into memory using mmap(2)'s
PROT_EXEC flag. This flag marks the pages executable; it is used on some
architectures to provide non-executable data pages, which can complicate
exploit attempts. AppArmor uses this mode to limit which files a
well-behaved program (or all programs on architectures that enforce
non-executable memory access controls) may use as libraries, to limit
the effect of invalid B<-L> flags given to ld(1) and B<LD_PRELOAD>,
B<LD_LIBRARY_PATH>, given to ld.so(8).
=item B<l - Link mode>
Allows the program to be able to create a link with this name. When a
link is created, the file that is being linked to B<MUST> have the same
access permissions as the link being created (with the exception that
the destination does not have to have link access.)
=back
=head2 Comments
Comments start with # and may begin at any place within a line. The
comment ends when the line ends. This is the same comment style as
shell scripts.
=head2 Capabilities
The only capabilities a confined process may use may be enumerated; for
the complete list, please refer to capabilities(7). Note that granting
some capabilities renders AppArmor confinement for that domain advisory;
while open(2), read(2), write(2), etc., will still return error when
access is not granted, some capabilities allow loading kernel modules,
arbitrary access to IPC, ability to bypass discretionary access controls,
and other operations that are typically reserved for the root user.
The only operations that cannot be controlled in this manner are mount(2),
umount(2), and loading new AppArmor policy into the kernel, which are
always denied to confined processes.
=head2 Variables
AppArmor's policy language allows embedding variables into file rules
to enable easier configuration for some common (and pervasive) setups.
Variables may have multiple values assigned, but any variable assignments
must be made before the start of the profile.
The parser will automatically expand variables to include all values
that they have been assigned; it is an error to reference a variable
without setting at least one value.
At the time of this writing, only B<@{HOME}> and B<@{HOMEDIR}>
are defined in the AppArmor policy provided with SUSE Linux, in the
F</etc/apparmor.d/tunables/home> file; these variables are used in many
of the abstractions described later.
=head2 Globbing
File resources may be specified with a globbing syntax similar to that
used by popular shells, such as csh(1), bash(1), zsh(1).
=over 4
=item B<*>
can substitute for any number of characters, excepting '/'
=item B<**>
can substitute for any number of characters, including '/'
=item B<?>
can substitute for any single character excepting '/'
=item B<[abc]>
will substitute for the single character a, b, or c
=item B<[a-c]>
will substitute for the single character a, b, or c
=item B<{ab,cd}>
will expand to one rule to match ab, one rule to match cd
=back
=head2 #include mechanism
AppArmor provides an easy abstraction mechanism to group common file
access requirements; this abstraction is an extremely flexible way to
grant site-specific rights and makes writing new AppArmor profiles very
simple by assembling the needed building blocks for any given program.
The use of '#include' is modelled directly after cpp(1); its use will
replace the '#include' statement with the specified file's contents.
B<#include "/absolute/path"> specifies that F</absolute/path> should be
used. B<#include "relative/path"> specifies that F<relative/path> should
be used, where the path is relative to the current working directory.
B<#include E<lt>magic/pathE<gt>> is the most common usage; it will load
F<magic/path> relative to a directory specified to apparmor_parser(8).
F</etc/apparmor.d/> is the AppArmor default.
The supplied AppArmor profiles follow several conventions; the
abstractions stored in F</etc/apparmor.d/abstractions/> are some
large clusters that are used in most profiles. What follows are short
descriptions of how some of the abstractions are used.
=over 4
=item F<abstractions/audio>
Includes accesses to device files used for audio applications.
=item F<abstractions/authentication>
Includes access to files and services typically necessary for services
that perform user authentication.
=item F<abstractions/base>
Includes files that should be readable and writable in all profiles.
=item F<abstractions/bash>
Includes many files used by bash; useful for interactive shells and
programs that call system(3).
=item F<abstractions/consoles>
Includes read and write access to the device files controlling the
virtual console, sshd(8), xterm(1), etc. This abstraction is needed for
many programs that interact with users.
=item F<abstractions/fonts>
Includes access to fonts and the font libraries.
=item F<abstractions/gnome>
Includes read and write access to GNOME configuration files, as well as
read access to GNOME libraries.
=item F<abstractions/kde>
Includes read and write access to KDE configuration files, as well as
read access to KDE libraries.
=item F<abstractions/kerberosclient>
Includes file access rules needed for common kerberos clients.
=item F<abstractions/nameservice>
Includes file rules to allow DNS, LDAP, NIS, SMB, user and group password
databases, services, and protocols lookups.
=item F<abstractions/perl>
Includes read access to perl modules.
=item F<abstractions/user-download>
=item F<abstractions/user-mail>
=item F<abstractions/user-manpages>
=item F<abstractions/user-tmp>
=item F<abstractions/user-write>
Some profiles for typical "user" programs will use these include files
to describe rights that users have in the system.
=item F<abstractions/wutmp>
Includes write access to files used to maintain wtmp(5) and utmp(5)
databases, used with the w(1) and associated commands.
=item F<abstractions/X>
Includes read access to libraries, configuration files, X authentication
files, and the X socket.
=back
The abstractions stored in F</etc/apparmor.d/program-chunks/> are
intended for use by specific program suites, and are not generally
useful.
Some of the abstractions rely on variables that are set in files in the
F</etc/apparmor.d/tunables/> directory. These variables are currently
B<@{HOME}> and B<@{HOMEDIR}>. Variables cannot be set in profile scope;
they can only be set before the profile. Therefore, any profiles that
use abstractions should either B<#include E<lt>tunables/globalE<gt>> or
otherwise ensure that B<@{HOME}> and B<@{HOMEDIR}> are set before
starting the profile definition. The autodep(8) and genprof(8) utilities
will automatically emit B<#include E<lt>tunables/globalE<gt>> in
generated profiles.
=head1 EXAMPLE
An example AppArmor profile:
# a variable definition
@{HOME} = /home/*/ /root/
# a comment about foo.
/usr/bin/foo {
/bin/mount ux,
/dev/{,u}random r,
/etc/ld.so.cache r,
/etc/foo.conf r,
/etc/foo/* r,
/lib/ld-*.so* x,
/lib/lib*.so* r,
/proc/[0-9]** r,
/usr/lib/** r,
/tmp/foo.pid wr,
/tmp/foo.* lrw,
/@{HOME}/.foo_file rw,
# a comment about foo's subprofile, bar.
^bar {
/lib/ld-*.so* x,
/usr/bin/bar ix,
/var/spool/* rwl,
}
}
=head1 FILES
=over 4
=item F</etc/init.d/boot.apparmor>
=item F</etc/apparmor.d/>
=back
=head1 SEE ALSO
apparmor(7), apparmor_parser(8), complain(1),
enforce(1), change_hat(2), mod_apparmor(5), and
L<http://forge.novell.com/modules/xfmod/project/?apparmor>.
=cut
Reference in a new issue View git blame Copy permalink