Zum Inhalt
Rechenknecht

Wartung & Eigenbau

Das Projekt selbst pflegen: die App bauen mit hochzählender Version, das EchtOS-Image bauen und ausliefern, eigene EchtOS-Plugins schreiben und einbinden.

Alle Befehle zum Kopieren. Quelle: WARTUNG.md im Projekt-Repo.

Was liegt wo

Ordner im Projekt
OrdnerInhalt
rechenknecht_app/Android-App (Kotlin/Compose). Build über build.sh.
server/rechenknecht_server/Python-Server: verteilt Aufgaben an die Handys, liefert Plugins aus.
werkbank-image-build/EchtOS-Images bauen (echtos-image.sh + die rootfs/-Bäume).
plugins/<name>/Austauschbare EchtOS-Plugins (ohne App-Neubau einbindbar).

Host-spezifisch ist nur der Server belana und der Download-Pfad /home/www/dev/rechenknecht/download/. Auf einem anderen Server die Variablen SRV/DL oben in build.sh und echtos-image.sh anpassen.

Hier geht es um die EchtOS-Plugins (Ordner mit plugin.json, laufen im Gast auf dem Handy). Die Server-Plugins (einzelne .py auf dem Rechner) sind ein eigenes System und stehen auf der Plugins-Seite.

1 · App bauen und Version hochzählen

Version setzen

Vor jedem Release die Version in rechenknecht_app/app/build.gradle.kts erhöhen:

versionCode = 112        // GANZZAHL, muss bei jedem Upload größer werden (Self-Update vergleicht die)
versionName = "0.9.76"   // Anzeigename, frei wählbar

versionCode ist die Pflicht-Stellschraube: Der Upload bricht ab, wenn er nicht größer ist als die zuletzt veröffentlichte Nummer. versionName ist nur Text.

Bauen

cd rechenknecht_app
./build.sh              // nur bauen → APK nach ../rechenknecht-apk/
./build.sh hochladen    // bauen UND auf den Server stellen + Self-Update scharf schalten
./build.sh install      // bauen UND per adb aufs angeschlossene Gerät

Was ./build.sh hochladen nacheinander tut:

  • Tests (:app:testDebugUnitTest) — schlägt einer fehl, bricht alles ab.
  • Signierte Release-APK (R8), 16-KB-Ausrichtung und Signatur geprüft.
  • Version aus der fertigen APK gelesen (nie aus einer Konstante).
  • Prüft, dass versionCode größer ist als die veröffentlichte Nummer.
  • APK per rsync nach belana, app-version.json gesetzt.
  • Gegenprüfung von außen: lädt die veröffentlichte APK zurück und vergleicht den SHA-256.
  • Registriert die Version beim Deck-Server, damit die Handys das Update finden.

Regeln

  • Der Build läuft über gradle-sicher.sh (eigener systemd-Scope + Sperre), damit der oom-Killer auf dem Deck nicht die Sitzung abräumt. Nie direkt ./gradlew aufrufen.
  • Der Keystore liegt in ~/.keystores/rechenknecht.jks (+ .ks_pass). Fehlt er, bricht der Build ab.
  • Build immer am Ende eines Arbeitsblocks, nicht zwischendurch (Ressourcen).

2 · EchtOS-Image bauen

Werkzeug: werkbank-image-build/echtos-image.sh. Es ändert das rootfs/ (Pakete/Dateien), baut daraus ein tar.gz, lädt es nach belana und pinnt SHA-256 + Größe in Distro.kt. Alles mit Gegenprüfung des Hashes.

Es gibt zwei Images: desktop (Standard, XFCE/VNC, rootfs/) und console (schlanke Konsole, konsole/rootfs/, mit -k oder --image console).

Befehle

cd werkbank-image-build

