mirror of
https://github.com/tildeclub/launcher.git
synced 2026-10-25 08:25:38 +00:00
Harden script approvals and add migration support
This commit is contained in:
7 files changed
+963
-339
No files matched your search
@@ -1,25 +1,123 @@
|
||||
# `tilde` - user script tilde-launcher
|
||||
# tilde launcher
|
||||
|
||||
```
|
||||
Usage: tilde [options] [command]
|
||||
`tilde` is a small POSIX shell utility for submitting and approving programs
|
||||
that can be run by other users. Approved commands remain available under
|
||||
`/tilde/bin`. This version targets Linux with GNU coreutils, `runuser`,
|
||||
`timeout`, `flock`, `getent`, `sha256sum`, and a sendmail-compatible MTA.
|
||||
|
||||
Options:
|
||||
-h, --help Show this help message and exit
|
||||
-v, --version Show version information
|
||||
## Commands
|
||||
|
||||
Commands:
|
||||
list Show a list of approved user scripts
|
||||
submit Start the submission flow for your own script
|
||||
about <script> Show description and details of a specific script
|
||||
approve Enter the approval queue for pending scripts (requires root)
|
||||
revoke <script> Revoke a previously approved script (requires root)
|
||||
run <script> Run an approved script
|
||||
|
||||
Please add /tilde/bin to your PATH to use approved scripts without this wrapper.
|
||||
```text
|
||||
tilde list Show published scripts
|
||||
tilde about <script> Show its description and author
|
||||
tilde submit Submit ~/bin/<script>
|
||||
tilde update <script> Submit a new revision of your published script
|
||||
tilde pending List your submissions awaiting review
|
||||
tilde status <script> Display approval status
|
||||
tilde run <script> [args] Run an approved script with arguments
|
||||
sudo tilde approve Inspect and approve submitted scripts
|
||||
sudo tilde revoke <name> Revoke an approved script
|
||||
sudo tilde migrate [name] Review and migrate legacy approvals
|
||||
sudo tilde init Create and secure storage directories
|
||||
```
|
||||
|
||||
approved scripts are placed in /tilde/bin and listed with `tilde list`
|
||||
`description` is an alias for `about`. Previously published scripts continue
|
||||
to work from `/tilde/bin` without the wrapper. Add that directory to `PATH` to
|
||||
run them directly.
|
||||
|
||||
submissions use sendmail to notify an admin.
|
||||
## How approvals work
|
||||
|
||||
admins can use `sudo tilde approve` and `sudo tilde revoke <script_name>`.
|
||||
New submissions are **copies** of an executable in the user's `~/bin`, not
|
||||
symlinks to live code. The submitted file and description remain user-writable;
|
||||
they are not considered trusted approval state. The administrator captures
|
||||
both files **under the submitter's UID** in a private review directory, sees
|
||||
the exact snapshot, and approves that snapshot. No submitted program is
|
||||
executed during approval.
|
||||
|
||||
Approved files are stored in root-owned `/tilde/approved/<name>/<sha256>`.
|
||||
`/tilde/bin/<name>` points to the approved version. Approval records live in
|
||||
root-owned `/tilde/metadata`; rejected submission fingerprints are tracked in
|
||||
`/tilde/rejected`. Published descriptions remain in
|
||||
`/tilde/descriptions`. Previous versions are retained without ordinary user
|
||||
read/execute permissions after an update or revocation. Each approval/revocation
|
||||
is also sent to syslog with the tag `tilde-launcher`.
|
||||
|
||||
An administrator can approve, reject (with a reason sent to the author), or
|
||||
skip a submission. A rejected submission may be replaced with `tilde submit`.
|
||||
|
||||
A submission is limited to 50 MiB with a 16 KiB description. Single-file
|
||||
scripts and executables work best. Scripts that load adjacent assets or rely on
|
||||
`dirname "$0"` may require an adjusted wrapper or an app-specific packaging
|
||||
approach; do not migrate those without checking them first.
|
||||
|
||||
## Installing or upgrading
|
||||
|
||||
```sh
|
||||
git clone https://github.com/tildeclub/launcher.git
|
||||
cd launcher
|
||||
sh tests/smoke.sh
|
||||
sudo make install
|
||||
sudo tilde init
|
||||
```
|
||||
|
||||
Review existing `/tilde` ownership and permissions before running `init`.
|
||||
It refuses pre-existing, unsafe symlink directories and group/world-writable
|
||||
administrative directories instead of silently overwriting them. The parent
|
||||
`/tilde/pending-submissions` is set to sticky mode `1733`; existing user
|
||||
submissions are not deleted. `/tilde/review` is root-only (`0700`).
|
||||
|
||||
**Important:** `make install` does not replace any previously approved
|
||||
`/tilde/bin` symlinks. They remain live links to user code until explicitly
|
||||
migrated. Administrators should plan a manual review:
|
||||
|
||||
```sh
|
||||
sudo tilde migrate # review each legacy link
|
||||
sudo tilde migrate some-script # or migrate one at a time
|
||||
```
|
||||
|
||||
A migration checks the target is under its owner's home `bin` directory,
|
||||
captures it under the author's UID, and asks for approval. Existing users'
|
||||
source files are not modified. If a legacy symlink relies on adjacent files,
|
||||
leave it untouched until it has a suitable standalone replacement.
|
||||
|
||||
Do **not** point `/tilde/approved`, `/tilde/metadata`, `/tilde/rejected`, or `/tilde/review` at
|
||||
user-controlled storage. The administrative directories must be root-owned,
|
||||
not symlinks, and not writable by other users. `runuser`, `timeout`, and `flock`
|
||||
are required for approval and migration. A working `/usr/sbin/sendmail` is
|
||||
recommended for notices; failure to send mail is reported without undoing a
|
||||
completed submission or approval.
|
||||
|
||||
To verify the deployment:
|
||||
|
||||
```sh
|
||||
sudo tilde init
|
||||
tilde --version
|
||||
tilde list
|
||||
tilde status some-script
|
||||
sudo journalctl -t tilde-launcher --since today
|
||||
```
|
||||
|
||||
For an optional full test on an isolated test machine or CI runner, execute
|
||||
`sudo sh tests/integration.sh`. It creates and removes a temporary system
|
||||
account and tests under `/tmp`, without using your live `/tilde` tree.
|
||||
|
||||
## Recovery and rollback
|
||||
|
||||
Before installing, archive `/tilde` and preserve the old launcher binary and
|
||||
manual page. Because existing approvals are not migrated automatically,
|
||||
reverting the command alone restores its original behaviour for unmigrated
|
||||
scripts. Migrated scripts are immutable copies; reverting to the old launcher
|
||||
does **not** restore the old user-owned symlinks. Restore the corresponding
|
||||
`/tilde/bin` links, descriptions, and metadata from the backup if you need to
|
||||
undo a migration. Avoid restoring old files over an active installation without
|
||||
first stopping administrative changes.
|
||||
|
||||
## Development
|
||||
|
||||
```sh
|
||||
sh tests/smoke.sh
|
||||
sudo sh tests/integration.sh # isolated test, needs root and useradd
|
||||
```
|
||||
|
||||
Please run ShellCheck and test on a non-production machine before deploying.
|
||||
No GitHub commit or migration occurs merely by applying a patch.
|
||||
Reference in new issue
Block a user