Das CyberPanel-Plugin

Vor der Installation

Der Shelltrap-Broker muss laufen, /run/shelltrap/api.sock muss vorhanden sein, und CyberPanel muss installiert sein. Das Plugin-Archiv wird reproduzierbar gebaut und enthält genau ein Verzeichnis shelltrap/ auf oberster Ebene, ohne Caches und ohne Python-Bytecode.

cd /usr/local/CyberCP
/usr/local/CyberCP/bin/python /usr/local/CyberCP/pluginInstaller/pluginInstaller.py \
  install --pluginName shelltrap

Warum die Installation so vorsichtig vorgeht

Der CyberPanel-Installer patcht Kerndateien — CyberCP/settings.py, CyberCP/urls.py und das Sidebar-Template — durch das Einfügen von Zeilen, und seine Hook-Aufrufe nutzen subprocess.call und ignorieren Exit-Codes. Ein fehlgeschlagener Preflight kann die Installation daher nicht daran hindern, Erfolg zu melden.

Deshalb verteidigt sich das Plugin selbst:

• pre_install schreibt einen root-eigenen Transaktionsmarker unter /var/lib/shelltrap/plugin-install-transaction.json und legt drei atomare Snapshots der Kerndateien an. Der Marker wird zuerst im Zustand preparing veröffentlicht, mit den geplanten Snapshot-Pfaden, Größen, SHA-256-Prüfsummen und ursprünglichen Metadaten; der vollständige Satz wechselt dann nach pending und, nach allen Prüfungen, nach ready. Symlinks, Hardlinks, falsche Eigentümer, unvollständige Snapshots oder abweichende Prüfsummen werden zurückgewiesen.
• post_install wertet diesen Marker aus, unabhängig davon, was der native Installer ausgegeben hat. Ein vollständiger Satz im Zustand preparing, failed oder pending wird validiert und zurückgerollt. Ein unvollständiger Satz führt zu degraded ohne teilweises Zurückrollen der Kerndateien, und der Marker bleibt zur Prüfung erhalten.
• Nur bei ready führt post_install das mitgelieferte repair.sh aus, das die drei Kerndateien prüft, ausschließlich den statischen Shelltrap-Teilbaum abgleicht, manage.py check ausführt und lscpd neu startet.
• Zuletzt wird die Health-Antwort über den Unix-Socket geprüft und das Ergebnis nach /var/lib/shelltrap/plugin-status.json geschrieben. Ein nicht erreichbarer oder degradierter Broker wird nie als gesund markiert, und eine Erfolgsmeldung des historischen Installers ersetzt diese Datei nicht.

Upgrade und Reparatur nach einem Panel-Upgrade

Der historische Installer entpackt ohne -o und kann interaktiv nachfragen, wenn Dateien bereits vorhanden sind. Für ein kontrolliertes Upgrade entpacken Sie ausdrücklich und führen die Hooks selbst aus:

unzip -oq /path/to/shelltrap.zip -d /usr/local/CyberCP
/usr/local/CyberCP/shelltrap/pre_install
/usr/local/CyberCP/shelltrap/post_install

Ein CyberPanel-Upgrade kann dieselben Kerndateien neu schreiben, deshalb ist das Reparaturskript idempotent und kann eigenständig ausgeführt werden:

/usr/local/CyberCP/shelltrap/repair.sh

Es stellt genau einen shelltrap-Eintrag in INSTALLED_APPS, genau einen Eintrag path('shelltrap/', include('shelltrap.urls')) und genau einen Sidebar-Link wieder her und erkennt dabei sowohl die alte Struktur url(...)/<li> als auch die aktuelle Form path(...)/<a class="menu-item">. Symlinks, Hardlinks und unerwartete Strukturen werden zurückgewiesen. Im Fehlerfall rollt es die drei Dateien und den eigenen statischen Teilbaum zurück und startet lscpd mit dem vorherigen Zustand neu. Es löscht niemals Zeilen, die es nicht selbst geschrieben hat.

Seiten

Dashboard und Health · Funde mit Filtern, Seitenblättern, Detailansicht und Signalen · Quarantäne mit Wiederherstellung, Purge nur für Administratoren · Richtlinien je Domain mit sichtbarer Vererbung global → account → domain · Ignore-Listen · Feed-Generationen · Audit nur für Administratoren · Jobs · Hilfe und Status.

Jede Signalanzeige führt Autor, Quelle und Lizenzangabe mit, sofern die Regel sie bereitstellt. Für einige der Regelsätze Dritter ist das eine Lizenzpflicht, und außerdem ist es schlicht nützlich.

Rollen

upload.on_error und heuristics.action bleiben für Reseller und Kunden jederzeit gesperrt, und der Broker setzt diese Grenze unabhängig von der Oberfläche durch. Sammelbearbeitung über mehrere Domains hinweg wird nur Administratoren angeboten; für alle anderen weist der Endpunkt eine Mehrfachauswahl fail-safe zurück und akzeptiert höchstens eine vom Broker autorisierte Domain.