// Ändern:
./echtos-image.sh add <pkg…>           // Pakete ins Image (apk, aarch64, ohne Skripte)
./echtos-image.sh del <pkg…>           // Pakete entfernen
./echtos-image.sh search <muster>      // Paket im Alpine-Repo suchen
./echtos-image.sh cp <lokal> <ziel>    // Datei ins rootfs kopieren
./echtos-image.sh edit <pfad>          // Datei im rootfs mit $EDITOR öffnen
./echtos-image.sh enter                // Gast-Shell (braucht qemu-aarch64)

// Bauen & ausliefern:
./echtos-image.sh build                // strip + tar.gz packen (SHA + Größe)
./echtos-image.sh upload               // tar nach belana (mit Hash-Gegenprüfung)
./echtos-image.sh pin                  // Distro.kt auf aktuelle SHA + Größe setzen
./echtos-image.sh release              // build + upload + pin in einem
./echtos-image.sh status               // SHA/Größe lokal vs belana vs Distro.kt

// Für das Konsolen-Image jeweils -k davor:
./echtos-image.sh -k add tor
./echtos-image.sh -k release

Typischer Ablauf (ein Paket hinzufügen)

cd werkbank-image-build
./echtos-image.sh add conky greybird-themes     // ins rootfs
./echtos-image.sh release                        // bauen, hochladen, Distro.kt pinnen
cd ../rechenknecht_app && ./build.sh hochladen   // APK zeigt auf das neue Image

Am Gerät danach: Linux-Reiter → Verwalten ▾ → Neu einrichten (lädt das neue Image).

Fallen

Pakete müssen INS Image gebacken werden — am Handy kann der Gast nichts nachinstallieren (kein Netz im proot, apk add scheitert). Niemals apk fix/Reinstall zur Laufzeit, das zerstört auf einem --no-cache-Image offline Dateien. strip (läuft bei build automatisch) hält das Image klein. enter braucht qemu-aarch64; ohne das reichen für Änderungen add/del/cp/edit.

Desktop lokal ansehen und stylen

Den XFCE-Desktop auf dem Rechner (statt am Handy) hochziehen, live hübsch machen und die Werte automatisch übernehmen.

Einmalig: qemu-user-static

sudo pacman -S --needed qemu-user-static qemu-user-static-binfmt
sudo systemctl restart systemd-binfmt

Zeigen & stylen

cd werkbank-image-build
./echtos-image.sh desktop          // startet den Desktop (nspawn+qemu), blockiert dann

Im Browser öffnen: http://127.0.0.1:6080/vnc.html?autoconnect=1&resize=scale (beenden: im Terminal Strg+] dreimal). Läuft auf freiem Display :8, weil der Rechner selbst :0/:1 belegt; am Gerät bleibt es bei :1.

Werte übernehmen (automatisch)

./echtos-image.sh theme            // GTK-Theme, Icons, DPI, Fensterrahmen → theme.env

Danach bauen: neue Themes/Icons installiert → ./echtos-image.sh release; und immer (cd ../rechenknecht_app && ./build.sh hochladen).

Wallpaper wechseln

./echtos-image.sh wallpaper /pfad/zum/bild.png     // PNG oder JPG
(cd ../rechenknecht_app && ./build.sh hochladen)   // kein release nötig (App-Asset)

Vorschau vorher mit ./echtos-image.sh desktop.

Grenze. Das Panel-Layout steckt noch fest in start-desktop.sh.

3 · EchtOS-Plugins schreiben und einbinden

EchtOS-Plugins sind austauschbar ohne App-Neubau: ein Ordner unter plugins/<name>/, den der Server SHA-256-gepinnt ans Handy ausliefert. Verwaltet werden sie im Plugins-Reiter der App (an/aus, synchronisieren).

plugin.json — Felder

name
Werkzeugname, Kleinbuchstaben/Unterstrich (z. B. cve_matcher).
beschreibung
Ein, zwei Sätze, wann das Plugin hilft (sieht die KI).
schema
JSON-Schema-Objekt: properties + required. Das sind die Argumente.
skript *
Einstiegsdatei. .py läuft mit python3, .sh mit sh.
dateien
Liste aller mitzuliefernden Dateien (Skript, Datenbanken …).
nur_lesen
true = läuft ohne Rückfrage; false = erst nach Bestätigung.
shell
echtos (Pentest-Gast) oder system (Android-Shell, ohne su).
tor
true = Verkehr über Tor; läuft nur bei aktivem Tor-Plugin (SOCKS 9050 live), sonst Abbruch.

