Konfiguration und Richtlinien

Das Richtlinienmodell

Jede Einstellung, die das Verhalten steuert, ist eine Richtlinie auf drei Ebenen:

1. global — der gesamte Host
2. account — ein CyberPanel-Benutzer
3. domain — eine Website oder Child-Domain

Die spezifischere Ebene gewinnt, und jede Ebene kann einzelne Schlüssel erben oder überschreiben. Innerhalb einer Domain sind zusätzlich Pfadregeln mit Globs relativ zum Document-Root möglich.

Die Zuordnung erfolgt über einen Document-Root-Index, den der Broker aus der CyberPanel-Datenbank führt (Website, Child-Domain, Document-Root, Eigentümer) und der per Timer sowie bei Änderungen im Panel aktualisiert wird. fanotify-Ereignisse werden über das längste passende Document-Root-Präfix einem Konto und einer Domain zugeordnet. Der PHP-Adapter übergibt DOCUMENT_ROOT und SERVER_NAME; entscheidend ist der Document-Root, der Servername dient nur als Plausibilitätsprüfung. Dateien außerhalb jedes Document-Roots — E-Mail, Backups, das Home-Verzeichnis — fallen unter die Kontorichtlinie.

Richtlinien sind versioniert. Eine Änderung verwirft nur die pfadabhängigen Richtlinien-Urteile der betroffenen Domain, nicht die inhaltlichen Urteile.

Die Schlüssel

Lesen und Schreiben aus der Shell:

shelltrap policy get global
shelltrap policy set global signature.action=report hash.action=report
shelltrap policy set domain 42 heuristics.action=quarantine
shelltrap policy effective site 42

policy effective ist der Befehl für den Streitfall: Jeder Schlüssel kommt mit seinem Wert und seiner Herkunft zurück — domain, account, global oder default —, sodass die Vererbung sichtbar ist und nicht erschlossen werden muss.

Ignore-Regeln sind keine Richtlinien

Ignore-Regeln liegen in einer eigenen API und sind eine Administratoraktion. Es gibt vier Arten: path_glob, signature, hash und user.

shelltrap ignore add --scope domain --scope-id 42 --kind path_glob --value 'cache/**' \
  --note 'generated cache'
shelltrap ignore list
shelltrap ignore remove <id>

Eine Ignore-Regel unterdrückt die Aktion, niemals den Scan oder die Aufzeichnung des Funds. Genau diese Unterscheidung macht eine Ignore-Liste prüfbar statt zur Augenbinde.

Die lokale API

Die API ist HTTP/1.1 über den Unix-Socket /run/shelltrap/api.sock, Modus 0600, Eigentümer root. Sie ist nicht über TCP erreichbar und verwendet keine Cookies. Der Server liest bei jeder angenommenen Verbindung SO_PEERCRED und akzeptiert im Produktivbetrieb nur die Peer-UID 0; alles andere erhält HTTP 403, bevor ein Backend-Aufruf stattfindet.

• JSON-Medientyp application/json, Anfrage-Bodys auf 1 MiB begrenzt, Seitengröße auf 500 begrenzt.
• X-Shelltrap-Actor: <panel-user> veranlasst den Broker, Name und Rolle selbst aufzulösen. Eine vom Client behauptete Rolle wird nie akzeptiert, und das Backend schränkt die Ergebnisse zusätzlich auf die eigenen Sites des Akteurs ein.
• Jede Antwort trägt X-Request-ID. Bei Schreibzugriffen wirkt eine vom Client gelieferte ID zugleich als Replay-Schutz: Wird sie innerhalb des Erinnerungsfensters erneut verwendet, kommt HTTP 409 replayed_request zurück.
• Die Ratenbegrenzung gilt je Peer-UID, standardmäßig 600 Anfragen pro Minute; bei Überschreitung kommt 429 zurück.
• Metriken kommen im Prometheus-Textformat zurück, nicht als JSON.

