trailofbits/open-sourcing

Ein Repository als Open Source veröffentlichen

Bereiten Sie ein Repository für die öffentliche Veröffentlichung vor, damit eine außenstehende Person ohne vorheriges Fachwissen es erstellen, nutzen und dazu beitragen kann – und damit nichts Vertrauliches damit ausgeliefert wird. Gehen Sie die Schritte der Reihe nach durch; das Audit für Geheimnisse kommt zuerst, da sein Ergebnis (Beibehalten vs. Neuerstellen des Repositories) alles danach beeinflusst.

Wann verwenden

• Ein privates Repository öffentlich machen
• Ein vorhandenes öffentliches Repository auf Release-Qualität prüfen („es offiziell machen“)
• Eine Lizenz für ein Projekt auswählen
• Paketerstellung, Versionierung oder Release-Automatisierung im Vorfeld einer öffentlichen Veröffentlichung einrichten

Wann NICHT verwenden

• Routinemäßige Entwicklung an einem bereits veröffentlichten Projekt (kein Release-Ereignis)
• Überprüfung von Code Dritter auf Schwachstellen (verwenden Sie einen Sicherheitsüberprüfungs-Skill)
• Veröffentlichung eines Pakets aus einem Repository, das privat bleibt – nur die Schritte zum Release-Management treffen zu; den Rest überspringen

Workflow

Schritt 1: Das Organisationsprofil erkennen

bash {baseDir}/scripts/detect_org.sh

Das Skript überprüft Git-Remotes und E-Mails aktueller Committer und gibt einen Profilnamen aus. Wenn es trailofbits ausgibt, lesen Sie references/trailofbits.md jetzt und wenden Sie dessen Lizenzrichtlinie, Veröffentlichungskonten und Prozesshinweise in den verbleibenden Schritten an. Wenn es generic ausgibt, fahren Sie nur mit der generischen Anleitung fort. Wenn der Benutzer sagt, dass die Erkennung falsch ist, vertrauen Sie dem Benutzer.

Schritt 2: Audit für Geheimnisse – vor allem anderen

Ein Repository, das jemals Geheimnisse enthielt (API-Schlüssel, Anmeldeinformationen, Kundendaten), sollte nicht öffentlich gemacht werden. Das Umschreiben der Historie ist fehleranfällig und erreicht keine Forks, Caches oder CI-Artefakte. Die zuverlässige Lösung ist ein neues Repository: Kopieren Sie den aktuellen Baum, committen Sie, und archivieren Sie das alte Repository privat.

1. Fragen Sie, ob das Projekt jemals Geheimnisse oder vertrauliche Kundendaten verarbeitet hat. Handelt es sich um Tools einer Sicherheitsberatung, fragen Sie auch, ob Test-Fixtures oder Beispieldaten aus Kundenprojekten stammen.
2. Scannen Sie die gesamte Historie mit einem dedizierten Tool, falls verfügbar – gitleaks git . oder trufflehog git file://. – anstatt nur zu überfliegen.
3. Überprüfen Sie über den Git-Baum hinaus: GitHub Actions-Protokolle und -Artefakte, alte Releases, Issue- und PR-Verlauf sowie das Repository-Wiki werden alle mit dem Repository öffentlich.
4. Aktivieren Sie nach der Veröffentlichung die GitHub-Geheimnisüberprüfung und den Push-Schutz in den Repository-Einstellungen.

Lehnen Sie diese Rechtfertigungen ab – dies ist der eine Schritt, der nach der Veröffentlichung nicht rückgängig gemacht werden kann:

• "Der Schlüssel wurde widerrufen, also ist die Historie in Ordnung." Widerrufene Anmeldeinformationen geben immer noch Infrastrukturnamen, interne URLs und Muster preis, die Angreifer für gezielte Angriffe nutzen.
• "Wir schreiben die Historie mit git-filter-repo um." Umschreibungen erfassen keine Forks, Klone, Caches und CI-Artefakte; der Ansatz mit einem neuen Repository tut dies nicht.
• "Es sind nur Testdaten." Fixtures, die aus Kundenprojekten oder Produktionssystemen stammen, sind unabhängig von ihrer Bezeichnung vertraulich.

Schritt 3: Bereitschaftsüberprüfung durchführen

bash {baseDir}/scripts/check_readiness.sh

