API Dokumentation Sicherheit: Ist Ihre Spezifikation in Git sicher?

Die Sicherheit der API-Dokumentation ist der Teil Ihres API-Programms, den fast niemand prüft. Sie härten die API selbst mit Authentifizierung, Ratenbegrenzungen und Sicherheitstests ab. Aber die Dokumentation, die diese API beschreibt, die OpenAPI-Spezifikation, die Swagger UI-Seite, die Markdown-Erklärung Ihres Authentifizierungsablaufs, befindet sich oft in einem Git-Repo oder auf einem statischen Host, den seit seiner Einrichtung niemand mehr überprüft hat. Am 20. Mai 2026 bestätigte GitHub, dass Angreifer Daten aus rund 3.800 seiner internen Code-Repositories gestohlen hatten. Der Einstiegspunkt war eine manipulierte VS Code-Erweiterung, die auf dem Laptop eines GitHub-Mitarbeiters installiert war. Dieser Vorfall ist ein guter Grund, eine unangenehme Frage zu Ihrem eigenen Setup zu stellen: Wenn jemand still und leise Ihre veröffentlichten API-Dokumente ändern könnte, würden Sie es bemerken, und würden Ihre API-Kunden es bemerken?

TL;DR

Sichere API-Dokumentation bedeutet, dass Ihre Dokumente über Zugriffskontrolle, Versionshistorie, überprüfbare Integrität und einen Audit-Trail verfügen, sodass ein kompromittiertes Repo oder ein Host nicht stillschweigend falsche Endpunkte, Tokens oder Authentifizierungsanweisungen an Entwickler weitergeben kann, die diese in die Produktion kopieren. Docs-as-Code in Git ist für viele Teams in Ordnung und bietet Ihnen kostenlose Überprüfung und Historie. Es wird zu einer Schwachstelle, wenn das Repo öffentlich und ohne Zugriffskontrolle ist, wenn veraltete Spezifikationen von der Live-API abweichen oder wenn ein manipuliertes Beispiel unbemerkt die Verbraucher erreicht. Eine verwaltete Dokumentationsebene wie Apidog fügt Passwortschutz, IP- und E-Mail-Allowlists, benutzerdefinierte Domains, Versionierung und eine Spezifikation hinzu, die als einzige Quelle der Wahrheit mit Ihrem API-Design synchronisiert bleibt.

Warum der GitHub-Vorfall Sie dazu bringen sollte, Ihre API-Dokumentation zu überprüfen

Der GitHub-Vorfall ist es wert, verstanden zu werden, bevor Sie in Panik geraten. Die Bedrohungsgruppe TeamPCP exfiltrierte interne GitHub-Repositories und verkauft den Datensatz nun für mehr als 50.000 US-Dollar in einem Untergrundforum. Die Berichterstattung von BleepingComputer bestätigt, dass die bösartige VS Code-Erweiterung direkt aus dem offiziellen Marktplatz stammte und auf einem Mitarbeitergerät ausgeführt wurde. GitHub gibt an, keine Beweise dafür gefunden zu haben, dass Kundendaten, die außerhalb ihrer internen Repos gespeichert waren, betroffen waren, und die Untersuchung läuft noch.

Der Vorfall liefert Ihnen einen Anlass. Er erinnert daran, zu überprüfen, wo und wie Ihre API-Dokumentation lebt und ob sie manipuliert werden kann. Die meisten Teams haben diese Frage noch nie gestellt. Sie haben vor drei Jahren Swagger UI auf GitHub Pages veröffentlicht, einen CNAME darauf gezeigt und sind weitergezogen. Das Repo ist öffentlich. Die Spezifikation ist das, was zuletzt zusammengeführt wurde. Niemand überprüft Änderungen an der Doku-Site mit der gleichen Sorgfalt, die sie auf Anwendungscode anwenden.

Diese Lücke ist wichtig, weil API-Dokumentation Anweisungen sind. Wenn ein Entwickler eine Integration mit Ihrer API vornimmt, kopiert er die Endpunktpfade, die Anforderungsstrukturen, die Authentifizierungs-Header und oft die Beispielwerte direkt aus Ihrer Dokumentation in seinen Code. Wenn ein Angreifer diese Anweisungen ändern kann, beschädigt er keine Marketingseite. Er bearbeitet Code, den andere Leute ausführen werden. Die gleiche Logik zeigt sich in den Nachbetrachtungen anderer Vorfälle von 2026; unser Artikel über API-Sicherheitslektionen aus dem Vercel-Vorfall behandelt, wie eine kleine Änderung in einer vertrauenswürdigen Oberfläche weitreichende Auswirkungen hat.

