[apparmor] [Patch] Document profile flags and module parameters

Fri Oct 20 20:11:12 UTC 2017

Hello,

Am Freitag, 20. Oktober 2017, 10:18:24 CEST schrieb John Johansen:
> === 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
...
> +=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>
> +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.

removed in 2.5 (and not documented until now) IMHO translates to "don't 
document this" ;-) so please just drop this paragraph.

> +=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

... profile mode _flag is given,_ the default

> I<enforce> will +be used.
> +
> +=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.
> +
> +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 +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 use of the keyword is not currently supported but can be achieved
> by +removing profile mode keywords for the profile flags.

You mention allow, stop and kill, but don't describe them. Besides that, 
the 2.11.1 parser doesn't accept these keywords.

Maybe you should just remove them from the "conflicts with" lists of both 
items?

> +=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.

... default_ is ...   or   ... defaults _to_ ...

If you write "default is /", you should also describe how to change that 
to something like /disconnected/. I'm not aware how to do this, so 
either I have to learn something, or you should rewrite the text ;-)

> +WARNING: it is not recommend that this option be used because it can

This sentence will cause headache ;-) Please use something like

    using this option is not recommended because ...

or if you want a smaller change

    it is not recommend _to use_ this option _ because ...

> result +in disconnected paths aliasing real path names, which can
> result in security +problems.
> +
> +The proper solution is almost always to uses delegation or

... to use_ ...

> disconnected +path rules. If this option is used the disconnect_root
> should be set to a +value other than the default of "/".

Once more - how to set disconnect_root?
And what are disconnected path rules?

> @@ -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. 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

"The setting these values" doesn't parse for me. I'd guess you meant 
something like "how to set them", so what about

    The full set of possible parameters and how to set them are 
    documented below.

> +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

Does this include quieting of audit rules? If so, I'd add
    (even for audit rules)

> +=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 noisy and it is recommended to use
> the per profile flag instead. +

... per profile _"audit"_ flag ...

> +  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.

IIRC this can be disabled in the kernel config, so please add a note like

    This is only available if your kernel was compiled with the WHATEVER 
    flag.

(obviously you'll need to replace WHATEVER with the real name of the 
config option)

> +=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

Are kill and unconfined mode described somewhere?

All that said - thanks for working on the documentation!

Regards,

Christian Boltz
-- 
> Weil es seit Jahrzehnten ging?
Ich denke wir beide haben sehr unterschiedliche Definitionen von "geht".
Ne Pferdekutsche "geht" auch, trotzdem fahren die meisten eher Auto.
[> Stephan von Krawczynski und Michael Meyer in opensuse-de]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: This is a digitally signed message part.
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20171020/90348918/attachment.sig>