From 02da244316b916124b3880e016dc1794245cb83f Mon Sep 17 00:00:00 2001 From: Eric Chiang Date: Mon, 17 Dec 2018 14:49:53 -0800 Subject: [PATCH] parser: add a man page for xattrs Signed-off-by: Eric Chiang --- parser/Makefile | 2 +- parser/apparmor.d.pod | 22 +++++++- parser/apparmor_xattrs.pod | 108 +++++++++++++++++++++++++++++++++++++ 3 files changed, 129 insertions(+), 3 deletions(-) create mode 100644 parser/apparmor_xattrs.pod diff --git a/parser/Makefile b/parser/Makefile index 9a18f4da0..2d40b06f5 100644 --- a/parser/Makefile +++ b/parser/Makefile @@ -30,7 +30,7 @@ SYSTEMD_UNIT_DIR=${DESTDIR}/usr/lib/systemd/system CONFDIR=/etc/apparmor INSTALL_CONFDIR=${DESTDIR}${CONFDIR} LOCALEDIR=/usr/share/locale -MANPAGES=apparmor.d.5 apparmor.7 apparmor_parser.8 aa-teardown.8 +MANPAGES=apparmor.d.5 apparmor.7 apparmor_parser.8 aa-teardown.8 apparmor_xattrs.7 YACC := bison YFLAGS := -d diff --git a/parser/apparmor.d.pod b/parser/apparmor.d.pod index 67b5900b4..7176d1870 100644 --- a/parser/apparmor.d.pod +++ b/parser/apparmor.d.pod @@ -66,7 +66,7 @@ B = '#' I [ '\r' ] '\n' B = any characters -B = ( I ) [ I ] [ I ] '{' ( I )* '}' +B = ( I ) [ I ] [ I ] [ I ] '{' ( I )* '}' B = [ 'profile' ] I | 'profile' I @@ -78,6 +78,12 @@ B = (must start with alphanumeric character (after variab B = I +B = [ 'xattrs=' ] '(' comma or white space separated list of I ')' + +B = extended attribute name '=' I + +B = I + B = [ 'flags=' ] '(' comma or white space separated list of I ')' B = 'complain' | 'audit' | 'enforce' | 'mediate_deleted' | 'attach_disconnected' | 'chroot_relative' @@ -1371,6 +1377,18 @@ Directories anywhere underneath F. =back +=head2 Extended Attributes + +AppArmor profiles have the ability to target files based on their xattr(7) +values in addition to their path. For example, the following profile matches +files in /usr/bin with the attribute "security.apparmor" and value "trusted": + + /usr/bin/* xattrs(security.apparmor="trusted") { + # ... + } + +See apparmor_xattrs(7) for further details. + =head2 Rule Qualifiers There are several rule qualifiers that can be applied to permission rules. @@ -1609,7 +1627,7 @@ negative values match when specifying one or the other. Eg, 'rw' matches when =head1 SEE ALSO -apparmor(7), apparmor_parser(8), aa-complain(1), +apparmor(7), apparmor_parser(8), apprmor_xattrs(7), aa-complain(1), aa-enforce(1), aa_change_hat(2), mod_apparmor(5), and L. diff --git a/parser/apparmor_xattrs.pod b/parser/apparmor_xattrs.pod new file mode 100644 index 000000000..39c4fcad4 --- /dev/null +++ b/parser/apparmor_xattrs.pod @@ -0,0 +1,108 @@ +# ---------------------------------------------------------------------- +# Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, +# 2008, 2009 +# NOVELL (All rights reserved) +# +# Copyright (c) 2010 +# Canonical Ltd. (All rights reserved) +# +# Copyright (c) 2013 +# Christian Boltz (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 profile xattr(7) matching + +=head1 DESCRIPTION + +AppArmor profiles can conditionally match files based on the presence and value +of extended attributes in addition to file path. The following profile applies +to any file under "/usr/bin" where the "security.apparmor" extended attribute +has the value "trusted": + + profile trusted /usr/bin/* xattrs=(security.apparmor="trusted") { + # ... + } + +Note that "security.apparmor" and "trusted" are arbitrary, and profiles can +match based on the value of any attribute. + +The xattrs value may also contain a path regex: + + profile trusted /usr/bin/* xattrs=(user.trust="tier/*") { + + # ... + } + +The getfattr(1) and setfattr(1) tools can be used to view and manage xattr +values: + + $ setfattr -n 'security.apparmor' -v 'trusted' /usr/bin/example-tool + $ getfattr --absolute-names -d -m - /usr/bin/example-tool + # file: usr/bin/example-tool + security.apparmor="trusted" + +The priority of each profile is determined by the length of the path, then the +number of xattrs specified. A more specific path is preferred over xattr +matches: + + # Highest priority, longest path. + profile example1 /usr/bin/example-tool { + # ... + } + + # Lower priority than the longer path, but higher priority than a rule + # with fewer xattr matches. + profile example2 /usr/** xattrs=( + security.apparmor="trusted" + user.domain="**" + ) { + # ... + } + + # Lowest priority. Same path length as the second profile, but has + # fewer xattr matches. + profile example2 /usr/** { + # ... + } + +xattr matching requires the following kernel feature: + + /sys/kernel/security/apparmor/features/domain/attach_conditions/xattr + +=head1 KNOWN ISSUES + +AppArmor profiles currently can't reliably match extended attributes with +binary values such as security.evm and security.ima. In the future AppArmor may +gain the ability to match based on the presence of certain attributes while +ignoring their values. + +=head1 SEE ALSO + +apparmor(8), +apparmor_parser(8), +apparmor.d(5), +xattr(7), +aa-autodep(1), clean(1), +auditd(8), +getfattr(1), +setfattr(1), +and L. + +=cut