← Back to branch summary

~apparmor-dev/apparmor/apparmor-ubuntu-citrain-trusty

« back to all changes in this revision

Viewing changes to utils/aa-sandbox.pod

  • Committer: Seth Arnold
  • Date: 2014-03-12 02:05:16 UTC
  • mto: This revision was merged to the branch mainline in revision 1496.
  • Revision ID: seth.arnold@canonical.com-20140312020516-zjike3pmw6hi861h
[ Jamie Strandboge ]
 * debian/debhelper/dh_apparmor: exit with error if aa-easyprof does not
   exist
 * debian/control: drop Depends on apparmor-easyprof to Suggests for
   dh-apparmor
[ Seth Arnold, Jamie Strandboge, Steve Beattie, John Johansen, Tyler Hicks ]
* New upstream snapshot (LP: #1278702, #1061693, #1285653) dropping very
  large Ubuntu delta and fixing the following bugs:
  - Adjust fonts abstraction for libthai (LP: #1278702)
  - Support translated XDG user directories (LP: #1061693)
  - Adjust abstractions/web-data to include /var/www/html (LP: #1285653)
    Refresh 0002-add-debian-integration-to-lighttpd.patch to include
    /etc/lighttpd/conf-available/*.conf
  - Adjust debian/libapparmor1.symbols to reflect new upstream versioning
    for the aa_query_label() function
  - Raise exceptions in Python bindings when something fails
* ship new Python replacements for previous Perl-based tools
  - debian/apparmor-utils.install: remove usr/share/perl5/Immunix/*.pm and add
    usr/sbin/aa-autodep, usr/sbin/aa-cleanprof and usr/sbin/aa-mergeprof
  - debian/control:
    + remove various Perl dependencies
    + add python-apparmor and python3-apparmor
    + python3-apparmor Breaks: apparmor-easyprof to move the file since it
      ships dist-packages/apparmor/__init__.py now
  - debian/apparmor-utils.manpages: ship new manpages for aa-cleanprof and
    aa-mergeprof
  - debian/rules: build and install Python tools
* debian/apparmor.install:
  - install apparmorfs, dovecot, kernelvars, securityfs, sys,
    and xdg-user-dirs tunables and xdg-user-dirs.d directory
* debian/apparmor.dirs:
  - install /etc/apparmor.d/tunables/xdg-user-dirs.d
* debian/apparmor.postinst: create xdg-user-dirs.d
* debian/apparmor.postrm: remove xdg-user-dirs.d
* Remaining patches:
  - 0001-add-chromium-browser.patch
  - 0002-add-debian-integration-to-lighttpd.patch
  - 0003-ubuntu-manpage-updates.patch
  - 0004-libapparmor-layout-deb.patch (renamed from 0008)
  - 0005-libapparmor-mention-dbus-method-in-getcon-man.patch (renamed from
    0068)
  - 0006-etc-writable.patch (renamed from 0070)
  - 0007-aa-utils_are_bilingual.patch (renamed from 0077)
  - 0008-remove-ptrace.patch
  - 0009-convert-to-rules.patch
  - 0010-list-fns.patch
  - 0011-parse-mode.patch
  - 0012-add-decimal-interp.patch
  - 0013-policy_mediates.patch
  - 0014-fix-failpath.patch
  - 0015-feature_file.patch
  - 0016-fix-network.patch
  - 0017-aare-to-class.patch
  - 0018-add-mediation-unix.patch
  - 0019-parser_version.patch
  - 0020-caching.patch
  - 0021-label-class.patch
  - 0022-signal.patch
  - 0023-fix-lexer-debug.patch
  - 0024-ptrace.patch
  - 0025-use-diff-encode.patch
  - 0026-fix-serialize.patch
  - 0027-fix-af.patch
  - 0028-opt_arg.patch
  - 0029-tests-cond-dbus.patch
  - 0030-tests.diff
* Move manpages from libapparmor1 to libapparmor-dev
  - debian/libapparmor-dev.manpages: install aa_change_hat.2,
    aa_change_profile.2, aa_find_mountpoint.2, aa_getcon.2
  - debian/control: libapparmor-dev Replaces: and Breaks: libapparmor1
* Move /usr/lib/python3/dist-packages/apparmor/__init__.py from
  apparmor-easyprof to python3-apparmor
  - debian/control: python3-apparmor Breaks: apparmor-easyprof
  - debian/apparmor-easyprof.install: remove
    usr/lib/python*.*/site-packages/apparmor*
* New profiles and abstractions:
  - debian/apparmor.install: tunables/dovecot, tunables/kernelvars,
    tunables/xdg-user-dirs, tunables/xdg-user-dirs.d
* Test merge from upstream new pyutils branch (rev 2385)

Show diffs side-by-side

added added

removed removed

Lines of Context:
utils/aa-sandbox.pod
 
1
# This publication is intellectual property of Canonical Ltd. Its contents
 
2
# can be duplicated, either in part or in whole, provided that a copyright
 
3
# label is visibly located on each copy.
 
4
#
 
5
# All information found in this book has been compiled with utmost
 
6
# attention to detail. However, this does not guarantee complete accuracy.
 
7
# Neither Canonical Ltd, the authors, nor the translators shall be held
 
8
# liable for possible errors or the consequences thereof.
 
9
#
 
10
# Many of the software and hardware descriptions cited in this book
 
11
# are registered trademarks. All trade names are subject to copyright
 
12
# restrictions and may be registered trade marks. Canonical Ltd
 
13
# essentially adheres to the manufacturer's spelling.
 
14
#
 
15
# Names of products and trademarks appearing in this book (with or without
 
16
# specific notation) are likewise subject to trademark and trade protection
 
17
# laws and may thus fall under copyright restrictions.
 
18
#
 
19
 
 
20
=pod
 
21
 
 
22
=head1 NAME
 
23
 
 
24
aa-sandbox - AppArmor sandboxing
 
25
 
 
26
=head1 SYNOPSIS
 
27
 
 
28
B<aa-sandbox> [option] <path to binary>
 
29
 
 
30
=head1 DESCRIPTION
 
31
 
 
32
B<aa-sandbox> provides a mechanism for sandboxing an application using an
 
33
existing profile or via dynamic profile generation. Please note that while this
 
34
tool can help with quickly confining an application, its utility is dependent on
 
35
the quality of the templates, policy groups and abstractions used. Also, this
 
36
tool may create policy which is less restrictive than creating policy by hand or
 
37
with B<aa-genprof> and B<aa-logprof>.
 
38
 
 
39
=head1 OPTIONS
 
40
 
 
41
B<aa-sandbox> accepts the following arguments:
 
42
 
 
43
=over 4
 
44
 
 
45
=item -t TEMPLATE, --template=TEMPLATE
 
46
 
 
47
Specify the template used to generate a profile. May specify either a system
 
48
template or a filename for the template to use. If not specified, uses
 
49
B<sandbox> or B<sandbox-x> when B<-X> is specified. See aa-easyprof(8) for
 
50
details. Privileged access is required to load the dynamically generated
 
51
profile (B<aa-sandbox> will prompt for a password).
 
52
 
 
53
=item -p POLICYGROUPS, --policy-groups=POLICYGROUPS
 
54
 
 
55
Specify POLICYGROUPS as a comma-separated list of policy groups. See
 
56
aa-easyprof(8) for more information on POLICYGROUPS.
 
57
 
 
58
=item -a ABSTRACTIONS, --abstractions=ABSTRACTIONS
 
59
 
 
60
Specify ABSTRACTIONS as a comma-separated list of AppArmor abstractions.
 
61
AppArmor abstractions are located in /etc/apparmor.d/abstractions. See
 
62
apparmor.d(5) for details.
 
63
 
 
64
=item -r PATH, --read-path=PATH
 
65
 
 
66
Specify a PATH to allow reads. May be specified multiple times. If the PATH
 
67
ends in a '/', then PATH is treated as a directory and reads are allowed to all
 
68
files under this directory. Can optionally use '/*' at the end of the PATH to
 
69
only allow reads to files directly in PATH.
 
70
 
 
71
=item -w PATH, --write-dir=PATH
 
72
 
 
73
Like --read-path but also allow writes in addition to reads.
 
74
 
 
75
=item --profile=PROFILE
 
76
 
 
77
Instead of generating a dynamic profile, specify an existing, loaded profile.
 
78
This does not require privileged access.
 
79
 
 
80
=item -X, --with-x
 
81
 
 
82
Run the sandboxed application in an isolated X server.
 
83
 
 
84
=item --with-xauthority=XAUTHORITY
 
85
 
 
86
Specify an Xauthority file to use rather than a dynamically generated one. This
 
87
is particularly useful in combination with --profile. This option must be used
 
88
with care to not allow too much access to the sandboxed application. In
 
89
particular, the profile specified with --profile must add a rule to deny access
 
90
to ~/.Xauthority for X sandboxing to be effective. Eg:
 
91
 
 
92
=over
 
93
 
 
94
audit deny @{HOME}/.Xauthority mrwlk,
 
95
 
 
96
=back
 
97
 
 
98
=item --with-xserver=XSERVER
 
99
 
 
100
Choose the nested XSERVER to use. Supported servers are: B<xpra> (the default),
 
101
B<xpra3d> and B<xephyr>. xpra uses the Xvfb(1) virtual framebuffer X server
 
102
while xpra3d uses the Xorg(1) server with the Xdummy (dummy_drv.so) driver.
 
103
 
 
104
=item --with-clipboard
 
105
 
 
106
Allow access to the clipboard when using B<xpra> or B<xpra3d>.
 
107
 
 
108
=item --with-xephyr-geometry=GEOMETRY
 
109
 
 
110
The starting geometry for the Xephyr(1) server to use.
 
111
 
 
112
=back
 
113
 
 
114
=head1 EXAMPLES
 
115
 
 
116
Use the existing system profile 'firefox' to sandbox /usr/bin/firefox:
 
117
 
 
118
=over
 
119
 
 
120
$ aa-sandbox -X --profile=firefox /usr/bin/firefox
 
121
 
 
122
=back
 
123
 
 
124
Sandbox xeyes:
 
125
 
 
126
=over
 
127
 
 
128
$ aa-sandbox -X /usr/bin/xeyes
 
129
 
 
130
=back
 
131
 
 
132
Sandbox glxgears:
 
133
 
 
134
=over
 
135
 
 
136
$ aa-sandbox -X --with-xserver=xpra3d /usr/bin/glxgears
 
137
 
 
138
=back
 
139
 
 
140
Sandbox uptime:
 
141
 
 
142
=over
 
143
 
 
144
$ aa-sandbox --read-path="/proc/*" /usr/bin/uptime
 
145
 
 
146
=back
 
147
 
 
148
=head1 NOTES
 
149
 
 
150
B<aa-sandbox> currently relies on Xsecurity rules based on Xauthority. As such,
 
151
xhost access controls need to be enabled and server interpreted values for
 
152
localuser must be removed. One way of achieving this is adding a late running
 
153
Xsession(5) script of the form:
 
154
 
 
155
=over
 
156
 
 
157
# Create an Xauthority file if it doesn't exist
 
158
 
 
159
[ ! -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xauth ] &&
 
160
    xauth generate :0 . trusted > /dev/null
 
161
 
 
162
# Default to the Xauthority file
 
163
 
 
164
[ -f "$HOME/.Xauthority" ] && [ -x /usr/bin/xhost ] && [ -x /usr/bin/id ] &&
 
165
    xhost -si:localuser:`id -un` > /dev/null
 
166
 
 
167
=back
 
168
 
 
169
After adding the above, it is recommended you remove the existing ~/.Xauthority
 
170
file, then restart your session.
 
171
 
 
172
=head1 KNOWN LIMITATIONS
 
173
 
 
174
While B<aa-sandbox> may be useful in certain situations, there are a number
 
175
of limitations regarding both confinement and usability:
 
176
 
 
177
=over
 
178
 
 
179
As mentioned, the quality of the template or the specified profile directly
 
180
affects the application's confinement.
 
181
 
 
182
DBus system access is all or nothing and DBus session access is unconditionally
 
183
allowed.
 
184
 
 
185
No environment filtering is performed.
 
186
 
 
187
X server usage has not been fully audited (though simple attacks are believed
 
188
to be protected against when the system is properly setup. See B<NOTES>,
 
189
above).
 
190
 
 
191
Using a nested X server for each application is expensive.
 
192
 
 
193
Only the old X cursor is available with B<xpra> and B<xpra3d>.
 
194
 
 
195
The Ubuntu global menu is not currently supported. Gtk and Qt applications
 
196
should display the non-global menu by default, but applications like Firefox
 
197
and Thunderbird should be adjusted to disable the global menu.
 
198
 
 
199
Xpra does not handle screen resizing when hotplugging monitors gracefully.
 
200
Restarting the sandbox will resolve the issue.
 
201
 
 
202
=back
 
203
 
 
204
=head1 BUGS
 
205
 
 
206
If you find any bugs, please report them to Launchpad at
 
207
L<https://bugs.launchpad.net/apparmor/+filebug>.
 
208
 
 
209
=head1 SEE ALSO
 
210
 
 
211
apparmor(7) apparmor.d(5) aa-easyprof(8) Xorg(1) Xecurity(7) xpra(1) Xvfb(1)
 
212
Xephyr(1)
 
213
 
 
214
=cut