Ein Administrator kann das über zwei Django-Einstellungen weiter einschränken, die mit der festen Liste der unterstützten Schlüssel geschnitten werden:

SHELLTRAP_POLICY_ALLOWED_KEYS = {
    "reseller": ["scan.window", "scan.exclude", "notify.targets"],
    "user": ["scan.window", "scan.exclude"],
}
SHELLTRAP_POLICY_LOCKED_KEYS = {
    "default": [],
    "user": ["scan.exclude"],
}

Fehlt eine Rolle in einer ausdrücklichen Allowlist oder ist eine Einstellung ungültig, verweigert das Plugin den Schreibvorgang fail-safe, statt zu raten.

Sicherheitsgrenzen

Die API ist ausschließlich als HTTP/1.1 über /run/shelltrap/api.sock erreichbar. Der Plugin-Client setzt X-Shelltrap-Actor aus der authentifizierten CyberPanel-Sitzung, und der Broker löst die effektive Rolle und den Site-Geltungsbereich selbst auf. Es gibt keine TCP-Verbindung, und das Plugin überträgt keine Root-Pfade. Jede Änderung aus dem Browser ist ein POST-Formular, das durch den Django-CSRF-Mechanismus von CyberPanel geschützt ist; die von der API benötigten PUT- und DELETE-Aufrufe erfolgen ausschließlich durch den serverseitigen Client.

Das Plugin führt weder Parser noch Scanner noch Quarantäneoperationen als root aus. Es zeigt IDs und Metadaten an, die der Broker liefert. Ein Ausfall der Oberfläche stoppt keinen laufenden Scan und keinen geplanten Job.

Bekannte Grenzen der API

Zwei Unebenheiten werden dokumentiert statt verschwiegen:

• Die globale Richtlinienebene ist über den HTTP-Endpunkt nur eingeschränkt zuverlässig, weil /v1/policies/{scope}/{scope_id} formal eine nicht leere scope_id verlangt, während der interne globale Geltungsbereich eine leere verwendet. Die effektive Site-Richtlinie einschließlich ihrer Herkunft funktioniert und ist die maßgebliche Sicht für den Betrieb.
• Die Ignore-API unterstützt Anlegen und Löschen, kennt aber kein atomares Aktualisieren. Eine Änderung legt deshalb zuerst die vollständig validierte neue Regel an, prüft die zurückgegebene opake ID streng und löscht erst dann die alte. Schlägt dieses Löschen fehl, versucht das Plugin zu kompensieren, indem es die neue Regel entfernt, und meldet den Fehlschlag sichtbar — einschließlich eines Fehlschlags der Kompensation selbst.

Deinstallation

/usr/local/CyberCP/bin/python /usr/local/CyberCP/pluginInstaller/pluginInstaller.py \
  remove --pluginName shelltrap

pre_remove entfernt idempotent den App-Eintrag, den URL-Eintrag, den modernen oder historischen Sidebar-Eintrag und den mitgelieferten statischen Teilbaum und löscht anschließend plugin-status.json. Es stoppt keinen Broker-Dienst und löscht weder Funde noch Quarantäne, Konfiguration, Logs oder die Broker-Datenbank. Das Plugin hält keine Django-Modelle und keinen eigenen Datenbankzustand.

Fehlersuche

1. test -S /run/shelltrap/api.sock bestätigt, dass der Socket wirklich ein Unix-Socket ist; prüfen Sie danach stat und den Inhalt von plugin-status.json.
2. Bei degraded prüfen Sie zuerst den Broker-Dienst und danach den CyberPanel-Dienst. Ein Health-Fehler ist eine Betriebsstörung und kein sauberer Scan.
3. Führen Sie nach einem Panel-Upgrade repair.sh erneut aus. Meldungen über Symlinks, Hardlinks oder eine unerwartete Struktur erfordern einen Menschen; das Skript löscht nichts, was ihm nicht gehört.
4. Scheitert eine Reparatur, ist die vorherige Fassung der drei Kerndateien intakt. Führen Sie manage.py check aus, sehen Sie sich die darin genannte Datei an und wiederholen Sie dann die Reparatur.

Meldet der native Installer Erfolg, obwohl ein Hook mit Fehler beendet wurde, löschen Sie den Marker nicht von Hand. Sehen Sie ihn sich an und führen Sie dann den vorgesehenen Rollback-Pfad erneut aus:

stat -c '%a %U:%G %n' /var/lib/shelltrap/plugin-install-transaction.json
cat /var/lib/shelltrap/plugin-install-transaction.json
/usr/local/CyberCP/shelltrap/post_install

Weiter

• Konfiguration und Richtlinien
• Lizenzierung und Aktivierung