1
# ----------------------------------------------------------------------
2
# Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
4
# NOVELL (All rights reserved)
6
# Copyright (c) 2010 - 2012
7
# Canonical Ltd. (All rights reserved)
9
# This program is free software; you can redistribute it and/or
10
# modify it under the terms of version 2 of the GNU General Public
11
# License published by the Free Software Foundation.
13
# This program is distributed in the hope that it will be useful,
14
# but WITHOUT ANY WARRANTY; without even the implied warranty of
15
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16
# GNU General Public License for more details.
18
# You should have received a copy of the GNU General Public License
19
# along with this program; if not, contact Novell, Inc or Canonical
21
# ----------------------------------------------------------------------
27
apparmor.d - syntax of security profiles for AppArmor.
31
AppArmor profiles describe mandatory access rights granted to given
32
programs and are fed to the AppArmor policy enforcement module using
33
apparmor_parser(8). This man page describes the format of the AppArmor
34
configuration files; see apparmor(7) for an overview of AppArmor.
38
The following is a BNF-style description of AppArmor policy
39
configuration files; see below for an example AppArmor policy file.
40
AppArmor configuration files are line-oriented; B<#> introduces a
41
comment, similar to shell scripting languages. The exception to this
42
rule is that B<#include> will I<include> the contents of a file inline
43
to the policy; this behaviour is modelled after cpp(1).
47
B<INCLUDE> = '#include' ( I<ABS PATH> | I<MAGIC PATH> )
49
B<ABS PATH> = '"' path '"' (the path is passed to open(2))
51
B<MAGIC PATH> = '<' relative path '>' (the path is relative to F</etc/apparmor.d/>)
53
B<COMMENT> = '#' I<TEXT>
55
B<TEXT> = any characters
57
B<PROFILE> = [ I<COMMENT> ... ] [ I<VARIABLE ASSIGNMENT> ... ] ( '"' I<PROGRAM> '"' | I<PROGRAM> ) [ 'flags=(complain)' ]'{' [ ( I<RESOURCE RULE> | I<COMMENT> | I<INCLUDE> | I<SUBPROFILE> | 'capability ' I<CAPABILITY> | I<NETWORK RULE> | 'change_profile -> ' I<PROGRAMCHILD> ) ... ] '}'
59
B<SUBPROFILE> = [ I<COMMENT> ... ] ( I<PROGRAMHAT> | 'profile ' I<PROGRAMCHILD> ) '{' [ ( I<FILE RULE> | I<COMMENT> | I<INCLUDE> ) ... ] '}'
61
B<CAPABILITY> = (lowercase capability name without 'CAP_' prefix; see
64
B<NETWORK RULE> = 'network' [ [ I<DOMAIN> ] [ I<TYPE> ] [ I <PROTOCOL> ] ] ','
66
B<DOMAIN> = ( 'inet' | 'ax25' | 'ipx' | 'appletalk' | 'netrom' | 'bridge' | 'atmpvc' | 'x25' | 'inet6' | 'rose' | 'netbeui' | 'security' | 'key' | 'packet' | 'ash' | 'econet' | 'atmsvc' | 'sna' | 'irda' | 'pppox' | 'wanpipe' | 'bluetooth' ) ','
68
B<TYPE> = ( 'stream' | 'dgram' | 'seqpacket' | 'rdm' | 'raw' | 'packet' )
70
B<PROTOCOL> = ( 'tcp' | 'udp' | 'icmp' )
72
B<PROGRAM> = (non-whitespace characters except for '^', must start with '/'. Embedded spaces or tabs must be quoted.)
74
B<PROGRAMHAT> = '^' (non-whitespace characters; see aa_change_hat(2) for a description of how this "hat" is used.)
76
B<PROGRAMCHILD> = I<SUBPROFILE> name
78
B<FILE RULE> = I<RULE QUALIFIER> ( '"' I<FILEGLOB> '"' | I<FILEGLOB> ) I<ACCESS> ','
80
B<RULE QUALIFIER> = [ 'audit' ] [ 'deny' ] [ 'owner' ]
82
B<FILEGLOB> = (must start with '/' (after variable expansion), B<?*[]{}^> have special meanings; see below. May include I<VARIABLE>. Rules with embedded spaces or tabs must be quoted. Rules must end with '/' to apply to directories.)
84
B<ACCESS> = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx -> ' I<PROGRAMCHILD> | 'Cx -> ' I<PROGRAMCHILD> | 'm' ) [ I<ACCESS> ... ] (not all combinations are allowed; see below.)
86
B<VARIABLE> = '@{' I<ALPHA> [ ( I<ALPHANUMERIC> | '_' ) ... ] '}'
88
B<VARIABLE ASSIGNMENT> = I<VARIABLE> ('=' | '+=') (space separated values)
90
B<ALIAS RULE> = I<ABS PATH> '->' I<REWRITTEN ABS PATH> ','
92
B<ALPHA> = ('a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
94
B<ALPHANUMERIC> = ('0', '1', '2', ... '9', 'a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z')
98
All resources and programs need a full path. There may be any number of
99
subprofiles (aka child profiles) in a profile, limited only by kernel
100
memory. Subprofile names are limited to 974 characters. Child profiles can
101
be used to confine an application in a special way, or when you want the
102
child to be unconfined on the system, but confined when called from the
103
parent. Hats are a special child profile that can be used with the
104
aa_change_hat(2) API call. Applications written or modified to use
105
aa_change_hat(2) can take advantage of subprofiles to run under different
106
confinements, dependent on program logic. Several aa_change_hat(2)-aware
107
applications exist, including an Apache module, mod_apparmor(5); a PAM
108
module, pam_apparmor; and a Tomcat valve, tomcat_apparmor. Applications
109
written or modified to use change_profile(2) transition permanently to the
110
specified profile. libvirt is one such application.
114
File permission access modes consists of combinations of the following
121
=item B<w> - write -- conflicts with append
123
=item B<a> - append -- conflicts with write
125
=item B<ux> - unconfined execute
127
=item B<Ux> - unconfined execute -- scrub the environment
129
=item B<px> - discrete profile execute
131
=item B<Px> - discrete profile execute -- scrub the environment
133
=item B<cx> - transition to subprofile on execute
135
=item B<Cx> - transition to subprofile on execute -- scrub the environment
137
=item B<ix> - inherit execute
139
=item B<m> - allow PROT_EXEC with mmap(2) calls
147
=head2 Access Modes Details
151
=item B<r - Read mode>
153
Allows the program to have read access to the file or directory listing. Read access is
154
required for shell scripts and other interpreted content.
156
=item B<w - Write mode>
158
Allows the program to have write access to the file. Files and directories
159
must have this permission if they are to be unlinked (removed.) Write mode
160
is not required on a directory to rename or create files within the directory.
162
This mode conflicts with append mode.
164
=item B<a - Append mode>
166
Allows the program to have a limited appending only write access to the file.
167
Append mode will prevent an application from opening the file for write unless
168
it passes the O_APPEND parameter flag on open.
170
The mode conflicts with Write mode.
172
=item B<ux - Unconfined execute mode>
174
Allows the program to execute the program without any AppArmor profile
175
being applied to the program.
177
This mode is useful when a confined program needs to be able to perform
178
a privileged operation, such as rebooting the machine. By placing the
179
privileged section in another executable and granting unconfined
180
execution rights, it is possible to bypass the mandatory constraints
181
imposed on all confined processes. For more information on what is
182
constrained, see the apparmor(7) man page.
184
B<WARNING> 'ux' should only be used in very special cases. It enables the
185
designated child processes to be run without any AppArmor protection.
186
'ux' does not scrub the environment of variables such as LD_PRELOAD;
187
as a result, the calling domain may have an undue amount of influence
188
over the callee. Use this mode only if the child absolutely must be
189
run unconfined and LD_PRELOAD must be used. Any profile using this mode
190
provides negligible security. Use at your own risk.
192
Incompatible with 'Ux', 'px', 'Px', 'cx', 'Cx', 'ix'.
194
=item B<Ux - unconfined execute -- scrub the environment>
196
'Ux' allows the named program to run in 'ux' mode, but AppArmor
197
will invoke the Linux Kernel's B<unsafe_exec> routines to scrub
198
the environment, similar to setuid programs. (See ld.so(8) for some
199
information on setuid/setgid environment scrubbing.)
201
B<WARNING> 'Ux' should only be used in very special cases. It enables the
202
designated child processes to be run without any AppArmor protection.
203
Use this mode only if the child absolutely must be run unconfined. Use
206
Incompatible with 'ux', 'px', 'Px', 'cx', 'Cx', 'ix'.
208
=item B<px - Discrete Profile execute mode>
210
This mode requires that a discrete security profile is defined for a
211
program executed and forces an AppArmor domain transition. If there is
212
no profile defined then the access will be denied.
214
B<WARNING> 'px' does not scrub the environment of variables such as
215
LD_PRELOAD; as a result, the calling domain may have an undue amount of
216
influence over the callee.
218
Incompatible with 'Ux', 'ux', 'Px', 'cx', 'Cx', 'ix'.
220
=item B<Px - Discrete Profile execute mode -- scrub the environment>
222
'Px' allows the named program to run in 'px' mode, but AppArmor
223
will invoke the Linux Kernel's B<unsafe_exec> routines to scrub
224
the environment, similar to setuid programs. (See ld.so(8) for some
225
information on setuid/setgid environment scrubbing.)
227
Incompatible with 'Ux', 'ux', 'px', 'cx', 'Cx', 'ix'.
229
=item B<cx - Transition to Subprofile execute mode>
231
This mode requires that a local security profile is defined and forces an
232
AppArmor domain transition to the named profile. If there is no profile
233
defined then the access will be denied.
235
B<WARNING> 'cx' does not scrub the environment of variables such as
236
LD_PRELOAD; as a result, the calling domain may have an undue amount of
237
influence over the callee.
239
Incompatible with 'Ux', 'ux', 'px', 'Px', 'Cx', 'ix'.
241
=item B<Cx - Transition to Subprofile execute mode -- scrub the environment>
243
'Cx' allows the named program to run in 'cx' mode, but AppArmor
244
will invoke the Linux Kernel's B<unsafe_exec> routines to scrub
245
the environment, similar to setuid programs. (See ld.so(8) for some
246
information on setuid/setgid environment scrubbing.)
248
Incompatible with 'Ux', 'ux', 'px', 'Px', 'cx', 'ix'.
250
=item B<ix - Inherit execute mode>
252
Prevent the normal AppArmor domain transition on execve(2) when the
253
profiled program executes the named program. Instead, the executed resource
254
will inherit the current profile.
256
This mode is useful when a confined program needs to call another
257
confined program without gaining the permissions of the target's
258
profile, or losing the permissions of the current profile. There is no
259
version to scrub the environment because 'ix' executions don't change
262
Incompatible with 'Ux', 'ux', 'Px', 'px', 'cx', 'Cx'. Implies 'm'.
264
=item B<m - Allow executable mapping>
266
This mode allows a file to be mapped into memory using mmap(2)'s
267
PROT_EXEC flag. This flag marks the pages executable; it is used on some
268
architectures to provide non-executable data pages, which can complicate
269
exploit attempts. AppArmor uses this mode to limit which files a
270
well-behaved program (or all programs on architectures that enforce
271
non-executable memory access controls) may use as libraries, to limit
272
the effect of invalid B<-L> flags given to ld(1) and B<LD_PRELOAD>,
273
B<LD_LIBRARY_PATH>, given to ld.so(8).
275
=item B<l - Link mode>
277
Allows the program to be able to create a link with this name. When a
278
link is created, the new link B<MUST> have a subset of permissions as
279
the original file (with the exception that
280
the destination does not have to have link access.) If there is an 'x' rule
281
on the new link, it must match the original file exactly.
283
=item B<k - lock mode>
285
Allows the program to be able lock a file with this name. This permission
286
covers both advisory and mandatory locking.
292
Comments start with # and may begin at any place within a line. The
293
comment ends when the line ends. This is the same comment style as
298
The only capabilities a confined process may use may be enumerated; for
299
the complete list, please refer to capabilities(7). Note that granting
300
some capabilities renders AppArmor confinement for that domain advisory;
301
while open(2), read(2), write(2), etc., will still return error when
302
access is not granted, some capabilities allow loading kernel modules,
303
arbitrary access to IPC, ability to bypass discretionary access controls,
304
and other operations that are typically reserved for the root user.
306
The only operations that cannot be controlled in this manner are mount(2),
307
umount(2), and loading new AppArmor policy into the kernel, which are
308
always denied to confined processes.
312
AppArmor supports simple coarse grained network mediation. The network
313
rule restrict all socket(2) based operations. The mediation done is
314
a course grained check on whether a socket of a given type and family
315
can be created, read, or written. There is no mediation based of port
316
number or protocol beyond tcp, udp, and raw.
318
AppArmor network rules are accumulated so that the granted network
319
permissions are the union of all the listed network rule permissions.
321
AppArmor network rules are broad and general and become more restrictive
322
as further information is specified.
326
network, #allow access to all networking
327
network tcp, #allow access to tcp
328
network inet tcp, #allow access to tcp only for inet4 addresses
329
network inet6 tcp, #allow access to tcp only for inet6 addresses
333
AppArmor's policy language allows embedding variables into file rules
334
to enable easier configuration for some common (and pervasive) setups.
335
Variables may have multiple values assigned, but any variable assignments
336
must be made before the start of the profile.
338
The parser will automatically expand variables to include all values
339
that they have been assigned; it is an error to reference a variable
340
without setting at least one value.
342
At the time of this writing, only B<@{HOME}> and B<@{HOMEDIRS}> are defined
343
in the AppArmor policy provided, in the F</etc/apparmor.d/tunables/home>
344
file; these variables are used in many of the abstractions described later.
345
You may also add files in F</etc/apparmor.d/tunables/home.d> for
346
site-specific customization of B<@{HOMEDIRS}>.
350
AppArmor also provides alias rules for remapping paths for site-specific
351
layouts. They are an alternative form of path rewriting to using variables,
352
and are done after variable resolution. Alias rules must occur within the
353
preamble of the profile. System-wide aliases are found in
354
F</etc/apparmor.d/tunables/alias>, which is included by
355
F</etc/apparmor.d/tunables/global>. F</etc/apparmor.d/tunables/global> is
356
typically included at the beginning of an AppArmor profile.
360
File resources may be specified with a globbing syntax similar to that
361
used by popular shells, such as csh(1), bash(1), zsh(1).
367
can substitute for any number of characters, excepting '/'
371
can substitute for any number of characters, including '/'
375
can substitute for any single character excepting '/'
379
will substitute for the single character a, b, or c
383
will substitute for the single character a, b, or c
387
will substitute for any single character not matching a, b or c
391
will expand to one rule to match ab, one rule to match cd
395
When AppArmor looks up a directory the pathname being looked up will
396
end with a slash (e.g., F</var/tmp/>); otherwise it will not end with a
397
slash. Only rules that match a trailing slash will match directories. Some
398
examples, none matching the F</tmp/> directory itself, are:
404
Files directly in F</tmp>.
408
Directories directly in F</tmp>.
412
Files and directories anywhere underneath F</tmp>.
416
Directories anywhere underneath F</tmp>.
420
=head2 Rule Qualifiers
422
There are several rule qualifiers that can be applied to permission rules.
423
Rule qualifiers can modify the rule and/or permissions within the rule.
429
Specifies that permissions requests that match the rule should be recorded
434
Specifies that permissions requests that match the rule should be denied
435
without logging. Can be combined with 'audit' to enable logging.
439
Specifies that the task must have the same euid/fsuid as the object being
440
referenced by the permission check.
444
=head2 #include mechanism
446
AppArmor provides an easy abstraction mechanism to group common file
447
access requirements; this abstraction is an extremely flexible way to
448
grant site-specific rights and makes writing new AppArmor profiles very
449
simple by assembling the needed building blocks for any given program.
451
The use of '#include' is modelled directly after cpp(1); its use will
452
replace the '#include' statement with the specified file's contents.
453
B<#include "/absolute/path"> specifies that F</absolute/path> should be
454
used. B<#include "relative/path"> specifies that F<relative/path> should
455
be used, where the path is relative to the current working directory.
456
B<#include E<lt>magic/pathE<gt>> is the most common usage; it will load
457
F<magic/path> relative to a directory specified to apparmor_parser(8).
458
F</etc/apparmor.d/> is the AppArmor default.
460
The supplied AppArmor profiles follow several conventions; the
461
abstractions stored in F</etc/apparmor.d/abstractions/> are some
462
large clusters that are used in most profiles. What follows are short
463
descriptions of how some of the abstractions are used.
468
=item F<abstractions/audio>
470
Includes accesses to device files used for audio applications.
472
=item F<abstractions/authentication>
474
Includes access to files and services typically necessary for services
475
that perform user authentication.
477
=item F<abstractions/base>
479
Includes files that should be readable and writable in all profiles.
481
=item F<abstractions/bash>
483
Includes many files used by bash; useful for interactive shells and
484
programs that call system(3).
486
=item F<abstractions/consoles>
488
Includes read and write access to the device files controlling the
489
virtual console, sshd(8), xterm(1), etc. This abstraction is needed for
490
many programs that interact with users.
492
=item F<abstractions/fonts>
494
Includes access to fonts and the font libraries.
496
=item F<abstractions/gnome>
498
Includes read and write access to GNOME configuration files, as well as
499
read access to GNOME libraries.
501
=item F<abstractions/kde>
503
Includes read and write access to KDE configuration files, as well as
504
read access to KDE libraries.
506
=item F<abstractions/kerberosclient>
508
Includes file access rules needed for common kerberos clients.
510
=item F<abstractions/nameservice>
512
Includes file rules to allow DNS, LDAP, NIS, SMB, user and group password
513
databases, services, and protocols lookups.
515
=item F<abstractions/perl>
517
Includes read access to perl modules.
519
=item F<abstractions/user-download>
521
=item F<abstractions/user-mail>
523
=item F<abstractions/user-manpages>
525
=item F<abstractions/user-tmp>
527
=item F<abstractions/user-write>
529
Some profiles for typical "user" programs will use these include files
530
to describe rights that users have in the system.
532
=item F<abstractions/wutmp>
534
Includes write access to files used to maintain wtmp(5) and utmp(5)
535
databases, used with the w(1) and associated commands.
537
=item F<abstractions/X>
539
Includes read access to libraries, configuration files, X authentication
540
files, and the X socket.
544
The abstractions stored in F</etc/apparmor.d/program-chunks/> are
545
intended for use by specific program suites, and are not generally
548
Some of the abstractions rely on variables that are set in files in the
549
F</etc/apparmor.d/tunables/> directory. These variables are currently
550
B<@{HOME}> and B<@{HOMEDIRS}>. Variables cannot be set in profile scope;
551
they can only be set before the profile. Therefore, any profiles that
552
use abstractions should either B<#include E<lt>tunables/globalE<gt>> or
553
otherwise ensure that B<@{HOME}> and B<@{HOMEDIRS}> are set before
554
starting the profile definition. The aa-autodep(8) and aa-genprof(8) utilities
555
will automatically emit B<#include E<lt>tunables/globalE<gt>> in
560
An example AppArmor profile:
562
# a variable definition in the preamble
563
@{HOME} = /home/*/ /root/
565
# a comment about foo.
578
/@{HOME}/.foo_file rw,
579
/usr/bin/baz Cx -> baz,
581
# a comment about foo's hat (subprofile), bar.
588
# a comment about foo's subprofile, baz.
590
#include <abstractions/bash>
591
owner /proc/[0-9]*/stat r,
594
owner /var/lib/baz/* rw,
602
=item F</etc/init.d/boot.apparmor>
604
=item F</etc/apparmor.d/>
610
apparmor(7), apparmor_parser(8), aa-complain(1),
611
aa-enforce(1), aa_change_hat(2), mod_apparmor(5), and
612
L<http://wiki.apparmor.net>.
added
removed
.pc/0014-apparmor-lp979095.patch/parser/apparmor.d.pod
