docs: multi-distro install script and practice-run instructions

- Add root-level setup.sh that detects the distro, installs build deps, and
  installs a static qo binary with qo-check/qo-setup/qo-reset aliases.
- Add GIST.md with step-by-step instructions for students: install, download the
  test archive, start the practice session, and run the test levels.
- Document the pristine-staging workflow in the threat model and README.

Author: MohammedNaser28

GIST.md

@@ -0,0 +1,73 @@
+# Linux evaluation '26 — Setup & Test Instructions
+
+> **Important:** run this on a Linux machine (Arch, Debian/Ubuntu, Fedora, OpenSUSE, Alpine all work). You need `sudo` access.
+
+## 1. Install `qo`
+
+Open a terminal and run:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Open-Source-Community/qo2/ctf-improvements/setup.sh | bash
+```
+
+The script detects your distro, installs the required tools (Go, tar, gzip), builds `qo`, and installs it to `/usr/local/bin/qo`. Verify:
+
+```bash
+qo --help
+```
+
+## 2. Download the test archive
+
+Get the practice archive from the drive:
+
+**https://drive.google.com/drive/folders/1nhKUefmOJ8FNPSUXz4sXmCMmDvnXtsc3?usp=sharing**
+
+Download `test.enc` and save it in your home folder.
+
+## 3. Start the practice session
+
+```bash
+cd ~
+sudo qo start -m test -i <YOUR_STUDENT_ID> -a ~/test.enc -p osc2026 -k testkey -d 90m
+```
+
+- `-i` — your student ID (the one you registered with, e.g. `2023001`)
+- `-a` — path to `test.enc`
+- `-p` — password (given above)
+- `-k` — starter key (given above)
+- `-d` — session duration in minutes
+
+You will land inside the sandbox shell (`ahmed@sandbox:~$`).
+
+## 4. Inside the sandbox
+
+```bash
+qo-setup                  # create all 10 test levels
+cd ~/challenges/test1
+bash tools-test.sh        # sanity check — expect: Total tests passed: 43/43
+cat README.md             # read the task
+# solve the task, then: 
+./check.sh                # get your flag for this level
+```
+
+Repeat for the other levels (`test2` … `test10`) — each has its own README.
+
+Useful commands inside the sandbox:
+
+```bash
+qo-setup test2            # set up one level
+qo-reset test2            # reset a level to its original files
+ls ~/challenges          # list all levels
+```
+
+## 5. Leaderboard
+
+Live rankings will be shown at: **https://<leaderboard-url>/** _(placeholder — link will be announced)_
+
+During practice, your test submissions appear on the admin dashboard under the **Test run** section, so the organizers can see you are comfortable with the tool before the real event.
+
+## 6. Tips
+
+- `exit` — leave the sandbox (your session ends).
+- The real event will use a different archive and password, announced later.
+- If anything is broken or a tool is missing in the sandbox, tell the organizers — this practice round exists to catch those issues.

README.md

@@ -143,6 +143,28 @@ diagnostic output — exactly like the historical tool. On success the parent
 replaces the hardcoded `key="..."` with a per-student flag derived via HMAC over
 `(base_flag, student_id)`, so every student gets their own flag.
 
+### Working in the sandbox (home-based challenges)
+
+Students never touch `/tmp`. On first login they set up their challenge folders
+from the root-only pristine staging area:
+
+```bash
+qo-setup          # copies every level into ~/challenges/
+qo-setup level1   # or just one level
+cd ~/challenges/level1
+cat README.md
+./check.sh        # verified from home
+```
+
+A level whose files were corrupted can be restored at any time:
+
+```bash
+qo-reset level1   # wipe ~/challenges/level1 and re-copy pristine files
+```
+
+Both commands relay over the same socket as `qo-check`; the parent copies only
+non-secret data and never exposes the real `check.sh` or the base flag.
+
 ## Customizing the Sandbox
 
 ### Adding System Binaries

docs/threat-model.md

@@ -49,7 +49,14 @@ flow is out of scope.
    next `ExtractRootfs`).
 5. **Level keys are validated.** The stub's level identity is checked against a
    path-containment rule before the parent touches `ChallengesDir`; `..`/
-   absolute/odd characters are rejected.
+   absolute/odd characters are rejected (applies to the `check`, `setup`, and
+   `reset` socket verbs alike).
+6. **The student never sees `/tmp`.** Non-secret level data is extracted to the
+   root-only pristine staging tree (`/tmp/rootfs_pristine`, mode `0700`) and
+   shipped to `~/challenges/<level>` only via the `qo-setup`/`qo-reset` socket
+   verbs. The student works exclusively from their home directory; a corrupted
+   working copy is restorable at any time by re-running `qo-setup`/`qo-reset`,
+   which wipes and re-copies from pristine.
 
 ## Attack surface and responses
 
@@ -61,9 +68,14 @@ flow is out of scope.
   leaves the parent (property 3).
 - **Student replays/brute-forces the socket**: the socket only runs the real
   check for the requested level and returns output; no new capability. `exit 0`
-  is still gated on the check passing.
+  is still gated on the check passing. The `setup`/`reset` verbs only copy
+  non-secret pristine data into the requester's own home; they cannot reach
+  `ChallengesDir`.
 - **Student alters the stub**: the stub carries no secrets; tampering only
   breaks their own `./check.sh`.
+- **Student corrupts their working copy**: `qo-setup`/`qo-reset` restore the
+  level from pristine; the pristine tree is root-only and re-extracted fresh on
+  every `qo start`.
 - **Student reads `/proc` of host processes**: possible (no PID namespace);
   accepted risk. Avoid placing session secrets in host process env/cmdlines.
 - **Network exfiltration**: sandbox shares the host network. The base flag never

scripts/test-e2e.sh

@@ -90,7 +90,7 @@ chmod +x "$CHALLENGE_DIR/level3/check.sh"
 
 # 2. Build qo binary and encrypt archive
 echo -e "${BLUE}[2/4] Building binary & encrypting challenge archive...${NC}"
-go build -o "$WORK_DIR/qo" main.go
+CGO_ENABLED=0 go build -o "$WORK_DIR/qo" main.go
 
 "$WORK_DIR/qo" build -f "$CHALLENGE_DIR" -p "$PASS" -k "$KEY" -u "2020-01-01 00:00" -o "$ARCHIVE_PATH"
 
@@ -103,7 +103,7 @@ echo -e "${GREEN}Encrypted archive built successfully.${NC}"
 # 3. Run the secrecy & archive round-trip tests (non-root)
 echo -e "${BLUE}[3/4] Running secrecy & archive round-trip tests...${NC}"
 go test -v ./pkg/archive/... -run 'TestArchiveRoundTripSecrecy|TestIsValidFolderStructure'
-go test -v ./pkg/sandbox/... -run 'TestWriteCheckStubsSecrecy|TestLoadBaseFlag|TestPresentCheckSuccess|TestValidateLevelKey|TestGenerateUniqueFlag'
+go test -v ./pkg/sandbox/... -run 'TestWriteCheckStubsSecrecy|TestLoadBaseFlag|TestPresentCheckSuccess|TestValidateLevelKey|TestGenerateUniqueFlag|TestRunSetup|TestSetupSocketRoundTrip'
 
 # 4. Run the root-required check-execution tests (real chroot + socket + HMAC)
 echo -e "${BLUE}[4/4] Running root-required check-execution tests...${NC}"

setup.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+#
+# setup.sh — install qo on Linux (multi-distro)
+#
+# Builds the static qo binary and installs it to /usr/local/bin, along with the
+# qo-check / qo-setup / qo-reset aliases the sandbox uses.
+#
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/Open-Source-Community/qo2/ctf-improvements/setup.sh | bash
+#
+# Or from a checkout:
+#   ./setup.sh
+#
+# Set QO_SKIP_DEPS=1 to skip the package-manager step (e.g. you already have go).
+set -e
+
+APP_NAME="qo"
+INSTALL_DIR="/usr/local/bin"
+REPO_URL="https://github.com/Open-Source-Community/qo2.git"
+
+log()  { printf '\033[1;36m[qo]\033[0m %s\n' "$*"; }
+warn() { printf '\033[1;33m[qo]\033[0m %s\n' "$*"; }
+die()  { printf '\033[1;31m[qo]\033[0m %s\n' "$*" >&2; exit 1; }
+
+need() { command -v "$1" >/dev/null 2>&1; }
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+detect_pkg_mgr() {
+    if have apt-get; then echo apt
+    elif have dnf; then echo dnf
+    elif have pacman; then echo pacman
+    elif have zypper; then echo zypper
+    elif have apk; then echo apk
+    elif have microdnf; then echo microdnf
+    else echo unknown; fi
+}
+
+install_deps() {
+    [ "${QO_SKIP_DEPS:-0}" = "1" ] && { log "skipping package install (QO_SKIP_DEPS=1)"; return; }
+
+    local mgr
+    mgr=$(detect_pkg_mgr)
+    log "detected package manager: $mgr"
+
+    case "$mgr" in
+        apt)
+            sudo apt-get update -y
+            sudo apt-get install -y git golang-go gcc libc6-dev tar gzip curl ca-certificates
+            ;;
+        dnf|microdnf)
+            if command -v sudo >/dev/null 2>&1; then
+                sudo dnf install -y git golang gcc glibc-devel tar gzip curl ca-certificates
+            else
+                dnf install -y git golang gcc glibc-devel tar gzip curl ca-certificates
+            fi
+            ;;
+        pacman)
+            sudo pacman -Sy --noconfirm --needed git go gcc tar gzip curl ca-certificates
+            ;;
+        zypper)
+            sudo zypper install -y git go gcc glibc-devel tar gzip curl ca-certificates
+            ;;
+        apk)
+            apk add --no-cache git go gcc musl-dev tar gzip curl ca-certificates
+            ;;
+        *)
+            warn "unsupported package manager; assuming go is already installed"
+            ;;
+    esac
+
+    if ! need go; then
+        warn "go is not on PATH; install it from https://go.dev/dl/ or re-run with QO_SKIP_DEPS=0"
+    fi
+}
+
+build_and_install() {
+    local srcdir="$1"
+
+    cd "$srcdir"
+
+    # Static build: the sandbox copies this binary into the chroot as /bin/qo-check,
+    # so it must not depend on host glibc.
+    log "building static binary (CGO_ENABLED=0)..."
+    CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o "$APP_NAME" .
+
+    local dest="$INSTALL_DIR/$APP_NAME"
+    if [ -w "$INSTALL_DIR" ]; then
+        mv -f "$APP_NAME" "$dest"
+    else
+        sudo mv -f "$APP_NAME" "$dest"
+    fi
+    sudo chmod 755 "$dest"
+
+    # Aliases the sandbox expects; they share the same binary and dispatch on argv[0].
+    for alias in qo-check qo-setup qo-reset; do
+        sudo ln -sf "$dest" "$INSTALL_DIR/$alias"
+    done
+
+    log "installed: $dest"
+}
+
+if [ "$1" = "uninstall" ]; then
+    for a in qo qo-check qo-setup qo-reset; do
+        sudo rm -f "$INSTALL_DIR/$a"
+        log "removed $INSTALL_DIR/$a"
+    done
+    exit 0
+fi
+
+# Build from a local checkout if present, otherwise clone a fresh copy.
+if [ -f ./main.go ] && [ -d ./pkg ]; then
+    log "building from local checkout: $PWD"
+    install_deps
+    build_and_install "$PWD"
+else
+    install_deps
+    TMP_DIR=$(mktemp -d)
+    trap 'rm -rf "$TMP_DIR"' EXIT
+    log "cloning $REPO_URL ..."
+    git clone --depth=1 "$REPO_URL" "$TMP_DIR/qo2"
+    build_and_install "$TMP_DIR/qo2"
+fi
+
+log "done. Verify with: qo --help"