Dieser Artikel behandelt vier Punkte: die konkreten Wege, wie kompromittierte API-Dokumente Ihren Kunden schaden, wann Docs-as-Code-in-Git wirklich in Ordnung ist und wann es zu einer Schwachstelle wird, was „sichere API-Dokumentation“ als Checkliste tatsächlich bedeutet und wie eine verwaltete Dokumentationsschicht die Lücken schließt. Zwei verwandte Artikel gehen tiefer auf zusammenhängende Aspekte ein: was der GitHub-Vorfall für selbst gehostete API-Tools bedeutet und Sicherheit von VS Code Extension API-Schlüsseln.

Was schiefgeht, wenn Ihr API-Dokumentations-Repo oder -Host kompromittiert wird

Beginnen wir mit dem Bedrohungsmodell. Ihre API-Dokumentation befindet sich auf einer Oberfläche: einem Git-Repo, einer CI-Pipeline, die sie erstellt, und einem Host, der sie bereitstellt. Wenn eine davon kompromittiert wird, folgen einige spezifische schlechte Ergebnisse. Keines davon ist theoretisch.

Dokumentenmanipulation erreicht Produktionscode

Dies ist der schlimmste und am wenigsten offensichtliche Fall. Ein Angreifer mit Schreibzugriff auf Ihr Dokumentations-Repo oder auf den Host, der die erstellte Website bereitstellt, nimmt eine kleine Änderung vor. Er ändert https://api.payments.acme.com/v2/charge in eine von ihm kontrollierte Domain. Er tauscht das Beispiel-Bearer-Token auf Ihrer „Erste Schritte“-Seite gegen eines aus, das über seinen Proxy geleitet wird. Er schreibt einen einzigen Satz in Ihrem OAuth-Abschnitt um, sodass der Token-Austausch an die falsche URL gesendet wird.

Nichts davon beeinträchtigt Ihre Website. Die Seite wird weiterhin gerendert. CI läuft weiterhin durch, da die Spezifikation immer noch gültiges YAML ist. Aber der nächste Entwickler, der eine Integration mit Ihrer API vornimmt, kopiert diesen Endpunkt oder diesen Ablauf in seinen Dienst. Die Änderung läuft nun in seiner Produktionsumgebung, und er hat ihr vertraut, weil sie aus Ihrer offiziellen Dokumentation stammte.

Betrachten Sie ein realistisches OpenAPI-Fragment. Ein Team dokumentiert einen Zahlungs-Endpunkt wie folgt:

paths:
  /v2/payment-intents:
    post:
      summary: Create a payment intent
      servers:
        - url: https://api.acme-pay.com
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentIntentRequest'
      responses:
        '201':
          description: Payment intent created

Eine Änderung an dieser servers-URL, über ein kompromittiertes Konto zusammengeführt oder auf einen gekaperten Host übertragen, und jeder Verbraucher, der einen Client aus der Spezifikation neu generiert, sendet nun Kartendaten an die Domain des Angreifers. Der Unterschied sind zwei Wörter. Niemand markiert zwei Wörter in einem Doku-Commit.

Interne und undokumentierte Endpunkte gelangen an die Öffentlichkeit

Doku-Repositories sammeln Dinge an. Eine Spezifikation, die als öffentliche API begann, enthält oft interne Pfade, Admin-Endpunkte, Debug-Routen oder nur für Partner gedachte Operationen, die niemals veröffentlicht werden sollten. Wenn das Repo öffentlich ist oder durch eine Fehlkonfiguration öffentlich wird, sind diese Endpunkte nun eine Karte für jeden, der Ihre Angriffsfläche scannt.