Das Skript gibt eine Checkliste mit Indikatoren (README, LIZENZ, CONTRIBUTING, SECURITY.md, CI, Tests, Semver-Tags, ...) aus und warnt vor nachverfolgten Dateien, die häufig Geheimnisse enthalten. Behandeln Sie nicht markierte Punkte als Diskussionsanregungen, nicht als harte Fehler – ein Forschungsprototyp braucht nicht alles, was eine Flaggschiff-Bibliothek braucht. Gehen Sie die Lücken mit dem Benutzer durch und beheben Sie diejenigen, die für dieses Projekt wichtig sind.

Schritt 4: Dokumentation

Die README ist die Eingangstür des Projekts. Bestätigen Sie, dass sie erklärt:

• Was das Projekt ist und welches Problem es löst (erster Absatz)
• Wie man es installiert – Paketmanager, Container-Image oder Bau aus dem Quellcode; ein Bau aus einem frischen Klon muss nur mit dem funktionieren, was sich im Repository befindet
• Wie man es verwendet – mindestens ein konkretes, kopierbares Beispiel
• Wie man beiträgt – direkt in der README oder über CONTRIBUTING.md
• Die Lizenz – ein kurzer Abschnitt, der sie nennt

Fügen Sie außerdem hinzu:

• SECURITY.md mit Anweisungen zur Meldung von Schwachstellen (eine Kontaktadresse oder die private Schwachstellenmeldung von GitHub). Für Sicherheitstools ist dies selbstverständlich.
• API-Dokumentation, erstellt und gehostet (GitHub Pages über CI ist der übliche Weg), verlinkt von der README und dem Repository-Website-Feld. Siehe die Sprachreferenzen unten für Ökosystem-spezifische Dokumentationswerkzeuge.
• Eine Verhaltenskodex, wenn das Projekt externe Mitwirkende erwartet.

Schritt 5: Lizenzierung

Keine Lizenz bedeutet nicht Open Source, unabhängig von der Sichtbarkeit. Lesen Sie references/licensing.md für Auswahlkriterien und Mechanik. Die Kurzfassung:

1. Wenden Sie die Richtlinie der Organisation an, falls eine in Schritt 1 erkannt wurde.
2. Andernfalls: Apache 2.0 als permissive Standardlizenz, AGPLv3 wenn private Änderungen durch Wettbewerber ein echtes Anliegen sind, Creative Commons für Nicht-Code-Artefakte.
3. Fügen Sie die LICENSE-Datei hinzu, setzen Sie SPDX-Identifikatoren in den Paketmetadaten, geben Sie die Lizenz in der README an und überprüfen Sie, ob alle drei übereinstimmen.

Schritt 6: Tests und CI

• Bestätigen Sie, dass die Testsuite existiert und bestanden wird; ein öffentliches Repository mit einer fehlschlagenden Standard-Branch signalisiert Aufgabe.
• Stellen Sie sicher, dass CI die Tests bei jedem PR ausführt, über die unterstützte Sprachversions- und Plattformmatrix hinweg.
• Setzen Sie Formatierung und Linting in CI durch (sprachspezifische Werkzeuge in den Referenzen unten), damit Stildebatten nie in Reviews landen.
• Respektieren Sie vorhandene Werkzeuge. Ersetzen Sie keinen funktionierenden Formatierer, Linter oder Typprüfer im Rahmen der Open-Source-Veröffentlichung. Wenn es hinter der aktuellen Generation zurückbleibt (die Sprachreferenzen nennen die aktuellen Werkzeuge), warnen Sie den Betreuer und lassen Sie ihn entscheiden; fügen Sie das aktuelle Standardwerkzeug nur hinzu, wenn eine Kategorie vollständig fehlt – kein Typprüfer, kein Formatierer.
• Ziehen Sie eine Coverage-Schwelle in Betracht, die CI fehlschlagen lässt, wenn die Codeabdeckung sinkt.
• Härten Sie die Workflows selbst, bevor sie öffentliche Angriffsfläche werden:
  • Verankern Sie Drittanbieter-Aktionen mit vollständigen Commit-SHAs; aktivieren Sie Dependabot für github-actions, damit die Verankerungen aktuell bleiben.
  • Setzen Sie permissions:-Blöcke mit minimalen Rechten (beginnen Sie mit permissions: {}).
  • Überprüfen Sie mit zizmor .github/workflows/ und linten Sie mit actionlint.

Schritt 7: Repository-Einstellungen

