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)). diff --git a/README.md b/README.md index 17e84b1..aee8318 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,9 @@ 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 +##### Man Pages -Cagebreak has man pages. To use them, make sure that you have `pandoc` +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 +88,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 +112,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` @@ -120,13 +125,16 @@ occur. Once any failure occurs the entire checklist must be completed from scrat * [ ] 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) * [ ] Fixed bugs documented in Bugs.md * [ ] Include issue description from github * [ ] Testing * [ ] Manual testing * [ ] Libfuzzer testing + * [ ] Build version without xwayland support * [ ] Version Number * [ ] meson.build * [ ] git tag @@ -165,6 +173,9 @@ occur. Once any failure occurs the entire checklist must be completed from scrat * [ ] `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 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..9fd151a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,90 @@ +# 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. 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 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