Auch ein privates Repo ist hier ein Problem. Eine Sicherheitsverletzung wie die von GitHub exfiltriert private Repositories. In dem Moment, in dem Ihre interne API-Spezifikation in einem gestohlenen Repo liegt, hat ein Angreifer ein präzises Inventar Ihrer Endpunkte, Parameter und erwarteten Payloads. Sie müssen nicht raten. Sie haben ihnen das Schema gegeben. Wenn Sie einen Rahmen suchen, um diese Lücken zu finden, bevor es jemand anderes tut, ist unsere Checkliste für API-Sicherheitstests für 2026 genau auf diese Art von Oberflächenüberprüfung ausgelegt.

Öffentliche GitHub Pages haben keine Zugriffskontrolle

GitHub Pages ist ein statischer Host. Es stellt Dateien bereit. Es hat keine Vorstellung davon, wer sie liest. Für eine wirklich öffentliche API ist das korrekt und in Ordnung. Für Dokumente, die nur zahlenden Kunden, einer bestimmten Gruppe von Partnern oder Ihrem eigenen Team sichtbar sein sollten, ist es das falsche Tool, da es überhaupt kein Tor gibt.

Teams umgehen dies mit „Sicherheit durch eine schwer zu erratende URL“. Die Dokumente leben an einem Pfad, auf den niemand verlinkt. Das ist keine Zugriffskontrolle. URLs gelangen über den Browserverlauf, Referrer-Header, Proxy-Logs und geteilte Lesezeichen an die Öffentlichkeit. Jeder, der den Link findet, sieht alles, für immer, ohne dass Sie wissen, dass er es getan hat.

Veraltete und unüberprüfbare Dokumente

Der leisere Fehlerfall benötigt überhaupt keinen Angreifer. Dokumente in einem Git-Repo driften auseinander. Jemand liefert eine API-Änderung aus, vergisst, die Spezifikation zu aktualisieren, und die Markdown-Beschreibung beschreibt nun einen Endpunkt, der sich in der Produktion anders verhält. Verbraucher integrieren sich gegen das dokumentierte Verhalten, stoßen auf das reale Verhalten und verbringen einen Tag mit der Fehlersuche.

Wenn Dokumente kompromittiert sind, verschärft sich dieses Problem, da Sie die Fähigkeit verlieren, Abweichungen von Manipulationen zu unterscheiden. War dieser Endpunkt schon immer falsch, oder hat ihn jemand geändert? Ohne eine überprüfbare Historie, die an Ihr tatsächliches API-Design gebunden ist, können Sie das nicht beantworten. Die Dokumente werden unüberprüfbar, und unüberprüfbare Dokumente sind nicht viel besser als gar keine Dokumente.

Wann Docs-as-Code in Git in Ordnung ist und wann es zu einer Schwachstelle wird

Docs-as-Code ist eine legitime, beliebte Praxis, und dieser Abschnitt ist kein Argument dagegen. Die Speicherung Ihrer OpenAPI-Spezifikation und Ihres Markdowns in einem Git-Repo, das Erstellen von Swagger UI oder Redoc mit CI und das Deployment auf einem statischen Host bietet Ihnen echte Vorteile. Sie erhalten Pull-Request-Reviews für Dokumentationsänderungen. Sie erhalten eine vollständige Historie darüber, wer wann was geändert hat. Die Dokumente werden zusammen mit dem Code versioniert. Das sind genau die Eigenschaften, die Manipulationen erkennbar machen, wenn der Workflow eingehalten wird.

Die Frage ist also nicht „Git oder nicht Git“. Es ist „ist dieses spezielle Setup für diese spezielle API sicher.“ Hier ist, wie sich die beiden Fälle aufteilen.

Docs-as-Code in Git ist in Ordnung, wenn

Die Praxis funktioniert unter bestimmten Bedingungen gut:

• Die API ist vollständig öffentlich, sodass nichts zu verbergen ist und keine Zugriffskontrolle erforderlich ist.
• Das Repo verfügt über Branch-Schutz, erforderliche Überprüfungen und einen kleinen, geprüften Kreis von Personen mit Schreibzugriff.
• Dokumentenänderungen durchlaufen die gleiche rigorose Überprüfung wie Code, sodass eine vertauschte URL oder ein Token im Review erkannt wird.
• Die Build-Pipeline ist gesperrt: festgeschriebene Aktionen, keine unüberprüften Drittanbieter-Schritte, eingeschränkte Bereitstellungsanmeldeinformationen.
• Die Spezifikation wird aus der realen API generiert oder gegen diese validiert, nicht manuell bearbeitet und auf das Beste gehofft.
• Jemand ist dafür verantwortlich, die Spezifikation aktuell zu halten, damit keine Abweichungen entstehen.