• Branch-Schutz auf dem Standard-Branch: keine Force-Pushes, PRs erforderlich. Bevorzugen Sie Rulesets für neue Repositories; klassischer Branch-Schutz wird weiterhin unterstützt.
• Merge-Schutz: erforderliche Statusprüfungen, sodass PRs nicht mit fehlschlagenden Tests gemergt werden können.
• Dependabot oder Renovate für Abhängigkeits- und Actions-Updates. Gruppieren Sie Updates, um PR-Rauschen zu reduzieren, und legen Sie ein Wartezeitfenster fest (z. B. 7 Tage), damit frisch veröffentlichte – und gelegentlich gekaperte – Versionen vor der Übernahme altern.
• .editorconfig damit die Editoren von Mitwirkenden bei grundlegenden Leerzeichen übereinstimmen.
• Labels: Erstellen Sie sie, sobald mehr als ein Issue oder PR eines benötigt; Präfixe für Facetten skalieren gut (C: Komponente, P: Plattform). Siehe blight's labels für ein ausgearbeitetes Beispiel.

Schritt 8: Releases und Versionierung

• Markieren Sie jedes Release mit vX.Y.Z gemäß semver; verwenden Sie Suffixe -rc.N / -pre.N für Release-Kandidaten und Vorabversionen.
• Machen Sie Releases CI-getrieben: Das Pushen eines Tags (oder die Veröffentlichung eines GitHub Releases) löst Bau, Paketerstellung und Upload ohne manuelle Schritte aus. Ein Release sollte git tag vX.Y.Z && git push origin vX.Y.Z sein.
• Veröffentlichen Sie Pakete unter einem organisations-eigenen Konto, nicht einem persönlichen, und verwenden Sie Trusted Publishing (OIDC) anstelle von langlebigen Tokens, wo immer der Index dies unterstützt.

Schritt 9: Sprachspezifische Praktiken

Identifizieren Sie die Sprachen des Projekts anhand seiner Markierungsdateien und lesen Sie die entsprechende Referenz für Paketerstellung, Veröffentlichung und Qualitätswerkzeuge:

Markierungsdatei	Referenz
pyproject.toml, setup.py	references/python.md – verweist für die Werkzeuge auf den modern-python Skill
CMakeLists.txt, Makefile (C/C++)	references/c-cpp.md
Cargo.toml	references/rust.md
go.mod	references/go.md
package.json	references/javascript.md
Gemfile, *.gemspec	references/ruby.md

Wenden Sie für andere Ökosysteme die übergreifenden Prinzipien an: reproduzierbare Builds aus einem frischen Klon, CI-getriebene Releases, Trusted Publishing oder organisations-eigene Konten sowie Lizenzmetadaten im Paketmanifest.

Abschließende Überprüfung

Bevor der Sichtbarkeitsschalter umgelegt wird, überprüfen Sie aus der Perspektive eines Außenstehenden:

1. Klonen Sie in ein leeres Verzeichnis und befolgen Sie die Build-Anweisungen der README wörtlich – funktionieren sie ohne Fachwissen?
2. Führen Sie {baseDir}/scripts/check_readiness.sh erneut aus und bestätigen Sie, dass die verbleibenden Lücken bewusste Entscheidungen sind, die dem Benutzer mitgeteilt wurden.
3. Bestätigen Sie, dass das Audit für Geheimnisse (Schritt 2) tatsächlich stattfand; dies ist der eine Schritt, der nach der Veröffentlichung nicht rückgängig gemacht werden kann.

Das Repository öffentlich zu machen, ist dann eine Änderung der Repository-Einstellungen. Verbinden Sie das Release mit einer Ankündigung, wenn die Organisation einen Prozess dafür hat.

Zusätzliche Ressourcen

Referenzdateien

• references/licensing.md – Lizenzauswahlkriterien, SPDX-Metadaten, Forks und Relizenzierung
• references/trailofbits.md – Trail of Bits Richtlinien-Overlay (wird nur geladen, wenn in Schritt 1 erkannt)
• references/python.md, references/c-cpp.md, references/rust.md, references/go.md, references/javascript.md, references/ruby.md – sprachspezifische Paketerstellung, Veröffentlichung und Qualitätswerkzeuge

Skripte

• scripts/detect_org.sh – gibt das Organisationsprofil (trailofbits oder generic) aus Git-Remotes und Committer-E-Mails aus
• scripts/check_readiness.sh – gibt Indikatoren für Dateien zur Release-Bereitschaft aus und markiert nachverfolgte Dateien, die häufig Geheimnisse enthalten