Zurück zur Schwachstellen-Datenbank

Unvollständige I/O-Dokumentation

Beschreibung

Unvollständige I/O-Dokumentation tritt auf, wenn die Dokumentation eines Produkts Eingaben, Ausgaben oder System-/Software-Schnittstellen nicht angemessen definiert. Dies umfasst fehlende Dokumentation für API-Parameter, Rückgabewerte, Fehlercodes, Datenformate, Nachrichtenprotokolle, Dateiformate und andere Schnittstellenspezifikationen. Ohne vollständige I/O-Dokumentation können Entwickler Clients oder Integrationen nicht korrekt implementieren, und Sicherheitsprüfer können die ordnungsgemäße Eingabevalidierung oder Ausgabekodierung nicht verifizieren.

Risiko

Unvollständige I/O-Dokumentation hat indirekte Sicherheitsimplikationen. Entwickler validieren Eingaben möglicherweise nicht ordnungsgemäß, ohne gültige Formate zu kennen. Fehlende Dokumentation von Fehlercodes kann zu unsachgemäßer Fehlerbehandlung führen. Undokumentierte Grenzfälle werden möglicherweise nicht sicher behandelt. Sicherheitsprüfer können die ordnungsgemäße Eingabevalidierungsabdeckung nicht verifizieren. Integrationsentwickler können falsche Annahmen über Datenformate treffen. Angreifer könnten undokumentierte Schnittstellen entdecken, die nicht ordnungsgemäß gesichert sind. Anforderungen an den Umgang mit sensiblen Daten werden möglicherweise nicht kommuniziert.

Lösung

Dokumentieren Sie alle Eingaben mit ihren Typen, gültigen Bereichen und Formaten. Dokumentieren Sie alle Ausgaben einschließlich Erfolgsantworten und Fehlerbedingungen. Spezifizieren Sie Fehlercodes und ihre Bedeutungen. Dokumentieren Sie alle API-Endpunkte und ihre Parameter. Fügen Sie Datenformatspezifikationen hinzu (JSON-Schema, XML-Schema, etc.). Dokumentieren Sie Authentifizierungs- und Autorisierungsanforderungen. Spezifizieren Sie Rate-Limits und Kontingente. Fügen Sie Beispiele für gültige und ungültige Eingaben hinzu. Dokumentieren Sie Anforderungen für den Umgang mit sensiblen Daten. Halten Sie die Dokumentation mit der Implementierung synchronisiert.

Häufige Auswirkungen

AuswirkungDetails
SonstigesBereich: Sonstiges

Reduzierte Wartbarkeit - Entwickler können Schnittstellen ohne Dokumentation nicht korrekt verwenden.
SonstigesBereich: Sonstiges

Erhöhte Analysekomplexität - Sicherheitsanalyse kann die ordnungsgemäße I/O-Behandlung nicht verifizieren.
IntegritätBereich: Integrität

Unsachgemäße Eingabebehandlung - Undokumentierte Eingaben werden möglicherweise nicht validiert.

Beispielcode und Lösung

Verwundbarer Code

// Verwundbar: API mit unvollständiger I/O-Dokumentation

// DATEI: api/users.py
// Fehlende Dokumentation für:
// - Anfrageparameter und ihre Typen
// - Gültige Wertebereiche
// - Antwortformat
// - Fehlercodes
// - Authentifizierungsanforderungen

@app.route('/api/users', methods=['POST'])
def create_user():
    # Welche Parameter akzeptiert dies?
    # Was sind die Validierungsregeln?
    # Was gibt es zurück?
    data = request.json
    user = User(**data)
    db.save(user)
    return jsonify(user.to_dict())

Sichere Lösung

# Sicher: Vollständige I/O-Dokumentation mit OpenAPI/Swagger

"""
Benutzerverwaltungs-API
=======================

Vollständige API-Dokumentation für Benutzerverwaltungs-Endpunkte.

Basis-URL: https://api.example.com/v1
Authentifizierung: Bearer-Token für alle Endpunkte erforderlich
Rate-Limit: 100 Anfragen pro Minute pro API-Schlüssel
"""

from dataclasses import dataclass
from typing import Optional, List
from enum import Enum


class BenutzerRolle(Enum):
    """
    Gültige Benutzerrollen.

    Attribute:
        BENUTZER: Standardbenutzer mit Basisberechtigungen
        ADMIN: Administrator mit Vollzugriff
        NUR_LESEN: Nur-Lese-Zugriff auf Ressourcen
    """
    BENUTZER = "benutzer"
    ADMIN = "admin"
    NUR_LESEN = "nur_lesen"


