ceos/cagebreak
1
0
Fork 0
mirror of https://cagebreak.project-repo.co/cagebreak.git synced 2026-08-22 21:44:19 +02:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'development' of https://github.com/project-repo/cagebreak into development

Browse source
This commit is contained in:
project-repo 2022-04-14 20:47:02 +02:00
commit dab95aab04
5 changed files with 169 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

37
FAQ.md Normal file
View file

@ -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)).

67
README.md
View file

@ -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

90
SECURITY.md Normal file
View file

@ -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.

2
man/cagebreak-config.5.md
View file

@ -1,4 +1,4 @@
cagebreak-config(5) "Version 1.8.2" "Cagebreak Manual"
cagebreak-config(5) "Version 1.9.0" "Cagebreak Manual"
# NAME

4
man/cagebreak.1.md
View file

@ -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