On Tue, Jun 07, 2016 at 01:46:46PM -0700, John Johansen wrote: > Add documentation of the profile flags and how to debug apparmor policy to > the apparmor.d man page
This is great, thanks! Acked-by: Seth Arnold <[email protected]> for all three branches. I've got some suggestions inline but feel free to commit this as-is if you want. > +=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 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. "apparmo 2.5" -- it feels like this should just get a mention of when this feature was (or will be) re-introduced rather than discuss the history. > + > +=head3 Profile Mode Flags > + > +=item B<allow> -- conflicts with complain, debug, enforce, kill "stop" is missing here, it's listed as conflicting below > +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 The language below is "Not yet supported" > + > +=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. "auditing/quieting" here feels awkward. I had to read it twice to understand it. Sorry, no suggestions for modification. > + > +Note: there is a known bug versions before AppArmor 4.0 where rules with > +a prefix with B<audit deny> will be treated as unknown accesses. "a known bug versions" -> "a known bug for versions" > + > +=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 profile > +flags. "user of the keyword" -> "use of the keyword" --- I'm surprised it's worth adding the "enforce" mode flag at all. > +=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 > + > +=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 Maybe it'd be easier to list which combinations of modes are valid, and what they accomplish. > + > + > +=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. "with names outside" isn't as clean as "and names outside" used in the paragraph above. > + > +=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 "/". This would be a nice place to show an example, once it works. :) > + > +=item B<no_attach_disconnected> DEFAULT -- conflicts with attach_disconnected > + > +Disconnected paths are not attached, or mediated via file pathname rules. "not attached or mediated" -- how does this work with e.g.: profile p { change_profile ** -> q, } profile q { ... } If a filedescriptor to bin/sh is available to a process executing in p will the change on exec happen? How about if it's written: change_profile -> q, ? or change_profile * -> q, ? > + > + > =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. "very noise" -> "very noisy" > + > + 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 > + I'd rather see "# " instead of "$" for the shell prompt in the examples. > +=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 The example above used E<gt> rather than > > + > +=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. > + > +=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. > + > + 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 > + > +=head2 sys/module/apparmor/parameters/mode > + > +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 It'd be nice to have here a small mention how we handle over-length filenames. (I can't recall recall if we fail with EPERM or ETOOLONG, so documenting it here would be handy. :) > + > + Eg. > + $cat /sys/module/apparmor/parameters/path_max > + 8192 > + > +=back > + Thanks
signature.asc
Description: PGP signature
-- AppArmor mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
