mirror of
https://gitlab.com/apparmor/apparmor.git
synced 2025-03-04 00:14:44 +01:00
c48d7dc71f
This patch adds a 'check_pod_files' make target to the common make
rules, and then fixes the errors it highlighted as well as most of
the warnings. It will cause 'make check' in most of the directories to
fail if there are errors in a pod file (but not if there are warnings).
Common issues were:
- using an '=over/=back' pair for code-like snippets that did not
contain any =items therein; the =over keyword is intended for
indenting lists of =item entries, and generates a warning if
there isn't any.
- not escaping '<' or '>'
- blank lines that contained spaces or tabs
The second -warnings flag passed to podchecker is to add additional
warnings, un-escaped '<' and '>' being of them.
I did not fix all of the warnings in apparmor.d.pod, as I have not come
up with a good warning-free way to express the BNF of the language
similar in format to what is currently generated. The existing
libapparmor warnings (complaints about duplicate =item definition
names) are actually a result of passing the second -warnings flag.
The integration into libapparmor is suboptimal due to automake's
expectation that there will be a test driver program(s) for make check
targets; that's why I added the podchecker call to the manpage
generation point.
Signed-off-by: Steve Beattie <steve@nxnw.org>
Acked-by: Seth Arnold <seth.arnold@canonical.com>
---
changehat/mod_apparmor/Makefile | 3
changehat/mod_apparmor/mod_apparmor.pod | 28 ++-
common/Make.rules | 4
libraries/libapparmor/doc/Makefile.am | 7
parser/Makefile | 2
parser/apparmor.d.pod | 275
+++++++++++++-------------------
utils/Makefile | 3
utils/aa-cleanprof.pod | 2
utils/aa-complain.pod | 2
utils/aa-decode.pod | 2
utils/aa-easyprof.pod | 69 +++-----
utils/aa-enforce.pod | 2
utils/aa-genprof.pod | 2
utils/aa-logprof.pod | 6
utils/aa-sandbox.pod | 64 ++-----
utils/logprof.conf.pod | 2
utils/vim/Makefile | 2
17 files changed, 212 insertions(+), 263 deletions(-)
190 lines
6.2 KiB
Text
190 lines
6.2 KiB
Text
# This publication is intellectual property of Canonical Ltd. Its contents
|
|
# can be duplicated, either in part or in whole, provided that a copyright
|
|
# label is visibly located on each copy.
|
|
#
|
|
# All information found in this book has been compiled with utmost
|
|
# attention to detail. However, this does not guarantee complete accuracy.
|
|
# Neither Canonical Ltd, the authors, nor the translators shall be held
|
|
# liable for possible errors or the consequences thereof.
|
|
#
|
|
# Many of the software and hardware descriptions cited in this book
|
|
# are registered trademarks. All trade names are subject to copyright
|
|
# restrictions and may be registered trade marks. Canonical Ltd
|
|
# essentially adheres to the manufacturer's spelling.
|
|
#
|
|
# Names of products and trademarks appearing in this book (with or without
|
|
# specific notation) are likewise subject to trademark and trade protection
|
|
# laws and may thus fall under copyright restrictions.
|
|
#
|
|
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
aa-sandbox - AppArmor sandboxing
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
B<aa-sandbox> [option] E<lt>path to binaryE<gt>
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
B<aa-sandbox> provides a mechanism for sandboxing an application using an
|
|
existing profile or via dynamic profile generation. Please note that while this
|
|
tool can help with quickly confining an application, its utility is dependent on
|
|
the quality of the templates, policy groups and abstractions used. Also, this
|
|
tool may create policy which is less restrictive than creating policy by hand or
|
|
with B<aa-genprof> and B<aa-logprof>.
|
|
|
|
=head1 OPTIONS
|
|
|
|
B<aa-sandbox> accepts the following arguments:
|
|
|
|
=over 4
|
|
|
|
=item -t TEMPLATE, --template=TEMPLATE
|
|
|
|
Specify the template used to generate a profile. May specify either a system
|
|
template or a filename for the template to use. If not specified, uses
|
|
B<sandbox> or B<sandbox-x> when B<-X> is specified. See aa-easyprof(8) for
|
|
details. Privileged access is required to load the dynamically generated
|
|
profile (B<aa-sandbox> will prompt for a password).
|
|
|
|
=item -p POLICYGROUPS, --policy-groups=POLICYGROUPS
|
|
|
|
Specify POLICYGROUPS as a comma-separated list of policy groups. See
|
|
aa-easyprof(8) for more information on POLICYGROUPS.
|
|
|
|
=item -a ABSTRACTIONS, --abstractions=ABSTRACTIONS
|
|
|
|
Specify ABSTRACTIONS as a comma-separated list of AppArmor abstractions.
|
|
AppArmor abstractions are located in /etc/apparmor.d/abstractions. See
|
|
apparmor.d(5) for details.
|
|
|
|
=item -r PATH, --read-path=PATH
|
|
|
|
Specify a PATH to allow reads. May be specified multiple times. If the PATH
|
|
ends in a '/', then PATH is treated as a directory and reads are allowed to all
|
|
files under this directory. Can optionally use '/*' at the end of the PATH to
|
|
only allow reads to files directly in PATH.
|
|
|
|
=item -w PATH, --write-dir=PATH
|
|
|
|
Like --read-path but also allow writes in addition to reads.
|
|
|
|
=item --profile=PROFILE
|
|
|
|
Instead of generating a dynamic profile, specify an existing, loaded profile.
|
|
This does not require privileged access.
|
|
|
|
=item -X, --with-x
|
|
|
|
Run the sandboxed application in an isolated X server.
|
|
|
|
=item --with-xauthority=XAUTHORITY
|
|
|
|
Specify an Xauthority file to use rather than a dynamically generated one. This
|
|
is particularly useful in combination with --profile. This option must be used
|
|
with care to not allow too much access to the sandboxed application. In
|
|
particular, the profile specified with --profile must add a rule to deny access
|
|
to ~/.Xauthority for X sandboxing to be effective. Eg:
|
|
|
|
audit deny @{HOME}/.Xauthority mrwlk,
|
|
|
|
=item --with-xserver=XSERVER
|
|
|
|
Choose the nested XSERVER to use. Supported servers are: B<xpra> (the default),
|
|
B<xpra3d> and B<xephyr>. xpra uses the Xvfb(1) virtual framebuffer X server
|
|
while xpra3d uses the Xorg(1) server with the Xdummy (dummy_drv.so) driver.
|
|
|
|
=item --with-clipboard
|
|
|
|
Allow access to the clipboard when using B<xpra> or B<xpra3d>.
|
|
|
|
=item --with-xephyr-geometry=GEOMETRY
|
|
|
|
The starting geometry for the Xephyr(1) server to use.
|
|
|
|
=back
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Use the existing system profile 'firefox' to sandbox /usr/bin/firefox:
|
|
|
|
$ aa-sandbox -X --profile=firefox /usr/bin/firefox
|
|
|
|
Sandbox xeyes:
|
|
|
|
$ aa-sandbox -X /usr/bin/xeyes
|
|
|
|
Sandbox glxgears:
|
|
|
|
$ aa-sandbox -X --with-xserver=xpra3d /usr/bin/glxgears
|
|
|
|
Sandbox uptime:
|
|
|
|
$ aa-sandbox --read-path="/proc/*" /usr/bin/uptime
|
|
|
|
=head1 NOTES
|
|
|
|
B<aa-sandbox> currently relies on Xsecurity rules based on Xauthority. As such,
|
|
xhost access controls need to be enabled and server interpreted values for
|
|
localuser must be removed. One way of achieving this is adding a late running
|
|
Xsession(5) script of the form:
|
|
|
|
# Create an Xauthority file if it doesn't exist
|
|
|
|
[ ! -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xauth ] &&
|
|
xauth generate :0 . trusted > /dev/null
|
|
|
|
# Default to the Xauthority file
|
|
|
|
[ -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xhost ] && [ -x /usr/bin/id ] &&
|
|
xhost -si:localuser:`id -un` > /dev/null
|
|
|
|
After adding the above, it is recommended you remove the existing ~/.Xauthority
|
|
file, then restart your session.
|
|
|
|
=head1 KNOWN LIMITATIONS
|
|
|
|
While B<aa-sandbox> may be useful in certain situations, there are a number
|
|
of limitations regarding both confinement and usability:
|
|
|
|
=over
|
|
|
|
=item * As mentioned, the quality of the template or the specified profile directly
|
|
affects the application's confinement.
|
|
|
|
=item * DBus system access is all or nothing and DBus session access is unconditionally
|
|
allowed.
|
|
|
|
=item * No environment filtering is performed.
|
|
|
|
=item * X server usage has not been fully audited (though simple attacks are believed
|
|
to be protected against when the system is properly setup. See B<NOTES>,
|
|
above).
|
|
|
|
=item * Using a nested X server for each application is expensive.
|
|
|
|
=item * Only the old X cursor is available with B<xpra> and B<xpra3d>.
|
|
|
|
=item * The Ubuntu global menu is not currently supported. Gtk and Qt applications
|
|
should display the non-global menu by default, but applications like Firefox
|
|
and Thunderbird should be adjusted to disable the global menu.
|
|
|
|
=item * Xpra does not handle screen resizing when hotplugging monitors gracefully.
|
|
Restarting the sandbox will resolve the issue.
|
|
|
|
=back
|
|
|
|
=head1 BUGS
|
|
|
|
If you find any bugs, please report them to Launchpad at
|
|
L<https://bugs.launchpad.net/apparmor/+filebug>.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
apparmor(7) apparmor.d(5) aa-easyprof(8) Xorg(1) Xecurity(7) xpra(1) Xvfb(1)
|
|
Xephyr(1)
|
|
|
|
=cut
|