From a11707ea273e5665047f8a7d9387ba07f08d72f6 Mon Sep 17 00:00:00 2001 From: netblue30 Date: Sat, 3 Jul 2021 22:09:20 -0400 Subject: [PATCH] allow/deny help and man pages --- src/firejail/main.c | 4 +- src/firejail/usage.c | 42 ++++++----- src/man/firejail-profile.txt | 98 ++++++++++++------------- src/man/firejail.txt | 138 +++++++++++++++++++---------------- 4 files changed, 148 insertions(+), 134 deletions(-) diff --git a/src/firejail/main.c b/src/firejail/main.c index 0b7f63a2492..b97b1f6adb6 100644 --- a/src/firejail/main.c +++ b/src/firejail/main.c @@ -1263,9 +1263,9 @@ int main(int argc, char **argv, char **envp) { arg_debug = 1; arg_quiet = 0; } - else if (strcmp(argv[i], "--debug-blacklists") == 0) + else if (strcmp(argv[i], "--debug-deny") == 0) arg_debug_blacklists = 1; - else if (strcmp(argv[i], "--debug-whitelists") == 0) + else if (strcmp(argv[i], "--debug-allow") == 0) arg_debug_whitelists = 1; else if (strcmp(argv[i], "--debug-private-lib") == 0) arg_debug_private_lib = 1; diff --git a/src/firejail/usage.c b/src/firejail/usage.c index 2093a4ed345..b4f3021c763 100644 --- a/src/firejail/usage.c +++ b/src/firejail/usage.c @@ -28,6 +28,7 @@ static char *usage_str = "\n" "Options:\n" " -- - signal the end of options and disables further option processing.\n" + " --allow=filename - allow file system access.\n" " --allow-debuggers - allow tools such as strace and gdb inside the sandbox.\n" " --allusers - all user home directories are visible inside the sandbox.\n" " --apparmor - enable AppArmor confinement.\n" @@ -38,13 +39,12 @@ static char *usage_str = #endif " --bind=dirname1,dirname2 - mount-bind dirname1 on top of dirname2.\n" " --bind=filename1,filename2 - mount-bind filename1 on top of filename2.\n" - " --blacklist=filename - blacklist directory or file.\n" - " --build - build a whitelisted profile for the application.\n" - " --build=filename - build a whitelisted profile for the application.\n" + " --build - build a profile for the application.\n" + " --build=filename - build a profile for the application.\n" " --caps - enable default Linux capabilities filter.\n" " --caps.drop=all - drop all capabilities.\n" - " --caps.drop=capability,capability - blacklist capabilities filter.\n" - " --caps.keep=capability,capability - whitelist capabilities filter.\n" + " --caps.drop=capability,capability - drop capabilities.\n" + " --caps.keep=capability,capability - allow capabilities.\n" " --caps.print=name|pid - print the caps filter.\n" #ifdef HAVE_FILE_TRANSFER " --cat=name|pid filename - print content of file from sandbox container.\n" @@ -58,32 +58,35 @@ static char *usage_str = #ifdef HAVE_DBUSPROXY " --dbus-log=file - set DBus log file location.\n" " --dbus-system=filter|none - set system DBus access policy.\n" - " --dbus-system.broadcast=rule - allow signals on the system DBus according to rule.\n" + " --dbus-system.broadcast=rule - allow signals on the system DBus according\n" + "\tto rule.\n" " --dbus-system.call=rule - allow calls on the system DBus according to rule.\n" - " --dbus-system.log - turn on logging for the system DBus." + " --dbus-system.log - turn on logging for the system DBus.\n" " --dbus-system.own=name - allow ownership of name on the system DBus.\n" " --dbus-system.see=name - allow seeing name on the system DBus.\n" " --dbus-system.talk=name - allow talking to name on the system DBus.\n" " --dbus-user=filter|none - set session DBus access policy.\n" - " --dbus-user.broadcast=rule - allow signals on the session DBus according to rule.\n" + " --dbus-user.broadcast=rule - allow signals on the session DBus according\n" + "\tto rule.\n" " --dbus-user.call=rule - allow calls on the session DBus according to rule.\n" - " --dbus-user.log - turn on logging for the user DBus." + " --dbus-user.log - turn on logging for the user DBus.\n" " --dbus-user.own=name - allow ownership of name on the session DBus.\n" " --dbus-user.see=name - allow seeing name on the session DBus.\n" " --dbus-user.talk=name - allow talking to name on the session DBus.\n" #endif " --debug - print sandbox debug messages.\n" - " --debug-blacklists - debug blacklisting.\n" + " --debug-allow - debug file system access.\n" + " --debug-deny - debug file system access.\n" " --debug-caps - print all recognized capabilities.\n" " --debug-errnos - print all recognized error numbers.\n" " --debug-private-lib - debug for --private-lib option.\n" " --debug-protocols - print all recognized protocols.\n" " --debug-syscalls - print all recognized system calls.\n" " --debug-syscalls32 - print all recognized 32 bit system calls.\n" - " --debug-whitelists - debug whitelisting.\n" #ifdef HAVE_NETWORK " --defaultgw=address - configure default gateway.\n" #endif + " --deny=filename - deny access to directory or file.\n" " --deterministic-exit-code - always exit with first child's status code.\n" " --dns=address - set DNS server.\n" " --dns.print=name|pid - print DNS configuration.\n" @@ -141,14 +144,15 @@ static char *usage_str = " --netfilter.print=name|pid - print the firewall.\n" " --netfilter6=filename - enable IPv6 firewall.\n" " --netfilter6.print=name|pid - print the IPv6 firewall.\n" - " --netmask=address - define a network mask when dealing with unconfigured" + " --netmask=address - define a network mask when dealing with unconfigured\n" "\tparrent interfaces.\n" " --netns=name - Run the program in a named, persistent network namespace.\n" " --netstats - monitor network statistics.\n" #endif " --nice=value - set nice value.\n" " --no3d - disable 3D hardware acceleration.\n" - " --noblacklist=filename - disable blacklist for file or directory.\n" + " --noallow=filename - disable allow command for file or directory.\n" + " --nodeny=filename - disable deny command for file or directory.\n" " --nodbus - disable D-Bus access.\n" " --nodvd - disable DVD and audio CD devices.\n" " --noexec=filename - remount the file or directory noexec nosuid and nodev.\n" @@ -163,7 +167,6 @@ static char *usage_str = " --noautopulse - disable automatic ~/.config/pulse init.\n" " --novideo - disable video devices.\n" " --nou2f - disable U2F devices.\n" - " --nowhitelist=filename - disable whitelist for file or directory.\n" #ifdef HAVE_OUTPUT " --output=logfile - stdout logging and log rotation.\n" " --output-stderr=logfile - stdout and stderr logging and log rotation.\n" @@ -220,14 +223,14 @@ static char *usage_str = #ifdef HAVE_NETWORK " --scan - ARP-scan all the networks from inside a network namespace.\n" #endif - " --seccomp - enable seccomp filter and apply the default blacklist.\n" - " --seccomp=syscall,syscall,syscall - enable seccomp filter, blacklist the\n" + " --seccomp - enable seccomp filter and drop the default syscalls.\n" + " --seccomp=syscall,syscall,syscall - enable seccomp filter, drop the\n" "\tdefault syscall list and the syscalls specified by the command.\n" " --seccomp.block-secondary - build only the native architecture filters.\n" " --seccomp.drop=syscall,syscall,syscall - enable seccomp filter, and\n" - "\tblacklist the syscalls specified by the command.\n" + "\tdrop the syscalls specified by the command.\n" " --seccomp.keep=syscall,syscall,syscall - enable seccomp filter, and\n" - "\twhitelist the syscalls specified by the command.\n" + "\tallow the syscalls specified by the command.\n" " --seccomp.print=name|pid - print the seccomp filter for the sandbox\n" "\tidentified by name or PID.\n" " --seccomp.32[.drop,.keep][=syscall] - like above but for 32 bit architecture.\n" @@ -242,7 +245,7 @@ static char *usage_str = " --top - monitor the most CPU-intensive sandboxes.\n" " --trace - trace open, access and connect system calls.\n" " --tracelog - add a syslog message for every access to files or\n" - "\tdirectories blacklisted by the security profile.\n" + "\tdirectories dropped by the security profile.\n" " --tree - print a tree of all sandboxed processes.\n" " --tunnel[=devname] - connect the sandbox to a tunnel created by\n" "\tfiretunnel utility.\n" @@ -250,7 +253,6 @@ static char *usage_str = #ifdef HAVE_NETWORK " --veth-name=name - use this name for the interface connected to the bridge.\n" #endif - " --whitelist=filename - whitelist directory or file.\n" " --writable-etc - /etc directory is mounted read-write.\n" " --writable-run-user - allow access to /run/user/$UID/systemd and\n" "\t/run/user/$UID/gnupg.\n" diff --git a/src/man/firejail-profile.txt b/src/man/firejail-profile.txt index db58e09104d..34f5e8bf944 100644 --- a/src/man/firejail-profile.txt +++ b/src/man/firejail-profile.txt @@ -156,7 +156,7 @@ Scripting commands: \fBFile and directory names File and directory names containing spaces are supported. The space character ' ' should not be escaped. -Example: "blacklist ~/My Virtual Machines" +Example: "deny ~/My Virtual Machines" .TP \fB# this is a comment @@ -170,9 +170,9 @@ net none # this command creates an empty network namespace \fB?CONDITIONAL: profile line Conditionally add profile line. -Example: "?HAS_APPIMAGE: whitelist ${HOME}/special/appimage/dir" +Example: "?HAS_APPIMAGE: allow ${HOME}/special/appimage/dir" -This example will load the whitelist profile line only if the \-\-appimage option has been specified on the command line. +This example will load the profile line only if the \-\-appimage option has been specified on the command line. Currently the only conditionals supported this way are HAS_APPIMAGE, HAS_NET, HAS_NODBUS, HAS_NOSOUND, HAS_PRIVATE and HAS_X11. The conditionals BROWSER_DISABLE_U2F and BROWSER_ALLOW_DRM can be enabled or disabled globally in Firejail's configuration file. @@ -205,16 +205,16 @@ storing modifications to the persistent configuration. Persistent .local files are included at the start of regular profile files. .TP -\fBnoblacklist file_name -If the file name matches file_name, the file will not be blacklisted in any blacklist commands that follow. +\fBnoallow file_name +If the file name matches file_name, the file will not be allowed in any allow commands that follow. -Example: "noblacklist ${HOME}/.mozilla" +Example: "nowhitelist ~/.config" .TP -\fBnowhitelist file_name -If the file name matches file_name, the file will not be whitelisted in any whitelist commands that follow. +\fBnodeny file_name +If the file name matches file_name, the file will not be denied any deny commands that follow. -Example: "nowhitelist ~/.config" +Example: "nodeny ${HOME}/.mozilla" .TP \fBignore @@ -242,19 +242,17 @@ HOME directories are searched, see the \fBfirejail\f(1) \fBFILE GLOBBING\fR sect for more details. Examples: .TP -\fBblacklist file_or_directory -Blacklist directory or file. Examples: +\fBallow file_or_directory +Allow directory or file. A temporary file system is mounted on the top directory, and the +allowed files are mount-binded inside. Modifications to allowd files are persistent, +everything else is discarded when the sandbox is closed. The top directory can be +all directories in / (except /proc and /sys), /sys/module, /run/user/$UID, $HOME and +all directories in /usr. .br .br -blacklist /usr/bin -.br -blacklist /usr/bin/gcc* -.br -blacklist ${PATH}/ifconfig -.br -blacklist ${HOME}/.ssh - +Symbolic link handling: with the exception of user home, both the link and the real file should be in +the same top directory. For user home, both the link and the real file should be owned by the user. .TP \fBblacklist-nolog file_or_directory When --tracelog flag is set, blacklisting generates syslog messages if the sandbox tries to access the file or directory. @@ -272,6 +270,20 @@ Mount-bind directory1 on top of directory2. This option is only available when r .TP \fBbind file1,file2 Mount-bind file1 on top of file2. This option is only available when running as root. +.TP +\fBdeny file_or_directory +Deny access to directory or file. Examples: +.br + +.br +deny /usr/bin +.br +deny /usr/bin/gcc* +.br +deny ${PATH}/ifconfig +.br +deny ${HOME}/.ssh + .TP \fBdisable-mnt Disable /mnt, /media, /run/mount and /run/media access. @@ -292,7 +304,7 @@ The directory is created if it doesn't already exist. .br .br -Use this command for whitelisted directories you need to preserve +Use this command for allowed directories you need to preserve when the sandbox is closed. Without it, the application will create the directory, and the directory will be deleted when the sandbox is closed. Subdirectories are recursively created. Example from firefox profile: @@ -305,7 +317,7 @@ whitelist ~/.mozilla .br mkdir ~/.cache/mozilla/firefox .br -whitelist ~/.cache/mozilla/firefox +allow ~/.cache/mozilla/firefox .br .br @@ -411,7 +423,7 @@ expressed as foo/bar -- is disallowed). All modifications are discarded when the sandbox is closed. .TP \fBprivate-tmp -Mount an empty temporary filesystem on top of /tmp directory whitelisting /tmp/.X11-unix. +Mount an empty temporary filesystem on top of /tmp directory allowing /tmp/.X11-unix. .TP \fBread-only file_or_directory Make directory or file read-only. @@ -423,25 +435,13 @@ Make directory or file read-write. Mount an empty tmpfs filesystem on top of directory. Directories outside user home or not owned by the user are not allowed. Sandboxes running as root are exempt from these restrictions. .TP \fBtracelog -Blacklist violations logged to syslog. -.TP -\fBwhitelist file_or_directory -Whitelist directory or file. A temporary file system is mounted on the top directory, and the -whitelisted files are mount-binded inside. Modifications to whitelisted files are persistent, -everything else is discarded when the sandbox is closed. The top directory can be -all directories in / (except /proc and /sys), /sys/module, /run/user/$UID, $HOME and -all directories in /usr. -.br - -.br -Symbolic link handling: with the exception of user home, both the link and the real file should be in -the same top directory. For user home, both the link and the real file should be owned by the user. +File system deny violations logged to syslog. .TP \fBwritable-etc Mount /etc directory read-write. .TP \fBwritable-run-user -Disable the default blacklisting of run/user/$UID/systemd and /run/user/$UID/gnupg. +Disable the default denying of run/user/$UID/systemd and /run/user/$UID/gnupg. .TP \fBwritable-var Mount /var directory read-write. @@ -455,7 +455,7 @@ The following security filters are currently implemented: .TP \fBallow-debuggers -Allow tools such as strace and gdb inside the sandbox by whitelisting system calls ptrace and process_vm_readv. +Allow tools such as strace and gdb inside the sandbox by allowing system calls ptrace and process_vm_readv. #ifdef HAVE_APPARMOR .TP \fBapparmor @@ -466,13 +466,13 @@ Enable AppArmor confinement. Enable default Linux capabilities filter. .TP \fBcaps.drop capability,capability,capability -Blacklist given Linux capabilities. +Deny given Linux capabilities. .TP \fBcaps.drop all -Blacklist all Linux capabilities. +Deny all Linux capabilities. .TP \fBcaps.keep capability,capability,capability -Whitelist given Linux capabilities. +Allow given Linux capabilities. .TP \fBmemory-deny-write-execute Install a seccomp filter to block attempts to create memory mappings @@ -497,32 +497,32 @@ first argument to socket system call. Recognized values: \fBunix\fR, \fBinet\fR, \fBinet6\fR, \fBnetlink\fR, \fBpacket\fR and \fBbluetooth\fR. .TP \fBseccomp -Enable seccomp filter and blacklist the syscalls in the default list. See man 1 firejail for more details. +Enable seccomp filter and deny the syscalls in the default list. See man 1 firejail for more details. .TP \fBseccomp.32 -Enable seccomp filter and blacklist the syscalls in the default list for 32 bit system calls on a 64 bit architecture system. +Enable seccomp filter and deny the syscalls in the default list for 32 bit system calls on a 64 bit architecture system. .TP \fBseccomp syscall,syscall,syscall -Enable seccomp filter and blacklist the system calls in the list on top of default seccomp filter. +Enable seccomp filter and deny the system calls in the list on top of default seccomp filter. .TP \fBseccomp.32 syscall,syscall,syscall -Enable seccomp filter and blacklist the system calls in the list on top of default seccomp filter for 32 bit system calls on a 64 bit architecture system. +Enable seccomp filter and deny the system calls in the list on top of default seccomp filter for 32 bit system calls on a 64 bit architecture system. .TP \fBseccomp.block-secondary Enable seccomp filter and filter system call architectures so that only the native architecture is allowed. .TP \fBseccomp.drop syscall,syscall,syscall -Enable seccomp filter and blacklist the system calls in the list. +Enable seccomp filter and deny the system calls in the list. .TP \fBseccomp.32.drop syscall,syscall,syscall -Enable seccomp filter and blacklist the system calls in the list for 32 bit system calls on a 64 bit architecture system. +Enable seccomp filter and deny the system calls in the list for 32 bit system calls on a 64 bit architecture system. .TP \fBseccomp.keep syscall,syscall,syscall -Enable seccomp filter and whitelist the system calls in the list. +Enable seccomp filter and allow the system calls in the list. .TP \fBseccomp.32.keep syscall,syscall,syscall -Enable seccomp filter and whitelist the system calls in the list for 32 bit system calls on a 64 bit architecture system. +Enable seccomp filter and allow the system calls in the list for 32 bit system calls on a 64 bit architecture system. .TP \fBseccomp-error-action kill | log | ERRNO Return a different error instead of EPERM to the process, kill it when @@ -534,7 +534,7 @@ attempt. Enable X11 sandboxing. .TP \fBx11 none -Blacklist /tmp/.X11-unix directory, ${HOME}/.Xauthority and file specified in ${XAUTHORITY} environment variable. +Deny access to /tmp/.X11-unix directory, ${HOME}/.Xauthority and file specified in ${XAUTHORITY} environment variable. Remove DISPLAY and XAUTHORITY environment variables. Stop with error message if X11 abstract socket will be accessible in jail. .TP diff --git a/src/man/firejail.txt b/src/man/firejail.txt index 0462705c008..498ff9aa94a 100644 --- a/src/man/firejail.txt +++ b/src/man/firejail.txt @@ -98,6 +98,40 @@ $ firejail [OPTIONS] firefox # starting Mozilla Firefox .TP \fB\-\- Signal the end of options and disables further option processing. +.TP +\fB\-\-allow=dirname_or_filename +Allow access to a directory or file. A temporary file system is mounted on the top directory, and the +allowed files are mount-binded inside. Modifications to allowed files are persistent, +everything else is discarded when the sandbox is closed. The top directory can be +all directories in / (except /proc and /sys), /sys/module, /run/user/$UID, $HOME and +all directories in /usr. +.br + +.br +Symbolic link handling: with the exception of user home, both the link and the real file should be in +the same top directory. For user home, both the link and the real file should be owned by the user. +.br + +.br +File globbing is supported, see \fBFILE GLOBBING\fR section for more details. +.br + +.br +Example: +.br +$ firejail \-\-noprofile \-\-allow=~/.mozilla +.br +$ firejail \-\-allow=/tmp/.X11-unix --allow=/dev/null +.br +$ firejail "\-\-allow=/home/username/My Virtual Machines" +.br +$ firejail \-\-allow=~/work* \-\-allow=/var/backups* + + + + + + .TP \fB\-\-allow-debuggers Allow tools such as strace and gdb inside the sandbox by whitelisting @@ -169,21 +203,6 @@ Example: .br # firejail \-\-bind=/config/etc/passwd,/etc/passwd .TP -\fB\-\-blacklist=dirname_or_filename -Blacklist directory or file. File globbing is supported, see \fBFILE GLOBBING\fR section for more details. -.br - -.br -Example: -.br -$ firejail \-\-blacklist=/sbin \-\-blacklist=/usr/sbin -.br -$ firejail \-\-blacklist=~/.mozilla -.br -$ firejail "\-\-blacklist=/home/username/My Virtual Machines" -.br -$ firejail \-\-blacklist=/home/username/My\\ Virtual\\ Machines -.TP \fB\-\-build The command builds a whitelisted profile. The profile is printed on the screen. If /usr/bin/strace is installed on the system, it also builds a whitelisted seccomp profile. The program is run in a very relaxed sandbox, @@ -243,7 +262,7 @@ $ firejail \-\-caps.drop=all warzone2100 .TP \fB\-\-caps.drop=capability,capability,capability -Define a custom blacklist Linux capabilities filter. +Define a custom Linux capabilities filter. .br .br @@ -624,14 +643,14 @@ Example: $ firejail \-\-debug firefox .TP -\fB\-\-debug-blacklists\fR -Debug blacklisting. +\fB\-\-debug-allow\fR +Debug file system access. .br .br Example: .br -$ firejail \-\-debug-blacklists firefox +$ firejail \-\-debug-allow firefox .TP \fB\-\-debug-caps @@ -643,6 +662,16 @@ Example: .br $ firejail \-\-debug-caps +.TP +\fB\-\-debug-deny\fR +Debug file access. +.br + +.br +Example: +.br +$ firejail \-\-debug-deny firefox + .TP \fB\-\-debug-errnos Print all recognized error numbers in the current Firejail software build and exit. @@ -677,15 +706,7 @@ $ firejail \-\-debug-syscalls \fB\-\-debug-syscalls32 Print all recognized 32 bit system calls in the current Firejail software build and exit. .br -.TP -\fB\-\-debug-whitelists\fR -Debug whitelisting. -.br -.br -Example: -.br -$ firejail \-\-debug-whitelists firefox #ifdef HAVE_NETWORK .TP \fB\-\-defaultgw=address @@ -697,13 +718,32 @@ Example: .br $ firejail \-\-net=eth0 \-\-defaultgw=10.10.20.1 firefox #endif + +.TP +\fB\-\-deny=dirname_or_filename +Deny access to directory or file. File globbing is supported, see \fBFILE GLOBBING\fR section for more details. +.br + +.br +Example: +.br +$ firejail \-\-deny=/sbin \-\-deny=/usr/sbin +.br +$ firejail \-\-deny=~/.mozilla +.br +$ firejail "\-\-deny=/home/username/My Virtual Machines" +.br +$ firejail \-\-deny=/home/username/My\\ Virtual\\ Machines + + + .TP \fB\-\-deterministic-exit-code Always exit firejail with the first child's exit status. The default behavior is to use the exit status of the final child to exit, which can be nondeterministic. .br .TP \fB\-\-disable-mnt -Blacklist /mnt, /media, /run/mount and /run/media access. +Deny access to /mnt, /media, /run/mount and /run/media. .br .br @@ -1470,13 +1510,17 @@ Example: .br $ firejail --no3d firefox +.TP +\fB\-\-noallow=dirname_or_filename +Disable \-\-allow for this directory or file. + .TP \fB\-\-noautopulse \fR(deprecated) See --keep-config-pulse. .TP -\fB\-\-noblacklist=dirname_or_filename -Disable blacklist for this directory or file. +\fB\-\-nodeny=dirname_or_filename +Disable \-\-deny for this directory or file. .br .br @@ -1492,7 +1536,7 @@ $ exit .br .br -$ firejail --noblacklist=/bin/nc +$ firejail --nodeny=/bin/nc .br $ nc dict.org 2628 .br @@ -1666,10 +1710,6 @@ $ firejail \-\-nou2f Disable video devices. .br -.TP -\fB\-\-nowhitelist=dirname_or_filename -Disable whitelist for this directory or file. - #ifdef HAVE_OUTPUT .TP \fB\-\-output=logfile @@ -2733,34 +2773,6 @@ Example: .br $ firejail \-\-net=br0 --veth-name=if0 #endif -.TP -\fB\-\-whitelist=dirname_or_filename -Whitelist directory or file. A temporary file system is mounted on the top directory, and the -whitelisted files are mount-binded inside. Modifications to whitelisted files are persistent, -everything else is discarded when the sandbox is closed. The top directory can be -all directories in / (except /proc and /sys), /sys/module, /run/user/$UID, $HOME and -all directories in /usr. -.br - -.br -Symbolic link handling: with the exception of user home, both the link and the real file should be in -the same top directory. For user home, both the link and the real file should be owned by the user. -.br - -.br -File globbing is supported, see \fBFILE GLOBBING\fR section for more details. -.br - -.br -Example: -.br -$ firejail \-\-noprofile \-\-whitelist=~/.mozilla -.br -$ firejail \-\-whitelist=/tmp/.X11-unix --whitelist=/dev/null -.br -$ firejail "\-\-whitelist=/home/username/My Virtual Machines" -.br -$ firejail \-\-whitelist=~/work* \-\-whitelist=/var/backups* .TP \fB\-\-writable-etc