On 06/07/2016 03:30 PM, Christian Boltz wrote: > Hello, > > Am Dienstag, 7. Juni 2016, 13:46:46 CEST schrieb John Johansen: >> Add documentation of the profile flags and how to debug apparmor >> policy to the apparmor.d man page >> >> --- >> >> === modified file 'parser/apparmor.d.pod' >> --- parser/apparmor.d.pod 2016-06-01 20:55:14 +0000 >> +++ parser/apparmor.d.pod 2016-06-07 20:45:20 +0000 >> @@ -299,6 +299,109 @@ >> written or modified to use change_profile(2) transition permanently >> to the specified profile. libvirt is one such application. >> >> +=head2 Profile Flags >> + >> +The profile flags allow for quick global control over profile >> behavior +and some override rule qualifiers allowing for quick global >> changes +for profile debugging or development. While multiple profile >> flags can +be specified some of the flags conflict (see below). >> + >> +If profile flags are not specified a the default flag set will be >> + flags=(enforce, namespace_relative, no_attach_disconnected) >> + >> +=over 8 >> + >> +=head3 Profile Audit Flags >> + >> +=item B<audit> >> +places the profile in audit mode which will cause all allowed >> accesses to +be audited. This is equivalent to placing the audit > > I'd say denied accesses (covered by a deny rule) will also be audited, > so please clarify this detail. > In fact they won't. I even double checked this in the code
> Also, maybe s/audited/logged/ - or clarify what "audited" actually means > (the explanation should probably contain hints to audit.log, dmesg and, > as a fallback, syslog) > that feels like an entirely different section. As what AppArmor does for auditing/logging needs to be understood even with out this. >> qualifier on all +allow rules in the profile. >> + >> +=item B<debug> >> +obsoleted in apparmo 2.5 and may result in a parse error (tested on >> 2.8), +it will be reintroduced at some point in the future. See below >> I<Debugging + AppArmor Policy> for other options. > > I'd guess nobody remembers this flag, so I wonder if we should mention it > at all. > I have pared it down to removed in apparmor 2.5, nothing about reintroducing it. >> +=head3 Profile Mode Flags > > Instead of the "conflicts with" notes on every mode, would a paragraph > saying > The profile mode flags allow, complain, debug, enforce and kill > conflict with each other, so you can't use more than one. > > I'm not even sure if we need to name all the flags here because they are > listed below, so it could also be > The profile mode flags conflict with each other, so you can't use > more than one. > > (Do we need to mention "or none"?) > > With this, we could then change the "conflicts with" to > conflicts with other profile mode flags > to make the manpage easier to read and easier to maintain (if we ever > add another flag, we don't need to edit all > makes sense. Done >> +=item B<allow> -- conflicts with complain, debug, enforce, kill >> +places the profile in allow mode which will cause all denied accesses >> +to be audited and allowed. Allow mode is similar to complain mode >> except +that explicitly denied accesses are also allowed. >> + >> +Not supported in versions before AppArmor 3.6 > > We should make clear that the version number is about the kernel side - > otherwise users will be completely confused if userspace is still at > 2.11 ;-) > well there was some email about bumping the userspace version > Also, my testing shows that the 2.11 beta parser doesn't understand the > "allow" flag, so maybe we shouldn't document it yet? (Same question for > other flags, see below.) > it should land soon, but maybe we should let tyler add this blurb in his patches >> +=item B<complain> -- conflicts with allow, enforce, kill, stop >> +places the profile in complain mode which will cause all unknown >> accesses +to be audited and allowed. Complain mode is used for >> profile development +so that unknown accesses can be logged without >> affecting program behavior +as the default white listing behavior >> would. > >> It is important to note +that allow rules still >> auditing/quieting as specified and deny rules +and their >> auditing/quieting behavior is also still applied, so normally +known >> denials will not show up in the audit stream. > > I'd rephrase the second paragraph to something like > > Note that deny rules will be enforced even in complain mode. > > The auditing/quieting of existing allow and deny rules will be > applied, so known accesses and denials will not show up in the audit > stream (unless the rule contains B<audit>). > > This text isn't perfect (improvements welcome), but (IMHO) easier to > understand for normal users. > >> +Note: there is a known bug versions before AppArmor 4.0 where rules > > See version number note above. > >> with +a prefix with B<audit deny> will be treated as unknown >> accesses. + >> +=item B<enforce> DEFAULT -- conflicts with allow, complain, stop, >> kill +The default profile mode, if no profile mode flag is specified. >> It puts +the profile into a white listing mode that denies all >> unknown accesses. + >> +The user of the keyword is not supported in versions before AppArmor >> 4.0, +but can be achieved by removing profile mode keywords for the > > version number again > > Also, the 2.11 beta parser doesn't understand "enforce". > it will soon >> profile +flags. >> + >> +=item B<kill> -- conflicts with allow, complain, enforce, stop >> +Instead of logging denials, send a kill signal to the task. Note >> there +are some accesses where a task is not associated, in those >> cases no +kill signal will be sent. >> + >> +Not yet supported in versions before AppArmor 4.0 > > another version number > > Also, the 2.11 beta parser doesn't understand "kill". > >> +=item B<stop> -- conflicts with allow, complain, enforce, kill >> +A debug mode where a SIGSTOP or SIGSYS may be sent to the task for >> unknown +accesses. Note there are some accesses where a task is not >> associated, in +those case a signal will not be sent. >> + >> +Not yet supported in versions before AppArmor 4.0 > > and one more > > Also, the 2.11 beta parser doesn't understand "stop". > I've removed these two for now > BTW: The "stop" mode sounds like it could be useful for interactive > profile development - stop the process, ask about the access, update the > profile, continue the process. > yes >> +=head3 Profile Path Relative Flags >> + >> +The path relative flags control what file name resolution is relative >> to for +the profile. >> + >> +=item B<chroot_relative> -- conflicts with namespace_relative >> +Pathnames are relative to the base of the chroot and names outside of >> the +chroot are determined by the path attach flags. >> + >> +=item B<namespace_relative> DEFAULT -- conflicts with chroot_relative >> +Pathnames are relative to the namespace (not the chroot) with names >> outside +of the namespace are determined by the path attach flags. >> + >> +=head3 Profile Path Attach Flags >> + >> +The attach flags control how disconnected paths are handled. >> + >> +=item B<attach_disconnect> -- conflicts with no_attach_disconnected >> +Tells apparmor to attach disconnected paths to the disconnect_root >> (default is +"/"). by prepending its value to the disconnected path. >> + >> +WARNING: it is not recommend that this option be used because it can >> result +in disconnected paths aliasing real path names, which can >> result in security +problems. >> + >> +The proper solution is almost always to uses delegation or >> disconnected +path rules. If this option is used the disconnect_root >> should be set to a +value other than the default of "/". > > Silly question - how do I set the disconnect_root? Or is this a not-yet- > implemented feature? > the patches are hanging around I just need to push them out > Same question about "disconnected path rules" - IIRC I've never seen > them. > these are still a wip. I am not really a fan othe them but they are better than nothing until I can land delegation, and that is not something I can see happening this year. > (On a general note, the manpage should only document things that are > available to the user. "man crystalball" might be an exception ;-) > meh, I have pulled out most of the future reference stuff >> +=item B<no_attach_disconnected> DEFAULT -- conflicts with >> attach_disconnected + >> +Disconnected paths are not attached, or mediated via file pathname >> rules. + > > The parser tests also contain mediate_deleted, delegate_deleted, > chroot_no_attach and chroot_attach. Some documentation for them would be > nice ;-) > no :) They are deprecated, and indeed delegate_deleted doesn't even work, the less they are documented and the sooner they go away the better. I will leave it at that. >> =head2 Access Modes >> >> File permission access modes consists of combinations of the >> following @@ -318,6 +421,8 @@ >> >> - append -- conflicts with write >> >> + >> + >> =item B<ux> >> >> - unconfined execute >> @@ -1572,6 +1677,99 @@ >> >> =back >> >> +=head1 Debugging AppArmor Policy >> + >> +=over 4 >> + >> +In addition to setting profile mode flags AppArmor provides a few >> global +controls that can help in debugging how policy is being >> enforced. To use +these controls the policy author must have >> sufficient privilege to +manage policy for the namespace. >> + >> +The most useful are the I<noquiet> audit value, and turning on the >> +debug parameters. These two values should suffice in most situations. >> +The setting these values and the full set of possible parameters are >> +documented below. >> + >> +=head2 /sys/module/apparmor/parameters/audit >> + >> +The audit paramenter allows controlling of how auditing is applied, >> it +can be in any of the follow states. >> + >> +=item B<normal> - auditing behaves as specified in the profile >> +=item B<quiet_denied> - there is no auditing of denials >> +=item B<quiet> - auditing is disabled >> +=item B<noquiet> - rule quieting is not used so explit denies will be >> logged +=item B<all> - all access whether allowed or denied are >> logged. Warning this +mode is very noise and it is recommended the >> per profile flag is used instead. + > > ... it is recommended _to use_ the per profile flag__instead. > meh, either actually works but your suggestion is probably better >> + Eg. >> + $cat /sys/module/apparmor/parameters/audit >> + normal >> + $echo -n "noquiet" E<gt> /sys/module/apparmor/parameters/audit >> + $cat /sys/module/apparmor/parameters/audit >> + noquiet >> + >> +=head2 /sys/module/apparmor/parameters/debug >> + >> +The boolean debug parameter turns on logging of extra information to >> the +kernel ring buffer (dmesg). This primarily contains information >> for domain +transitions like scrubbing of environment variables, >> clearing of unsafe +personality bits and seccomp's no-new-privs mode. >> + >> + Eg. >> + $cat /sys/module/apparmor/parameters/debug >> + N >> + $echo Y > /sys/module/apparmor/parameters/debug >> + $cat /sys/module/apparmor/parameters/debug >> + Y >> + >> +=head2 /sys/module/apparmor/parameters/enabled >> + >> +The boolean enabled parameter allows checking if the AppArmor kernel >> +module is enabled. It is recommneded that the user uses aa-enabled(8) >> +or the api aa_is_enabled(2) to do this check as they provide more >> +information other requirements for AppArmor policy to be enforced. + > > ...more information _about_ other requirements... ? > >> +=head2 /sys/module/apparmor/parameters/lock_policy >> + >> +The boolean lock_policy parameter allows checking if policy loads >> have +been locked this preventing further changes to AppArmor policy. > > ...locked_,_ th_u_s preventing... > >> + Eg. >> + $cat /sys/module/apparmor/parameters/lock_policy >> + N >> + $echo Y > /sys/module/apparmor/parameters/lock_policy >> + $cat /sys/module/apparmor/parameters/lock_policy >> + Y > > Some quick testing shows that after setting this to Y it can't be > changed back. This makes sense, but should be documented. > > It would also be nice if apparmor_parser would error out with a more > helpful error message (not just "permission denied") when the policy is > locked ;-) > >> +=head2 sys/module/apparmor/parameters/mode > > _/_sys/... > >> +The mode parameter allows overriding the profiles enforcement mode. >> + >> +=item B<enforce> - enfoce profile as specified by its flags >> +=item B<complain> - put all profiles into complain mode >> +=item B<kill> - put all profiles into kill mode >> +=item B<unconfined> - put all profiles into unconfined mode >> + >> + Eg. >> + $cat /sys/module/apparmor/parameters/mode >> + enforce >> + $echo -n "complain" E<gt> /sys/module/apparmor/parameters/mode >> + $cat /sys/module/apparmor/parameters/mode >> + complain >> + >> +=head2 /sys/module/apparmor/parameters/path_max >> + >> +The path_max parameter allows discovering the current maximum length >> +for path name resolution >> + >> + Eg. >> + $cat /sys/module/apparmor/parameters/path_max >> + 8192 > > Besides my comments above - apparmor.d(5) is titled "syntax of security > profiles for AppArmor". > > All those /sys/module/apparmor details are not really related to that, > so maybe they should be in their own manpage? > Something like "apparmor.sys"? (better names welcome) > I am not opposed to moving them into their own man page but I don't think having information about debugging/developing a profile is out of place here. I am going to leave it here for now, but if we get some more info together we can look at moving it over.
signature.asc
Description: OpenPGP digital signature
-- AppArmor mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
