diff options
Diffstat (limited to 'README.md')
-rw-r--r-- | README.md | 263 |
1 files changed, 35 insertions, 228 deletions
@@ -31,255 +31,62 @@ Features: https://firejail.wordpress.com/features-3/ | |||
31 | Documentation: https://firejail.wordpress.com/documentation-2/ | 31 | Documentation: https://firejail.wordpress.com/documentation-2/ |
32 | 32 | ||
33 | FAQ: https://firejail.wordpress.com/support/frequently-asked-questions/ | 33 | FAQ: https://firejail.wordpress.com/support/frequently-asked-questions/ |
34 | ````` | ||
35 | |||
36 | ````` | ||
37 | # Current development version: 0.9.40-rc2 | ||
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 | 34 | ||
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 | ````` | 35 | ````` |
127 | 36 | ||
128 | ## Firecfg | ||
129 | ````` | 37 | ````` |
130 | NAME | 38 | ## User submitted profile repositories |
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 | 39 | ||
142 | The symbolic links are placed in /usr/local/bin. For more information, | 40 | If you keep your Firejail profiles in a public repository, please give us a link: |
143 | see DESKTOP INTEGRATION section in man 1 firejail. | ||
144 | 41 | ||
145 | OPTIONS | 42 | * https://github.com/chiraag-nataraj/firejail-profiles |
146 | --clear | ||
147 | Clear all firejail symbolic links | ||
148 | 43 | ||
149 | -?, --help | 44 | * https://github.com/triceratops1/fe |
150 | Print options end exit. | ||
151 | 45 | ||
152 | --list List all firejail symbolic links | 46 | Use this issue to request new profiles: https://github.com/netblue30/firejail/issues/825 |
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 --clear | ||
168 | /usr/local/bin/firefox removed | ||
169 | /usr/local/bin/vlc removed | ||
170 | [...] | ||
171 | ````` | 47 | ````` |
172 | 48 | ||
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 | ````` | 49 | ````` |
187 | bind Enable or disable bind support, default enabled. | 50 | # Current development version: 0.9.45 |
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 and | ||
201 | --net=ethXXX only to root user. Regular users are only allowed | ||
202 | --net=none. | ||
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 | xephyr-screen | ||
211 | Screen size for --x11=xephyr, default 800x600. Run | ||
212 | /usr/bin/xrandr for a full list of resolutions available on your | ||
213 | specific setup. Examples: | ||
214 | |||
215 | xephyr-screen 640x480 | ||
216 | xephyr-screen 800x600 | ||
217 | xephyr-screen 1024x768 | ||
218 | xephyr-screen 1280x1024 | ||
219 | ````` | 51 | ````` |
220 | 52 | ||
221 | ## Default seccomp filter update | ||
222 | |||
223 | Currently 50 syscalls are blacklisted by default, out of a total of 318 calls (AMD64, Debian Jessie). | ||
224 | |||
225 | ## STUN/WebRTC disabled in default netfilter configuration | ||
226 | |||
227 | The current netfilter configuration (--netfilter option) looks like this: | ||
228 | ````` | 53 | ````` |
229 | *filter | 54 | ## AppImage type 2 support |
230 | :INPUT DROP [0:0] | ||
231 | :FORWARD DROP [0:0] | ||
232 | :OUTPUT ACCEPT [0:0] | ||
233 | -A INPUT -i lo -j ACCEPT | ||
234 | -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT | ||
235 | # allow ping | ||
236 | -A INPUT -p icmp --icmp-type destination-unreachable -j ACCEPT | ||
237 | -A INPUT -p icmp --icmp-type time-exceeded -j ACCEPT | ||
238 | -A INPUT -p icmp --icmp-type echo-request -j ACCEPT | ||
239 | # drop STUN (WebRTC) requests | ||
240 | -A OUTPUT -p udp --dport 3478 -j DROP | ||
241 | -A OUTPUT -p udp --dport 3479 -j DROP | ||
242 | -A OUTPUT -p tcp --dport 3478 -j DROP | ||
243 | -A OUTPUT -p tcp --dport 3479 -j DROP | ||
244 | COMMIT | ||
245 | ````` | 55 | ````` |
246 | 56 | ||
247 | The filter is loaded by default for Firefox if a network namespace is configured: | ||
248 | ````` | ||
249 | $ firejail --net=eth0 firefox | ||
250 | ````` | 57 | ````` |
251 | 58 | ## New command line options | |
252 | ## Set sandbox nice value | ||
253 | ````` | 59 | ````` |
254 | --nice=value | 60 | --private-opt=file,directory |
255 | Set nice value for all processes running inside the sandbox. | 61 | Build a new /opt in a temporary filesystem, and copy the files |
62 | and directories in the list. If no listed file is found, /opt | ||
63 | directory will be empty. All modifications are discarded when | ||
64 | the sandbox is closed. | ||
256 | 65 | ||
257 | Example: | 66 | Example: |
258 | $ firejail --nice=-5 firefox | 67 | $ firejail --private-opt=firefox /opt/firefox/firefox |
259 | ````` | ||
260 | |||
261 | ## mkdir | ||
262 | |||
263 | ````` | ||
264 | $ man firejail-profile | ||
265 | [...] | ||
266 | mkdir directory | ||
267 | Create a directory in user home. Use this command for | ||
268 | whitelisted directories you need to preserve when the sandbox is | ||
269 | closed. Subdirectories also need to be created using mkdir. | ||
270 | Example from firefox profile: | ||
271 | 68 | ||
272 | mkdir ~/.mozilla | 69 | --private-srv=file,directory |
273 | whitelist ~/.mozilla | 70 | Build a new /srv in a temporary filesystem, and copy the files |
274 | mkdir ~/.cache | 71 | and directories in the list. If no listed file is found, /srv |
275 | mkdir ~/.cache/mozilla | 72 | directory will be empty. All modifications are discarded when |
276 | mkdir ~/.cache/mozilla/firefox | 73 | the sandbox is closed. |
277 | whitelist ~/.cache/mozilla/firefox | ||
278 | 74 | ||
279 | [...] | 75 | Example: |
280 | ````` | 76 | # firejail --private-srv=www /etc/init.d/apache2 start |
281 | 77 | ||
282 | ## New security profiles | 78 | --machine-id |
283 | lxterminal, Epiphany, cherrytree, Polari, Vivaldi, Atril, qutebrowser, SlimJet, Battle for Wesnoth, Hedgewars, qTox, | 79 | Preserve id number in /etc/machine-id file. By default a new |
284 | OpenSSH client, OpenBox window manager, Dillo, cmus, dnsmasq, PaleMoon, Icedove, abrowser, 0ad | 80 | random id is generated inside the sandbox. |
285 | 81 | ||
82 | Example: | ||
83 | $ firejail --machine-id | ||
84 | ````` | ||
85 | ## New Profiles | ||
86 | xiphos, Tor Browser Bundle, display (imagemagik), Wire, mumble, zoom, Guayadeque, qemu, keypass2, | ||
87 | amarok, ark, atool, bleachbit, brasero, dolphin, dragon, elinks, enchant, exiftool, file-roller, gedit, | ||
88 | gjs, gnome-books, gnome-clocks, gnome-documents, gnome-maps, gnome-music, gnome-photos, gnome-weather, | ||
89 | goobox, gpa, gpg, gpg-agent, highlight, img2txt, k3b, kate, lynx, mediainfo, nautilus, odt2txt, pdftotext, | ||
90 | simple-scan, skanlite, ssh-agent, tracker, transmission-cli, transmission-show, w3m, xfburn, xpra, wget, | ||
91 | xed, pluma, Cryptocat, Bless, Gnome 2048, Gnome Calculator, Gnome Contacts, JD-GUI, Lollypop, MultiMC5, | ||
92 | PDFSam, Pithos, Xonotic, wireshark | ||