[apparmor] [PATCH] man page updates for signals, ptrace and new variables

Wed Apr 2 22:17:55 UTC 2014

On 04/02/2014 02:23 PM, Jamie Strandboge wrote:
> Subject says it all. Thanks to John for starting this.
> 
> -- Jamie Strandboge http://www.ubuntu.com/
> 

So this looks good and can go in as is, but I think adding the clarification
I've added below might avoid some questions in the future.

Acked-by: John Johansen <john.johansen at canonical.com>

> 
> 0001-manpage-signal-ptrace.diff
> 
> 
> === modified file 'parser/apparmor.d.pod'
> --- parser/apparmor.d.pod	2013-12-06 19:18:17 +0000
> +++ parser/apparmor.d.pod	2014-04-02 21:23:32 +0000
> @@ -3,7 +3,7 @@
>  #                  2008, 2009
>  #    NOVELL (All rights reserved)
>  #
> -#    Copyright (c) 2010 - 2013
> +#    Copyright (c) 2010 - 2014
>  #    Canonical Ltd. (All rights reserved)
>  #
>  #    This program is free software; you can redistribute it and/or
> @@ -99,6 +99,32 @@
>  
>  B<MOUNT EXPRESSION> = ( I<ALPHANUMERIC> | I<AARE> ) ...
>  
> +B<PTRACE_RULE> = [ 'audit' ] [ 'deny' ] 'ptrace' [ I<PTRACE ACCESS PERMISSIONS> ] [ I<PTRACE PEER> ]
> +
> +B<PTRACE ACCESS PERMISSIONS> = I<PTRACE ACCESS> | I<PTRACE ACCESS LIST>
> +
> +B<PTRACE ACCESS LIST> = '(' Comma or space separated list of I<PTRACE ACCESS> ')'
> +
> +B<PTRACE ACCESS> = ( 'r' | 'w' | 'rw' | 'read' | 'readby' | 'trace' | 'tracedby' )
> +
> +B<PTRACE PEER> = 'peer' '=' I<AARE>
> +
> +B<SIGNAL_RULE> = [ 'audit' ] [ 'deny' ] 'signal' [ I<SIGNAL ACCESS PERMISSIONS> ] [ I<SIGNAL SET> ] [ I<SIGNAL PEER> ]
> +
> +B<SIGNAL ACCESS PERMISSIONS> = I<SIGNAL ACCESS> | I<SIGNAL ACCESS LIST>
> +
> +B<SIGNAL ACCESS LIST> = '(' Comma or space separated list of I<SIGNAL ACCESS> ')'
> +
> +B<SIGNAL ACCESS> = ( 'r' | 'w' | 'rw' | 'read' | 'write' | 'send' | 'receive' )
> +
> +B<SIGNAL SET> = 'set' '=' '(' I<SIGNAL LIST> ')'
> +
> +B<SIGNAL LIST> = Comma or space separated list of I<SIGNALS>
> +
> +B<SIGNALS> = ( 'hup' | 'int' | 'quit' | 'ill' | 'trap' | 'abrt' | 'bus' | 'fpe' | 'kill' | 'usr1' | 'segv' | 'usr2' | 'pipe' | 'alrm' | 'term' | 'stkflt' | 'chld' | 'cont' | 'stop' | 'stp' | 'ttin' | 'ttou' | 'urg' | 'xcpu' | 'xfsz' | 'vtalrm' | 'prof' | 'winch' | 'io' | 'pwr' | 'sys' | 'emt' | 'exists' )
> +
> +B<SIGNAL PEER> = 'peer' '=' I<AARE>
> +
>  B<DBUS RULE> = ( I<DBUS MESSAGE RULE> | I<DBUS SERVICE RULE> | I<DBUS EAVESDROP RULE> | I<DBUS COMBINED RULE> )
>  
>  B<DBUS MESSAGE RULE> = [ 'audit' ] [ 'deny' ] 'dbus' [ I<DBUS ACCESS EXPRESSION> ] [ I<DBUS BUS> ] [ I<DBUS PATH> ] [ I<DBUS INTERFACE> ] [ I<DBUS MEMBER> ] [ I<DBUS PEER> ]
> @@ -655,6 +681,66 @@
>  
>  =back
>  
> +=head2 PTrace rules
> +
> +AppArmor supports mediation of ptrace(2). AppArmor PTrace rules are accumulated
> +so that the granted PTrace permissions are the union of all the listed PTrace
> +rule permissions.
> +
> +AppArmor PTrace permissions are implied when a rule does not explicitly state
> +an access list. By default, all PTrace permissions are implied.
> +
> +The trace and tracedby permissions govern ptrace(2) while read and readby
> +govern certain proc(5) filesystem accesses, kcmp(2), futexes
> +(get_robust_list(2)) and perf trace events.
> +
For a ptrace operation to be allowed the profile of the tracing process and the
profile of the target task must both have the correct permissions. For example
the profile of the process attaching to another task must have the trace
permission for the target task's profile, and the task being traced must have the
tracedby permission for the tracing process' profile.

