Sicherheitsdokumentation für Entwickler schreiben und prüfen

## Ratschläge schreiben, die Entwickler anwenden können, und beim Thema Sicherheit bleiben Schreibe für Entwickler und nicht für Sicherheitsspezialisten. Der Leitfaden muss präzise, praxistauglich, knapp und meinungsstark sein. Bevorzuge gute Ratschläge, die ein Entwickler anwenden kann, gegenüber theoretisch optimalen Ratschlägen, die zu kompliziert zu befolgen sind. Halte jede Empfehlung innerhalb des Sicherheitsbedrohungsmodells des Dokuments. Allgemeine Hinweise zu Codequalität, Leistung und Architektur gehören an eine andere Stelle, sofern sie nicht unmittelbar ein Sicherheitsrisiko begrenzen. Behandle die Beitragsregeln für jedes Autorenwerkzeug als verbindlich. Bewahre das maßgebliche menschliche Verfahren und die Schreibrichtlinien des Projektarchivs und verwende den kürzeren Leitfaden für Assistenzsysteme ausschließlich als Betriebszusammenfassung. ## Jede zitierte Quelle lesen und prüfen, ob sie die Aussage stützt Rufe jede zitierte Quelle ab, lies sie und bestätige anschließend, dass sie die genaue Aussage stützt. Erfinde oder errate niemals eine URL, zitiere keine Seite, die auf eine unpassende Zielseite weiterleitet, und verlasse dich weder auf antrainiertes Wissen noch auf eine Zusammenfassung. Verweise auf die konkrete Seite oder den Abschnitt mit dem Beleg. Prüfe interne Querverweise vor ihrer Verwendung. Verweise nicht auf ein Dokument oder eine Sprungmarke, die nicht vorhanden ist. Wenn Vorgaben zur Belegdichte gelten, füge in jeden neuen H2-Abschnitt mindestens einen eingebetteten HTTPS-Verweis ein. Belege neuartige, überraschende, parameterspezifische oder anfechtbare Aussagen jeweils gesondert; anerkannte übliche Verfahren benötigen nicht in jedem Satz eine Quellenangabe. Quellen können im Text stehen oder in einem Quellenverzeichnis gesammelt werden. Bevorzuge Normen, staatliche oder branchenspezifische Sicherheitsleitlinien, offizielle Projekt- und Herstellerdokumentation, gut gepflegte Plattformnachschlagewerke, maßgebliche Quellarchive und begutachtete Forschung. Meide auf Suchmaschinen zugeschnittene Vermarktungsportale ohne fachlichen Wert. Vorgaben zur Belegdichte bilden eine Untergrenze und beweisen nicht, dass der Inhalt richtig ist. ## Zu jeder Bedrohung eine Maßnahme nennen und sagen, wovor sie nicht schützt Quellenangaben sind notwendig, reichen aber nicht aus. Ordne jeder Bedrohung eine konkrete Gegenmaßnahme zu und benenne ausdrücklich, wogegen die Schutzmaßnahme schützt und wogegen nicht. Führe ohne einen deutlichen Vorbehalt keine Angriffe außerhalb des festgelegten Bedrohungsmodells ein. Eine Schutzmaßnahme für eine Schicht darf nicht als Schutz vor einer Kompromittierung auf einer anderen Schicht dargestellt werden. Ergänze nur Hinweise, die tatsächlich eine Sicherheitsmaßnahme oder ein Sicherheitsrisiko betreffen. Prüfe fachliche Richtigkeit, praktische Anwendbarkeit für Entwickler und Themenbezug unabhängig voneinander; eine gut belegte, aber falsche Empfehlung muss dennoch abgelehnt werden. ## Jede Änderung klein halten und verlinken statt kopieren Beschränke eine Änderung auf ein einzelnes Leitfadendokument oder eine kleine, eindeutig abgestimmte Gruppe. Wenn das Projektarchiv diese Grenzen vorgibt, dürfen ohne einen genehmigten Nachverfolgungsvorgang weder drei Inhaltsdokumente noch 1.500 netto hinzugefügte Zeilen überschritten werden. Für Änderungen an Abhängigkeiten und Automatisierungen sowie reine Tippfehlerkorrekturen gelten jeweils eigene Umfangsregeln. Beginne mit einem sauberen Zweig auf Grundlage des Standardzweigs und behandle nur ein Thema je Zweig. Eröffne niemals zwei Änderungsanträge aus demselben Zweig, da sonst sachfremde Änderungen zwischen ihnen übergehen können. Verlange einen genehmigten Vorgang, bevor ein neues oder wesentlich überarbeitetes Leitfadendokument vorgeschlagen wird. Bündele keine beiläufigen Formatänderungen, Massenbearbeitungen oder sachfremden Korrekturen. Durchsuche vor dem Ergänzen eines Abschnitts das aktuelle Dokument, verwandte Dokumente und das Verzeichnis des Projektarchivs. Verweise auf vorhandene Anleitungen, statt sie zu wiederholen. Erhalte bewusst sternförmig aufgebaute Dokumentfamilien. Abgestimmte Querverweise sind zulässig, das Kopieren der Anleitung eines anderen Dokuments ist es nicht. Gehört ein Inhalt zu einem anderen Thema, verschiebe ihn in das passende vorhandene oder neue Dokument, statt den aktuellen Umfang zu überdehnen. ## Zuerst den Aufbau erklären und Code nur verwenden, wenn das Thema ihn braucht Bevorzuge bei allgemeinen Themen Architekturmuster, Entwurfsgrundsätze und Sicherheitsentscheidungen gegenüber sprachspezifischem Programmcode. Code veraltet schnell, und einzelne Ausschnitte können unsicher sein, wenn sie ohne ihren ursprünglichen Zusammenhang übernommen werden. Setze Code ausgiebig ein, wenn das Thema untrennbar mit einer Programmiersprache, mit Einschleusungsangriffen, mit Parametrisierung oder mit konkreter Härtung verbunden ist. Ein hoher Codeanteil ist angemessen, wenn die ausführbaren Einzelheiten selbst die Sicherheitsanleitung bilden und nicht nur beiläufiger Standardcode sind. Halte Beispielcode kurz, kennzeichne abgegrenzte Codeblöcke nach Möglichkeit mit einer Sprache und stelle Beispiele nur dann als produktionsreif dar, wenn sie nach diesem Maßstab entworfen und geprüft wurden. ## Fülltext streichen und einen klaren Weg empfehlen Streiche allgemeine Vorreden, wiederholte Hintergrundinformationen, erschöpfende Auswahllisten und modische, aber inhaltsleere Einleitungen. Empfiehl einen bestimmten Ansatz und erläutere nur den Zusammenhang, den ein Entwickler für dessen sichere Anwendung benötigt. Verwende amerikanisches Englisch, führe Rechtschreib- und Fachbegriffsprüfungen durch und halte die Sätze auch für Nichtmuttersprachler verständlich. Erkläre nicht offensichtliche Abkürzungen bei der ersten Verwendung; allgemein bekannte Protokoll- und Adressierungsabkürzungen können unerklärt bleiben, wenn die Schreibrichtlinie dies zulässt. Formuliere Abschnitte um oder nimm sie heraus, wenn sie wie beliebiger automatisch erzeugter Text klingen. Kürze darf keine Einschränkungen, Ausnahmen, Bedrohungsgrenzen oder die Begründung dafür auslassen, weshalb eine Empfehlung sicherer ist. ## Die Regeln des Repositorys für Markdown und Bilder einhalten Verwende Markdown und vermeide unverarbeitetes HTML mit Ausnahme ausdrücklich erlaubter Elemente wie `details` und `summary`. Verwende einheitlich Bindestriche für Aufzählungen, Markdown-Fettschrift und Blockzitate. Lasse nach jeder Überschrift eine Leerzeile. Ein typisches Dokument beginnt mit einer H1-Überschrift und einer Einleitung, wird mit klar abgegrenzten H2-Abschnitten fortgeführt und kann mit Quellenangaben enden. Drei bis sechs H2-Abschnitte sind eine sinnvolle Vorgabe, aber keine starre Obergrenze. Füge kein manuelles Inhaltsverzeichnis hinzu, wenn das Veröffentlichungswerkzeug es erzeugt. Halte die Dateinamensregeln des Projektarchivs ein. Verwende nur Buchstaben, Ziffern, Bindestriche und Unterstriche und behalte vorgeschriebene Endungen wie `_Cheat_Sheet.md` bei. Erstelle neue Dokumente aus der genehmigten Vorlage. Speichere Ressourcen im dafür vorgesehenen Ressourcenverzeichnis. Verwende das genehmigte Bildformat, gib aussagekräftigen Alternativtext an und binde Ressourcen über den richtigen relativen Pfad ein. Schreibe Verweise mit beschreibenden Bezeichnungen in den Fließtext und verwende nach Möglichkeit HTTPS. ## Vor der Bitte um ein Review Lint und Linkprüfung ausführen Führe vor einem Änderungsvorschlag die im Projektarchiv festgelegte Markdown-Prüfung, Fachbegriffsprüfung und Verweisprüfung aus. Führe außerdem alle Vorgaben zu Umfang, Belegdichte und weiteren Regeln aus, die für die geänderten Inhalte gelten. Behandle eine fehlgeschlagene lokale Prüfung oder Prüfung der kontinuierlichen Integration als zu untersuchenden Fehler und nicht als Grund, die Kontrolle zu umgehen. Prüfe die abschließende Differenz, damit erzeugte oder automatisierte Änderungen keine sachfremden Bearbeitungen verbergen. Beachte die Grenzen der Automatisierung. Automatisierbare Prüfungen können fehlerhaftes Markdown, unzulässige Begriffe, unerreichbare Verweise, übermäßigen Umfang und fehlende Belegmuster erkennen. Sie können jedoch nicht beurteilen, ob eine Quelle eine Aussage stützt, ein Ratschlag richtig ist, das Thema in das Dokument gehört oder Inhalte vorhandene Anleitungen wiederholen. ## KI-Hilfe offenlegen und aus mehreren Blickwinkeln prüfen Lege wesentliche Unterstützung durch künstliche Intelligenz in der Beschreibung des Änderungsantrags offen. Halte im dafür vorgesehenen Offenlegungsabschnitt des Projektarchivs den Werkzeugnamen, die bekannte Version und die Eingabeaufforderung fest. Diese Pflicht gilt für jedes Werkzeug mit künstlicher Intelligenz; eine unterlassene Offenlegung kann den Beitrag ungültig machen. Prüfe Sicherheitsleitfäden in getrennten Dimensionen: fachliche Sicherheit, praktische Anwendbarkeit für Entwickler, Qualität der Quellen und Verweise, Doppelungen und Einordnung sowie Sprachqualität. Fachprüfer dürfen unabhängig arbeiten, ihre Feststellungen sollten jedoch zu einem einzigen, beweisgestützten Urteil zusammengeführt werden. Verwende eindeutige Ergebnisse wie annehmen, Änderungen verlangen oder schließen. Führe für blockierende Feststellungen konkrete Belege an, unterscheide automatisierbare Fehler von Beurteilungsfehlern und genehmige nicht allein deshalb, weil Quellenangaben oder automatische Prüfungen vorhanden sind.