dschlueter/integrity_scanner_fuer_statische_Webseiten
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

docs: comprehensive documentation update

Browse source 
README.md:
- Workflow examples updated to URL-first syntax throughout
- report --diff-only added to Incident and Legitimate-Change workflows
- scanner.sh symlink hint added to installation section
- Directory structure overhauled: per-site layout, scanner.sh, template dir
- Removed report --diff-only from "not implemented" extensions list

BEDIENUNGSANLEITUNG.md:
- Section 2: scanner.sh wrapper usage added
- Section 4: manual scan uses URL-first syntax
- Section 9 (alarm): report --diff-only as first investigation step,
  updated all commands to URL-first syntax
- Section 16: directory structure reflects per-site layout + scanner.sh
- Section 19: asset baseline setup now correctly described as automatic

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Dieter Schlüter 2026-06-12 22:34:25 +02:00
commit 0aaf53135a
2 changed files with 92 additions and 77 deletions
Download patch file Download diff file Expand all files Collapse all files

102
BEDIENUNGSANLEITUNG.md
View file

@ -110,7 +110,14 @@ source venv/bin/activate
pip install -r requirements.txt
```
Alle Befehle müssen aus dem Projektverzeichnis ausgeführt werden.
Alle Befehle müssen aus dem Projektverzeichnis ausgeführt werden. Alternativ steht das
Wrapper-Script `scanner.sh` zur Verfügung, das automatisch ins Projektverzeichnis wechselt:
```bash
./scanner.sh https://ihre-website.de scan
# oder nach Ablage in ~/bin/:
scanner https://ihre-website.de scan
```
---
@ -160,10 +167,10 @@ Ab jetzt ist der tägliche Betrieb möglich.
### Manueller Scan
```bash
python -m scanner scan
python -m scanner https://ihre-website.de scan
```
Ergebnis erscheint direkt im Terminal. Der vollständige Report liegt in `reports/`.
Ergebnis erscheint direkt im Terminal. Der vollständige Report liegt in `ihre-website.de/reports/`.
### Automatischer Scan (Cron)
@ -333,10 +340,11 @@ python -m scanner approve --rebuild --note "Nach Angriff bereinigt, neues Redesi
### YELLOW — Warnung
1. Report lesen: `python -m scanner report`
2. Markierte URLs im Browser aufrufen und Quelltext prüfen
3. Ist die Änderung legitim?
- Ja: `python -m scanner approve --url <URL> --note "Grund"`
1. Diffs sichten: `python -m scanner https://ihre-website.de report --diff-only`
2. Vollständigen Report lesen: `python -m scanner https://ihre-website.de report`
3. Markierte URLs im Browser aufrufen und Quelltext prüfen
4. Ist die Änderung legitim?
- Ja: `python -m scanner https://ihre-website.de approve --url <URL> --note "Grund"`
- Nein: Abschnitt [Angriff](#angriff) lesen
### RED — Alarm
@ -348,15 +356,16 @@ Der Score ist ≥ 60. Typische Auslöser: neue externe Domain (50 Pkt.) + Hidden
1. **Nicht sofort approve aufrufen** — das würde den kompromittierten Zustand als neue
Baseline festschreiben.
2. Report sichern: `cp -r reports/$(ls reports/ | tail -1) ~/alarm-$(date +%Y%m%d)/`
3. Website im Browser aufrufen und nach sichtbaren Fremdinhalten suchen.
4. Quelltext der betroffenen Seiten prüfen (insbesondere `display:none`-Bereiche).
5. Hoster kontaktieren, SSH-/FTP-Zugriffslogs prüfen.
6. Dateien mit Backup vergleichen (diff oder rsync --dry-run).
7. Nach vollständiger Bereinigung:
2. Diffs sichten: `python -m scanner https://ihre-website.de report --diff-only`
3. Report sichern: `cp -r ihre-website.de/reports/$(ls ihre-website.de/reports/ | tail -1) ~/alarm-$(date +%Y%m%d)/`
4. Website im Browser aufrufen und nach sichtbaren Fremdinhalten suchen.
5. Quelltext der betroffenen Seiten prüfen (insbesondere `display:none`-Bereiche).
6. Hoster kontaktieren, SSH-/FTP-Zugriffslogs prüfen.
7. Dateien mit Backup vergleichen (diff oder rsync --dry-run).
8. Nach vollständiger Bereinigung:
```bash
python -m scanner scan # muss GREEN ergeben
python -m scanner approve --rebuild --note "Nach Angriff bereinigt $(date +%Y-%m-%d)"
python -m scanner https://ihre-website.de scan # muss GREEN ergeben
python -m scanner https://ihre-website.de approve --rebuild --note "Nach Angriff bereinigt $(date +%Y-%m-%d)"
```
---
@ -637,35 +646,32 @@ angewendet — falsch-positive Alarme durch dynamische CMS-Inhalte werden so unt
## 16. Verzeichnisstruktur
```
config.yaml Hauptkonfiguration
config/
allowed_external.yaml Whitelist erlaubter externer Domains
ignore_rules.yaml Kommentierte Beispiele für Rausch-Unterdrückung
data/
baseline/ Freigegebene Referenz (NIEMALS automatisch geändert)
manifest.json Wer/was/wann freigegeben hat
pages/ Pro URL eine JSON-Datei (16-stelliger Hex-Name)
asset_hashes.json SHA-256-Hashes aller freigegebenen Assets (approve-assets)
snapshots/ Ein Verzeichnis pro Crawl-Durchlauf
YYYYMMDD_HHMMSS/
manifest.json Zeitstempel, Seitenzahl, Fehler
pages/ Extrahierte Seiten-Daten
logs/
scanner.log Detailliertes Laufzeit-Log
cron.log Ausgabe der Cron-Ausführungen
reports/
YYYYMMDD_HHMMSS/ Normaler Scan-Report
report.md
report.json
YYYYMMDD_HHMMSS_cloak/ Cloaking-Check-Report
report.md
report.json
YYYYMMDD_HHMMSS_ext-links/ Externer-Links-Report
report.md
report.json
YYYYMMDD_HHMMSS_assets/ Asset-Check-Report
report.md
report.json
scanner.sh Wrapper-Script (ausführbar, startet python -m scanner)
meine-seite.de/ Template für neue Targets
ihre-website.de/ Automatisch angelegtes Zielverzeichnis (ein Ordner pro Site)
config.yaml Hauptkonfiguration
config/
allowed_external.yaml Whitelist erlaubter externer Domains
ignore_rules.yaml Kommentierte Beispiele für Rausch-Unterdrückung
data/
baseline/ Freigegebene Referenz (NIEMALS automatisch geändert)
manifest.json Wer/was/wann freigegeben hat
pages/ Pro URL eine JSON-Datei (16-stelliger Hex-Name)
asset_hashes.json SHA-256-Hashes aller freigegebenen Assets
snapshots/ Ein Verzeichnis pro Crawl-Durchlauf
YYYYMMDD_HHMMSS/
manifest.json Zeitstempel, Seitenzahl, Fehler
pages/ Extrahierte Seiten-Daten
logs/
scanner.log Detailliertes Laufzeit-Log
cron.log Ausgabe der Cron-Ausführungen
reports/
YYYYMMDD_HHMMSS/ Normaler Scan-Report
report.md
report.json
YYYYMMDD_HHMMSS_cloak/ Cloaking-Check-Report
YYYYMMDD_HHMMSS_ext-links/ Externer-Links-Report
YYYYMMDD_HHMMSS_assets/ Asset-Check-Report
scanner/ Python-Paket (Quellcode)
tests/ Automatisierte Tests
```
@ -766,11 +772,13 @@ Der Report liegt unter `reports/<ts>_ext-links/report.md`.
Der tägliche `scan` erkennt Änderungen im HTML-Text und an Link-URLs, aber nicht ob der
*Inhalt* einer Bilddatei oder eines JavaScript-Files ausgetauscht wurde. Dafür:
### Ersteinrichtung (einmalig)
### Ersteinrichtung
Die Asset-Baseline wird **automatisch** beim ersten `approve --all` angelegt — kein
separater Schritt nötig. Nur wenn die Asset-Baseline manuell neu gesetzt werden soll:
```bash
python -m scanner crawl # aktuellen Snapshot anlegen (falls noch keiner vorhanden)
python -m scanner approve-assets # SHA-256-Hashes aller Assets als Baseline speichern
python -m scanner https://ihre-website.de approve-assets --note "Manuelle Baseline nach CDN-Wechsel"
```
### Regelmäßige Prüfung

67
README.md
View file

@ -18,6 +18,8 @@ cd integrity_scanner_fuer_statische_Webseiten
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Optional: scanner.sh in ~/bin/ verlinken für systemweiten Aufruf
ln -s "$PWD/scanner.sh" ~/bin/scanner
```
```bash
@ -64,8 +66,8 @@ Alle Befehle akzeptieren `--config path/to/config.yaml` und `--verbose`.
## Workflow: Erstinitialisierung
```
python -m scanner init
```bash
python -m scanner https://ihre-website.de init
```
Ausgabe zeigt:
@ -74,18 +76,18 @@ Ausgabe zeigt:
- potenzielle Auffälligkeiten (Hidden Content, Meta-Refresh, ...)
**Wichtig**: Die Ausgabe manuell prüfen, bevor die Baseline gesetzt wird.
Insbesondere externe Links in `config/allowed_external.yaml` eintragen.
Insbesondere externe Links in `ihre-website.de/config/allowed_external.yaml` eintragen.
```
python -m scanner approve --all --note "Initiale Baseline, geprüft am $(date)"
```bash
python -m scanner https://ihre-website.de approve --all --note "Initiale Baseline, geprüft am $(date +%Y-%m-%d)"
```
---
## Workflow: Täglicher Betrieb (Cron)
```
python -m scanner scan
```bash
python -m scanner https://ihre-website.de scan
```
Exit-Codes:
@ -99,26 +101,28 @@ Exit-Codes:
```bash
# 1. Scan durchgeführt, Warnung auf /impressum/
python -m scanner report # Report ansehen
python -m scanner approve --url https://bredelar.info/impressum/ --note "Impressum aktualisiert"
python -m scanner https://ihre-website.de report --diff-only # Nur Diffs ansehen
python -m scanner https://ihre-website.de report # Vollständiger Report
python -m scanner https://ihre-website.de approve --url https://ihre-website.de/impressum/ --note "Impressum aktualisiert"
# 2. Oder alle Änderungen auf einmal (wenn alles geprüft)
python -m scanner approve --all --note "Redesign vom 2026-06-12 freigegeben"
python -m scanner https://ihre-website.de approve --all --note "Redesign vom 2026-06-12 freigegeben"
# 3. Nach großem Redesign: komplette neue Baseline
python -m scanner approve --rebuild --note "Komplettes Redesign, alle Seiten neu"
python -m scanner https://ihre-website.de approve --rebuild --note "Komplettes Redesign, alle Seiten neu"
```
---
## Workflow: Incident (Alarm)
1. Report lesen: `python -m scanner report`
2. Verdächtige URLs manuell im Browser prüfen
3. Quelltext der betroffenen Seiten ansehen (insb. `display:none`-Bereiche)
4. Dienstleister kontaktieren, Zugriff auf Hosting prüfen
5. Nach Bereinigung: `python -m scanner scan` — muss grün sein
6. Dann: `python -m scanner approve --rebuild --note "Nach Incident bereinigt"`
1. Diffs sichten: `python -m scanner https://ihre-website.de report --diff-only`
2. Vollständigen Report lesen: `python -m scanner https://ihre-website.de report`
3. Verdächtige URLs manuell im Browser prüfen
4. Quelltext der betroffenen Seiten ansehen (insb. `display:none`-Bereiche)
5. Dienstleister kontaktieren, Zugriff auf Hosting prüfen
6. Nach Bereinigung: `python -m scanner https://ihre-website.de scan` — muss grün sein
7. Dann: `python -m scanner https://ihre-website.de approve --rebuild --note "Nach Incident bereinigt"`
**Wichtig**: Niemals `approve` auf eine kompromittierte Seite anwenden.
@ -218,18 +222,22 @@ Nach dem ersten `init` alle legitimen externen Domains in
## Verzeichnisstruktur
```
data/
baseline/ Aktuell freigegebene Referenz (NIEMALS automatisch aktualisiert)
manifest.json Wer/was/wann freigegeben hat
pages/ Pro URL eine JSON-Datei
snapshots/ Zeitgestempelte Crawl-Ergebnisse
YYYYMMDD_HHMMSS/
reports/ Generierte Reports (JSON + Markdown)
logs/ scanner.log
config/
allowed_external.yaml
allowed_paths.yaml
ignore_rules.yaml
scanner.sh Wrapper-Script (ausführbar, startet python -m scanner)
meine-seite.de/ Template für neue Targets (config.yaml + config/)
ihre-website.de/ Automatisch angelegtes Zielverzeichnis
config.yaml Konfiguration für diese Site
config/
allowed_external.yaml Whitelist erlaubter externer Domains
ignore_rules.yaml Kommentierte Beispiele für Rausch-Unterdrückung
data/
baseline/ Aktuell freigegebene Referenz (NIEMALS automatisch aktualisiert)
manifest.json Wer/was/wann freigegeben hat
pages/ Pro URL eine JSON-Datei
snapshots/ Zeitgestempelte Crawl-Ergebnisse
reports/ Generierte Reports (JSON + Markdown)
logs/ scanner.log + cron.log
scanner/ Python-Paket (Quellcode)
tests/ Automatisierte Tests
```
---
@ -246,5 +254,4 @@ pytest tests/ -v
- Ollama-Integration: Neue Textblöcke semantisch auf Spam-Kategorien prüfen
- Telegram-Bot: direkter Alert-Kanal
- Diff-Anzeige im Terminal: `python -m scanner report --diff-only`
- Automatische Archivierung alter Snapshots nach N Tagen