[apparmor] PATCH: apparmor.d man page

[Christian Boltz]

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.

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)

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

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

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

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

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

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

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.

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

Same question about "disconnected path rules" - IIRC I've never seen 
them.

(On a general note, the manpage should only document things that are 
available to the user. "man crystalball" might be an exception ;-)

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

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

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


Regards,

Christian Boltz

PS: overlong sig - gut given the size of this mail, I hope nobody will 
    complain ;-)
-- 
Wenn Du dermaleinst Deinen Enkeln von Deinen Erlebnissen im Usenet
erzählst, daß Du also einmal ganz unschuldig eine einfache Frage
gestellt hast, und schilderst, wie Du daraufhin wegen Deiner Tastatur,
Einleitungszeile und allem möglichen anderen Kram angemacht wurdest,
aber niemand auch nur im Traum daran dachte, die Frage zu beantworten,
dann kannst Du fortfahren mit dem Satz "Also frage ich noch einmal ganz
brav, ob jemand ein oben genanntes Tool kenne", wobei Du auch noch das
perfektische Präsens verwendest, durch das die Erzählung lebendiger
wirkt als in einer grammatikalischen Vergangenheitsform - ein weiteres
jener unzähligen Details, an denen ein Grammatikprüfprogramm zuverlässig
scheitern wird, abgesehen von all den anderen Problemen, die es mit
einem Satz wie diesem voraussichtlich ohnehin haben wird, an dem man
übrigens auch sehen kann, warum im Deutschen im Gegensatz zu manch
anderen Sprachen, in denen die Sätze kürzer zu sein pflegen, die Groß-
und Kleinschreibung wichtig ist.   [Ralf Bader in desd]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: This is a digitally signed message part.
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20160608/857e83b8/attachment-0001.pgp>