docs: comprehensive documentation update

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

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