apparmor/utils/aa-sandbox.pod

# 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 Gitlab at
L<https://gitlab.com/apparmor/apparmor/-/issues>.

=head1 SEE ALSO

apparmor(7) apparmor.d(5) aa-easyprof(8) Xorg(1) Xecurity(7) xpra(1) Xvfb(1)
Xephyr(1)

=cut