Add sone documentation and README's.
This commit is contained in:
@@ -0,0 +1,134 @@
|
||||
# Bad-Signature-Toolkit: Zusammenfassung der neuen/aktualisierten Scripte
|
||||
|
||||
Stand: 14.09.2026
|
||||
|
||||
## Ausgangslage
|
||||
|
||||
Im Rahmen der Bereinigung von "Bad Signature"-Fehlern (fehlerhafte Server-Side-Encryption-Signaturen) auf mehreren Nextcloud-Instanzen wurde das bestehende Toolkit um zwei Punkte erweitert:
|
||||
|
||||
1. **`restore_bad_signature.sh`** schreibt jetzt standardmäßig nicht nur streng geprüfte ("VALID"), sondern auch plausible, aber nicht abschließend prüfbare Dateien zurück ("Nicht prüfbar"/UNVERIFIED).
|
||||
2. **`delete_files.sh`** ist ein neues, generisches Script, um eine explizite Liste nicht benötigter Dateien zu löschen – unabhängig von Account oder Site, ohne Sonder-/Einmal-Scripte pro Vorfall.
|
||||
|
||||
Damit lässt sich der komplette Workflow konsequent nach einem einfachen Prinzip abbilden:
|
||||
|
||||
> **Unauffällige Dateien schreiben wir zurück. Dateien, die es nicht braucht, löschen wir.**
|
||||
|
||||
Beide Scripte reihen sich in das bestehende Toolkit ein:
|
||||
|
||||
```
|
||||
scan_bad_signature.sh -> findet betroffene Dateien (read-only)
|
||||
recover_bad_signature.sh -> entschlüsselt/prüft sie in ein separates Verzeichnis (read-only)
|
||||
restore_bad_signature.sh -> schreibt geprüfte Dateien an ihren Originalort zurück
|
||||
recreate_bad_signature.sh -> Fallback: löscht+erstellt neu (bricht Freigaben, nur für die schwierigere Fehlerklasse)
|
||||
delete_files.sh -> NEU: löscht eine explizite Liste nicht benötigter Dateien
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 1. `restore_bad_signature.sh` (aktualisiert)
|
||||
|
||||
### Zweck (unverändert)
|
||||
|
||||
Schreibt bereits wiederhergestellte und geprüfte Dateien (Ergebnis eines vorherigen `recover_bad_signature.sh`-Laufs) über die normale Nextcloud-Files-API an ihren **ursprünglichen Pfad** zurück. Das ist der einzige Schreibweg, der Datei-ID und Freigaben erhält (im Gegensatz zu `recreate_bad_signature.sh`).
|
||||
|
||||
### Was sich geändert hat
|
||||
|
||||
Bisher wurden nur Dateien zurückgeschrieben, deren Recovery-Report-Eintrag `validation=VALID` trug – also Dateien, bei denen eine dedizierte Strukturprüfung (PDF-Header, ZIP-Integrität, Bildsignatur usw.) den Inhalt tatsächlich bestätigen konnte.
|
||||
|
||||
**Jetzt werden standardmäßig zwei Kategorien zurückgeschrieben:**
|
||||
|
||||
| Kategorie | Bedeutung | Wird restauriert? |
|
||||
|---|---|---|
|
||||
| `VALID` | Dedizierte Strukturprüfung hat den Inhalt bestätigt | Ja (wie bisher) |
|
||||
| `UNVERIFIED` ("Nicht prüfbar"), Größenverhältnis plausibel | Kein dedizierter Check für diesen Dateityp vorhanden, aber nichts sieht falsch aus | **Ja, neu** |
|
||||
| `UNVERIFIED`, Größenverhältnis "LOOKS OFF" | Wie oben, aber das Größenverhältnis der Datei ist auffällig | Nein – wie `INVALID`/"Datenmüll" ausgeschlossen |
|
||||
| `INVALID` ("Datenmüll") | Strukturprüfung ist fehlgeschlagen | Nein (unverändert) |
|
||||
|
||||
Der einzige Fall, der tatsächlich ein Warnsignal ist (auffälliges Größenverhältnis), bleibt also weiterhin ausgeschlossen – kein Override möglich. Alles andere, das lediglich "nicht abschließend prüfbar, aber unauffällig" ist, wird ab sofort mit restauriert, ohne dass dafür ein Sonder-Script pro Account nötig wäre.
|
||||
|
||||
### Transparenz
|
||||
|
||||
Damit eine zurückgeschriebene UNVERIFIED-Datei nie mit einer echten VALID-Verifikation verwechselt wird:
|
||||
|
||||
- Der Restore-Report bekommt eine eigene Spalte `origin` (`VALID` oder `UNVERIFIED`).
|
||||
- Eigene Zähler pro Account und in der Gesamtsumme ("davon 'Nicht prüfbar'/UNVERIFIED: N").
|
||||
- Ausdrücklicher Hinweis im Report und am Ende des Laufs, diese Dateien stichprobenartig zu prüfen.
|
||||
|
||||
### Sicherheitsmechanismen (unverändert)
|
||||
|
||||
- Jede Datei wird unmittelbar vor dem Schreiben mit den *aktuellen* Prüfregeln erneut validiert (nicht blind aus dem alten Report übernommen).
|
||||
- Der aktuell noch kaputte Chiffretext wird vor dem Überschreiben byte-genau gesichert (`/var/nc-restore-backup/<website>`).
|
||||
- Nach jedem Schreiben wird die Datei über den normalen Lesepfad zurückgelesen und per SHA-256 mit der Quelle verglichen.
|
||||
- Dry-Run ist Standard, ohne `-n` wird interaktiv gefragt; eine ausdrückliche `YES`-Bestätigung ist für den echten Lauf nötig.
|
||||
|
||||
### Aufruf
|
||||
|
||||
```bash
|
||||
./restore_bad_signature.sh -s <website>
|
||||
# oder, nur Dry-Run:
|
||||
./restore_bad_signature.sh -n -s <website>
|
||||
```
|
||||
|
||||
Danach interaktiv: Auswahl des Recovery-Reports, Auswahl der Accounts ("VALID + plausibel UNVERIFIED"-Einträge).
|
||||
|
||||
> **Hinweis:** Ein erneuter Lauf über denselben Report wählt wieder *alle* passenden Einträge des jeweiligen Accounts aus – auch bereits erfolgreich restaurierte. Um gezielt nur einzelne, noch offene Dateien nachzuziehen (z. B. nachträglich als "unauffällig" eingestufte Dateien), empfiehlt es sich, einen auf diese Dateien reduzierten Mini-Report zu verwenden, statt den kompletten Account-Bestand erneut zu überschreiben.
|
||||
|
||||
---
|
||||
|
||||
## 2. `delete_files.sh` (neu)
|
||||
|
||||
### Zweck
|
||||
|
||||
Generischer, wiederverwendbarer Begleiter zu `restore_bad_signature.sh` für die andere Hälfte des Workflows: eine explizite, von Hand geprüfte Liste von Dateien aus der Nextcloud-Live-Ablage entfernen – z. B. Systemdateien (macOS-Spotlight-Index), Fragmente aus "Webseite speichern"-Aktionen oder andere Dateien, die nach Durchsicht als nicht erhaltenswert eingestuft wurden.
|
||||
|
||||
**Nicht** account- oder site-spezifisch – ein einziges Script für alle Fälle, kein Einmal-Script pro Vorfall mehr nötig.
|
||||
|
||||
### Eingabeformat
|
||||
|
||||
Einfache Textdatei, ein Nextcloud-Pfad pro Zeile, im selben Format wie die `path`-Spalte der Toolkit-Reports:
|
||||
|
||||
```
|
||||
/inge/files/Ordner/Datei.ext
|
||||
# Kommentarzeilen mit '#' und Leerzeilen werden ignoriert
|
||||
/anderer-account/files/Anderer/Pfad/datei2.ext
|
||||
```
|
||||
|
||||
Der jeweilige Account wird automatisch aus dem ersten Pfadsegment erkannt – eine Liste kann also Dateien mehrerer Accounts derselben Site mischen.
|
||||
|
||||
### Was passiert beim Löschen
|
||||
|
||||
- Löschen erfolgt über die normale Nextcloud-Files-API (`$node->delete()`) – **derselbe Weg wie im Webinterface**. Ist die App `files_trashbin` aktiv (Standard), landet die Datei im Papierkorb des jeweiligen Accounts und ist von dort wiederherstellbar.
|
||||
- Vor dem Löschen wird der aktuelle Chiffretext zusätzlich byte-genau in ein eigenes Backup-Verzeichnis gesichert (`/var/nc-delete-backup/<website>`) – unabhängig von Nextcloud/Papierkorb.
|
||||
- Ein Pfad, der gar nicht mehr existiert, wird als `NOT_FOUND` gemeldet, nicht als Fehler.
|
||||
- Dry-Run ist Standard, ohne `-n` wird interaktiv gefragt; eine ausdrückliche `YES`-Bestätigung ist für den echten Lauf nötig.
|
||||
|
||||
### Aufruf
|
||||
|
||||
```bash
|
||||
./delete_files.sh -s <website> -f <pfadliste.txt>
|
||||
# oder, nur Dry-Run:
|
||||
./delete_files.sh -n -s <website> -f <pfadliste.txt>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Zusammenspiel der beiden Scripte
|
||||
|
||||
Für einen typischen "Nicht prüfbar"-Restbestand nach einem `recover_bad_signature.sh`-Lauf:
|
||||
|
||||
1. `restore_bad_signature.sh` läuft ganz normal für den Account – nimmt automatisch alle VALID- und plausiblen UNVERIFIED-Dateien mit.
|
||||
2. Was danach als nicht erhaltenswert erkannt wird (z. B. Systemdateien), wandert in eine einfache Pfadliste.
|
||||
3. `delete_files.sh` räumt diese Liste ab – unabhängig davon, ob die Dateien vorher restauriert wurden oder nicht.
|
||||
|
||||
Kein Account und kein Vorfall braucht dafür mehr ein eigenes Script – beide Werkzeuge sind allgemein einsetzbar und für jede Site/jeden Account nutzbar.
|
||||
|
||||
---
|
||||
|
||||
## Beispiel aus der aktuellen Bereinigung (cloud-01.oopen.de)
|
||||
|
||||
Beim Recovery-Lauf für `cloud-01.oopen.de` (Accounts `chris` + `inge`) blieben 11 von 6249 Dateien als "Nicht prüfbar" übrig:
|
||||
|
||||
- **2 Dateien** (Ressourcen eines Lernspiels, `.ctf`/`.md8`) wurden als plausibel eingestuft und werden per `restore_bad_signature.sh` zurückgeschrieben.
|
||||
- **9 Dateien** (7 macOS-Spotlight-Indexdateien, 2 Fragmente aus "Webseite speichern") wurden als nicht erhaltenswert eingestuft und werden per `delete_files.sh` entfernt.
|
||||
|
||||
Beide Scripte behandeln diesen Fall jetzt mit ihrer regulären, generischen Logik – ohne das ursprünglich dafür gebaute Einmal-Script `cleanup_11_misc_files_cloud01.sh`, das damit hinfällig ist.
|
||||
Reference in New Issue
Block a user