@dataclass
class BenutzerErstellenAnfrage:
    """
    Anfragekörper zum Erstellen eines neuen Benutzers.

    Attribute:
        benutzername: Eindeutiger Benutzername (3-50 alphanumerische Zeichen)
        email: Gültige E-Mail-Adresse (RFC 5322 Format)
        passwort: Passwort (8-128 Zeichen, muss Großbuchstaben,
                  Kleinbuchstaben und Zahl enthalten)
        rolle: Benutzerrolle (Standard: BENUTZER)

    Beispiel:
        {
            "benutzername": "max_mustermann",
            "email": "[email protected]",
            "passwort": "SicheresPasswort123",
            "rolle": "benutzer"
        }

    Validierungsfehler:
        - "benutzername_ungültig": Benutzername entspricht nicht Muster
        - "benutzername_vergeben": Benutzername existiert bereits
        - "email_ungültig": E-Mail-Format ist ungültig
        - "email_vergeben": E-Mail bereits registriert
        - "passwort_schwach": Passwort erfüllt Anforderungen nicht
    """
    benutzername: str
    email: str
    passwort: str
    rolle: BenutzerRolle = BenutzerRolle.BENUTZER


class FehlerCode(Enum):
    """
    API-Fehlercodes

    Alle Fehler geben JSON mit Format zurück:
    {
        "fehler": {
            "code": "<fehler_code>",
            "nachricht": "<lesbare_nachricht>",
            "details": { ... }  // Optionale zusätzliche Details
        }
    }
    """
    # Validierungsfehler (400)
    VALIDIERUNGSFEHLER = "validierungsfehler"
    BENUTZERNAME_UNGÜLTIG = "benutzername_ungültig"
    BENUTZERNAME_VERGEBEN = "benutzername_vergeben"
    EMAIL_UNGÜLTIG = "email_ungültig"
    EMAIL_VERGEBEN = "email_vergeben"
    PASSWORT_SCHWACH = "passwort_schwach"

    # Authentifizierungsfehler (401)
    AUTH_ERFORDERLICH = "authentifizierung_erforderlich"
    AUTH_UNGÜLTIG = "authentifizierung_ungültig"
    TOKEN_ABGELAUFEN = "token_abgelaufen"

    # Autorisierungsfehler (403)
    VERBOTEN = "verboten"
    UNZUREICHENDE_BERECHTIGUNGEN = "unzureichende_berechtigungen"

    # Nicht gefunden Fehler (404)
    BENUTZER_NICHT_GEFUNDEN = "benutzer_nicht_gefunden"
    RESSOURCE_NICHT_GEFUNDEN = "ressource_nicht_gefunden"

    # Rate-Limiting (429)
    RATE_LIMITIERT = "rate_limitiert"

    # Serverfehler (500)
    INTERNER_FEHLER = "interner_fehler"


@app.route('/api/v1/benutzer', methods=['POST'])
def benutzer_erstellen():
    """
    Neues Benutzerkonto erstellen.

    **Endpunkt:** POST /api/v1/benutzer

    **Authentifizierung:** Erforderlich (Bearer-Token)

    **Autorisierung:**
    - ADMIN-Rolle erforderlich zum Erstellen von ADMIN-Benutzern
    - ADMIN- oder BENUTZER-Rolle kann BENUTZER oder NUR_LESEN erstellen

    **Anfrage-Header:**
    - Authorization: Bearer <access_token> (erforderlich)
    - Content-Type: application/json (erforderlich)
    - X-Idempotency-Key: <uuid> (optional, verhindert doppelte Erstellung)

    **Anfragekörper:** BenutzerErstellenAnfrage

    **Antworten:**

    | Status | Beschreibung | Body |
    |--------|--------------|------|
    | 201 | Benutzer erstellt | BenutzerErstellenAntwort |
    | 400 | Validierungsfehler | FehlerAntwort |
    | 401 | Nicht authentifiziert | FehlerAntwort |
    | 403 | Nicht autorisiert | FehlerAntwort |
    | 409 | Benutzername/Email existiert | FehlerAntwort |
    | 429 | Rate limitiert | FehlerAntwort |
    | 500 | Serverfehler | FehlerAntwort |

    **Rate-Limiting:**
    - 10 Benutzererstellungen pro Stunde pro authentifiziertem Benutzer
    - Gibt Retry-After-Header zurück wenn limitiert
    """
    # Implementierung mit dokumentiertem Verhalten
    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-1110: Unvollständige Design-Dokumentation (verwandt)

Referenzen

  1. MITRE Corporation. "CWE-1111: Incomplete I/O Documentation." https://cwe.mitre.org/data/definitions/1111.html

  2. OpenAPI Specification. https://swagger.io/specification/