Wenn all dies zutrifft, sind Git-gehostete Dokumente ein starkes, transparentes System. Die Historie ist Ihr Audit-Trail. Die Reviews sind Ihre Integritätsprüfung.

Docs-as-Code in Git wird zu einer Schwachstelle, wenn

Dasselbe Setup wird riskant, wenn die Bedingungen vernachlässigt werden:

• Die Dokumente sollten privat oder nur für Partner zugänglich sein, aber der Host hat keine Zugriffskontrolle, sodass „privat“ „unverlinkt“ bedeutet.
• Der Schreibzugriff ist breit gefächert oder umfasst Dienstkonten und CI-Token, die niemand nachverfolgt.
• Dokumenten-Commits werden ohne genaue Prüfung genehmigt, weil es ja „nur Dokumente“ sind, sodass ein bösartiger Unterschied unbemerkt bleibt.
• Die Spezifikation wird manuell gepflegt und weicht von der Live-API ab, sodass die Benutzer ihr nicht vertrauen können.
• Das Repo enthält interne oder undokumentierte Endpunkte neben den öffentlichen.
• Es gibt kein Integritätssignal: Niemand könnte Ihnen sagen, ob die bereitgestellte Website mit der überprüften Quelle übereinstimmt.

Der GitHub-Vorfall fällt genau auf diese Fehlerarten. Der Angriff erfolgte über einen Entwickler-Endpunkt und erreichte interne Repos. Wenn Ihre private API-Spezifikation in einem dieser Repos lebte, hat der Vorfall Ihr Schema offengelegt, unabhängig davon, wie sorgfältig Ihr Überprüfungsprozess war. Git bietet Ihnen Transparenz; es bietet Ihnen keine Vertraulichkeit, sobald das Repo selbst gestohlen wird. Für einen umfassenderen Vergleich, wo verschiedene selbstgehostete Dokumentationsansätze bei diesen Kompromissen stehen, siehe unseren Vergleich selbstgehosteter API-Dokumente.

Die Schlussfolgerung ist bewusst ausgewogen. Behalten Sie Docs-as-Code bei, wenn Ihre API öffentlich ist und Ihre Pipeline diszipliniert ist. Überdenken Sie es, wenn Ihre Dokumente eine Zugriffskontrolle benötigen, wenn Ihr Überprüfungsprozess Dokumente als zweitrangig behandelt oder wenn Sie die Frage „entspricht die Live-Site der überprüften Quelle?“ nicht beantworten können.

Was „sichere API-Dokumentation“ tatsächlich bedeutet

„Sichere API-Dokumentation“ ist vage, bis man sie in überprüfbare Eigenschaften aufteilt. Vier davon tragen das Gewicht.

Zugriffskontrolle

Die Dokumente sind nur für die Personen sichtbar, die sie sehen sollen. Öffentlich für eine öffentliche API. Eingeschränkt für kundenbezogene, partnerbezogene oder interne Dokumente. Die Einschränkung muss ein echtes Tor sein, ein Passwort, eine IP-Whitelist, eine E-Mail-Whitelist oder SSO, keine obskure URL. Der Test: Können Sie genau benennen, wer Ihre Dokumente gerade lesen kann, und einem davon innerhalb einer Minute die Berechtigung entziehen?

Versionierung

Jede veröffentlichte Version der Dokumente wird aufbewahrt und ist identifizierbar. Verbraucher Ihrer v1 API sehen v1 Dokumente; v2 Verbraucher sehen v2. Sie können zeigen, was die Dokumente zu einem bestimmten Datum besagten. Der Test: Kann ein Entwickler, der gegen Ihre ältere API-Version integriert, immer noch genaue Dokumente dafür finden, anstatt Dokumente, die stillschweigend auf v2 aktualisiert wurden?

Integrität

Sie können überprüfen, ob die veröffentlichten Dokumente Ihren Absichten entsprechen. Entweder werden die Dokumente aus einer kontrollierten Quelle der Wahrheit generiert, oder es gibt einen ausreichend starken Überprüfungs- und Historienpfad, so dass eine unautorisierte Änderung auffällt. Der Test: Würde Ihnen etwas verraten, wenn jemand vor einer Stunde eine Endpunkt-URL in Ihren Live-Dokumenten geändert hätte?