> +Example AppArmor PTrace rules:
> +
> +    # Allow all PTrace access
> +    ptrace,
> +
> +    # Explicitly allow all PTrace access,
> +    ptrace (read, readby, trace, tracedby),
> +
> +    # Explicitly deny use of ptrace(2)
> +    deny ptrace (trace),
> +
> +    # Allow unconfined processes (eg, a debugger) to ptrace us
> +    ptrace (readby, tracedby) peer=unconfined,
> +
> +    # Allow ptrace of a process running under the /usr/bin/foo profile
> +    ptrace (trace) peer=/usr/bin/foo,
> +
> +=head2 Signal rules
> +
> +AppArmor supports mediation of signal(7). AppArmor signal rules are accumulated
> +so that the granted signal permissions are the union of all the listed signal
> +rule permissions.
> +
> +AppArmor signal permissions are implied when a rule does not explicitly state
> +an access list. By default, all signal permissions are implied.
> +
For the sending of a signal to be allowed, the profile of the sending process and
the profile of the target task must both have the correct permissions. For example
the profile of a process sending a signal to another task must have the send
permission for the target task's profile, and the task receiving the signal must
have a receive permission for the sending process' profile.

> +Example AppArmor signal rules:
> +
> +    # Allow all signal access
> +    signal,
> +
> +    # Explicitly deny sending the HUP and INT signals
> +    deny signal (send) set=(hup, int),
> +
> +    # Allow unconfined processes to send us signals
> +    signal (receive) peer=unconfined,
> +
> +    # Allow sending of signals to a process running under the /usr/bin/foo
> +    # profile
> +    signal (send) peer=/usr/bin/foo,
> +
> +    # Allow checking for PID existence
> +    signal (receive, send) set=("exists"),
> +
> +    # Allow us to signal ourselves using the built-in @{profile_name} variable
> +    signal peer=@{profile_name},
> +
>  =head2 DBus rules
>  
>  AppArmor supports DBus mediation. The mediation is performed in conjunction
> @@ -725,11 +811,36 @@
>  that they have been assigned; it is an error to reference a variable
>  without setting at least one value.
>  
> -At the time of this writing, only B<@{HOME}> and B<@{HOMEDIRS}> are defined
> -in the AppArmor policy provided, in the F</etc/apparmor.d/tunables/home>
> -file; these variables are used in many of the abstractions described later.
> +At the time of this writing, the following variables are defined in the
> +provided AppArmor policy:
> +
> +  @{HOME}
> +  @{HOMEDIRS}
> +  @{multiarch}
> +  @{pid}
> +  @{PROC}
> +  @{securityfs}
> +  @{sys}
> +  @{tid}
> +  @{XDG_DESKTOP_DIR}
> +  @{XDG_DOWNLOAD_DIR}
> +  @{XDG_TEMPLATES_DIR}
> +  @{XDG_PUBLICSHARE_DIR}
> +  @{XDG_DOCUMENTS_DIR}
> +  @{XDG_MUSIC_DIR}
> +  @{XDG_PICTURES_DIR}
> +  @{XDG_VIDEOS_DIR}
> +
> +These are defined in files in F</etc/apparmor.d/tunables> and are used in many
> +of the abstractions described later.
> +
>  You may also add files in F</etc/apparmor.d/tunables/home.d> for
> -site-specific customization of B<@{HOMEDIRS}>.
> +site-specific customization of B<@{HOMEDIRS}>,
> +F</etc/apparmor.d/tunables/multiarch.d> for B<@{multiarch}> and
> +F</etc/apparmor.d/tunables/xdg-user-dirs.d> for B<@{XDG_*}>.
> +
> +The special B<@{profile_name}> variable is set to the profile name and may be
> +used in all policy.
>  
>  =head2 Alias rules
>  
> 
> 
> 
> -- AppArmor mailing list AppArmor at lists.ubuntu.com Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/apparmor
> 