Unvollständige Design-Dokumentation
Beschreibung
Unvollständige Design-Dokumentation tritt auf, wenn die Designdokumentation eines Produkts kritische Aspekte des Systems nicht angemessen beschreibt. Dies umfasst unzureichende Dokumentation von Kontrollfluss, Datenfluss, System-Initialisierungssequenzen, Beziehungen zwischen Komponenten, Vertrauensgrenzen, Design-Begründungen, Sicherheitsannahmen und anderen wesentlichen Designelementen. Ohne umfassende Designdokumentation können Entwickler und Sicherheitsprüfer nicht vollständig verstehen, wie das System funktionieren soll, was es schwierig macht, die korrekte Implementierung zu verifizieren oder Sicherheitsprobleme zu identifizieren.
Risiko
Unvollständige Designdokumentation hat indirekte Sicherheitsimplikationen. Sicherheitsprüfer können nicht verifizieren, dass die Implementierung den Sicherheitsanforderungen entspricht. Vertrauensgrenzen können unklar sein, was zu unsachgemäßer Platzierung der Zugriffskontrolle führt. Datenflusspfade werden möglicherweise nicht dokumentiert, was potenzielle Datenleckagerouten verbirgt. Bedrohungsmodellierung ist ohne Verständnis des Systemdesigns unvollständig. Neue Entwickler können falsche Annahmen über Sicherheitsanforderungen treffen. Wartungsänderungen können undokumentierte Sicherheitsinvarianten verletzen. Incident Response wird behindert, wenn Systemverhalten schlecht dokumentiert ist.
Lösung
Erstellen Sie umfassende Designdokumentation, die alle kritischen Aspekte des Systems abdeckt. Dokumentieren Sie Kontrollfluss und Datenfluss explizit. Identifizieren und dokumentieren Sie Vertrauensgrenzen klar. Beschreiben Sie Sicherheitsannahmen und -anforderungen. Dokumentieren Sie die Begründung für Designentscheidungen, insbesondere sicherheitsrelevante. Fügen Sie Sequenzdiagramme für kritische Operationen hinzu. Dokumentieren Sie System-Initialisierungs- und Herunterfahrprozeduren. Pflegen Sie die Dokumentation während der Systementwicklung. Verwenden Sie Vorlagen, um konsistente Dokumentationsabdeckung sicherzustellen. Überprüfen Sie die Dokumentation regelmäßig auf Vollständigkeit.
Häufige Auswirkungen
| Auswirkung | Details |
|---|---|
| Sonstiges | Bereich: Sonstiges Reduzierte Wartbarkeit - Unvollständige Dokumentation macht Wartung fehleranfällig. |
| Sonstiges | Bereich: Sonstiges Erhöhte Analysekomplexität - Sicherheitsanalyse kann ohne Designdokumentation nicht gründlich sein. |
| Integrität | Bereich: Integrität Design-Abweichung - Implementierung kann ohne Dokumentation als Referenz vom beabsichtigten Design abweichen. |
Beispielcode und Lösung
Verwundbarer Code
// Verwundbar: Unvollständige oder fehlende Designdokumentation
// DATEI: auth_service.py
// Keine Dokumentation über:
// - Welche Authentifizierungsmethoden unterstützt werden
// - Session-Token-Generierungsalgorithmus
// - Token-Ablaufrichtlinie
// - Kontosperrmechanismus
// - Passwortanforderungen
// - Vertrauensgrenzen
class AuthService:
def login(self, username, password):
# Implementierung ohne dokumentiertes Design
user = self.db.find_user(username)
if user and check_password(password, user.password_hash):
return generate_token(user)
return None
// Fragen, die die Dokumentation beantworten sollte:
// - Wie lange ist eine Session gültig?
// - Was passiert nach N fehlgeschlagenen Versuchen?
// - Können Benutzer mehrere aktive Sessions haben?
// - Wie werden Tokens validiert?
// - Von wo sollte dieser Service aufgerufen werden?
// DATEI: payment_processor.py
// Fehlende kritische Designdokumentation:
// - Zahlungsablauf-Sequenz
// - Fehlerbehandlungsstrategie
// - Wiederholungsrichtlinie
// - Idempotenz-Behandlung
// - PCI-Konformitätsüberlegungen
class PaymentProcessor:
def process_payment(self, order, payment_info):
# Komplexe Zahlungslogik ohne Design-Dokumente
validated = self.validate(payment_info)
if not validated:
return {"error": "validation_failed"}
result = self.gateway.charge(payment_info)
if result.success:
self.update_order(order, result)
return result
// Unbeantwortete Fragen:
// - Was wenn Belastung erfolgreich aber Update fehlschlägt?
// - Wie werden doppelte Einreichungen behandelt?
// - Welche Daten werden geloggt?
// - Was sind die Vertrauensgrenzen zum Gateway?
// DATEI: data_pipeline.py
// Keine Datenfluss-Dokumentation
// Fehlend:
// - Datenquellen und -senken
// - Datentransformationen
// - Behandlung sensibler Daten
// - Zugriffskontrolle auf Daten
class DataPipeline:
def process(self, data):
# Daten fließen ohne dokumentierten Pfad durch
cleaned = self.clean(data)
transformed = self.transform(cleaned)
enriched = self.enrich(transformed)
self.store(enriched)
// Kritische unbeantwortete Fragen:
// - Welche PII fließen durch diese Pipeline?
// - Wie werden Daten bereinigt?
// - Wer kann auf die gespeicherten Daten zugreifen?
// - Wie lange werden Daten aufbewahrt?
Sichere Lösung
// Sicher: Umfassende Designdokumentation
/*
* ============================================================================
* AUTHENTIFIZIERUNGSSERVICE - DESIGNDOKUMENT
* ============================================================================
*
* 1. ÜBERBLICK
* ------------
* Der AuthService ist verantwortlich für Benutzerauthentifizierung und
* Session-Verwaltung. Er dient als einziger Authentifizierungspunkt für
* alle Anwendungskomponenten.
*
* 2. VERTRAUENSGRENZEN
* --------------------
* +------------------+ +------------------+ +------------------+
* | Client/UI | --> | AuthService | --> | Benutzer-DB |
* | (Nicht vertraut)| | (Vertraut) | | (Vertraut) |
* +------------------+ +------------------+ +------------------+
*
* - Alle Client-Eingaben sind nicht vertrauenswürdig und müssen validiert werden
* - AuthService ist die Vertrauensgrenze für Authentifizierungsentscheidungen
* - Datenbankzugriff ist auf AuthService für Benutzeranmeldedaten beschränkt
*
* 3. AUTHENTIFIZIERUNGSFLUSS
* --------------------------
* Client AuthService Database SessionStore
* | | | |
* |--login(u,p)----->| | |
* | |--find_user(u)-->| |
* | |<--user_record---| |
* | | | |
* | |--verify_password(p, hash) |
* | | | |
* | |--generate_token() |
* | |--store_session----------------->|
* |<--token----------| | |
* | | | |
*
* 4. SICHERHEITSANFORDERUNGEN
* ---------------------------
*
* 4.1 Passwortanforderungen:
* - Mindestlänge: 8 Zeichen
* - Muss enthalten: Großbuchstaben, Kleinbuchstaben, Zahl
* - Gespeichert mit: bcrypt mit Kostenfaktor 12
* - Wird niemals geloggt oder in Antworten zurückgegeben
*
* 4.2 Session-Verwaltung:
* - Token-Format: JWT signiert mit RS256
* - Token-Lebensdauer: 15 Minuten (Zugriff), 7 Tage (Refresh)
* - Maximale gleichzeitige Sessions: 5 pro Benutzer
* - Tokens gespeichert in: Redis mit TTL
*
* 4.3 Kontoschutz:
* - Sperrung nach: 5 fehlgeschlagenen Versuchen
* - Sperrdauer: 30 Minuten
* - Fehlgeschlagene Versuche verfolgt pro: IP + Benutzername-Kombination
* - Sperrbenachrichtigung: E-Mail an Benutzer gesendet
*
* 5. FEHLERBEHANDLUNG
* -------------------
* - Ungültige Anmeldedaten: Generische "Authentifizierung fehlgeschlagen"-Meldung zurückgeben
* - Konto gesperrt: "Konto vorübergehend gesperrt" mit Wiederholungszeitpunkt zurückgeben
* - Ratenlimit: 429 mit Retry-After-Header zurückgeben
* - Interne Fehler: Details loggen, generischen Fehler an Client zurückgeben
*
* 6. LOGGING UND AUDIT
* --------------------
* Geloggte Ereignisse (ohne sensible Daten):
* - Anmeldeversuche (Erfolg/Fehlschlag)
* - Kontosperrungen
* - Token-Generierung
* - Session-Invalidierung
*
* NICHT geloggt:
* - Passwörter
* - Vollständige Tokens (nur letzte 8 Zeichen zur Korrelation)
*/
class AuthService:
"""
Authentifizierungsservice, der das oben dokumentierte Design implementiert.
Siehe: docs/design/auth-service.md für vollständige Designdokumentation
"""
# Konstanten entsprechend dokumentierter Anforderungen
MAX_ANMELDEVERSUCHE = 5 # Gemäß Designdokument Abschnitt 4.3
SPERRDAUER_MINUTEN = 30
ZUGANGSTOKEN_LEBENSDAUER_MINUTEN = 15
REFRESH_TOKEN_LEBENSDAUER_TAGE = 7
MAX_GLEICHZEITIGE_SESSIONS = 5
def login(self, username: str, password: str) -> LoginResult:
"""
Benutzer authentifizieren und Session erstellen.
Ablauf:
1. Kontosperrstatus prüfen
2. Benutzer aus Datenbank abrufen
3. Passwort mit bcrypt verifizieren
4. JWT-Tokens generieren
5. Session in Redis speichern
6. Tokens an Aufrufer zurückgeben
Sicherheitshinweise:
- Passwort wird niemals geloggt (siehe Designdokument Abschnitt 6)
- Generische Fehlermeldungen verhindern Benutzernamen-Enumeration
- Rate-Limiting gemäß Designdokument Abschnitt 4.3 angewendet
Args:
username: Benutzername des Benutzers (auf Format validiert)
password: Passwort des Benutzers (wird niemals gespeichert oder geloggt)
Returns:
LoginResult mit Tokens bei Erfolg, Fehlercode bei Fehlschlag
Raises:
AccountLockedException: Wenn Konto gesperrt ist (siehe Design 4.3)
RateLimitedException: Wenn zu viele Anfragen (siehe Design 5)
"""
# Implementierung folgt dokumentiertem Design
pass
/*
* ============================================================================
* ZAHLUNGSVERARBEITUNG - DESIGNDOKUMENT
* ============================================================================
*
* 1. ZAHLUNGSABLAUF-SEQUENZ
* -------------------------
*
* Client PaymentProcessor Validator Gateway Database
* | | | | |
* |--process---->| | | |
* | |--validate----->| | |
* | |<--result-------| | |
* | | | |
* | |--create_idempotency_key----------------->|
* | |--charge------------------->| |
* | |<--charge_result-----------| |
* | | | |
* | |--update_order--------------------------->|
* | |--log_transaction------------------------->|
* |<--result-----| | |
*
* 2. IDEMPOTENZ-BEHANDLUNG
* ------------------------
* - Jede Zahlungsanfrage muss Client-generierten Idempotenz-Schlüssel enthalten
* - Schlüssel 24 Stunden in Datenbank gespeichert
* - Doppelte Anfragen geben gecachtes Ergebnis zurück, keine erneute Belastung
* - Schlüsselformat: UUID v4, bei Eingabe validiert
*
* 3. FEHLERBEHANDLUNG
* -------------------
*
* Szenario | Aktion | Wiederholung?
* ---------------------------|----------------------|--------
* Validierungsfehler | Fehler zurückgeben | Nein
* Gateway-Timeout | Ausstehend markieren | Ja (3x)
* Gateway-Ablehnung | Ablehnung zurückgeben| Nein
* Belastung OK, Update fehlgeschl. | Belastung stornieren| Nein
*
* 4. PCI DSS-KONFORMITÄT
* ----------------------
* - Kartennummern: Nie gespeichert, nur tokenisiert
* - CVV: Nie gespeichert, nur für einzelne Transaktion verwendet
* - Logs: Kartennummern maskiert (nur erste 6, letzte 4)
* - Übertragung: Nur TLS 1.2+ zum Gateway
*/
class PaymentProcessor:
"""
Zahlungsverarbeitung die PCI-konforme Zahlungsabwicklung implementiert.
Siehe: docs/design/payment-processor.md für vollständiges Design
"""
def process_payment(
self,
order: Order,
payment_info: PaymentInfo,
idempotency_key: str
) -> PaymentResult:
"""
Zahlung gemäß dokumentiertem Ablauf verarbeiten.
Idempotenz:
- Doppelte Anfragen mit gleichem Schlüssel geben gecachtes Ergebnis zurück
- Schlüssel muss UUID v4-Format haben
- Schlüssel verfallen nach 24 Stunden
PCI-Konformität:
- Kartendaten direkt an Gateway übergeben, nie gespeichert
- CVV nur für diese Transaktion verwendet
- Alle Kartendaten in Logs maskiert
Fehlerbehandlung:
- Gateway-Timeout: 3 Wiederholungen mit exponentiellem Backoff
- Belastung erfolgreich + Update fehlgeschlagen: Automatische Rückerstattung eingeleitet
Args:
order: Bestellung für die die Zahlung verarbeitet wird
payment_info: Kartendetails (gemäß PCI DSS behandelt)
idempotency_key: UUID v4 zur Duplikaterkennung
Returns:
PaymentResult mit Transaktionsdetails
"""
pass
CVE-Beispiele
Diese CWE ist als VERBOTEN für direkte CVE-Zuordnung markiert, da sie ein Dokumentationsqualitätsproblem und keine direkte Sicherheitslücke darstellt.
Verwandte CWEs
- CWE-1059: Unzureichende technische Dokumentation (Eltern)
- CWE-1225: Dokumentationsprobleme (Kategoriemitglied)
- CWE-1111: Unvollständige I/O-Dokumentation (verwandt)
Referenzen
-
MITRE Corporation. "CWE-1110: Incomplete Design Documentation." https://cwe.mitre.org/data/definitions/1110.html
-
OWASP. "Threat Modeling."
-
Martin & Shafer (1996). "Software Quality Assessment Framework."