convince/sway/sway-security.7.txt

/////
vim:set ts=4 sw=4 tw=82 noet:
/////
sway-security (7)
=================

Name
----
sway-security - Guidelines for securing your sway install

Security Overview
-----------------

**Sway is NOT secure**. We are working on it but do not trust that we have it all
figured out yet. The following man page is provisional.

Securing sway requires careful configuration of your environment, the sort that's
usually best suited to a distro maintainer who wants to ship a secure sway
environment in their distro. Sway provides a number of means of securing it but
you must make a few changes external to sway first.

Configuration of security features is limited to files in the security directory
(this is likely /etc/sway/security.d/*, but depends on your installation prefix).
Files in this directory must be owned by root:root and chmod 600. The default
security configuration is installed to /etc/sway/security.d/00-defaults, and
should not be modified - it will be updated with the latest recommended security
defaults between releases. To override the defaults, you should add more files to
this directory.

Environment security
--------------------

LD_PRELOAD is a mechanism designed to ruin the security of your system. There are
a number of strategies for dealing with this but they all suck a little. In order
of most practical to least practical:

1. Only run important programs via exec. Sway's exec command will ensure that
	LD_PRELOAD is unset when running programs.

2. Remove LD_PRELOAD support from your dynamic loader (requires patching libc).
	This may break programs that rely on LD_PRELOAD for legitimate functionality,
	but this is the most effective solution.

3. Use static linking for important programs. Of course statically linked programs
	are unaffected by the dynamic linking security dumpster fire.

Note that should you choose method 1, you MUST ensure that sway itself isn't
compromised by LD_PRELOAD. It probably isn't, but you can be sure by setting
/usr/bin/sway to a+s (setuid), which will instruct the dynamic linker not to
permit LD_PRELOAD for it (and will also run it as root, which sway will shortly
drop). You could also statically link sway itself.

Note that LD_LIBRARY_PATH has all of the same problems, and all of the same
solutions.

Read your log
-------------

Sway does sanity checks and prints big red warnings to stderr if they fail. Read
them.

Feature policies
----------------

Certain sway features are security sensitive and may be configured with security
policies. These features are:

**background**::
	Permission for a program to become the background.

**fullscreen**::
	Permission to become fullscreen. Note that users can always make a window
	fullscreen themselves with the fullscreen command.

**ipc**::
	Permission to connect to sway's IPC socket.

**keyboard**::
	Permission to receive keyboard events (only while they are focused).

**lock**::
	Permission for a program to act as a screen locker. This involves becoming
	fullscreen (on all outputs) and receiving _all_ keyboard and mouse input for
	the duration of the process.

**mouse**::
	Permission to receive mouse events (only while the mouse is over them).

**panel**::
	Permission for a program to stick its windows to the sides of the screen.

**screenshot**::
	Permission to take screenshots or record the screen.

By default, no permissions are granted (though saner defaults are provided in
/etc/sway/config.d/security). You can use the following config commands to control
a program's access:

**permit** <executable> <features...>::
	Permits <executable> to use <features> (each feature seperated by a space).
	<executable> may be * to affect the default policy, or the full path to the
	executable file.

**reject** <executable> <features...>::
	Disallows <executable> from using <features> (each feature seperated by a space).
	<executable> may be * to affect the default policy, or the full path to the
	executable file.

Note that policy enforcement requires procfs to be mounted at /proc and the sway
process to be able to access _/proc/[pid]/exe_ (see **procfs(5)** for details on
this access - setcap cap_sys_ptrace=eip /usr/bin/sway should do the trick). If
sway is unable to read _/proc/[pid]/exe_, it will apply the default policy.

To work correctly, sway's own programs require the following permissions:

- swaybg: background
- swaylock: lock, keyboard
- swaybar: panel, mouse, ipc
- swaygrab: screenshot, ipc

When you first declare a policy for an executable, it will inherit the default
policy. Further changes to the default policy will not retroactively affect which
permissions an earlier policy inherits. You must explicitly reject any features
from the default policy that you do not want an executable to receive permission
for.

Command policies
----------------

You can also control the context from which a command may execute. The different
contexts you can control are:

**config**::
	Can be run from your config file.

**binding**::
	Can be run from bindsym or bindcode commands.

**ipc**::
	Can be run by IPC clients.

**criteria**::
	Can be run when evaluating window criteria.

**all**::
	Shorthand for granting permission in all contexts.

By default a command is allowed to execute in any context. To configure this, open
a commands block and fill it with policies:

	commands {
		<name> <contexts...>
		...
	}

For example, you could do this to limit the use of the focus command to just
binding and critiera:

	commands {
		focus binding criteria
	}

Setting a command policy overwrites any previous policy that was in place.

IPC policies
------------

Disabling IPC access via swaymsg is encouraged if you intend to secure the IPC
socket, because any program that can execute swaymsg could circumvent its own
security policy by simply invoking swaymsg.

You can configure which features of IPC are available for particular clients:

	ipc <executable> {
		...
	}

You may use * for <executable> to configure the default policy for all clients.
Configuring IPC policies for specific executables is not supported on FreeBSD, and
the default policy will be applied to all IPC connections.

The following commands are available within this block:

**bar-config** <enabled|disabled>::
	Controls GET_BAR_CONFIG (required for swaybar to work at all).

**command** <enabled|disabled>::
	Controls executing sway commands via IPC.

**inputs** <enabled|disabled>::
	Controls GET_INPUTS (input device information).

**marks** <enabled|disabled>::
	Controls GET_MARKS.

**outputs** <enabled|disabled>::
	Controls GET_OUTPUTS.

**tree** <enabled|disabled>::
	Controls GET_TREE.

**workspaces** <enabled|disabled>::
	Controls GET_WORKSPACES.

You can also control which IPC events can be raised with an events block:

	ipc <executable> {
		events {
			...
		}
	}

The following commands are vaild within an ipc events block:

**binding** <enabled|disabled>::
	Controls keybinding notifications (disabled by default).

**input** <enabled|disabled>::
	Controls input device hotplugging notifications.

**mode** <enabled|disabled>::
	Controls output hotplugging notifications.

**output** <enabled|disabled>::
	Controls output hotplugging notifications.

**window** <enabled|disabled>::
	Controls window event notifications.

**workspace** <enabled|disabled>::
	Controls workspace notifications.

In each of these blocks, you may use * (as in "* enabled" or "* disabled") to
control access to every feature at once.

Authors
-------
Maintained by Drew DeVault <sir@cmpwn.com>, who is assisted by other open
source contributors. For more information about sway development, see
<https://github.com/SirCmpwn/sway>.