# 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 [option] =head1 DESCRIPTION B 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 and B. =head1 OPTIONS B 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 or B when B<-X> is specified. See aa-easyprof(8) for details. Privileged access is required to load the dynamically generated profile (B 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: =over audit deny @{HOME}/.Xauthority mrwlk, =back =item --with-xserver=XSERVER Choose the nested XSERVER to use. Supported servers are: B (the default), B and B. 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 or B. =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: =over $ aa-sandbox -X --profile=firefox /usr/bin/firefox =back Sandbox xeyes: =over $ aa-sandbox -X /usr/bin/xeyes =back Sandbox glxgears: =over $ aa-sandbox -X --with-xserver=xpra3d /usr/bin/glxgears =back Sandbox uptime: =over $ aa-sandbox --read-path="/proc/*" /usr/bin/uptime =back =head1 NOTES B 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: =over # 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 =back After adding the above, it is recommended you remove the existing ~/.Xauthority file, then restart your session. =head1 KNOWN LIMITATIONS While B may be useful in certain situations, there are a number of limitations regarding both confinement and usability: =over As mentioned, the quality of the template or the specified profile directly affects the application's confinement. DBus system access is all or nothing and DBus session access is unconditionally allowed. No environment filtering is performed. 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, above). Using a nested X server for each application is expensive. Only the old X cursor is available with B and B. 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. =back =head1 BUGS If you find any bugs, please report them to Launchpad at L. =head1 SEE ALSO apparmor(7) apparmor.d(5) aa-easyprof(8) Xorg(1) Xecurity(7) xpra(1) Xvfb(1) Xephyr(1) =cut