* Reine Dienst-Plugins (wie tor) haben statt skript die Felder start/stop, kein_werkzeug: true und ggf. braucht_pkg.

Minimalbeispiel

plugins/hallo/plugin.json:

{
  "name": "hallo",
  "beschreibung": "Begrüßt einen Namen. Nur ein Test.",
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string", "description": "Wen grüßen" }
    },
    "required": ["name"]
  },
  "nur_lesen": true,
  "shell": "echtos",
  "tor": false,
  "skript": "skript.py",
  "dateien": ["skript.py"]
}

plugins/hallo/skript.py:

import sys, json
args = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {}
print(f"Moin, {args.get('name', 'Welt')}!")

Runner-Vertrag

  • Das Plugin bekommt seine Argumente als ein JSON-String als erstes Argument und gibt sein Ergebnis über stdout zurück (reiner Text).
  • shell: echtos läuft im Gast (/root/plugins/<name>/), shell: system in der Android-Shell (App-privat).
  • Bei tor: true setzt der Runner RK_PROXY/ALL_PROXY auf socks5://127.0.0.1:9050 — aber nur, wenn das Tor-Plugin aktiv und der Port live ist.
  • Ergebnisse werden zusätzlich im Gast unter /root/ergebnisse/<name>-<zeit>.txt abgelegt (überleben einen abgebrochenen Aufruf).

Echte Beispiele zum Abgucken

Zwei fertige, nutzbare Plugins liegen als Vorlage im Repo — gute Muster für eigene (HTTP holen, HTML parsen, Text ausgeben):

  • plugins/kleinanzeigen/ — Suche auf Kleinanzeigen.de (Ort/Umkreis, Preisfilter, Trefferliste).
  • plugins/wayback/ — Wayback Machine (archive.org): Aufnahmen finden, auflisten, lesen, zwei Zeitpunkte vergleichen.

Beide nutzen requests + beautifulsoup4 (liegen im Image) und spiegeln eingebaute App-Werkzeuge. wayback heißt anders als das eingebaute wayback_machine, kollidiert also nicht; kleinanzeigen gibt es nur noch als Plugin, eingebaut ist es nicht mehr.

Einbinden (am Gerät, ohne App-Neubau)

  1. Ordner unter plugins/<name>/ ablegen, Server läuft.

  2. In der App: Plugins-Reiter → Deck-Plugins → Synchronisieren. Die App lädt geänderte Dateien SHA-geprüft in den Gast.

  3. Plugin anschalten. Danach kennt die KI es als Werkzeug.

Braucht dein Plugin ein Programm im Gast (z. B. nmap), muss das vorher ins Image (Abschnitt 2, add). Reine Python-Skripte mit Standardbibliothek brauchen das nicht.

Sicherheit

nur_lesen: true nur für Plugins, die wirklich nichts verändern — alles andere fragt vor jedem Lauf. Tor-gebundene Plugins (tor: true) laufen nie ungeschützt direkt: ohne aktives Tor-Plugin bricht der Runner ab.

4 · Spickzettel: Reihenfolge

Nur App geändert (Kotlin)

cd rechenknecht_app
// Version in app/build.gradle.kts hochzählen
./build.sh hochladen

Image geändert (Paket/Datei im Gast)

cd werkbank-image-build
./echtos-image.sh add <pkg>        // oder del/cp/edit
./echtos-image.sh release
cd ../rechenknecht_app && ./build.sh hochladen
// Gerät: Linux → Verwalten ▾ → Neu einrichten

Plugin geändert (kein Build nötig)

// Datei in plugins/<name>/ ändern → in der App: Plugins → Synchronisieren