Working on Wren Linux

Wren Linux is shell scripts that turn a bare Debian 13 install into a small, careful desktop. If you can read bash, you can read all of it, and help is welcome: a typo, a test, a new extra, or a page that explains something better.

Found a security hole? Don't open a public issue. SECURITY.md says how to report it.

Get a copy and run the tests

git clone https://wrenlinux.org/git/wren-linux.git
cd wren-linux
sudo apt install shellcheck gnupg gpgv acl sway foot rsync nftables xclip cage socat keepassxc lintian python3 wget
PATH=$PATH:/usr/sbin bash test.sh --offline

That takes about 10 minutes. It installs nothing, and the tests work in temp folders with a pretend sudo, apt and the like. A few could reach the real sudo, so a throwaway VM is the safest place for them. Use Debian 13 if you can, since that's what Wren Linux is written for. On another system some checks can fail for reasons that have nothing to do with your change.

While you work, run only the test for what you changed:

bash tools/test-w3m.sh

Don't start two test runs at once, or edit files while one runs: some tests depend on timing, and all of them copy your folder.

To try a change for real, use a computer or VM you can throw away. The scripts change system files: that's their job.

Find your way around

docs/architecture.md shows how the pieces fit together, in about five minutes. In short:

What a good change looks like

• It does one thing. One topic per commit, and a message that says why.
• It has a test that can fail. Every behaviour has a check in tools/test-*.sh. Run it on the old code and watch it fail, or it proves nothing.
• It's shellcheck-clean. test.sh runs shellcheck, with the settings in .shellcheckrc. A few security-critical commands in bin/ are Python (bin/wren-watch): standard library only, and the first line exactly #!/usr/bin/python3 -I, which test.sh checks.
• It's as plain as it can be. Someone should be able to read the script before they run it. A comment says why, not what.
• It keeps its promises. Re-running a script repairs. --remove undoes. Never claim protection a script doesn't give: if you change what something protects, change THREAT-MODEL.md in the same commit.
• It uses foot. It's the only terminal the scripts support. Install another for your own use if you like, but a change that adds another for the scripts won't be taken.
• It says what was tested. "Ran on a real desktop" and "passes with a pretend sway" are different, and both are fine to say.

Some code needs extra care: firewall rules, sudo rules, sshd settings, signature checks and anything that downloads. These changes are welcome, but expect slower review and more questions. A new outside key goes in pins.sh with the date you checked it and where.

Add an extra

An extra is one script in extras/. extras/w3m.sh is a short one to copy. It needs:

#!/bin/bash
# What it is, and why it's set up this way. Comments here are for the person
# deciding whether to run it.
# Usage: bash NAME.sh [--remove | --manual]
# summary: One line for the install list, 52 characters at most
# security: some
# status: apt:PACKAGE bin:COMMAND
. "$(dirname -- "${BASH_SOURCE[0]}")/../lib.sh"
if [ "${1:-}" = --manual ]; then print_manual; exit; fi
need_user

if [ "${1:-}" = --remove ]; then
    apt_purge PACKAGE
    exit
fi

say "Installing NAME"
apt_install PACKAGE

• # security: is which group of the install list it goes in. extras/whonix.sh says most; a text browser says some. install-extras.sh explains the groups.
• # status: lists what only this script sets up, so status.sh can tell if it's there: apt:, bin:, opt:, file:, or gone: for something it removes. A package another script also installs doesn't belong here.
• # files: names repository files a library function installs for the script, so update.sh knows when to run it again.
• docs/extras/NAME.md is required, and a test checks it. Copy docs/extras/w3m.md: SYNOPSIS, one paragraph, LIMITS (be honest), and MANUAL INSTALL. That last section is what --manual prints, and it's also how someone can do it all by hand without trusting the script. Values from pins.sh go in as @NAME@, never typed in.
• A row in docs/extras.md, and a line in README.md if people will look for it.
• Anything from outside Debian must be checked against a key pinned in pins.sh before it's used.

To drop an extra, don't delete it at once: add # retired: WHY under its first line. It leaves the install list, and update.sh offers its --remove to anyone who still has it. The file goes a release or two later.

Add a test

A test is a script in tools/ named test-NAME.sh, added to test.sh with a line like:

dev_test w3m "w3m keeps cookies only while it is open (bin/w3m), with a pretend w3m" "w3m checks"

tools/test-w3m.sh is a small one to copy. Tests work in a temp folder and put pretend programs first on the PATH. Some replace sleep with one that returns at once, so use /bin/sleep where a test must really wait.

Send your change

1. Fork the repository, and make a branch.
2. Run bash test.sh --offline, and say what it shows, including any failures you think aren't yours.
3. Open a pull request saying what changed, why, and what you tested.

Everything reaches main the same way, whoever wrote it. Wren Linux's computers take an update only if its newest commit is signed by the project's key, so the maintainer reads each change, then signs on top. That signature vouches for every line below it, so review takes as long as it takes, and small changes get in faster.

The project is under the MIT license, and so is what you send.

Places to start

Some things that would help, none of them urgent:

• More systems in get-iso: SystemRescue, GParted Live, Clonezilla and Fedora. Each one needs its signing key found in two independent places, and a test (tools/test-get-iso.sh).
• A guide: the docs are for people who are new to this. If something took you a while to understand, a page explaining it may be the most useful thing you can send.
• Try it on your hardware: install it and report what didn't work. Laptops differ, and this has been tested on few of them.
• A test for something untested: many checks use pretend programs, and docs/extras/whonix.md lists what hasn't been tried for real.

If you want to take on something bigger, open an issue first, so nobody's work is wasted.