<commit_before>/////
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 security
----------------------

Many of Sway's security features are configurable. It's important that a possibly
untrusted program is not able to edit this. Security rules are kept in
_/etc/sway/config.d/security_ (usually), which should only be writable by root.
However, configuration of security rules is not limited to this file - any config
file that sway loads (including i.e. _~/.config/sway/config_) should not be editable
by the user you intend to run programs as. One simple strategy is to use
/etc/sway/config instead of a config file in your home directory, but that doesn't
work well for multi-user systems. A more robust strategy is to run untrusted
programs as another user, or in a sandbox. Configuring this is up to you.

Note that _/etc/sway/config.d/*_ must be included explicitly from your config file.
This is done by default in /etc/sway/config but you must check your own config if
you choose to place it in other locations.

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

LD_PRELOAD is a mechanism designed by GNU for the purpose of ruining the security
of your system. One of the many ways LD_PRELOAD kills security is by making
Wayland keyloggers possible.

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 security dumpster fire that is dynamic linking.

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.

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.

**keyboard**::
	Permission to receive keyboard events.

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

**mouse**::
	Permission to receive mouse events.

**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, all programs are granted **fullscreen**, **keyboard**, and **mouse**
permissions. 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.

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

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.

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.<commit_msg>Add docs on what features sway programs require<commit_after>/////
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 security
----------------------

Many of Sway's security features are configurable. It's important that a possibly
untrusted program is not able to edit this. Security rules are kept in
_/etc/sway/config.d/security_ (usually), which should only be writable by root.
However, configuration of security rules is not limited to this file - any config
file that sway loads (including i.e. _~/.config/sway/config_) should not be editable
by the user you intend to run programs as. One simple strategy is to use
/etc/sway/config instead of a config file in your home directory, but that doesn't
work well for multi-user systems. A more robust strategy is to run untrusted
programs as another user, or in a sandbox. Configuring this is up to you.

Note that _/etc/sway/config.d/*_ must be included explicitly from your config file.
This is done by default in /etc/sway/config but you must check your own config if
you choose to place it in other locations.

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

LD_PRELOAD is a mechanism designed by GNU for the purpose of ruining the security
of your system. One of the many ways LD_PRELOAD kills security is by making
Wayland keyloggers possible.

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 security dumpster fire that is dynamic linking.

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.

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.

**keyboard**::
	Permission to receive keyboard events.

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

**mouse**::
	Permission to receive mouse events.

**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, all programs are granted **fullscreen**, **keyboard**, and **mouse**
permissions. 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.

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

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
- swaygrab: screenshot

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.
{'fraction_non_alphanumeric': 0.08325746079919069, 'fraction_numerical': 0.0020232675771370764, 'mean_word_length': 3.8508341511285575, 'pattern_counts': {'":': 0, '<': 23, '<?xml version=': 0, '>': 23, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4406844', 'n_tokens_mistral': 2599, 'n_tokens_neox': 2515, 'n_words': 1462}