curl --silent --unix-socket /run/shelltrap/api.sock http://localhost/v1/health
curl --silent --unix-socket /run/shelltrap/api.sock \
  -H 'X-Shelltrap-Actor: reseller1' \
  'http://localhost/v1/findings?verdict=malicious&page=1&page_size=50'

Das freie Scannen beliebiger Pfade (POST /v1/scan mit einem path) steht ausschließlich dem Systemakteur auf einer Verbindung mit Peer-UID 0 offen. Ein Panel- oder UI-Akteur kann durch die Angabe eines Pfads niemals einen Dateizugriff als root auslösen.

Die CLI

shelltrap status
shelltrap health
shelltrap scan SITE | --account ACCOUNT | --path PATH
shelltrap findings list|show|resolve
shelltrap quarantine list|restore|purge
shelltrap policy get|set|effective
shelltrap ignore add|list|remove
shelltrap feeds list|update|rollback
shelltrap audit tail
shelltrap jobs list
shelltrap metrics

Globale Optionen sind --json, --socket PATH (Voreinstellung /run/shelltrap/api.sock) und --actor NAME; sie stehen vor dem Befehl. --json gibt die API-Antwort unverändert aus; ohne die Option erhalten Sie eine deterministische, menschenlesbare Tabelle. Exit-Codes: 0 Erfolg, 1 API- oder Antwortfehler, 2 Aufruffehler, 3 API nicht erreichbar.

$ shelltrap license activate STL-7QK3M-P2VDA-XN94T-B6HRE-Z8SWF
plan             server
key prefix       STL-7QK3M
valid until      2027-09-04
token until      2026-10-04
fingerprint      e3b0c44298fc1c14…
servers          1 of 1
token written to /etc/shelltrap/license.token (0600, root)
$ shelltrap --json health
{"status":"ok","watcher_tier":"A","scanner_workers":2,"clamd":"ok",
 "ruleset_gen":"20260903T120000Z-0001","policy_gen":17,"queue_age_s":0,
 "overflows":0,"feeds":"ok"}

Aktivierung und eine Health-Prüfung mit –json, das die API-Antwort unverändert zurückgibt.

Health und worauf Sie alarmieren sollten

GET /v1/health liefert den Betriebszustand:

{
  "status": "ok",
  "watcher_tier": "A",
  "scanner_workers": 2,
  "clamd": "ok",
  "ruleset_gen": "20260903T120000Z-0001",
  "policy_gen": 17,
  "queue_age_s": 0,
  "overflows": 0,
  "feeds": "ok"
}

status lautet ok oder degraded. Bei degraded nennt degraded_reasons jede Ursache — Live-Prüfungen wie ruleset_missing, worker_dead, worker_landlock_missing, clamd_unavailable, namespace_fallback, policy_generation_unavailable, notify_target_unavailable und policy_error sowie interne Fehlerzähler seit dem Prozessstart.

Ein Unterstatus not_configured an einem optionalen Benachrichtigungsziel macht den Gesamtstatus für sich genommen nicht degradiert. Ein beeinträchtigter Scanner oder ein clamd-Ausfall darf niemals als sauberer Scan gelesen werden.

Eine Alarmregel wert, aus unserer eigenen Beobachtungscheckliste:

Halten Sie an und gehen Sie der Sache nach, wenn Overflows anhalten, das Queue-Alter zehn Minuten überschreitet, Worker in einer Schleife neu starten, der RSS eines Workers unbegrenzt wächst oder Kunden über I/O-Last klagen.

Aufbewahrung und Datenschutz

Voreinstellungen: Funde 180 Tage, Quarantäne 30 Tage mit Vorwarnung, Audit ein Jahr. Alles konfigurierbar. Ein Purge läuft nie stillschweigend ab. Standardmäßig verlässt nichts den Host: Ausgehende Ziele stehen auf einer Allowlist, und Code für Samples und Telemetrie wird ohne Opt-in nicht geladen. Logs enthalten keine Geheimnisse und keine Dateiinhalte.

Weiter

• Das CyberPanel-Plugin — dieselben Operationen mit Rollen, im Panel
• Signatur-Feeds — Generationen, Gating und Rollback