aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md284
1 files changed, 174 insertions, 110 deletions
diff --git a/README.md b/README.md
index 22e2fa291..09a3276e6 100644
--- a/README.md
+++ b/README.md
@@ -1,79 +1,91 @@
1# Firejail 1# Firejail
2[![Build Status](https://gitlab.com/Firejail/firejail_ci/badges/master/pipeline.svg)](https://gitlab.com/Firejail/firejail_ci/pipelines/) 2
3[![CodeQL](https://github.com/netblue30/firejail/workflows/CodeQL/badge.svg)](https://github.com/netblue30/firejail/actions?query=workflow%3ACodeQL) 3[![Build CI (GitLab)](https://gitlab.com/Firejail/firejail_ci/badges/master/pipeline.svg)](https://gitlab.com/Firejail/firejail_ci/pipelines)
4[![Build CI](https://github.com/netblue30/firejail/workflows/Build%20CI/badge.svg)](https://github.com/netblue30/firejail/actions?query=workflow%3A%22Build+CI%22) 4[![Build CI (GitHub)](https://github.com/netblue30/firejail/workflows/Build%20CI/badge.svg)](https://github.com/netblue30/firejail/actions?query=workflow%3A%22Build+CI%22)
5[![Packaging status](https://repology.org/badge/tiny-repos/firejail.svg)](https://repology.org/project/firejail/versions) 5[![CodeQL CI](https://github.com/netblue30/firejail/workflows/CodeQL/badge.svg)](https://github.com/netblue30/firejail/actions?query=workflow%3ACodeQL)
6 6[![Packaging status (Repology)](https://repology.org/badge/tiny-repos/firejail.svg)](https://repology.org/project/firejail/versions)
7Firejail is a SUID sandbox program that reduces the risk of security breaches by restricting 7
8the running environment of untrusted applications using Linux namespaces, seccomp-bpf 8Firejail is a SUID sandbox program that reduces the risk of security breaches
9and Linux capabilities. It allows a process and all its descendants to have their own private 9by restricting the running environment of untrusted applications using Linux
10view of the globally shared kernel resources, such as the network stack, process table, mount table. 10namespaces, seccomp-bpf and Linux capabilities. It allows a process and all
11Firejail can work in a SELinux or AppArmor environment, and it is integrated with Linux Control Groups. 11its descendants to have their own private view of the globally shared kernel
12 12resources, such as the network stack, process table, mount table. Firejail can
13Written in C with virtually no dependencies, the software runs on any Linux computer with a 3.x kernel 13work in a SELinux or AppArmor environment, and it is integrated with Linux
14version or newer. It can sandbox any type of processes: servers, graphical applications, and even 14Control Groups.
15user login sessions. The software includes sandbox profiles for a number of more common Linux programs, 15
16Written in C with virtually no dependencies, the software runs on any Linux
17computer with a 3.x kernel version or newer. It can sandbox any type of
18processes: servers, graphical applications, and even user login sessions. The
19software includes sandbox profiles for a number of more common Linux programs,
16such as Mozilla Firefox, Chromium, VLC, Transmission etc. 20such as Mozilla Firefox, Chromium, VLC, Transmission etc.
17 21
18The sandbox is lightweight, the overhead is low. There are no complicated configuration files to edit, 22The sandbox is lightweight, the overhead is low. There are no complicated
19no socket connections open, no daemons running in the background. All security features are 23configuration files to edit, no socket connections open, no daemons running in
20implemented directly in Linux kernel and available on any Linux computer. 24the background. All security features are implemented directly in Linux kernel
25and available on any Linux computer.
26
27## Videos
21 28
22<table><tr> 29<table>
30<tr>
23 31
24<td> 32<td>
25<a href="https://odysee.com/@netblue30:9/firefox:c" target="_blank"> 33<a href="https://odysee.com/@netblue30:9/firefox:c" target="_blank">
26<img src="https://thumbs.odycdn.com/acf4b1c66737feb97640fb1d28a7daa6.png" 34<img src="https://thumbs.odycdn.com/acf4b1c66737feb97640fb1d28a7daa6.png"
27alt="Advanced Browser Security" width="240" height="142" border="10" /><br/>Advanced Browser Security</a> 35alt="Advanced Browser Security" width="240" height="142" border="10" />
36<br/>Advanced Browser Security
37</a>
28</td> 38</td>
29 39
30<td> 40<td>
31<a href="https://odysee.com/@netblue30:9/nonet:7" target="_blank"> 41<a href="https://odysee.com/@netblue30:9/nonet:7" target="_blank">
32<img src="https://thumbs.odycdn.com/5be2964201c31689ee8f78cb9f35e89a.png" 42<img src="https://thumbs.odycdn.com/5be2964201c31689ee8f78cb9f35e89a.png"
33alt="How To Disable Network Access" width="240" height="142" border="10" /><br/>How To Disable Network Access</a> 43alt="How To Disable Network Access" width="240" height="142" border="10" />
44<br/>How To Disable Network Access
45</a>
34</td> 46</td>
35 47
36<td> 48<td>
37<a href="https://odysee.com/@netblue30:9/divested:2" target="_blank"> 49<a href="https://odysee.com/@netblue30:9/divested:2" target="_blank">
38<img src="https://thumbs.odycdn.com/f30ece33a6547af9ae48244f4ba73028.png" 50<img src="https://thumbs.odycdn.com/f30ece33a6547af9ae48244f4ba73028.png"
39alt="Deep Dive" width="240" height="142" border="10" /><br/>Deep Dive</a> 51alt="Deep Dive" width="240" height="142" border="10" />
52<br/>Deep Dive
53</a>
40</td> 54</td>
41 55
42</tr></table> 56</tr>
43 57</table>
44Project webpage: https://firejail.wordpress.com/
45
46IRC: https://web.libera.chat/#firejail
47
48Download and Installation: https://firejail.wordpress.com/download-2/
49
50Features: https://firejail.wordpress.com/features-3/
51 58
52Documentation: https://firejail.wordpress.com/documentation-2/ 59## Links
53 60
54FAQ: https://github.com/netblue30/firejail/wiki/Frequently-Asked-Questions 61* Project webpage: <https://firejail.wordpress.com/>
55 62* IRC: <https://web.libera.chat/#firejail>
56Wiki: https://github.com/netblue30/firejail/wiki 63* Download and Installation: <https://firejail.wordpress.com/download-2/>
57 64* Features: <https://firejail.wordpress.com/features-3/>
58GitLab-CI status: https://gitlab.com/Firejail/firejail_ci/pipelines/ 65* Documentation: <https://firejail.wordpress.com/documentation-2/>
59 66* FAQ: <https://github.com/netblue30/firejail/wiki/Frequently-Asked-Questions>
60Video Channel: https://odysee.com/@netblue30:9?order=new 67* Wiki: <https://github.com/netblue30/firejail/wiki>
61 68* GitHub Actions: <https://github.com/netblue30/firejail/actions>
62Backup Video Channel: https://www.bitchute.com/profile/JSBsA1aoQVfW/ 69* GitLab CI: <https://gitlab.com/Firejail/firejail_ci/pipelines>
70* Video Channel: <https://odysee.com/@netblue30:9?order=new>
71* Backup Video Channel: <https://www.bitchute.com/profile/JSBsA1aoQVfW/>
63 72
64## Security vulnerabilities 73## Security vulnerabilities
65 74
66We take security bugs very seriously. If you believe you have found one, please report it by emailing us at netblue30@protonmail.com 75See [SECURITY.md](SECURITY.md).
67 76
68## Installing 77## Installing
69 78
70### Debian 79### Debian
71 80
72Debian stable (bullseye): We recommend to use the [backports](https://packages.debian.org/bullseye-backports/firejail) package. 81Debian stable (bullseye): We recommend to use the
82[backports](https://packages.debian.org/bullseye-backports/firejail) package.
73 83
74### Ubuntu 84### Ubuntu
75 85
76For Ubuntu 18.04+ and derivatives (such as Linux Mint), users are **strongly advised** to use the [PPA](https://launchpad.net/~deki/+archive/ubuntu/firejail). 86For Ubuntu 18.04+ and derivatives (such as Linux Mint), users are **strongly
87advised** to use the
88[PPA](https://launchpad.net/~deki/+archive/ubuntu/firejail).
77 89
78How to add and install from the PPA: 90How to add and install from the PPA:
79 91
@@ -83,140 +95,186 @@ sudo apt-get update
83sudo apt-get install firejail firejail-profiles 95sudo apt-get install firejail firejail-profiles
84``` 96```
85 97
86Reason: The firejail package for Ubuntu 20.04 has been left vulnerable to CVE-2021-26910 for months after a patch for it was posted on Launchpad: 98Reason: The firejail package for Ubuntu 20.04 has been left vulnerable to
99CVE-2021-26910 for months after a patch for it was posted on Launchpad:
87 100
88* [firejail version in Ubuntu 20.04 LTS is vulnerable to CVE-2021-26910](https://bugs.launchpad.net/ubuntu/+source/firejail/+bug/1916767) 101* [CVE-2021-26910](https://github.com/advisories/GHSA-2q4h-h5jp-942w)
102* [firejail version in Ubuntu 20.04 LTS is vulnerable to
103 CVE-2021-26910](https://bugs.launchpad.net/ubuntu/+source/firejail/+bug/1916767)
89 104
90See also <https://wiki.ubuntu.com/SecurityTeam/FAQ>: 105See also <https://wiki.ubuntu.com/SecurityTeam/FAQ>:
91 106
92> What software is supported by the Ubuntu Security team? 107> What software is supported by the Ubuntu Security team?
93> 108>
94> Ubuntu is currently divided into four components: main, restricted, universe 109> Ubuntu is currently divided into four components: main, restricted, universe
95> and multiverse. All binary packages in main and restricted are supported by 110> and multiverse. All binary packages in main and restricted are supported by
96> the Ubuntu Security team for the life of an Ubuntu release, while binary 111> the Ubuntu Security team for the life of an Ubuntu release, while binary
97> packages in universe and multiverse are supported by the Ubuntu community. 112> packages in universe and multiverse are supported by the Ubuntu community.
98 113
99Additionally, the PPA version is likely to be more recent and to contain more profile fixes. 114Additionally, the PPA version is likely to be more recent and to contain more
115profile fixes.
100 116
101See the following discussions for details: 117See the following discussions for details:
102 118
103* [Should I keep using the version of firejail available in my distro repos?](https://github.com/netblue30/firejail/discussions/4666) 119* [Should I keep using the version of firejail available in my distro
104* [How to install the latest version on Ubuntu and derivatives](https://github.com/netblue30/firejail/discussions/4663) 120 repos?](https://github.com/netblue30/firejail/discussions/4666)
121* [How to install the latest version on Ubuntu and
122 derivatives](https://github.com/netblue30/firejail/discussions/4663)
105 123
106### Other 124### Other
107 125
108Firejail is included in a large number of Linux distributions. 126Firejail is available in multiple Linux distributions:
127
128<details>
129<summary>Repology</summary>
130<p>
131
132[![Packaging status (Repology)](https://repology.org/badge/vertical-allrepos/firejail.svg)](https://repology.org/project/firejail/versions)
109 133
110You can also install one of the [released packages](http://sourceforge.net/projects/firejail/files/firejail), or clone Firejail’s source code from our Git repository and compile manually: 134</p>
135</details>
111 136
112````` 137Other than the [aforementioned exceptions](#installing), as long as your
113$ git clone https://github.com/netblue30/firejail.git 138distribution provides a [supported version](SECURITY.md) of firejail, it's
114$ cd firejail 139generally a good idea to install it from the distribution.
115$ ./configure && make && sudo make install-strip 140
116````` 141The version can be checked with `firejail --version` after installing.
117On Debian/Ubuntu you will need to install git and gcc compiler. AppArmor 142
118development libraries and pkg-config are required when using `--enable-apparmor` 143You can also install one of the [released
144packages](https://github.com/netblue30/firejail/releases).
145
146Or clone the source code from our git repository and build manually:
147
148```sh
149git clone https://github.com/netblue30/firejail.git
150cd firejail
151./configure && make && sudo make install-strip
152```
153
154On Debian/Ubuntu you will need to install git and gcc. AppArmor development
155libraries and pkg-config are required when using the `--enable-apparmor`
119./configure option: 156./configure option:
120````` 157
121$ sudo apt-get install git build-essential libapparmor-dev pkg-config gawk 158```sh
122````` 159sudo apt-get install git build-essential libapparmor-dev pkg-config gawk
160```
161
123For `--selinux` option, add libselinux1-dev (libselinux-devel for Fedora). 162For `--selinux` option, add libselinux1-dev (libselinux-devel for Fedora).
124 163
125Detailed information on using firejail from git is available on the [wiki](https://github.com/netblue30/firejail/wiki/Using-firejail-from-git). 164Detailed information on using firejail from git is available on the
165[wiki](https://github.com/netblue30/firejail/wiki/Using-firejail-from-git).
126 166
127## Running the sandbox 167## Running the sandbox
128 168
129To start the sandbox, prefix your command with `firejail`: 169To start the sandbox, prefix your command with `firejail`:
130 170
131````` 171```sh
132$ firejail firefox # starting Mozilla Firefox 172firejail firefox # starting Mozilla Firefox
133$ firejail transmission-gtk # starting Transmission BitTorrent 173firejail transmission-gtk # starting Transmission BitTorrent
134$ firejail vlc # starting VideoLAN Client 174firejail vlc # starting VideoLAN Client
135$ sudo firejail /etc/init.d/nginx start 175sudo firejail /etc/init.d/nginx start
136````` 176```
137Run `firejail --list` in a terminal to list all active sandboxes. Example: 177
138````` 178Run `firejail --list` in a terminal to list all active sandboxes. Example:
179
180```console
139$ firejail --list 181$ firejail --list
1401617:netblue:/usr/bin/firejail /usr/bin/firefox-esr 1821617:netblue:/usr/bin/firejail /usr/bin/firefox-esr
1417719:netblue:/usr/bin/firejail /usr/bin/transmission-qt 1837719:netblue:/usr/bin/firejail /usr/bin/transmission-qt
1427779:netblue:/usr/bin/firejail /usr/bin/galculator 1847779:netblue:/usr/bin/firejail /usr/bin/galculator
1437874:netblue:/usr/bin/firejail /usr/bin/vlc --started-from-file file:///home/netblue/firejail-whitelist.mp4 1857874:netblue:/usr/bin/firejail /usr/bin/vlc --started-from-file file:///home/netblue/firejail-whitelist.mp4
1447916:netblue:firejail --list 1867916:netblue:firejail --list
145````` 187```
146 188
147## Desktop integration 189## Desktop integration
148 190
149Integrate your sandbox into your desktop by running the following two commands: 191Integrate your sandbox into your desktop by running the following two commands:
150`````
151$ firecfg --fix-sound
152$ sudo firecfg
153`````
154 192
155The first command solves some shared memory/PID namespace bugs in PulseAudio software prior to version 9. 193```sh
156The second command integrates Firejail into your desktop. You would need to logout and login back to apply 194firecfg --fix-sound
157PulseAudio changes. 195sudo firecfg
196```
197
198The first command solves some shared memory/PID namespace bugs in PulseAudio
199software prior to version 9. The second command integrates Firejail into your
200desktop. You would need to logout and login back to apply PulseAudio changes.
201
202Start your programs the way you are used to: desktop manager menus, file
203manager, desktop launchers.
158 204
159Start your programs the way you are used to: desktop manager menus, file manager, desktop launchers. 205The integration applies to any program supported by default by Firejail. There
160The integration applies to any program supported by default by Firejail. There are about 250 default applications 206are over 900 default applications in the current Firejail version, and the
161in current Firejail version, and the number goes up with every new release. 207number goes up with every new release.
162We keep the application list in [/etc/firejail/firecfg.config](https://github.com/netblue30/firejail/blob/master/src/firecfg/firecfg.config) file. 208
209We keep the application list in
210[src/firecfg/firecfg.config](src/firecfg/firecfg.config)
211(/etc/firejail/firecfg.config when installed).
163 212
164## Security profiles 213## Security profiles
165 214
166Most Firejail command line options can be passed to the sandbox using profile files. 215Most Firejail command line options can be passed to the sandbox using profile
167You can find the profiles for all supported applications in [/etc/firejail](https://github.com/netblue30/firejail/tree/master/etc) directory. 216files.
217
218You can find the profiles for all supported applications in [etc/](etc/)
219(/etc/firejail/ when installed).
220
221We also keep a list of profile fixes for previous released versions in
222[etc-fixes/](etc-fixes/).
168 223
169If you keep additional Firejail security profiles in a public repository, please give us a link: 224If you keep additional Firejail security profiles in a public repository,
225please give us a link:
170 226
171* https://github.com/chiraag-nataraj/firejail-profiles 227* <https://github.com/chiraag-nataraj/firejail-profiles>
228* <https://github.com/triceratops1/fe>
172 229
173* https://github.com/triceratops1/fe 230Use this issue to request new profiles:
174 231
175Use this issue to request new profiles: [#1139](https://github.com/netblue30/firejail/issues/1139) 232* [Profile requests](https://github.com/netblue30/firejail/issues/1139)
176 233
177You can also use this tool to get a list of syscalls needed by a program: [contrib/syscalls.sh](contrib/syscalls.sh). 234You can also use this tool to get a list of syscalls needed by a program:
178 235
179We also keep a list of profile fixes for previous released versions in [etc-fixes](https://github.com/netblue30/firejail/tree/master/etc-fixes) directory. 236* [contrib/syscalls.sh](contrib/syscalls.sh)
180 237
181## Latest released version: 0.9.72 238## Latest released version: 0.9.72
182 239
183## Current development version: 0.9.73 240## Current development version: 0.9.73
184 241
185### --keep-shell-rc 242### --keep-shell-rc
186````` 243
244```text
187 --keep-shell-rc 245 --keep-shell-rc
188 By default, when using a private home directory, firejail copies 246 By default, when using a private home directory, firejail copies
189 files from the system's user home template (/etc/skel) into it, 247 files from the system's user home template (/etc/skel) into it,
190 which overrides attempts to whitelist the original files (such 248 which overrides attempts to whitelist the original files (such
191 as ~/.bashrc and ~/.zshrc). This option disables this feature, 249 as ~/.bashrc and ~/.zshrc). This option disables this feature,
192 and enables the user to whitelist the original files. 250 and enables the user to whitelist the original files.
193 251```
194`````
195 252
196### private-etc rework 253### private-etc rework
197````` 254
255```text
198 --private-etc, --private-etc=file,directory,@group 256 --private-etc, --private-etc=file,directory,@group
199 The files installed by --private-etc are copies of the original 257 The files installed by --private-etc are copies of the original
200 system files from /etc directory. By default, the command 258 system files from /etc directory. By default, the command
201 brings in a skeleton of files and directories used by most con‐ 259 brings in a skeleton of files and directories used by most
202 sole tools: 260 console tools:
203 261
204 $ firejail --private-etc dig debian.org 262 $ firejail --private-etc dig debian.org
205 263
206 For X11/GTK/QT/Gnome/KDE programs add @x11 group as a parame‐ 264 For X11/GTK/QT/Gnome/KDE programs add @x11 group as a
207 ter. Example: 265 parameter. Example:
208 266
209 $ firejail --private-etc=@x11,gcrypt,python* gimp 267 $ firejail --private-etc=@x11,gcrypt,python* gimp
210 268
211 gcrypt and /etc/python* directories are not part of the generic 269 gcrypt and /etc/python* directories are not part of the generic
212 @x11 group. File globbing is supported. 270 @x11 group. File globbing is supported.
213 271
214 For games, add @games group: 272 For games, add @games group:
215 273
216 $ firejail --private-etc=@games,@x11 warzone2100 274 $ firejail --private-etc=@games,@x11 warzone2100
217 275
218 Sound and networking files are included automatically, unless 276 Sound and networking files are included automatically, unless
219 --nosound or --net=none are specified. Files for encrypted 277 --nosound or --net=none are specified. Files for encrypted
220 TLS/SSL protocol are in @tls-ca group. 278 TLS/SSL protocol are in @tls-ca group.
221 279
222 $ firejail --private-etc=@tls-ca,wgetrc wget https://debian.org 280 $ firejail --private-etc=@tls-ca,wgetrc wget https://debian.org
@@ -225,22 +283,29 @@ We also keep a list of profile fixes for previous released versions in [etc-fixe
225 by your program is using strace utility: 283 by your program is using strace utility:
226 284
227 $ strace /usr/bin/transmission-qt 2>&1 | grep open | grep etc 285 $ strace /usr/bin/transmission-qt 2>&1 | grep open | grep etc
286```
287
288We keep the list of groups in
289[src/include/etc_groups.h](src/include/etc_groups.h).
228 290
229````` 291Discussion:
230We keep the list of groups in [src/include/etc_groups.h](https://github.com/netblue30/firejail/blob/master/src/include/etc_groups.h) 292
231Discussion: https://github.com/netblue30/firejail/discussions/5610 293* [private-etc rework](https://github.com/netblue30/firejail/discussions/5610)
232 294
233### Profile Statistics 295### Profile Statistics
234 296
235A small tool to print profile statistics. Compile and install as usual. The tool is installed in /usr/lib/firejail directory. 297A small tool to print profile statistics. Compile and install as usual. The
298tool is installed in the /usr/lib/firejail directory.
299
236Run it over the profiles in /etc/profiles: 300Run it over the profiles in /etc/profiles:
237``` 301
302```console
238$ /usr/lib/firejail/profstats /etc/firejail/*.profile 303$ /usr/lib/firejail/profstats /etc/firejail/*.profile
239No include .local found in /etc/firejail/noprofile.profile 304No include .local found in /etc/firejail/noprofile.profile
240Warning: multiple caps in /etc/firejail/transmission-daemon.profile 305Warning: multiple caps in /etc/firejail/transmission-daemon.profile
241 306
242Stats: 307Stats:
243 profiles 1209 308 profiles 1209
244 include local profile 1208 (include profile-name.local) 309 include local profile 1208 (include profile-name.local)
245 include globals 1181 (include globals.local) 310 include globals 1181 (include globals.local)
246 blacklist ~/.ssh 1079 (include disable-common.inc) 311 blacklist ~/.ssh 1079 (include disable-common.inc)
@@ -266,5 +331,4 @@ Stats:
266 dbus-user filter 141 331 dbus-user filter 141
267 dbus-system none 851 332 dbus-system none 851
268 dbus-system filter 12 333 dbus-system filter 12
269
270``` 334```
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2024-08-31 19:28:05 +0000