On Fri, 2017-10-20 at 01:18 -0700, John Johansen wrote: > === modified file 'parser/apparmor.d.pod' > --- parser/apparmor.d.pod 2017-08-30 09:06:19 +0000 > +++ parser/apparmor.d.pod 2017-10-20 08:08:45 +0000 > @@ -299,6 +299,91 @@ > 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). > +
I suggest: The profile flags allow for quick global control of profile behavior and add some override rule qualifiers to allow for global changes when performing 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) > + Perhaps: If profile flags are unspecified, the default flag set is > +=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 qualifier on all > +allow rules in the profile. > + places the profile into audit mode which causes all allowed access to be audited.... > +=item B<debug> > +removed in apparmor 2.5 and may result in a parse error (tested on > 2.8), > +See below I<Debugging AppArmor Policy> for other options. > + > + > +=head3 Profile Mode Flags > + > +The profile mode flags conflict with each other, so you can't use > more > +than one. If no profile mode flags the default value of I<enforce> > will > +be used. > + You may only specify one profile mode flag at a time. If the profile mode flag is unspecified, the default profile flag of I<enforce> is used. > +=item B<complain> -- conflicts with allow, enforce, kill, stop With the rephrasing above, I think you can drop the 'conflicts with ...' since we clearly stated only one may be specified at a time. > +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. > + s/as the default white listing behavior would// > +Note that deny rules will be enforced even in complain mode. The > auditing > +and 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>). > + > +Note: there is a known bug where rules with a prefix with B<audit > deny> will > +be treated as unknown accesses. > + > +=item B<enforce> DEFAULT -- conflicts with allow, complain, stop, > kill ditto wrt conflicts with... > +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 default profile mode when the profile mode flag is unspecified. Enforce mode operates as a whitelist where all unknown accesses are denied. > + > +The use of the keyword is not currently supported but can be > achieved by > +removing profile mode keywords for the profile flags. > + > +=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) and 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. Where is disconnect_root documented? The next section implies it is settable... > + > +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 "/". While I understand why this is the case, this is very strong language considering the current limitations wrt disconnected paths. Unfortunately, we've had to use it for a long time in click and snappy. :\ > +=item B<no_attach_disconnected> DEFAULT -- conflicts with > attach_disconnected > + > +Disconnected paths are not attached or mediated via file pathname > rules. > + > + > =head2 Access Modes > > File permission access modes consists of combinations of the > following > @@ -318,6 +403,8 @@ > > - append -- conflicts with write > > + > + > =item B<ux> > > - unconfined execute > @@ -1572,6 +1659,103 @@ > > =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. In addition to profile mode flags, Apparmor provides additional global controls to aid in debugging policy enforcement. > To use > +these controls the policy author must have sufficient privilege to > +manage policy for the namespace. s/controls/controls,/ That said, how is this different from managing any other aspect of policy? In other words, you always (today) need sufficient privilege to manage policy, why are you calling it out here 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. s/value,/value/ > +The setting these values and the full set of possible parameters are > +documented below. > + The setting of these as well as the full set... > +=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. The audit parameter allows controlling how auditing is applied and can be set to one of the following: > + > +=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 I suggest switching the order like so: =item B<quiet> - all auditing is disabled =item B<quiet_denied> - auditing of denials is disabled > +=item B<noquiet> - rule quieting is not used so explit denies will > be logged =item B<noquiet> - rule quieting is disabled (ie, explit denies will be logged) > +=item B<all> - all access whether allowed or denied are logged. =item B<all> - all allowed and denied accesses are logged > Warning this > +mode is very noisy and it is recommended to use the per profile flag > instead. > + > + 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 > + s/#/# / > +=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 E<gt> /sys/module/apparmor/parameters/debug > + #cat /sys/module/apparmor/parameters/debug > + Y > + s/#/# / > +=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 and other requirements (such as whether securityfs is > +mounted) for AppArmor policy to be enforced. > + The boolean enabled parameter reports if the AppArmor kernel module is enabled. In general, either the aa-enabled(8) command or the aa_is_enabled(2) API should be used instead since they will very other requirements are met for policy enforcement. > +=head2 /sys/module/apparmor/parameters/lock_policy > + > +The boolean lock_policy parameter allows checking if policy loads > have > +been locked, thus preventing further changes to AppArmor policy. > Once > +locked the flag can not be toggled back to an unlocked state. This only implies that lock_policy is settable. The boolean lock_policy parameter reports if policy loads are locked. Setting lock_policy to 'Y' locks the policy such that it may not be changed and the flag may not be toggled back to the unlocked state. > + > + Eg. > + #cat /sys/module/apparmor/parameters/lock_policy > + N > + #echo Y E<gt> /sys/module/apparmor/parameters/lock_policy > + #cat /sys/module/apparmor/parameters/lock_policy > + Y > + s/#/s# / > +=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 s/enfoce/enforce/ > +=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 > + s/#/# / > +=head2 /sys/module/apparmor/parameters/path_max > + > +The path_max parameter allows discovering the current maximum length > +for path name resolution. The path_max value can only be set on > boot. > +Paths longer than the maximum value will result in access requests > that > +are denied with ETOOLONG. > + > + Eg. > + #cat /sys/module/apparmor/parameters/path_max > + 8192 > + > +=back > + > =head1 KNOWN BUGS > > =over 4 > > -- Jamie Strandboge | http://www.canonical.com
signature.asc
Description: This is a digitally signed message part
-- AppArmor mailing list AppArmor@lists.ubuntu.com Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
