From c48d7dc71f546228bf8d832ba077100192fc41b1 Mon Sep 17 00:00:00 2001 From: Steve Beattie Date: Mon, 15 Sep 2014 11:30:47 -0700 Subject: [PATCH] manpages: incorporate podchecker; fix errors and (most) warnings This patch adds a 'check_pod_files' make target to the common make rules, and then fixes the errors it highlighted as well as most of the warnings. It will cause 'make check' in most of the directories to fail if there are errors in a pod file (but not if there are warnings). Common issues were: - using an '=over/=back' pair for code-like snippets that did not contain any =items therein; the =over keyword is intended for indenting lists of =item entries, and generates a warning if there isn't any. - not escaping '<' or '>' - blank lines that contained spaces or tabs The second -warnings flag passed to podchecker is to add additional warnings, un-escaped '<' and '>' being of them. I did not fix all of the warnings in apparmor.d.pod, as I have not come up with a good warning-free way to express the BNF of the language similar in format to what is currently generated. The existing libapparmor warnings (complaints about duplicate =item definition names) are actually a result of passing the second -warnings flag. The integration into libapparmor is suboptimal due to automake's expectation that there will be a test driver program(s) for make check targets; that's why I added the podchecker call to the manpage generation point. Signed-off-by: Steve Beattie Acked-by: Seth Arnold --- changehat/mod_apparmor/Makefile | 3 changehat/mod_apparmor/mod_apparmor.pod | 28 ++- common/Make.rules | 4 libraries/libapparmor/doc/Makefile.am | 7 parser/Makefile | 2 parser/apparmor.d.pod | 275 +++++++++++++------------------- utils/Makefile | 3 utils/aa-cleanprof.pod | 2 utils/aa-complain.pod | 2 utils/aa-decode.pod | 2 utils/aa-easyprof.pod | 69 +++----- utils/aa-enforce.pod | 2 utils/aa-genprof.pod | 2 utils/aa-logprof.pod | 6 utils/aa-sandbox.pod | 64 ++----- utils/logprof.conf.pod | 2 utils/vim/Makefile | 2 17 files changed, 212 insertions(+), 263 deletions(-) --- changehat/mod_apparmor/Makefile | 3 + changehat/mod_apparmor/mod_apparmor.pod | 28 ++- common/Make.rules | 4 + libraries/libapparmor/doc/Makefile.am | 7 + parser/Makefile | 2 +- parser/apparmor.d.pod | 275 ++++++++++-------------- utils/Makefile | 3 +- utils/aa-cleanprof.pod | 2 +- utils/aa-complain.pod | 2 +- utils/aa-decode.pod | 2 +- utils/aa-easyprof.pod | 69 +++--- utils/aa-enforce.pod | 2 +- utils/aa-genprof.pod | 2 +- utils/aa-logprof.pod | 6 +- utils/aa-sandbox.pod | 64 ++---- utils/logprof.conf.pod | 2 +- utils/vim/Makefile | 2 +- 17 files changed, 212 insertions(+), 263 deletions(-) diff --git a/changehat/mod_apparmor/Makefile b/changehat/mod_apparmor/Makefile index 90db16519..c0c70c255 100644 --- a/changehat/mod_apparmor/Makefile +++ b/changehat/mod_apparmor/Makefile @@ -95,3 +95,6 @@ install: ${TARGET} ${MANPAGES} clean: _clean rm -rf .libs rm -f *.la *.lo *.so *.o *.slo Make.rules + +.PHONY: check +check: check_pod_files diff --git a/changehat/mod_apparmor/mod_apparmor.pod b/changehat/mod_apparmor/mod_apparmor.pod index 3176bdaf9..46a6f9879 100644 --- a/changehat/mod_apparmor/mod_apparmor.pod +++ b/changehat/mod_apparmor/mod_apparmor.pod @@ -64,7 +64,7 @@ provides the AAHatName and AADefaultHatName Apache configuration options. =item B AAHatName allows you to specify a hat to be used for a given Apache -EDirectoryE, EDirectoryMatch>, ELocationE or +EDirectoryE, EDirectoryMatchE, ELocationE or ELocationMatchE directive (see the Apache documenation for more details). Note that mod_apparmor behavior can become confused if EDirectory*E and ELocation*E directives are intermingled @@ -95,23 +95,35 @@ On each URI request, mod_apparmor will first aa_change_hat(2) into Then, after performing the initial parsing of the request, mod_apparmor will: -=over 2 +=over 4 -1. try to aa_change_hat(2) into a matching AAHatName hat if it exists and +=item 1 + +try to aa_change_hat(2) into a matching AAHatName hat if it exists and applies, otherwise it will -2. try to aa_change_hat(2) into an AADefaultHatName hat, either the +=item 2 + +try to aa_change_hat(2) into an AADefaultHatName hat, either the ServerName (the default) or the configuration value specified by the AADefaultHatName directive, for the server/vhost, otherwise it will -3. try to aa_change_hat(2) into the ServerName-URI, otherwise it will +=item 3 -4. try to aa_change_hat(2) into the URI itself, otherwise it will +try to aa_change_hat(2) into the ServerName-URI, otherwise it will -5. try to aa_change_hat(2) into the DEFAULT_URI hat, if it exists, otherwise it +=item 4 + +try to aa_change_hat(2) into the URI itself, otherwise it will + +=item 5 + +try to aa_change_hat(2) into the DEFAULT_URI hat, if it exists, otherwise it will -6. fall back to the global Apache policy +=item 6 + +fall back to the global Apache policy =back diff --git a/common/Make.rules b/common/Make.rules index 673c99ed2..05fa3f726 100644 --- a/common/Make.rules +++ b/common/Make.rules @@ -266,3 +266,7 @@ ENSCRIPT_ARGS=-C -2jGr -f Courier6 -E %.pm.ps: %.pm enscript ${ENSCRIPT_ARGS} -o $@ $< + +.PHONY: check_pod_files +check_pod_files: + LANG=C podchecker -warning -warning *.pod diff --git a/libraries/libapparmor/doc/Makefile.am b/libraries/libapparmor/doc/Makefile.am index 80cdcac0d..52f333139 100644 --- a/libraries/libapparmor/doc/Makefile.am +++ b/libraries/libapparmor/doc/Makefile.am @@ -1,6 +1,10 @@ ## Process this file with automake to produce Makefile.in POD2MAN = pod2man +PODCHECKER = podchecker + +# No perl, no manpages +if HAVE_PERL man_MANS = aa_change_hat.2 aa_change_profile.2 aa_getcon.2 aa_find_mountpoint.2 @@ -12,9 +16,12 @@ EXTRA_DIST = $(man_MANS) $(PODS) BUILT_SOURCES = $(man_MANS) %.2: %.pod + $(PODCHECKER) -warnings -warnings $< $(POD2MAN) \ --section=2 \ --release="AppArmor $(VERSION)" \ --center="AppArmor" \ --stderr \ $< > $@ + +endif diff --git a/parser/Makefile b/parser/Makefile index 88b79427f..be84e659d 100644 --- a/parser/Makefile +++ b/parser/Makefile @@ -291,7 +291,7 @@ tst_%: parser_%.c parser.h $(filter-out parser_%.o, ${TEST_OBJECTS}) .SILENT: check .PHONY: check -check: tests +check: check_pod_files tests .SILENT: tests tests: apparmor_parser ${TESTS} diff --git a/parser/apparmor.d.pod b/parser/apparmor.d.pod index 9cf136d85..7e5295dd0 100644 --- a/parser/apparmor.d.pod +++ b/parser/apparmor.d.pod @@ -48,20 +48,20 @@ B = '#include' ( I | I ) B = '"' path '"' (the path is passed to open(2)) -B = '<' relative path '>' (the path is relative to F) +B = 'E' relative path 'E' (the path is relative to F) B = '#' I B = any characters -B = [ I ... ] [ I ... ] ( '"' I '"' | I ) [ 'flags=(complain)' ]'{' [ ( I | I | I | I | 'capability ' I | I | I | I | I | I I | 'change_profile -> ' I ) ... ] '}' +B = [ I ... ] [ I ... ] ( '"' I '"' | I ) [ 'flags=(complain)' ]'{' [ ( I | I | I | I | 'capability ' I | I | I | I | I | I I | 'change_profile -E ' I ) ... ] '}' B = [ I ... ] ( I | 'profile ' I ) '{' [ ( I | I | I ) ... ] '}' B = (lowercase capability name without 'CAP_' prefix; see capabilities(7)) -B = 'network' [ [ I ] [ I ] [ I ] ] ',' +B = 'network' [ [ I ] [ I ] [ I ] ] ',' B = ( 'inet' | 'ax25' | 'ipx' | 'appletalk' | 'netrom' | 'bridge' | 'atmpvc' | 'x25' | 'inet6' | 'rose' | 'netbeui' | 'security' | 'key' | 'packet' | 'ash' | 'econet' | 'atmsvc' | 'sna' | 'irda' | 'pppox' | 'wanpipe' | 'bluetooth' | 'netlink' ) ',' @@ -77,7 +77,7 @@ B = I name B = ( I | I | I ) -B = [ 'audit' ] [ 'deny' ] 'mount' [ I ] [ I ] [ -> [ I ] +B = [ 'audit' ] [ 'deny' ] 'mount' [ I ] [ I ] [ -E [ I ] B = [ 'audit' ] [ 'deny' ] 'remount' [ I ] I @@ -97,7 +97,7 @@ B = ( 'ro' | 'rw' | 'nosuid' | 'suid' | 'nodev' | 'dev' | 'noexec' B = ( I | I ) ... -B = [ 'audit' ] [ 'deny' ] pivot_root [ oldroot=I ] [ I ] [ -> I ] +B = [ 'audit' ] [ 'deny' ] pivot_root [ oldroot=I ] [ I ] [ -E I ] B = [ 'audit' ] [ 'deny' ] 'ptrace' [ I ] [ I ] @@ -166,14 +166,14 @@ B = ( I | I ) B = ( 'create' | 'bind' | 'listen' | 'accept' | 'connect' | 'shutdown' | 'getattr' | 'setattr' | 'getopt' | 'setopt' | 'send' | 'receive' | 'r' | 'w' | 'rw' ) (some access modes are incompatible with some rules or require additional parameters) -B = '(' I ( [','] )* ')' +B = '(' I ( [','] I )* ')' B = ( I | I ) each cond can appear at most once -B = 'type' '=' ( | '(' ( '"' '"' | )+ ')' ) +B = 'type' '=' ( I | '(' ( '"' I '"' | I )+ ')' ) -B = 'protocol' '=' ( | '(' ( '"' '"' | )+ ')' ) +B = 'protocol' '=' ( I | '(' ( '"' I '"' | I )+ ')' ) B = ( I | I | I | I )* each cond can appear at most once @@ -181,13 +181,13 @@ B = ( I | I | I = 'peer' '=' ( I | I )+ each cond can appear at most once -B 'addr' '=' ( | '(' '"' '"' | ')' ) +B 'addr' '=' ( I | '(' '"' I '"' | I ')' ) -B 'label' '=' ( | '(' '"' '"' | ')' ) +B 'label' '=' ( I | '(' '"' I '"' | I ')' ) -B 'attr' '=' ( | '(' '"' '"' | ')' ) +B 'attr' '=' ( I | '(' '"' I '"' | I ')' ) -B 'opt' '=' ( | '(' '"' '"' | ')' ) +B 'opt' '=' ( I | '(' '"' I '"' | I ')' ) B = I ( '"' I '"' | I ) I ',' @@ -195,13 +195,13 @@ B = [ 'audit' ] [ 'deny' ] [ 'owner' ] B = (must start with '/' (after variable expansion), B have special meanings; see below. May include I. Rules with embedded spaces or tabs must be quoted. Rules must end with '/' to apply to directories.) -B = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx -> ' I | 'Cx -> ' I | 'm' ) [ I ... ] (not all combinations are allowed; see below.) +B = ( 'r' | 'w' | 'l' | 'ix' | 'ux' | 'Ux' | 'px' | 'Px' | 'cx -E ' I | 'Cx -E ' I | 'm' ) [ I ... ] (not all combinations are allowed; see below.) B = '@{' I [ ( I | '_' ) ... ] '}' B = I ('=' | '+=') (space separated values) -B = I '->' I ',' +B = I '-E' I ',' B = ('a', 'b', 'c', ... 'z', 'A', 'B', ... 'Z') @@ -230,31 +230,57 @@ modes: =over 8 -=item B - read +=item B -=item B - write -- conflicts with append +- read -=item B - append -- conflicts with write +=item B -=item B - unconfined execute +- write -- conflicts with append -=item B - unconfined execute -- scrub the environment +=item B -=item B - discrete profile execute +- append -- conflicts with write -=item B - discrete profile execute -- scrub the environment +=item B -=item B - transition to subprofile on execute +- unconfined execute -=item B - transition to subprofile on execute -- scrub the environment +=item B -=item B - inherit execute +- unconfined execute -- scrub the environment -=item B - allow PROT_EXEC with mmap(2) calls +=item B -=item B - link +- discrete profile execute -=item B - lock +=item B + +- discrete profile execute -- scrub the environment + +=item B + +- transition to subprofile on execute + +=item B + +- transition to subprofile on execute -- scrub the environment + +=item B + +- inherit execute + +=item B + +- allow PROT_EXEC with mmap(2) calls + +=item B + +- link + +=item B + +- lock =back @@ -459,29 +485,17 @@ If a conditional is specified using '=', then the rule only grants permission for mounts matching the exactly specified options. For example, an AppArmor policy with the following rule: -=over 4 - -mount options=ro /dev/foo -> /mnt/, - -=back + mount options=ro /dev/foo -E /mnt/, Would match: -=over 4 - -$ mount -o ro /dev/foo /mnt - -=back + $ mount -o ro /dev/foo /mnt but not either of these: -=over 4 + $ mount -o ro,atime /dev/foo /mnt -$ mount -o ro,atime /dev/foo /mnt - -$ mount -o rw /dev/foo /mnt - -=back + $ mount -o rw /dev/foo /mnt =item 2. @@ -489,39 +503,27 @@ If a conditional is specified using 'in', then the rule grants permission for mounts matching any combination of the specified options. For example, if an AppArmor policy has the following rule: -=over 4 - -mount options in (ro,atime) /dev/foo -> /mnt/, - -=back + mount options in (ro,atime) /dev/foo -> /mnt/, all of these mount commands will match: -=over 4 + $ mount -o ro /dev/foo /mnt -$ mount -o ro /dev/foo /mnt + $ mount -o ro,atime /dev/foo /mnt -$ mount -o ro,atime /dev/foo /mnt - -$ mount -o atime /dev/foo /mnt - -=back + $ mount -o atime /dev/foo /mnt but none of these will: -=over 4 + $ mount -o ro,sync /dev/foo /mnt -$ mount -o ro,sync /dev/foo /mnt + $ mount -o ro,atime,sync /dev/foo /mnt -$ mount -o ro,atime,sync /dev/foo /mnt + $ mount -o rw /dev/foo /mnt -$ mount -o rw /dev/foo /mnt + $ mount -o rw,noatime /dev/foo /mnt -$ mount -o rw,noatime /dev/foo /mnt - -$ mount /dev/foo /mnt - -=back + $ mount /dev/foo /mnt =item 3. @@ -530,51 +532,32 @@ grants permission for each set of options. This provides a shorthand when writing mount rules which might help to logically break up a conditional. For example, if an AppArmor policy has the following rule: -=over 4 - -mount options=ro options=atime - -=back + mount options=ro options=atime both of these mount commands will match: -=over 4 + $ mount -o ro /dev/foo /mnt -$ mount -o ro /dev/foo /mnt - -$ mount -o atime /dev/foo /mnt - -=back + $ mount -o atime /dev/foo /mnt but this one will not: -=over 4 - -$ mount -o ro,atime /dev/foo /mnt - -=back + $ mount -o ro,atime /dev/foo /mnt =back Note that separate mount rules are distinct and the options do not accumulate. For example, these AppArmor mount rules: -=over 4 + mount options=ro, -mount options=ro, -mount options=atime, - -=back + mount options=atime, are not equivalent to either of these mount rules: -=over 4 + mount options=(ro,atime), -mount options=(ro,atime), - -mount options in (ro,atime), - -=back + mount options in (ro,atime), To help clarify the flexibility and complexity of mount rules, here are some example rules with accompanying matching commands: @@ -584,65 +567,49 @@ example rules with accompanying matching commands: =item B the 'mount' rule without any conditionals is the most generic and allows any -mount. Equivalent to 'mount fstype=** options=** ** -> /**'. +mount. Equivalent to 'mount fstype=** options=** ** -E /**'. =item B allow mounting of /dev/foo anywhere with any options. Some matching mount commands: -=over 4 + $ mount /dev/foo /mnt -$ mount /dev/foo /mnt + $ mount -t ext3 /dev/foo /mnt -$ mount -t ext3 /dev/foo /mnt + $ mount -t vfat /dev/foo /mnt -$ mount -t vfat /dev/foo /mnt - -$ mount -o ro,atime,noexec,nodiratime /dev/foo /srv/some/mountpoint - -=back + $ mount -o ro,atime,noexec,nodiratime /dev/foo /srv/some/mountpoint =item B allow mounting of /dev/foo anywhere, as read only. Some matching mount commands: -=over 4 + $ mount -o ro /dev/foo /mnt -$ mount -o ro /dev/foo /mnt - -$ mount -o ro /dev/foo /some/where/else - -=back + $ mount -o ro /dev/foo /some/where/else =item B allow mount of /dev/foo anywhere, as read only and using inode access times. Some matching mount commands: -=over 4 + $ mount -o ro,atime /dev/foo /mnt -$ mount -o ro,atime /dev/foo /mnt - -$ mount -o ro,atime /dev/foo /some/where/else - -=back + $ mount -o ro,atime /dev/foo /some/where/else =item B allow mount of /dev/foo anywhere using some combination of 'ro' and 'atime' (see above). Some matching mount commands: -=over 4 + $ mount -o ro /dev/foo /mnt -$ mount -o ro /dev/foo /mnt + $ mount -o atime /dev/foo /some/where/else -$ mount -o atime /dev/foo /some/where/else - -$ mount -o ro,atime /dev/foo /some/other/place - -=back + $ mount -o ro,atime /dev/foo /some/other/place =item B @@ -650,68 +617,48 @@ allow mount of /dev/foo anywhere as read only, and allow mount of /dev/foo anywhere using inode access times. Note this is expressed as two different rules. Matches: -=over 4 + $ mount -o ro /dev/foo /mnt/1 -$ mount -o ro /dev/foo /mnt/1 + $ mount -o atime /dev/foo /mnt/2 -$ mount -o atime /dev/foo /mnt/2 - -=back - -=item B<< mount -> /mnt/**, >> +=item B<< mount -E /mnt/**, >> allow mounting anything under a directory in /mnt/**. Some matching mount commands: -=over 4 + $ mount /dev/foo1 /mnt/1 -$ mount /dev/foo1 /mnt/1 + $ mount -o ro,atime,noexec,nodiratime /dev/foo2 /mnt/deep/path/foo2 -$ mount -o ro,atime,noexec,nodiratime /dev/foo2 /mnt/deep/path/foo2 - -=back - -=item B<< mount options=ro -> /mnt/**, >> +=item B<< mount options=ro -E /mnt/**, >> allow mounting anything under /mnt/**, as read only. Some matching mount commands: -=over 4 + $ mount -o ro /dev/foo1 /mnt/1 -$ mount -o ro /dev/foo1 /mnt/1 + $ mount -o ro /dev/foo2 /mnt/deep/path/foo2 -$ mount -o ro /dev/foo2 /mnt/deep/path/foo2 - -=back - -=item B<< mount fstype=ext3 options=(rw,atime) /dev/sdb1 -> /mnt/stick/, >> +=item B<< mount fstype=ext3 options=(rw,atime) /dev/sdb1 -E /mnt/stick/, >> allow mounting an ext3 filesystem in /dev/sdb1 on /mnt/stick as read/write and using inode access times. Matches only: -=over 4 + $ mount -o rw,atime /dev/sdb1 /mnt/stick -$ mount -o rw,atime /dev/sdb1 /mnt/stick - -=back - -=item B<< mount options=(ro, atime) options in (nodev, user) /dev/foo -> /mnt/, >> +=item B<< mount options=(ro, atime) options in (nodev, user) /dev/foo -E /mnt/, >> allow mounting /dev/foo on /mmt/ read only and using inode access times or allow mounting /dev/foo on /mnt/ with some combination of 'nodev' and 'user'. Matches only: -=over 4 + $ mount -o ro,atime /dev/foo /mnt -$ mount -o ro,atime /dev/foo /mnt + $ mount -o nodev /dev/foo /mnt -$ mount -o nodev /dev/foo /mnt + $ mount -o user /dev/foo /mnt -$ mount -o user /dev/foo /mnt - -$ mount -o nodev,user /dev/foo /mnt - -=back + $ mount -o nodev,user /dev/foo /mnt =back @@ -898,6 +845,7 @@ domain sockets, see unix(7) for more information. The sun_path component (aka the socket address) of a unix domain socket is specified by the + addr= conditional. If an address conditional is not specified as part of @@ -911,17 +859,20 @@ characters must be specified by using an escape sequence I<\000> or I<\x00>. The pattern matching is the same as is used by file path matching so * will not match I even though it has no special meaning with in an abstract socket name. Eg. + unix addr=@*, Anonymous unix domain sockets have no sun_path associated with the socket address, however it can be specified with the special I keyword to indicate the rule only applies to anonymous unix domain sockets. Eg. + unix addr=none, If the address component of a rule is not specified then the rule applies to both abstract and anonymous sockets. =head3 Unix socket permissions + Unix domain socket rules are accumulated so that the granted unix socket permissions are the union of all the listed unix rule permissions. @@ -988,18 +939,20 @@ sockets as well. When fine grained unix domain socket mediation is available the coarse grained network rule is mapped into the equivalent unix socket rule. -Eg. +E.G. + network unix, => unix, network unix stream, => unix stream, Fine grained mediation rules however can not be lossly converted back -to the coarse grained network rule. Eg +to the coarse grained network rule; e.g. unix bind addr=@example, Has no exact match under coarse grained network rules, the closest match is -the much wider permission rule of. +the much wider permission rule of + network unix, =head2 Variables @@ -1308,18 +1261,26 @@ An example AppArmor profile: =over 4 +=item * + Mount options support the use of pattern matching but mount flags are not correctly intersected against specified patterns. Eg, 'mount options=**,' should be equivalent to 'mount,', but it is not. (LP: #965690) +=item * + The fstype may not be matched against when certain mount command flags are used. Specifically fstype matching currently only works when creating a new mount and not remount, bind, etc. +=item * + Mount rules with multiple 'options' conditionals are not applied as documented but instead merged such that 'options in (ro,nodev) options in (atime)' is equivalent to 'options in (ro,nodev,atime)'. +=item * + When specifying mount options with the 'in' conditional, both the positive and negative values match when specifying one or the other. Eg, 'rw' matches when 'ro' is specified and 'dev' matches when 'nodev' is specified such that diff --git a/utils/Makefile b/utils/Makefile index 7340326a4..3d85aaf4b 100644 --- a/utils/Makefile +++ b/utils/Makefile @@ -90,9 +90,10 @@ check_severity_db: /usr/include/linux/capability.h severity.db done ; \ test "$$RC" -eq 0 +# check_pod_files is defined in common/Make.rules .PHONY: check .SILENT: check -check: check_severity_db +check: check_severity_db check_pod_files for i in ${PERLTOOLS} ; do \ perl -c $$i || exit 1; \ done diff --git a/utils/aa-cleanprof.pod b/utils/aa-cleanprof.pod index 1651b5a55..95ab12951 100644 --- a/utils/aa-cleanprof.pod +++ b/utils/aa-cleanprof.pod @@ -14,7 +14,7 @@ B<-d --dir /path/to/profiles> Specifies where to look for the AppArmor security profile set. Defaults to /etc/apparmor.d. - + B<-s --silent> Silently overwrites the profile without user prompt. diff --git a/utils/aa-complain.pod b/utils/aa-complain.pod index 437c9be48..b2802abc6 100644 --- a/utils/aa-complain.pod +++ b/utils/aa-complain.pod @@ -26,7 +26,7 @@ aa-complain - set an AppArmor security profile to I mode. =head1 SYNOPSIS -BexecutableE> [IexecutableE> ...] [I<-d /path/to/profiles>] +B<< aa-complain IexecutableE> [IexecutableE> ...] [I<-d /path/to/profiles>] >> =head1 OPTIONS diff --git a/utils/aa-decode.pod b/utils/aa-decode.pod index 98a005f15..178ca5c4c 100644 --- a/utils/aa-decode.pod +++ b/utils/aa-decode.pod @@ -6,7 +6,7 @@ aa-decode - decode hex-encoded in AppArmor log files =head1 SYNOPSIS -B [option] +B [option] EHEX STRINGE =head1 DESCRIPTION diff --git a/utils/aa-easyprof.pod b/utils/aa-easyprof.pod index 486edead2..b01448994 100644 --- a/utils/aa-easyprof.pod +++ b/utils/aa-easyprof.pod @@ -25,7 +25,7 @@ aa-easyprof - AppArmor profile generation made easy. =head1 SYNOPSIS -B [option] +B [option] Epath to binaryE =head1 DESCRIPTION @@ -125,14 +125,11 @@ VENDOR/VERSION within the policy-groups and templates directory. The specified version must be a positive decimal number compatible with the JSON Number type. Eg, when using: -=over - $ aa-easyprof --templates-dir=/usr/share/apparmor/easyprof/templates \ - --policy-groups-dir=/usr/share/apparmor/easyprof/policygroups \ - --policy-vendor="foo" \ - --policy-version=1.0 - -=back + $ aa-easyprof --templates-dir=/usr/share/apparmor/easyprof/templates \ + --policy-groups-dir=/usr/share/apparmor/easyprof/policygroups \ + --policy-vendor="foo" \ + --policy-version=1.0 Then /usr/share/apparmor/easyprof/templates/foo/1.0 will be searched for templates and /usr/share/apparmor/easyprof/policygroups/foo/1.0 for policy @@ -255,49 +252,37 @@ Specify output directory for profile. If unspecified, policy is sent to stdout. =back -=head1 EXAMPLE +=head1 EXAMPLES Example usage for a program named 'foo' which is installed in /opt/foo: -=over - - $ aa-easyprof --template=user-application --template-var="@{APPNAME}=foo" \ - --policy-groups=opt-application,user-application \ - /opt/foo/bin/FooApp - -=back + $ aa-easyprof --template=user-application --template-var="@{APPNAME}=foo" \ + --policy-groups=opt-application,user-application \ + /opt/foo/bin/FooApp When using a manifest file: -=over - - $ aa-easyprof --manifest=manifest.json - -=back + $ aa-easyprof --manifest=manifest.json To output a manifest file based on aa-easyprof arguments: -=over - - $ aa-easyprof --output-format=json \ - --author="Your Name" \ - --comment="Unstructured single-line comment" \ - --copyright="Unstructured single-line copyright statement" \ - --name="My Foo App" \ - --profile-name="com.example.foo" \ - --template="user-application" \ - --policy-groups="user-application,networking" \ - --abstractions="audio,gnome" \ - --read-path="/tmp/foo_r" \ - --read-path="/tmp/bar_r/" \ - --write-path="/tmp/foo_w" \ - --write-path=/tmp/bar_w/ \ - --template-var="@{APPNAME}=foo" \ - --template-var="@{VAR1}=bar" \ - --template-var="@{VAR2}=baz" \ - "/opt/foo/**" - -=back + $ aa-easyprof --output-format=json \ + --author="Your Name" \ + --comment="Unstructured single-line comment" \ + --copyright="Unstructured single-line copyright statement" \ + --name="My Foo App" \ + --profile-name="com.example.foo" \ + --template="user-application" \ + --policy-groups="user-application,networking" \ + --abstractions="audio,gnome" \ + --read-path="/tmp/foo_r" \ + --read-path="/tmp/bar_r/" \ + --write-path="/tmp/foo_w" \ + --write-path=/tmp/bar_w/ \ + --template-var="@{APPNAME}=foo" \ + --template-var="@{VAR1}=bar" \ + --template-var="@{VAR2}=baz" \ + "/opt/foo/**" =head1 BUGS diff --git a/utils/aa-enforce.pod b/utils/aa-enforce.pod index 3130ae2e0..464b8a8b4 100644 --- a/utils/aa-enforce.pod +++ b/utils/aa-enforce.pod @@ -27,7 +27,7 @@ being disabled or I mode. =head1 SYNOPSIS -BexecutableE> [IexecutableE> ...] [I<-d /path/to/profiles>] +B<< aa-enforce IexecutableE> [IexecutableE> ...] [I<-d /path/to/profiles>] >> =head1 OPTIONS diff --git a/utils/aa-genprof.pod b/utils/aa-genprof.pod index c259408a1..beda6d627 100644 --- a/utils/aa-genprof.pod +++ b/utils/aa-genprof.pod @@ -36,7 +36,7 @@ B<-d --dir /path/to/profiles> Defaults to /etc/apparmor.d. B<-f --file /path/to/logfile> - + Specifies the location of logfile. Default locations are read from F. Typical defaults are: diff --git a/utils/aa-logprof.pod b/utils/aa-logprof.pod index 6219c12fc..c7dbb87a8 100644 --- a/utils/aa-logprof.pod +++ b/utils/aa-logprof.pod @@ -31,12 +31,12 @@ B] [I<-f /path/to/logfile>] [I<-m Emark =head1 OPTIONS B<-d --dir /path/to/profiles> - + Specifies where to look for the AppArmor security profile set. Defaults to /etc/apparmor.d. B<-f --file /path/to/logfile> - + Specifies the location of logfile that contains AppArmor security events. Default locations are read from F. Typical defaults are: @@ -45,7 +45,7 @@ B<-f --file /path/to/logfile> /var/log/messages B< -m --logmark "mark"> - + aa-logprof will ignore all events in the system log before the specified mark is seen. If the mark contains spaces, it must be surrounded with quotes to work correctly. diff --git a/utils/aa-sandbox.pod b/utils/aa-sandbox.pod index 5c921cc37..324b809df 100644 --- a/utils/aa-sandbox.pod +++ b/utils/aa-sandbox.pod @@ -25,7 +25,7 @@ aa-sandbox - AppArmor sandboxing =head1 SYNOPSIS -B [option] +B [option] Epath to binaryE =head1 DESCRIPTION @@ -89,11 +89,7 @@ with care to not allow too much access to the sandboxed application. In particular, the profile specified with --profile must add a rule to deny access to ~/.Xauthority for X sandboxing to be effective. Eg: -=over - -audit deny @{HOME}/.Xauthority mrwlk, - -=back + audit deny @{HOME}/.Xauthority mrwlk, =item --with-xserver=XSERVER @@ -115,35 +111,19 @@ The starting geometry for the Xephyr(1) server to use. Use the existing system profile 'firefox' to sandbox /usr/bin/firefox: -=over - -$ aa-sandbox -X --profile=firefox /usr/bin/firefox - -=back + $ aa-sandbox -X --profile=firefox /usr/bin/firefox Sandbox xeyes: -=over - -$ aa-sandbox -X /usr/bin/xeyes - -=back + $ aa-sandbox -X /usr/bin/xeyes Sandbox glxgears: -=over - -$ aa-sandbox -X --with-xserver=xpra3d /usr/bin/glxgears - -=back + $ aa-sandbox -X --with-xserver=xpra3d /usr/bin/glxgears Sandbox uptime: -=over - -$ aa-sandbox --read-path="/proc/*" /usr/bin/uptime - -=back + $ aa-sandbox --read-path="/proc/*" /usr/bin/uptime =head1 NOTES @@ -152,19 +132,15 @@ xhost access controls need to be enabled and server interpreted values for localuser must be removed. One way of achieving this is adding a late running Xsession(5) script of the form: -=over + # Create an Xauthority file if it doesn't exist -# Create an Xauthority file if it doesn't exist + [ ! -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xauth ] && + xauth generate :0 . trusted > /dev/null -[ ! -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xauth ] && - xauth generate :0 . trusted > /dev/null + # Default to the Xauthority file -# Default to the Xauthority file - -[ -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xhost ] && [ -x /usr/bin/id ] && - xhost -si:localuser:`id -un` > /dev/null - -=back + [ -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xhost ] && [ -x /usr/bin/id ] && + xhost -si:localuser:`id -un` > /dev/null After adding the above, it is recommended you remove the existing ~/.Xauthority file, then restart your session. @@ -176,27 +152,27 @@ of limitations regarding both confinement and usability: =over -As mentioned, the quality of the template or the specified profile directly +=item * As mentioned, the quality of the template or the specified profile directly affects the application's confinement. -DBus system access is all or nothing and DBus session access is unconditionally +=item * DBus system access is all or nothing and DBus session access is unconditionally allowed. -No environment filtering is performed. +=item * No environment filtering is performed. -X server usage has not been fully audited (though simple attacks are believed +=item * X server usage has not been fully audited (though simple attacks are believed to be protected against when the system is properly setup. See B, above). -Using a nested X server for each application is expensive. +=item * Using a nested X server for each application is expensive. -Only the old X cursor is available with B and B. +=item * Only the old X cursor is available with B and B. -The Ubuntu global menu is not currently supported. Gtk and Qt applications +=item * The Ubuntu global menu is not currently supported. Gtk and Qt applications should display the non-global menu by default, but applications like Firefox and Thunderbird should be adjusted to disable the global menu. -Xpra does not handle screen resizing when hotplugging monitors gracefully. +=item * Xpra does not handle screen resizing when hotplugging monitors gracefully. Restarting the sandbox will resolve the issue. =back diff --git a/utils/logprof.conf.pod b/utils/logprof.conf.pod index dee85ea5d..b50c138dd 100644 --- a/utils/logprof.conf.pod +++ b/utils/logprof.conf.pod @@ -61,7 +61,7 @@ own hat. The B<[globs]> section allows modification of the logprof rule engine with respect to globbing suggestions that the user will be prompted with. -The format of each line is-- " = ". +The format of each line is-- "Eperl globE = Eapparmor globE". When aa-logprof(1) asks about a specific path, if the perl glob matches the path, it replaces the part of the path that matched with the corresponding diff --git a/utils/vim/Makefile b/utils/vim/Makefile index 4e1057cb8..b0a616c3a 100644 --- a/utils/vim/Makefile +++ b/utils/vim/Makefile @@ -25,7 +25,7 @@ install: apparmor.vim manpages $(MAKE) install_manpages DESTDIR=${DESTDIR} .PHONY: check -check: +check: check_pod_files #Testing with all pythons $(call pyalldo, create-apparmor.vim.py > /dev/null)