[apparmor] PATCH: apparmor.d man page

Thu Jun 9 07:43:34 UTC 2016

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.

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: OpenPGP digital signature
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20160609/6601b530/attachment-0001.pgp>