From 89d617ab70beadca619edfb84c8aa88fddb68587 Mon Sep 17 00:00:00 2001 From: duffyduck Date: Sat, 22 Aug 2026 18:59:11 +0200 Subject: [PATCH] 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 --- README.md | 40 ++++++++++++++++++++++++++++++++++++ tools/audit-notary/README.md | 40 +++++++++++++++++++++++++++++++++--- 2 files changed, 77 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5f654d15..46da5340 100644 --- a/README.md +++ b/README.md @@ -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 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. +
Technische Details (für Entwickler/Admins) @@ -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 diff --git a/tools/audit-notary/README.md b/tools/audit-notary/README.md index bd41e50e..97d9ac98 100644 --- a/tools/audit-notary/README.md +++ b/tools/audit-notary/README.md @@ -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: