Zurück zur Schwachstellen-Datenbank

Unzureichende technische Dokumentation

Beschreibung

Unzureichende technische Dokumentation tritt auf, wenn ein Produkt nicht ausreichende technische oder Engineering-Dokumentation enthält, die alle relevanten Software/Hardware-Elemente des Systems beschreibt. Dies umfasst fehlende oder inadäquate Architekturdokumentation, Design-Spezifikationen, API-Dokumentation, Dokumentation der Sicherheitskontrollen, Hardware-Spezifikationen und Betriebsverfahren. Ohne umfassende Dokumentation wird das Verständnis der Systemfunktionsweise, seiner Sicherheitsgrenzen und seines beabsichtigten Verhaltens extrem schwierig.

Risiko

Unzureichende Dokumentation hat erhebliche indirekte Sicherheitsimplikationen. Sicherheitsauditoren und Penetrationstester verschwenden Zeit damit, die Architektur zu verstehen, anstatt Schwachstellen zu finden. Bedrohungsmodellierung wird behindert, ohne Datenflüsse und Vertrauensgrenzen zu verstehen. Entwickler können Schwachstellen einführen, weil sie das Systemdesign missverstehen. Incident Response wird verlangsamt, wenn Responder die Systemarchitektur nicht verstehen. Compliance-Anforderungen für Dokumentation (SOC2, PCI-DSS, HIPAA) werden möglicherweise nicht erfüllt. Drittanbieter-Integrationen können aufgrund unklarer Schnittstellen unsicher implementiert werden. Nach-Fertigungs-Verifizierung von Hardware wird ohne ordnungsgemäße Spezifikationen unmöglich.

Lösung

Erstellen und pflegen Sie umfassende technische Dokumentation einschließlich: (1) Architektur- und Design-Dokumentation, (2) API-Spezifikationen und Schnittstellenverträge, (3) Sicherheitsarchitektur- und Kontroll-Dokumentation, (4) Datenflussdiagramme und Vertrauensgrenzendefinitionen, (5) Bedrohungsmodelle, (6) Hardware-Spezifikationen und Toleranzdokumentation, (7) Bereitstellungs- und Konfigurationsleitfäden, (8) Betriebsverfahren und Runbooks. Behandeln Sie Dokumentation wie Code - versionskontrollieren Sie sie, prüfen Sie Änderungen, halten Sie sie aktuell. Generieren Sie Dokumentation aus Code, wo möglich. Nehmen Sie Dokumentationsanforderungen in die Definition of Done auf.

Häufige Auswirkungen

AuswirkungDetails
AndereBereich: Ändere

Reduzierte Wartbarkeit - Unzureichende Dokumentation macht das Produkt schwerer zu verstehen, zu warten und zu sichern.
AndereBereich: Ändere

Qualitätsverschlechterung - Ohne ordnungsgemäße Dokumentation wird die Verifizierung, dass das Produkt wie beabsichtigt funktioniert, unmöglich.
AndereBereich: Ändere

Reduzierte Zuverlässigkeit - Mangelnde Dokumentation kann zu unsachgemäßer Verwendung, Fehlkonfiguration und Zuverlässigkeitsproblemen führen.

Beispielcode

Anfälliger Code

// Der "Code" für diese CWE ist das FEHLEN von Dokumentation
// Dieser Abschnitt beschreibt, wie unzureichende Dokumentation aussieht

/* ============================================================
   BEISPIEL Für UNZUREICHENDE DOKUMENTATION
   ============================================================

   Projekt: Zahlungsverarbeitungssystem

   README.md Inhalt:
   ------------------
   "Führe npm install aus, dann npm start"

   Das ist alles. Keine weitere Dokumentation existiert.

   FEHLENDE DOKUMENTATION:
   -----------------------

   1. ARCHITEKTURDOKUMENTATION (Fehlt)
      - Kein Systemarchitekturdiagramm
      - Keine Beschreibung der Komponenten
      - Keine Erklärung der Datenflüsse
      - Keine Vertrauensgrenzendefinitionen

   2. API-DOKUMENTATION (Fehlt)
      - Keine Endpunktbeschreibungen
      - Keine Authentifizierungsanforderungen
      - Keine Request/Response-Formate
      - Keine Fehlerbehandlungsdokumentation

   3. SICHERHEITSDOKUMENTATION (Fehlt)
      - Kein Bedrohungsmodell
      - Keine Beschreibung der Sicherheitskontrollen
      - Kein Authentifizierungs-/Autorisierungsmodell
      - Kein Datenklassifizierungsschema
      - Keine Verschlüsselungsspezifikationen

   4. KONFIGURATIONSDOKUMENTATION (Fehlt)
      - Keine Beschreibung der Umgebungsvariablen
      - Keine Konfigurationsoptionen
      - Keine Bereitstellungsanforderungen
      - Keine Infrastrukturspezifikationen

   5. BETRIEBSDOKUMENTATION (Fehlt)
      - Kein Monitoring/Alerting-Setup
      - Keine Incident-Response-Verfahren
      - Keine Backup/Recovery-Verfahren
      - Keine Skalierungsrichtlinien

   AUSWIRKUNG:
   -----------
   - Neuer Entwickler verbringt Wochen mit Verstehen der Codebasis
   - Sicherheitsauditor kann System nicht effektiv prüfen
   - Operations-Team kann nicht ordnungsgemäß konfigurieren/überwachen
   - Incident Response ist stark behindert
   - Compliance-Audits scheitern
*/

Korrigierter Code

# Korrigiert: Umfassende technische Dokumentation

## Projekt-Dokumentationsstruktur

