Doku: Gegenbuch in der Haupt-README, zwei Betriebsarten getrennt

Zwei Luecken, beide beim Nachlesen aufgefallen:

1. Die Haupt-README erwaehnte das Gegenbuch mit keinem Wort - ausgerechnet
   dort, wo der Betreiber nach einem git pull nachschaut. Jetzt ein Abschnitt
   direkt nach dem Audit-Siegel: wozu es gut ist, die Richtung der Verbindung
   (Gegenbuch holt, CRM kennt es nicht), die vier Befehle zum Einrichten und
   der Verweis auf die ausfuehrliche Anleitung. Ausdruecklich als optional
   gekennzeichnet - ohne Gegenbuch bleibt der Schutz in der Anwendung
   vollstaendig. Projektbaum ergaenzt.

2. Die Notar-README stammte aus der Zeit mit externem Git-Server. Fuer den
   lokalen Betrieb standen darin Anforderungen, die es dort gar nicht gibt -
   "Force-Push serverseitig sperren, das ist Pflicht" ist ohne Server
   sinnlos und verwirrt. Jetzt eine Entscheidungstabelle ganz oben (lokal =
   Normalfall vs. externes Repository = zusaetzliche Haertung), und alles
   Server-Bezogene gesammelt unter einer eigenen Ueberschrift mit dem Hinweis,
   dass es im lokalen Betrieb uebersprungen werden kann.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-22 18:59:11 +02:00
co-authored by Claude Opus 5
parent cb9f1f5fce
commit 89d617ab70
2 changed files with 77 additions and 3 deletions
+40
View File
@@ -452,6 +452,45 @@ zwei Dinge:
Notiere dir die Zahl nach dem ersten Deploy: Bleibt sie konstant, ist alles
in Ordnung. Steigt sie, lohnt ein Blick.
### Gegenbuch optionaler Zusatzschutz auf zweitem Rechner
Das Audit-Siegel schützt die Einträge **innerhalb** der Anwendung. Es liegt aber
in derselben Datenbank, die es absichert: Wer vollen Zugriff auf den Server hat,
kommt am Ende auch an das Siegel.
Dagegen gibt es das **Gegenbuch**. Ein zweiter Rechner holt regelmäßig einen
kurzen Kontrollwert vom CRM und schreibt ihn mit. Wird später im CRM etwas
nachträglich verändert oder gelöscht, widerspricht das dem Gegenbuch und fällt
beim nächsten Durchlauf auf.
Die Richtung ist dabei entscheidend:
```
Gegenbuch ──holt lesend──> OpenCRM (HTTPS, Token nur mit audit:read)
OpenCRM ─────────────────> (kennt das Gegenbuch nicht)
```
Wer OpenCRM übernimmt, kommt damit nicht an das Gegenbuch. Das CRM braucht
dafür **keinerlei Konfiguration** es liefert nur einen lesbaren Prüfwert, der
keine Geheimnisse enthält.
**Einrichten** (auf einem anderen Rechner als dem CRM):
```bash
git clone <dieses Repository> opencrm
cd opencrm/tools/audit-notary
cp .env.example .env # CRM-Adresse und Token eintragen
docker compose up -d
```
Zwei Bücher auf einer Maschine etwa für Produktion und Test sind
vorgesehen. Alles Weitere in
[tools/audit-notary/README.md](tools/audit-notary/README.md).
> **Optional.** Ohne Gegenbuch bleibt der Schutz innerhalb der Anwendung
> vollständig erhalten. Es deckt zusätzlich den Fall ab, dass jemand den
> CRM-Server selbst übernimmt.
<details>
<summary><b>Technische Details</b> (für Entwickler/Admins)</summary>
@@ -911,6 +950,7 @@ opencrm/
│ │ └── App.tsx # Haupt-Komponente
│ └── package.json
├── Caddyfile # Optionaler Reverse-Proxy (nur mit --profile caddy)
├── tools/audit-notary/ # Gegenbuch läuft auf einem zweiten Rechner
│ ├── Dockerfile # Multi-Stage Build
│ ├── docker-compose.yml # Produktion (MariaDB, App, Caddy)
│ ├── Caddyfile # Reverse-Proxy mit SSL
+37 -3
View File
@@ -6,9 +6,28 @@ absichern sollen. Wer dort schreiben kann, sitzt am Ende immer schon auf der
Ebene, die den Beweis führt. Genau das hat der Pentest über mehrere Runden
Schicht für Schicht gezeigt.
Das Gegenbuch durchbricht das: Ein zweiter Rechner holt regelmäßig einen kurzen
Kontrollwert vom CRM, prüft ihn gegen seine eigene Historie und hängt ihn
signiert an ein privates Repository an.
Das Gegenbuch durchbricht das: Ein **zweiter Rechner** holt regelmäßig einen
kurzen Kontrollwert vom CRM, prüft ihn gegen seine eigene Historie und schreibt
ihn signiert fort. Wird später im CRM etwas nachträglich verändert,
widerspricht das dem Gegenbuch.
## Zwei Betriebsarten erst hier entscheiden
| | **Lokal** (Normalfall) | **Mit externem Repository** |
|---|---|---|
| Das Buch liegt | auf dem Gegenbuch-Rechner | zusätzlich auf einem dritten Server |
| Aufwand | Docker starten, fertig | privates Git-Repo, Schlüssel, Server-Regeln |
| Schützt gegen | jemand verändert Daten **im CRM** | zusätzlich: jemand übernimmt den **Gegenbuch-Rechner** |
**Für die allermeisten Installationen ist „lokal" die richtige Wahl.** Der
Schutz, um den es geht nachträgliche Änderungen im CRM auffliegen zu lassen
steht damit vollständig. Die zweite Variante deckt einen Angreifer ab, der
zusätzlich den Gegenbuch-Rechner übernimmt; sie kostet spürbar mehr Einrichtung
und laufende Aufmerksamkeit.
Diese Anleitung beschreibt zuerst den lokalen Betrieb. Alles zur zweiten
Variante steht gesammelt unter **„Zusätzliche Härtung"** weiter unten wer
lokal betreibt, kann diesen ganzen Teil überspringen.
## Die eine nicht verhandelbare Bedingung
@@ -102,6 +121,21 @@ bei jedem Lauf, damit sie nicht in Vergessenheit gerät.
---
---
# Zusätzliche Härtung: externes Repository
> **Alles ab hier gilt nur für die zweite Betriebsart.** Wer das Gegenbuch
> lokal auf einer eigenen Maschine betreibt der Normalfall, siehe oben kann
> diesen gesamten Abschnitt überspringen. Die Anforderungen darin (Git-Server,
> Rewind-Sperre, geschützte Refs) beziehen sich auf ein zusätzliches Repository
> auf einem dritten Server und existieren im lokalen Betrieb nicht.
Sinn der Variante: Beim lokalen Betrieb liegt das Buch auf demselben Rechner
wie der Signaturschlüssel. Wer diesen Rechner übernimmt, kann beides
manipulieren. Ein zusätzliches Repository auf einem dritten Server, das nur
Anhängen erlaubt, schließt auch das vorausgesetzt, dessen Regeln stimmen.
## Einrichten ohne Docker
Auf einem **anderen** Rechner als dem CRM-Server: