[apparmor] PATCH: apparmor.d man page

Tue Jun 7 22:47:30 UTC 2016

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 <seth.arnold at canonical.com>
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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 473 bytes
Desc: not available
URL: <https://lists.ubuntu.com/archives/apparmor/attachments/20160607/d045f917/attachment.pgp>