docs/
├── architecture/
│ ├── overview.md # Systemarchitektur-Überblick
│ ├── components.md # Komponentenbeschreibungen
│ ├── data-flow.md # Datenflussdiagramme
│ └── decisions/ # Architecture Decision Records (ADRs)
│ ├── ADR-001-database.md
│ └── ADR-002-auth.md
├── api/
│ ├── openapi.yaml # OpenAPI/Swagger-Spezifikation
│ ├── authentication.md # Auth-Dokumentation
│ └── error-codes.md # Fehlerbehandlung
├── security/
│ ├── threat-model.md # Bedrohungsmodell
│ ├── controls.md # Sicherheitskontrollen
│ ├── data-classification.md # Datenhandhabung
│ └── encryption.md # Verschlüsselungsspezifikationen
├── operations/
│ ├── deployment.md # Bereitstellungsleitfaden
│ ├── configuration.md # Konfigurationsreferenz
│ ├── monitoring.md # Monitoring-Setup
│ └── runbooks/ # Operationale Runbooks
│ ├── incident-response.md
│ └── disaster-recovery.md
└── development/
├── setup.md # Entwickler-Setup-Leitfaden
├── testing.md # Testrichtlinien
└── contributing.md # Beitragsleitfaden


## 1. Architekturdokumentation Beispiel

### docs/architecture/overview.md

# Zahlungsverarbeitungssystem-Architektur

## Überblick

Das Zahlungsverarbeitungssystem ist eine Microservices-basierte Plattform,
die Kreditkartenzahlungen, Rückerstattungen und Berichte für
E-Commerce-Händler verarbeitet.

## Architekturdiagramm

┌─────────────────────────────────────────────────────────────────┐
│ Externe Clients │
└───────────────────────────────┬─────────────────────────────────┘
│ HTTPS/TLS 1.3
▼
┌─────────────────────────────────────────────────────────────────┐
│ API Gateway (Kong) │
│ • Ratenlimitierung (1000 Req/Min pro API-Schlüssel) │
│ • JWT-Validierung │
│ • Request-Logging │
└───────────────────────────────┬─────────────────────────────────┘
│ Internes mTLS
┌───────────────────┼───────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Payment API │ │ Merchant API │ │ Reporting API │
│ Service │ │ Service │ │ Service │
│ (Node.js) │ │ (Node.js) │ │ (Python) │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘


## Vertrauensgrenzen

1. **Extern → API Gateway**: TLS-Terminierung, Authentifizierung erforderlich
2. **API Gateway → Services**: mTLS, JWT-Claims validiert
3. **Services → Datenbank**: Verschlüsselte Verbindungen, Service-Konten
4. **Services → Payment Gateway**: PCI-DSS-konformer Kanal


## 2. Sicherheitsdokumentation Beispiel

### docs/security/controls.md

# Sicherheitskontrollen

## Authentifizierung

| Kontrolle | Implementierung | Standard |
|-----------|-----------------|----------|
| API-Authentifizierung | JWT (RS256, 15-Min Ablauf) | OAuth 2.0 |
| Service-zu-Service | mTLS mit Zertifikatsrotation | NIST |
| Admin-Zugriff | MFA erforderlich, SSO via Okta | NIST 800-63B |

## Datenschutz

### Daten im Ruhezustand
- Datenbank: AES-256-GCM-Verschlüsselung (AWS KMS)
- Dateispeicher: S3 serverseitige Verschlüsselung
- Backups: Mit separatem Schlüssel verschlüsselt

### Daten bei Übertragung
- Extern: Nur TLS 1.3
- Intern: mTLS zwischen allen Services
- Certificate Pinning für Payment Gateway


## 3. Operationale Dokumentation Beispiel

### docs/operations/runbooks/incident-response.md

# Incident Response Runbook

## Schweregrade

| Stufe | Definition | Reaktionszeit | Beispiele |
|-------|------------|---------------|-----------|
| SEV1 | Service ausgefallen, Datenleck | 15 Minuten | Zahlungsverarbeitung gestoppt |
| SEV2 | Größe Verschlechterung | 30 Minuten | Hohe Fehlerrate >5% |
| SEV3 | Kleines Problem | 2 Stunden | Einzelner Händler betroffen |
| SEV4 | Geringe Auswirkung | Nächster Werktag | UI-Bug |

## SEV1 Reaktionsverfahren

### 1. Erste Reaktion (0-15 Minuten)
- [ ] Vorfall in PagerDuty bestätigen
- [ ] Incident Slack Channel #incident-active beitreten
- [ ] Incident Commander (IC) zuweisen
- [ ] Untersuchung beginnen

### 2. Bewertung (15-30 Minuten)
- [ ] Umfang und Auswirkung bestimmen
- [ ] Monitoring-Dashboards prüfen
- [ ] Kürzliche Deployments überprüfen
- [ ] Stakeholder benachrichtigen

CVE-Beispiele

Diese CWE ist für direkte CVE-Zuordnung als VERBOTEN markiert, da sie ein Dokumentations-/Qualitätsproblem und keine direkte Sicherheitsschwachstelle darstellt.

Verwandte CWEs

  • CWE-710: Improper Adherence to Coding Standards (Eltern)
  • CWE-1053: Missing Documentation for Design (Kind)
  • CWE-1110: Incomplete Design Documentation (Kind)
  • CWE-1225: Documentation Issues (Kategoriemitglied)

Referenzen

  1. MITRE Corporation. "CWE-1059: Insufficient Technical Documentation." https://cwe.mitre.org/data/definitions/1059.html

  2. NIST. "Security Documentation Requirements."

  3. PCI Security Standards Council. "Documentation Requirements for PCI DSS."