diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 258 |
1 files changed, 1 insertions, 257 deletions
@@ -34,260 +34,4 @@ FAQ: https://firejail.wordpress.com/support/frequently-asked-questions/ | |||
34 | ````` | 34 | ````` |
35 | 35 | ||
36 | ````` | 36 | ````` |
37 | # Current development version: 0.9.40~rc2 | 37 | # Current development version: 0.9.41 |
38 | Version 0.9.40-rc1 released! | ||
39 | |||
40 | ## X11 sandboxing support | ||
41 | |||
42 | X11 support is built around Xpra (http://xpra.org/) or Xephyr. | ||
43 | ````` | ||
44 | --x11 Start a new X11 server using Xpra or Xephyr and attach the sand‐ | ||
45 | box to this server. The regular X11 server (display 0) is not | ||
46 | visible in the sandbox. This prevents screenshot and keylogger | ||
47 | applications started in the sandbox from accessing other X11 | ||
48 | displays. A network namespace needs to be instantiated in order | ||
49 | to deny access to X11 abstract Unix domain socket. | ||
50 | |||
51 | Firejail will try first Xpra, and if Xpra is not installed on | ||
52 | the system, it will try to find Xephyr. This feature is not | ||
53 | available when running as root. | ||
54 | |||
55 | Example: | ||
56 | $ firejail --x11 --net=eth0 firefox | ||
57 | |||
58 | --x11=xpra | ||
59 | Start a new X11 server using Xpra (http://xpra.org) and attach | ||
60 | the sandbox to this server. Xpra is a persistent remote display | ||
61 | server and client for forwarding X11 applications and desktop | ||
62 | screens. On Debian platforms Xpra is installed with the command | ||
63 | sudo apt-get install xpra. This feature is not available when | ||
64 | running as root. | ||
65 | |||
66 | Example: | ||
67 | $ firejail --x11 --net=eth0 firefox | ||
68 | |||
69 | --x11=xephyr | ||
70 | Start a new X11 server using Xephyr and attach the sandbox to | ||
71 | this server. Xephyr is a display server implementing the X11 | ||
72 | display server protocol. It runs in a window just like other X | ||
73 | applications, but it is an X server itself in which you can run | ||
74 | other software. The default Xephyr window size is 800x600. This | ||
75 | can be modified in /etc/firejail/firejail.config file, see man 5 | ||
76 | firejail-config for more details. | ||
77 | |||
78 | The recommended way to use this feature is to run a window man‐ | ||
79 | ager inside the sandbox. A security profile for OpenBox is pro‐ | ||
80 | vided. On Debian platforms Xephyr is installed with the command | ||
81 | sudo apt-get install xserver-xephyr. This feature is not avail‐ | ||
82 | able when running as root. | ||
83 | |||
84 | Example: | ||
85 | $ firejail --x11 --net=eth0 openbox | ||
86 | ````` | ||
87 | More information here: https://firejail.wordpress.com/documentation-2/x11-guide/ | ||
88 | |||
89 | ## File transfers | ||
90 | ````` | ||
91 | FILE TRANSFER | ||
92 | These features allow the user to inspect the filesystem container of an | ||
93 | existing sandbox and transfer files from the container to the host | ||
94 | filesystem. | ||
95 | |||
96 | --get=name filename | ||
97 | Retrieve the container file and store it on the host in the cur‐ | ||
98 | rent working directory. The container is specified by name | ||
99 | (--name option). Full path is needed for filename. | ||
100 | |||
101 | --get=pid filename | ||
102 | Retrieve the container file and store it on the host in the cur‐ | ||
103 | rent working directory. The container is specified by process | ||
104 | ID. Full path is needed for filename. | ||
105 | |||
106 | --ls=name dir_or_filename | ||
107 | List container files. The container is specified by name | ||
108 | (--name option). Full path is needed for dir_or_filename. | ||
109 | |||
110 | --ls=pid dir_or_filename | ||
111 | List container files. The container is specified by process ID. | ||
112 | Full path is needed for dir_or_filename. | ||
113 | |||
114 | Examples: | ||
115 | |||
116 | $ firejail --name=mybrowser --private firefox | ||
117 | |||
118 | $ firejail --ls=mybrowser ~/Downloads | ||
119 | drwxr-xr-x netblue netblue 4096 . | ||
120 | drwxr-xr-x netblue netblue 4096 .. | ||
121 | -rw-r--r-- netblue netblue 7847 x11-x305.png | ||
122 | -rw-r--r-- netblue netblue 6800 x11-x642.png | ||
123 | -rw-r--r-- netblue netblue 34139 xpra-clipboard.png | ||
124 | |||
125 | $ firejail --get=mybrowser ~/Downloads/xpra-clipboard.png | ||
126 | ````` | ||
127 | |||
128 | ## Firecfg | ||
129 | ````` | ||
130 | NAME | ||
131 | Firecfg - Desktop configuration program for Firejail software. | ||
132 | |||
133 | SYNOPSIS | ||
134 | firecfg [OPTIONS] | ||
135 | |||
136 | DESCRIPTION | ||
137 | Firecfg is the desktop configuration utility for Firejail software. The | ||
138 | utility creates several symbolic links to firejail executable. This | ||
139 | allows the user to sandbox applications automatically, just by clicking | ||
140 | on a regular desktop menus and icons. | ||
141 | |||
142 | The symbolic links are placed in /usr/local/bin. For more information, | ||
143 | see DESKTOP INTEGRATION section in man 1 firejail. | ||
144 | |||
145 | OPTIONS | ||
146 | --clean | ||
147 | Remove all firejail symbolic links | ||
148 | |||
149 | -?, --help | ||
150 | Print options end exit. | ||
151 | |||
152 | --list List all firejail symbolic links | ||
153 | |||
154 | --version | ||
155 | Print program version and exit. | ||
156 | |||
157 | Example: | ||
158 | |||
159 | $ sudo firecfg | ||
160 | /usr/local/bin/firefox created | ||
161 | /usr/local/bin/vlc created | ||
162 | [...] | ||
163 | $ firecfg --list | ||
164 | /usr/local/bin/firefox | ||
165 | /usr/local/bin/vlc | ||
166 | [...] | ||
167 | $ sudo firecfg --clean | ||
168 | /usr/local/bin/firefox removed | ||
169 | /usr/local/bin/vlc removed | ||
170 | [...] | ||
171 | ````` | ||
172 | |||
173 | |||
174 | ## Compile time and run time configuration support | ||
175 | |||
176 | Most Linux kernel security features require root privileges during configuration. | ||
177 | The same is true for kernel networking features. Firejail (SUID binary) opens the | ||
178 | access to these features to regular users. The privilege escalation is restricted | ||
179 | to the sandbox being configured, and is not extended to the rest of the system. | ||
180 | This arrangement works fine for user desktops or servers where the access is already limited. | ||
181 | |||
182 | If you not happy with a particular feature, all the support can be eliminated from SUID binary at compile time, | ||
183 | or at run time by editing /etc/firejail/firejail.config file. | ||
184 | |||
185 | The following features can be enabled or disabled: | ||
186 | ````` | ||
187 | bind Enable or disable bind support, default enabled. | ||
188 | |||
189 | chroot Enable or disable chroot support, default enabled. | ||
190 | |||
191 | file-transfer | ||
192 | Enable or disable file transfer support, default enabled. | ||
193 | |||
194 | network | ||
195 | Enable or disable networking features, default enabled. | ||
196 | |||
197 | restricted-network | ||
198 | Enable or disable restricted network support, default disabled. | ||
199 | If enabled, networking features should also be enabled (network | ||
200 | yes). Restricted networking grants access to --interface, | ||
201 | --net=ethXXX and --netfilter only to root user. Regular users | ||
202 | are only allowed --net=none. Default disabled | ||
203 | |||
204 | secomp Enable or disable seccomp support, default enabled. | ||
205 | |||
206 | userns Enable or disable user namespace support, default enabled. | ||
207 | |||
208 | x11 Enable or disable X11 sandboxing support, default enabled. | ||
209 | |||
210 | force-nonewprivs | ||
211 | Force use of theh NO_NEW_PRIVS prctl(2) flag. | ||
212 | This mitigates the possibility of a user abusing firejail's | ||
213 | features to trick a privileged (suid or file capabilities) | ||
214 | process into loading code or configuration that is partially | ||
215 | under their control. Default disabled | ||
216 | |||
217 | xephyr-screen | ||
218 | Screen size for --x11=xephyr, default 800x600. Run | ||
219 | /usr/bin/xrandr for a full list of resolutions available on your | ||
220 | specific setup. Examples: | ||
221 | |||
222 | xephyr-screen 640x480 | ||
223 | xephyr-screen 800x600 | ||
224 | xephyr-screen 1024x768 | ||
225 | xephyr-screen 1280x1024 | ||
226 | ````` | ||
227 | |||
228 | ## Default seccomp filter update | ||
229 | |||
230 | Currently 50 syscalls are blacklisted by default, out of a total of 318 calls (AMD64, Debian Jessie). | ||
231 | |||
232 | ## STUN/WebRTC disabled in default netfilter configuration | ||
233 | |||
234 | The current netfilter configuration (--netfilter option) looks like this: | ||
235 | ````` | ||
236 | *filter | ||
237 | :INPUT DROP [0:0] | ||
238 | :FORWARD DROP [0:0] | ||
239 | :OUTPUT ACCEPT [0:0] | ||
240 | -A INPUT -i lo -j ACCEPT | ||
241 | -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT | ||
242 | # allow ping | ||
243 | -A INPUT -p icmp --icmp-type destination-unreachable -j ACCEPT | ||
244 | -A INPUT -p icmp --icmp-type time-exceeded -j ACCEPT | ||
245 | -A INPUT -p icmp --icmp-type echo-request -j ACCEPT | ||
246 | # drop STUN (WebRTC) requests | ||
247 | -A OUTPUT -p udp --dport 3478 -j DROP | ||
248 | -A OUTPUT -p udp --dport 3479 -j DROP | ||
249 | -A OUTPUT -p tcp --dport 3478 -j DROP | ||
250 | -A OUTPUT -p tcp --dport 3479 -j DROP | ||
251 | COMMIT | ||
252 | ````` | ||
253 | |||
254 | The filter is loaded by default for Firefox if a network namespace is configured: | ||
255 | ````` | ||
256 | $ firejail --net=eth0 firefox | ||
257 | ````` | ||
258 | |||
259 | ## Set sandbox nice value | ||
260 | ````` | ||
261 | --nice=value | ||
262 | Set nice value for all processes running inside the sandbox. | ||
263 | |||
264 | Example: | ||
265 | $ firejail --nice=-5 firefox | ||
266 | ````` | ||
267 | |||
268 | ## mkdir | ||
269 | |||
270 | ````` | ||
271 | $ man firejail-profile | ||
272 | [...] | ||
273 | mkdir directory | ||
274 | Create a directory in user home. Use this command for | ||
275 | whitelisted directories you need to preserve when the sandbox is | ||
276 | closed. Subdirectories also need to be created using mkdir. | ||
277 | Example from firefox profile: | ||
278 | |||
279 | mkdir ~/.mozilla | ||
280 | whitelist ~/.mozilla | ||
281 | mkdir ~/.cache | ||
282 | mkdir ~/.cache/mozilla | ||
283 | mkdir ~/.cache/mozilla/firefox | ||
284 | whitelist ~/.cache/mozilla/firefox | ||
285 | |||
286 | [...] | ||
287 | ````` | ||
288 | |||
289 | ## New security profiles | ||
290 | lxterminal, Epiphany, cherrytree, Polari, Vivaldi, Atril, qutebrowser, SlimJet, Battle for Wesnoth, Hedgewars, qTox, | ||
291 | OpenSSH client, OpenBox window manager, Dillo, cmus, dnsmasq, PaleMoon, Icedove, abrowser, 0ad, netsurf, | ||
292 | Warzone2100, okular, gwenview, Gpredict, Aweather, Stellarium, Google-Play-Music-Desktop-Player, quiterss, | ||
293 | cyberfox, generic Ubuntu snap application profile, xplayer, xreader, xviewer, mcabber, Psi+, Corebird, Konversation, Brave | ||