Audit-Trail

Sie können beantworten, wer die Dokumente geändert hat, was geändert wurde und wann. Die Git-Historie liefert Ihnen dies für das Repository; Sie benötigen es auch für die veröffentlichte Oberfläche, da der Bereitstellungsschritt ein eigener Angriffspunkt ist. Der Test: Können Sie ein Änderungsprotokoll für Ihre veröffentlichten Dokumente der letzten 90 Tage erstellen?

Ein Setup, das alle vier Punkte erfüllt, ist eine sichere Dokumentation. Git-gehostete Dokumente können Versionierung, Integrität und Audit-Trail durch Branch-Schutz und Historie erreichen. Der Punkt, den sie auf einem statischen Host normalerweise verpassen, ist die Zugriffskontrolle, und diese Lücke ist der Grund für eine verwaltete Dokumentationsschicht.

Wie Apidog Ihnen eine sichere API-Dokumentation bietet

Apidog ist eine All-in-One-API-Plattform zum Entwerfen, Debuggen, Testen, Mocken und Dokumentieren von APIs. Die Dokumentationsseite ist so aufgebaut, dass die oben genannten vier Eigenschaften Standards sind und nicht Dinge, die Sie nachträglich hinzufügen. Um mitzumachen, laden Sie Apidog herunter und öffnen Sie ein beliebiges Projekt mit einer API-Definition.

Veröffentlichte Dokumentation aus einer kontrollierten Quelle der Wahrheit

In Apidog wird die Dokumentation aus Ihrem API-Design innerhalb des Projekts generiert. Sie entwerfen Endpunkte, Schemas und Authentifizierung im visuellen Designer, und Apidog generiert die Dokumentation automatisch aus dieser Definition. Klicken Sie auf „Veröffentlichen“, und Sie erhalten eine interaktive Dokumentationsseite mit einer „Testen“-Konsole und mehrsprachigen Codebeispielen.

Der Integritätsvorteil ist strukturell. Die veröffentlichten Dokumente sind keine separat bearbeitbaren Markdowns, die abweichen oder manipuliert werden können. Sie spiegeln die API-Definition wider. Ändern Sie die Definition, folgen die Dokumente. Um zu ändern, was Verbraucher sehen, ändern Sie das Design innerhalb des Projekts, das über eigene Berechtigungen und eine Änderungsverlauf verfügt, anstatt eine lose Datei auf einem statischen Host zu bearbeiten.

Zugriffskontrolle der Dokumentation

Hier schließt Apidog die Lücke von GitHub Pages. Wenn Sie veröffentlichen, wählen Sie die Sichtbarkeit, und die Optionen sind echte Schranken, keine Verschleierung:

• Öffentlich: Jeder mit dem Link kann es lesen. Korrekt für eine wirklich offene API.
• Passwortschutz: Legen Sie ein Passwort fest (oder generieren Sie ein zufälliges) und teilen Sie es mit den Stakeholdern. Nur Personen mit dem Passwort erhalten Zugang.
• IP-Whitelist: Beschränken Sie den Zugriff auf bestimmte IPs oder Bereiche, wie Ihr Büro oder VPN. Nützlich für interne Dokumente.
• E-Mail-Whitelist: Listen Sie die erlaubten E-Mail-Adressen oder Domains auf; Benutzer verifizieren sich mit einem Einmalcode. Wildcards wie *@ihre-firma.com decken eine ganze Organisation ab.
• Benutzerdefinierter Login: Verbinden Sie Ihr eigenes Authentifizierungssystem; Ihr Server stellt ein JWT aus, Apidog überprüft es, und der Zugriff hängt von der Gültigkeit ab.

Apidog dokumentiert alle fünf Methoden in seinem Leitfaden zur Kontrolle des Zugriffs auf API-Dokumentation. Das beantwortet die Zugriffssteuerungsprüfung direkt: Sie können angeben, wer die Dokumente lesen darf, und Sie können ein Passwort widerrufen oder eine E-Mail sofort von der Whitelist entfernen.

Benutzerdefinierte Domain

