From f4b7a5a498040fc74bb99a8f63dcae49ff8acaae Mon Sep 17 00:00:00 2001 From: Cagebreak Signing Key 7 Date: Thu, 14 Apr 2022 17:00:05 +0200 Subject: [PATCH 1/9] Improve README --- README.md | 66 ++++++++++++++++++++++++++++++++----------------------- 1 file changed, 39 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 17e84b1..7c7e59b 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,23 @@ # Cagebreak: A Wayland Tiling Compositor Inspired by Ratpoison -This is Cagebreak, a Wayland tiling compositor. The goal of this project is to -provide a successor to ratpoison for Wayland users. However, this is -no reimplementation of ratpoison. Should you like to know if a feature -will be implemented, open an issue or get in touch with the development team. +This is Cagebreak, a Wayland tiling compositor. + +The goal of this project is to provide a successor to ratpoison for Wayland +users. However, this is no reimplementation of ratpoison. + +Should you like to know if a feature will be implemented, open an issue +or get in touch with the development team. For documentation of Cagebreak, please see -the man pages for [cagebreak](man/cagebreak.1.md) and cagebreak -[configuration](man/cagebreak-config.5.md) and the -[Wiki](https://github.com/project-repo/cagebreak/wiki/). + * the man pages + * [cagebreak](man/cagebreak.1.md) + * [configuration](man/cagebreak-config.5.md) + * also the [FAQ](FAQ.md) Cagebreak is based on [Cage](https://github.com/Hjdskes/cage), a Wayland kiosk compositor. -Cagebreak is currently being developed under Arch Linux and uses the libraries +Cagebreak is developed under Arch Linux and uses the libraries as they are obtained through pacman. However, cagebreak should also work on other distributions given the proper library versions. @@ -21,8 +25,11 @@ other distributions given the proper library versions. If you are using archlinux, just use the PKGBUILDs from the aur: - * Using the `cagebreak` package, Cagebreak is compiled on the target system (since release 1.3.0) - * Using `cagebreak-bin` package, the pre-built binaries are extracted to the appropriate paths on the target system (since release 1.3.2) + * Using [cagebreak](https://aur.archlinux.org/packages/cagebreak), Cagebreak is + compiled on the target system (since release 1.3.0) + * Using [cagebreak-bin](https://aur.archlinux.org/packages/cagebreak-bin), + the pre-built binaries are extracted to + appropriate paths on the target system (since release 1.3.2) See [cagebreak-pkgbuild](https://github.com/project-repo/cagebreak-pkgbuild) for details. @@ -59,7 +66,7 @@ $ ninja -C build By default, this builds a debug build. To build a release build, use `meson build --buildtype=release`. -#### Xwayland Support +##### Xwayland Support Cagebreak comes with compile-time support for XWayland. To enable this, first make sure that your version of wlroots is compiled with this @@ -67,9 +74,16 @@ option. Then, add `-Dxwayland=true` to the `meson` command above. Note that you'll need to have the XWayland binary installed on your system for this to work. -#### Man Pages +#### -D option -Cagebreak has man pages. To use them, make sure that you have `pandoc` +If cagebreak is not a release build, the binary has the -D option, which +enables damage-debug mode. In damage-debug mode, all regions of the screen +which are not rerendered are colored in red in order to facilitate debugging +of damage tracking issues. + +##### Man Pages + +Cagebreak has man pages. To use them, make sure that you have `scdoc` installed. Then, add `-Dman-pages=true` to the `meson` command. ### Running Cagebreak @@ -81,24 +95,22 @@ KMS+DRM backend. For more configuration options, see the man pages. ## Contributing to Cagebreak -Cagebreak is currently developed to fit the needs of its creators. Should you desire -to implement a feature, please let us know in advance by opening an issue. However, -the feature set is intentionally limited (i.e. we removed support for a desktop -background) and will continue to be so in the future. +Cagebreak is currently developed to fit the needs of its creators. Should you +desire to implement a feature, please let us know in advance by opening +an issue. However, the feature set is intentionally limited (i.e. we removed +support for a desktop background) and will continue to be so in the future. -Nonetheless, don't be intimidated by the (slightly lengthy) release checklist or any other -part of this file. Do what you can, open an issue and we will collaborate -toward a solution. +Nonetheless, don't be intimidated by the (slightly lengthy) release checklist +or any other part of this file. Do what you can, open an issue and we will +collaborate toward a solution. ### Branching Strategy and Versioning -All features are to be developed on feature branches, named after the feature. +There exists a branch `development` to which all reasonable code +is comitted for final testing. -There exists a branch `development` to which all reasonable feature branches -are merged for final testing. - -Once `development` is ready for a release, meaning that the release checklist is fulfilled, -it is merged into `master`, creating a new release, which is tagged and signed. +Once `development` is ready for a release, it is merged into `master` (possibly via +a cherry-picked branch), creating a new release, which is tagged and signed. All releases are tagged according to [semantic versioning](https://semver.org) guidelines. @@ -107,7 +119,7 @@ In the past, our git history did not perfectly reflect this scheme. ### Releases The release checklist must be completely fulfilled in one run for a release to -occur. Once any failure occurs the entire checklist must be completed from scratch. +occur. * [ ] `git checkout development` * [ ] `git pull origin development` From 1f9a720809a1e60b25b7ce16375fd8d34a9eee20 Mon Sep 17 00:00:00 2001 From: Cagebreak Signing Key 7 Date: Thu, 14 Apr 2022 17:06:01 +0200 Subject: [PATCH 2/9] Add SECURITY.md relevance check to release checks --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 7c7e59b..b7b7fcf 100644 --- a/README.md +++ b/README.md @@ -134,6 +134,8 @@ occur. * [ ] Set EPOCH to release day in man generation in meson.build * [ ] wiki * [ ] Changelog.md for major and minor releases but not patches + * [ ] Check features for SECURITY.md relevance (changes to socket scope + for example) * [ ] Fixed bugs documented in Bugs.md * [ ] Include issue description from github * [ ] Testing From 132112c2a5c3ab19a994860869cd48fe1c574071 Mon Sep 17 00:00:00 2001 From: Cagebreak Signing Key 7 Date: Thu, 14 Apr 2022 17:40:01 +0200 Subject: [PATCH 3/9] Remove -D option doc --- README.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/README.md b/README.md index b7b7fcf..f5a5df6 100644 --- a/README.md +++ b/README.md @@ -74,13 +74,6 @@ option. Then, add `-Dxwayland=true` to the `meson` command above. Note that you'll need to have the XWayland binary installed on your system for this to work. -#### -D option - -If cagebreak is not a release build, the binary has the -D option, which -enables damage-debug mode. In damage-debug mode, all regions of the screen -which are not rerendered are colored in red in order to facilitate debugging -of damage tracking issues. - ##### Man Pages Cagebreak has man pages. To use them, make sure that you have `scdoc` From a3c5e6baf1c61a7f0542e1910f212fcf79c5bcea Mon Sep 17 00:00:00 2001 From: Cagebreak Signing Key 7 Date: Thu, 14 Apr 2022 18:02:44 +0200 Subject: [PATCH 4/9] Prepare man page for 1.9.0 --- man/cagebreak.1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/man/cagebreak.1.md b/man/cagebreak.1.md index a7c8d5f..ff3d7e8 100644 --- a/man/cagebreak.1.md +++ b/man/cagebreak.1.md @@ -1,8 +1,8 @@ -cagebreak(1) "Version 1.8.2" "Cagebreak Manual" +cagebreak(1) "Version 1.9.0" "Cagebreak Manual" # NAME -cagebreak - A Wayland tiling compositor to the likes of ratpoison +cagebreak - A Wayland tiling compositor # SYNOPSIS From e5cce909b61ff1caccf023b18ceba174b5929808 Mon Sep 17 00:00:00 2001 From: Cagebreak Signing Key 7 Date: Thu, 14 Apr 2022 18:06:17 +0200 Subject: [PATCH 5/9] Prepare config man page for 1.9.0 --- man/cagebreak-config.5.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/cagebreak-config.5.md b/man/cagebreak-config.5.md index 4ab4cca..2e1fc8f 100644 --- a/man/cagebreak-config.5.md +++ b/man/cagebreak-config.5.md @@ -1,4 +1,4 @@ -cagebreak-config(5) "Version 1.8.2" "Cagebreak Manual" +cagebreak-config(5) "Version 1.9.0" "Cagebreak Manual" # NAME From 55ac751fc1d01a64aaf90afb6af80d28172ee258 Mon Sep 17 00:00:00 2001 From: Cagebreak Signing Key 7 Date: Thu, 14 Apr 2022 18:10:38 +0200 Subject: [PATCH 6/9] Add SECURITY.md --- SECURITY.md | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..1353450 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,64 @@ +# Security + +The main possibility for security bugs to occur in cagebreak is by privilege escalation using the socket. Indeed, any program with access to the socket immediately gains arbitrary code execution rights. As of right now, the socket is world-writable. If you disagree with this threat model, you may contact us via email (See section Email Contact below.) or [open an issue on github](https://github.com/project-repo/cagebreak/issues/new). + +Should any problem with the github issue system arise or any other reason for (potentially confidential) contact with the Cagebreak authors appear, you may contact us via email (See section Email Contact below.). + +## Supported Versions + +The latest release always contains the latest bug fixes and features. There are no official backports for security vulnerabilities. Builds are reproducible under conditions outlined in [README.md](README.md). + +## Bug Reports + +For normal bugs you may [open an issue on github](https://github.com/project-repo/cagebreak/issues/new). + +For everything else, an email contact (with gpg encryption and signature) is available below. + +## Email Contact + +Should you want to get in touch with the developers of cagebreak to report a security vulnerability or anything else via email, contact `cagebreak @ project-repo . co`. + +We will try to respond to everything that is not obvious spam. + +### GPG-Encrypted Emails + +If you can, please encrypt your email with the appropriate GPG key found in `keys/` and sign your message with your own key. + +* B15B92642760E11FE002DE168708D42451A94AB5 +* F8DD9F8DD12B85A28F5827C4678E34D2E753AA3C + +Note that our keys are signed by cagebreak signing keys. + +If you want us to respond via GPG-encrypted email, please include your own public key or provide the fingerprint and directions to obtain the key. + +## Threat Model + +Cagebreak is a wayland compositor, which is run by the user of the system and thus has access to whichever resources this user has access to. Cagebreak can restrict other programs in no way, because this would hamper usability (consider a web browser unable to write a downloaded file to disk for instance). There is no transmission of information by cagebreak other than to the screens, ipc and potentially other documented local channels. + +### STRIDE Threat List + +This is not a thorough analysis, just an overview of the ways in which cagebreak has/does not have an attack surface. + +#### Spoofing + +Not applicable - Using cagebreak already requires a login as a user. + +#### Tampering + +Not applicable - Cagebreak must allow system manipulation for user software. + +#### Repudiation + +Not applicable - There are no prohibited operations (See Tampering above.). While cagebreak does send events over documented channels there is no logging activated by default, though, of course, this can be changed by the user by logging socket output for example. + +#### Information Disclosure + +Not applicable - Information disclosure over documented channels is a feature and any software run by the user may exfiltrate any data the user has access to. + +#### Denial of Service + +Not applicable - Cagebreak offers functionality to terminate itself, which is available to all user software over the socket. + +#### Elevation of privilege + +Software may gain arbitrary code execution rights if it has access to the Cagebreak socket. Privilege escalation to root is unlikely since privileges are dropped before any user input is accepted. \ No newline at end of file From 83b1562a5502d5caad6c4360db1ef2f759b3d3e3 Mon Sep 17 00:00:00 2001 From: Cagebreak Signing Key 7 Date: Thu, 14 Apr 2022 18:15:25 +0200 Subject: [PATCH 7/9] Reformat SECURITY.md --- SECURITY.md | 52 +++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 39 insertions(+), 13 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 1353450..9fd151a 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,43 +1,62 @@ # Security -The main possibility for security bugs to occur in cagebreak is by privilege escalation using the socket. Indeed, any program with access to the socket immediately gains arbitrary code execution rights. As of right now, the socket is world-writable. If you disagree with this threat model, you may contact us via email (See section Email Contact below.) or [open an issue on github](https://github.com/project-repo/cagebreak/issues/new). +The main possibility for security bugs to occur in cagebreak is by privilege +escalation using the socket. Indeed, any program with access to the socket +immediately gains arbitrary code execution rights. As of right now, the socket +is world-writable. If you disagree with this threat model, you may contact +us via email (See section Email Contact below.) or [open an issue on github](https://github.com/project-repo/cagebreak/issues/new). -Should any problem with the github issue system arise or any other reason for (potentially confidential) contact with the Cagebreak authors appear, you may contact us via email (See section Email Contact below.). +Should any problem with the github issue system arise or any other reason +for (potentially confidential) contact with the Cagebreak authors appear, +you may contact us via email (See section Email Contact below.). ## Supported Versions -The latest release always contains the latest bug fixes and features. There are no official backports for security vulnerabilities. Builds are reproducible under conditions outlined in [README.md](README.md). +The latest release always contains the latest bug fixes and features. +There are no official backports for security vulnerabilities. Builds +are reproducible under conditions outlined in [README.md](README.md). ## Bug Reports For normal bugs you may [open an issue on github](https://github.com/project-repo/cagebreak/issues/new). -For everything else, an email contact (with gpg encryption and signature) is available below. +For everything else, an email contact (with gpg encryption and signature) +is available below. ## Email Contact -Should you want to get in touch with the developers of cagebreak to report a security vulnerability or anything else via email, contact `cagebreak @ project-repo . co`. +Should you want to get in touch with the developers of cagebreak to report +a security vulnerability or anything else via email, contact +`cagebreak @ project-repo . co`. We will try to respond to everything that is not obvious spam. ### GPG-Encrypted Emails -If you can, please encrypt your email with the appropriate GPG key found in `keys/` and sign your message with your own key. +If you can, please encrypt your email with the appropriate GPG key found +in `keys/` and sign your message with your own key. * B15B92642760E11FE002DE168708D42451A94AB5 * F8DD9F8DD12B85A28F5827C4678E34D2E753AA3C Note that our keys are signed by cagebreak signing keys. -If you want us to respond via GPG-encrypted email, please include your own public key or provide the fingerprint and directions to obtain the key. +If you want us to respond via GPG-encrypted email, please include your own +public key or provide the fingerprint and directions to obtain the key. ## Threat Model -Cagebreak is a wayland compositor, which is run by the user of the system and thus has access to whichever resources this user has access to. Cagebreak can restrict other programs in no way, because this would hamper usability (consider a web browser unable to write a downloaded file to disk for instance). There is no transmission of information by cagebreak other than to the screens, ipc and potentially other documented local channels. +Cagebreak is a wayland compositor, which is run by the user of the system +and thus has access to whichever resources this user has access to. +Cagebreak can restrict other programs in no way, because this would hamper +usability (consider a web browser unable to write a downloaded file to disk +for instance). There is no transmission of information by cagebreak other +than to the screens, ipc and potentially other documented local channels. ### STRIDE Threat List -This is not a thorough analysis, just an overview of the ways in which cagebreak has/does not have an attack surface. +This is not a thorough analysis, just an overview of the ways in which cagebreak +has/does not have an attack surface. #### Spoofing @@ -49,16 +68,23 @@ Not applicable - Cagebreak must allow system manipulation for user software. #### Repudiation -Not applicable - There are no prohibited operations (See Tampering above.). While cagebreak does send events over documented channels there is no logging activated by default, though, of course, this can be changed by the user by logging socket output for example. +Not applicable - There are no prohibited operations (See Tampering above.). +While cagebreak does send events over documented channels there is no logging +activated by default, though, of course, this can be changed by the user +by logging socket output for example. #### Information Disclosure -Not applicable - Information disclosure over documented channels is a feature and any software run by the user may exfiltrate any data the user has access to. +Not applicable - Information disclosure over documented channels is a feature +and any software run by the user may exfiltrate any data the user has access to. #### Denial of Service -Not applicable - Cagebreak offers functionality to terminate itself, which is available to all user software over the socket. +Not applicable - Cagebreak offers functionality to terminate itself, which is +available to all user software over the socket. #### Elevation of privilege -Software may gain arbitrary code execution rights if it has access to the Cagebreak socket. Privilege escalation to root is unlikely since privileges are dropped before any user input is accepted. \ No newline at end of file +Software may gain arbitrary code execution rights if it has access to the +Cagebreak socket. Privilege escalation to root is unlikely since privileges +are dropped before any user input is accepted. From ce80f86b49b64a231cd8b785bdc44963a8e81483 Mon Sep 17 00:00:00 2001 From: Cagebreak Signing Key 7 Date: Thu, 14 Apr 2022 19:20:52 +0200 Subject: [PATCH 8/9] Add FAQ.md --- FAQ.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) create mode 100644 FAQ.md diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..a494392 --- /dev/null +++ b/FAQ.md @@ -0,0 +1,37 @@ +# Frequently Asked Questions + +## How do I do $thing with cagebreak? + + * Check the man pages + * [cagebreak config](man/cagebreak-config.5.md) (probably where you find the answer) + * [cagebreak](man/cagebreak.1.md) (command line options etc.) + * Check the rest of this FAQ + * [Open an issue](https://wiki.archlinux.org/title/Linux_console/Keyboard_configuration) or otherwise get in touch with the development team (See section Email Contact in [SECURITY.md](SECURITY.md)). + +Note that the feature set of cagebreak is intentionally limited. + +## How do I remap Caps Lock? + +Remapping Caps Lock globally seems to be the best option. +Follow instructions [here](https://wiki.archlinux.org/title/Linux_console/Keyboard_configuration) to achieve this (should be roughly +distribution-agnostic). + +## How do I get firefox to run under wayland? + +Set the following environment variables + + * `MOZ_USE_WAYLAND=1` + * `GDK_BACKEND=wayland` + +to activate wayland support for firefox. + +## Which further resources are available? + + * [Arch Linux Wiki entry for Cagebreak](https://wiki.archlinux.org/title/Cagebreak) + * [Sway Wiki](https://github.com/swaywm/sway/wiki) + * [Cage Wiki](https://github.com/Hjdskes/cage/wiki) + +## This FAQ did not help me. What now? + + * Consider [opening an issue](https://github.com/project-repo/cagebreak/issues/new) on github or getting in touch with the + development team (See section Email Contact in [SECURITY.md](SECURITY.md)). From f31ee224cafd94203cd47f5cac618135201b29ef Mon Sep 17 00:00:00 2001 From: Cagebreak Signing Key 7 Date: Thu, 14 Apr 2022 19:58:49 +0200 Subject: [PATCH 9/9] Adapt README to upcoming release --- README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f5a5df6..aee8318 100644 --- a/README.md +++ b/README.md @@ -125,7 +125,7 @@ occur. * [ ] man/cagebreak * [ ] man/cagebreak-config * [ ] Set EPOCH to release day in man generation in meson.build - * [ ] wiki + * [ ] FAQ.md * [ ] Changelog.md for major and minor releases but not patches * [ ] Check features for SECURITY.md relevance (changes to socket scope for example) @@ -134,6 +134,7 @@ occur. * [ ] Testing * [ ] Manual testing * [ ] Libfuzzer testing + * [ ] Build version without xwayland support * [ ] Version Number * [ ] meson.build * [ ] git tag @@ -172,6 +173,9 @@ occur. * [ ] `cp build/cagebreak-config.5 release-artefacts_version/` * [ ] `cp build/cagebreak-config.5.sig release-artefacts_version/` * [ ] `cp LICENSE release-artefacts_version/` + * [ ] `cp README.md release-artefacts_version/` + * [ ] `cp SECURITY.md release-artefacts_version/` + * [ ] `cp FAQ.md release-artefacts_version/` * [ ] `export SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct) ; tar --sort=name --mtime= --owner=0 --group=0 --numeric-owner -czf release-artefacts_version.tar.gz release-artefacts_version` * [ ] Checked archive * [ ] tar -xvf release_version.tar.gz