Sie können veröffentlichte Dokumente auf Ihrer eigenen Domain bereitstellen, sodass Benutzer developer.ihre-firma.com anstelle einer generischen URL sehen. Apidog unterstützt eine benutzerdefinierte Domain über einen DNS-CNAME (der empfohlene Weg) oder einen Reverse-Proxy. Eine benutzerdefinierte Domain allein ist keine Sicherheitskontrolle, aber sie hält Ihre Dokumente auf einer von Ihnen verwalteten und kontrollierten Infrastruktur, anstatt sie über Hosts zu verteilen, die niemandem gehören.

OpenAPI-Spezifikation, synchronisiert mit Ihrem API-Design

Abweichungen sind ein Problem für die Sicherheit der Dokumentation, da sie Dokumente unüberprüfbar machen. Apidog behandelt das API-Design als die einzige Quelle der Wahrheit und hält die Dokumentation synchron, wenn sich das Design ändert. Apidog importiert OpenAPI 3.0, 3.1 und Swagger 2.0 und unterstützt geplante Importe, sodass eine externe Spezifikation automatisch aktuell bleibt.

Wenn Sie derzeit eine Spezifikation manuell in einem Git-Repo pflegen, ist das das Setup mit der höchsten Abweichung und der schwierigsten Überprüfung. Die Übernahme der Spezifikation in Apidog als Quelle der Wahrheit bedeutet, dass die veröffentlichten Dokumente immer einer von Ihnen kontrollierten Definition entsprechen. Teams, die von SwaggerHub kommen, können unserem Leitfaden zur Migration von SwaggerHub API-Dokumenten zu Apidog folgen.

Dokumentations-Versionierung

Apidog unterstützt die Dokumentenversionierung, sodass Sie mehrere Versionen nebeneinander veröffentlichen und beibehalten können. Ein Consumer, der sich mit Ihrer v1-API integriert, liest genaue v1-Dokumente, selbst nachdem v2 veröffentlicht wurde. Die Versionierung ist mit Branches und der Änderungsgeschichte verbunden, sodass die Entwicklung der API und ihrer Dokumente verfolgt wird. Dies deckt sowohl die Versionierungs- als auch die Audit-Trail-Tests ab.

Nichts davon hätte TeamPCP daran gehindert, den Laptop eines Entwicklers zu kompromittieren. Es bedeutet jedoch etwas anderes: eine klare Antwort darauf, wer Ihre Dokumente lesen kann, ob die veröffentlichte Version mit Ihrem Design übereinstimmt und was sich im Laufe der Zeit geändert hat. Das ist das Audit, das der GitHub-Vorfall Sie dazu drängen sollte, durchzuführen.

Vergleich der Dokumentations-Hosting-Optionen

Ein kurzer Vergleich der gängigen Ansätze anhand der vier Sicherheitseigenschaften.

Es gibt keine universell richtige Zeile. Öffentliche GitHub Pages sind eine gute Wahl für eine öffentliche API mit einer gesicherten Pipeline. Self-Hosting eignet sich für Teams mit strengen Anforderungen an die Residenz oder Isolation; unser Vergleich selbst gehosteter API-Dokumente und der Vergleich von Scalar, SwaggerHub und Apidog für API-Dokumente legen diese Kompromisse detailliert dar. Der Punkt ist, bewusst anhand der vier Eigenschaften zu wählen, und nicht ein Setup von vor drei Jahren zu übernehmen und nie wieder anzusehen.

Fazit

Der GitHub-Vorfall ist kein Grund, Docs-as-Code aufzugeben oder GitHub zu misstrauen. Er ist ein Anlass, eine Oberfläche zu prüfen, die die meisten Teams ignoriert haben: wo Ihre API-Dokumentation lebt und ob sie manipuliert werden kann.

Nächster Schritt: Listen Sie jeden Ort auf, an dem Ihre API-Dokumente veröffentlicht werden, prüfen Sie jeden anhand der vier Eigenschaften und schließen Sie die größte Lücke. Wenn die Zugriffskontrolle die Lücke ist, laden Sie Apidog herunter und veröffentlichen Sie die Dokumente eines Projekts mit einem Passwort oder einer E-Mail-Whitelist, um zu sehen, wie eine verwaltete Ebene damit umgeht.