
GitHub-App zum Festlegen und Durchsetzen von Sicherheitsrichtlinien
Allstar ist eine GitHub-App, die kontinuierlich GitHub-Organisationen oder -Repositories auf die Einhaltung von Sicherheitsbest Practices überwacht. Wenn Allstar eine Verletzung der Sicherheitsrichtlinie erkennt, erstellt es ein Issue, um den Repository- oder Organisationsbesitzer zu warnen. Für einige Sicherheitsrichtlinien kann Allstar auch automatisch die Projekteinstellung ändern, die die Verletzung verursacht hat, und sie in den erwarteten Zustand zurücksetzen.
Allstars Ziel ist es, Ihnen eine fein abgestimmte Kontrolle über die Dateien und Einstellungen zu geben, die die Sicherheit Ihrer Projekte beeinflussen. Sie können auswählen, welche Sicherheitsrichtlinien sowohl auf Organisations- als auch auf Repository-Ebene überwacht werden sollen, und wie mit Richtlinienverletzungen umzugehen ist. Sie können auch neue Richtlinien entwickeln oder dazu beitragen.
Allstar wird als Teil des OpenSSF Scorecard-Projekts entwickelt.
Wenn Sie unerwünschte Issues erhalten, die von Allstar erstellt wurden, folgen Sie diesen Anweisungen, um sich abzumelden.
Allstar ist hochgradig konfigurierbar. Es gibt drei Hauptebenen der Steuerung:
Diese Konfigurationen erfolgen im .allstar-Repository der Organisation.
Repository-Ebene: Repository-Betreuer in einer Organisation, die Allstar
verwendet, können ihr Repository in organisationsweite Durchsetzungen
ein- oder aus ihnen auswählen. Hinweis: Diese Repository-Ebene-Steuerungen
sind nur funktional, wenn "Repo-Override" in den Einstellungen auf
Organisationsebene erlaubt ist. Diese Konfigurationen erfolgen im
.allstar-Verzeichnis des Repositorys.
Richtlinienebene: Administratoren oder Betreuer können auswählen, welche
Richtlinien auf bestimmten Repos aktiviert sind und welche Aktionen Allstar
bei einer Richtlinienverletzung ergreift. Diese Konfigurationen erfolgen in
einer Richtlinien-YAML-Datei entweder im .allstar-Repository der
Organisation (Admins) oder im .allstar-Verzeichnis des Repositorys
(Betreuer).
Bevor Sie Allstar auf Organisationsebene installieren, sollten Sie ungefähr entscheiden, auf wie vielen Repositories Allstar ausgeführt werden soll. Dies hilft Ihnen, zwischen der Opt-In- und der Opt-Out-Strategie zu wählen.
Die Opt-In-Strategie ermöglicht es Ihnen, manuell die Repositories hinzuzufügen, auf denen Allstar ausgeführt werden soll. Wenn Sie keine Repositories angeben, wird Allstar trotz Installation nicht ausgeführt. Wählen Sie die Opt-In-Strategie, wenn Sie Richtlinien nur auf einer kleinen Anzahl Ihrer gesamten Repositories durchsetzen möchten oder Allstar zuerst auf einem einzelnen Repository ausprobieren möchten, bevor Sie es auf weiteren aktivieren. Seit Version 4.3 werden Globs unterstützt, um problemlos mehrere Repositories mit ähnlichem Namen hinzuzufügen.
Die Opt-Out-Strategie (empfohlen) aktiviert Allstar auf allen Repositories und ermöglicht es Ihnen, manuell die Repositories auszuwählen, die von Allstar-Durchsetzungen ausgeschlossen werden sollen. Sie können auch wählen, alle öffentlichen Repos oder alle privaten Repos auszuschließen. Wählen Sie diese Option, wenn Sie Allstar auf allen Repositories in einer Organisation ausführen möchten oder nur eine kleine Anzahl von Repositories oder einen bestimmten Typ (z. B. öffentlich vs. privat) ausschließen möchten. Seit Version 4.3 werden Globs unterstützt, um problemlos mehrere Repositories mit ähnlichem Namen hinzuzufügen.
Sowohl die Schnellstart-Installation als auch die
Manuelle Installation umfassen die Installation der
Allstar-App in Ihrer GitHub-Organisation.
Die Allstar-App wird von OpenSSF betrieben und ist eine gute
Wahl für die meisten Open-Source-Repositories. Sie können die angeforderten
Berechtigungen einsehen. Die App verlangt Lesezugriff auf die meisten
Einstellungen und Dateiinhalte, um Sicherheitskonformität zu erkennen. Sie
verlangt Schreibzugriff auf Issues und Checks, um Issues erstellen und die
block-Aktion ermöglichen zu können.
Wenn Sie die von OpenSSF betriebene Allstar-App nicht verwenden möchten, können Sie Allstar selbst hosten und Ihre eigene Allstar-App erstellen. Dies bietet direkte Kontrolle über die App, mit dem Nachteil, dass die App konfiguriert, gesichert, überwacht und gewartet werden muss.
Schnellstart- oder manuelle Installation werden empfohlen, es sei denn, Sie haben spezifische Sicherheits- oder Compliance-Beschränkungen, die Sie daran hindern, die von OpenSSF verwaltete Allstar-App zu verwenden.
Diese Installationsoption aktiviert Allstar mit der Opt-Out-Strategie auf allen Repositories in Ihrer Organisation. Alle aktuellen Richtlinien werden aktiviert, und Allstar benachrichtigt Sie über Richtlinienverletzungen, indem es ein Issue erstellt. Dies ist der schnellste und einfachste Weg, mit Allstar zu beginnen, und Sie können später noch beliebige Konfigurationen ändern.
Aufwand: sehr einfach
Schritte:
.allstar einDas war's! Alle aktuellen Allstar-Richtlinien sind jetzt auf allen Ihren Repositories aktiviert. Allstar erstellt ein Issue, wenn eine Richtlinie verletzt wird.
Um Konfigurationen zu ändern, lesen Sie die Anleitung zur manuellen Installation.
Diese Installationsoption führt Sie durch die Erstellung von Konfigurationsdateien gemäß entweder der Opt-In- oder der Opt-Out-Strategie. Diese Option bietet von Anfang an eine detailliertere Kontrolle über Konfigurationen.
Aufwand: mittel
Schritte:
Nur selbst hosten, wenn es sein muss! Die Allstar-App erfordert Konfiguration, Sicherung und laufende Wartung. Wenn eine neue Allstar-Version veröffentlicht wird, müssen Sie Ihre selbst gehostete Lösung aktualisieren.
Zwei Ansätze zum Selbsthosten werden beschrieben:
Diese Installationsoption führt Allstar als geplanten Job mit GitHub Actions aus.
Aufwand: hoch
Folgen Sie der Anleitung zur GitHub Actions-Installation, um:
.allstar) zu erstellen, wie
in der Schnellstart-Installation oder
manuellen Installation beschrieben. (Ignorieren Sie
die Schritte zur Installation der von OpenSSF verwalteten Allstar-App in
Ihrer Organisation.).allstar-Repository einzurichten, um
Allstar im Batch-Modus auszuführen.Diese Installationsoption führt Allstar als persistenten Prozess aus.
Aufwand: sehr hoch
Siehe Betreiberanweisungen für weitere Informationen, einschließlich der Erstellung einer Allstar-App, der Verwaltung von Secrets und verfügbarer Umgebungsvariablen.
Jede Richtlinie kann mit einer Aktion konfiguriert werden, die Allstar ergreift, wenn es feststellt, dass ein Repository nicht konform ist.
log: Dies ist die Standardaktion und findet tatsächlich für alle Aktionen
statt. Alle Ergebnisse und Details der Richtlinienausführung werden protokolliert.
Protokolle sind derzeit nur für den App-Betreiber sichtbar; Pläne, diese
zugänglich zu machen, werden diskutiert.issue: Diese Aktion erstellt ein GitHub-Issue. Pro Richtlinie wird nur ein
Issue erstellt, und der Text beschreibt die Details der Richtlinienverletzung.
Wenn das Issue bereits offen ist, wird es alle 24 Stunden ohne Aktualisierung
mit einem Kommentar angepingt (derzeit nicht benutzerkonfigurierbar). Wenn sich
das Richtlinienergebnis ändert, wird ein neuer Kommentar im Issue hinterlassen
und im Issue-Text verlinkt. Sobald die Verletzung behoben ist, wird das Issue
von Allstar innerhalb von 5-10 Minuten automatisch geschlossen.fix: Diese Aktion ist richtlinienspezifisch. Die Richtlinie nimmt
Änderungen an den GitHub-Einstellungen vor, um die Richtlinienverletzung zu
beheben. Nicht alle Richtlinien werden dies unterstützen können (siehe unten).Vorgeschlagene, aber noch nicht implementierte Aktionen. Definitionen werden in Zukunft hinzugefügt.
block: Allstar kann einen GitHub-Status-Check
setzen und jeden Pull Request im Repository am Zusammenführen hindern, wenn
der Check fehlschlägt.email: Allstar würde eine E-Mail an den/die Repository-Administrator(en)
senden.rpc: Allstar würde einen RPC an ein organisationsspezifisches System senden.Zwei Einstellungen sind verfügbar, um die Issue-Aktion zu konfigurieren:
issueLabel ist auf Organisations- und Repository-Ebene verfügbar. Das Setzen
überschreibt das Standard-Label allstar, das Allstar zur Identifizierung
seiner Issues verwendet.
issueRepo ist auf Organisationsebene verfügbar. Das Setzen erzwingt, dass
alle in der Organisation erstellten Issues im angegebenen Repository erstellt
werden.
Ähnlich wie bei der Konfiguration zur Aktivierung der Allstar-App werden alle
Richtlinien mit einer YAML-Datei entweder im .allstar-Repository der
Organisation oder im .allstar-Verzeichnis des Repositorys aktiviert und
konfiguriert. Wie bei der App sind Richtlinien standardmäßig opt-in, auch die
Standardaktion log wird keine sichtbaren Ergebnisse liefern. Eine einfache
Möglichkeit, alle Richtlinien zu aktivieren, besteht darin, für jede Richtlinie
eine YAML-Datei mit folgendem Inhalt zu erstellen:```yaml
optConfig:
optOutStrategy: true
action: issue
Die Einzelheiten zur Funktionsweise der `fix`-Aktion für jede Richtlinie sind unten aufgeführt. Wenn sie unten nicht aufgeführt ist, ist die `fix`-Aktion nicht anwendbar.
### Branch-Schutz
Die Konfigurationsdatei dieser Richtlinie heißt `branch_protection.yaml`, und die [Konfigurationsdefinitionen befinden sich hier](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig).
Die Branch-Schutz-Richtlinie prüft, ob die [Branch-Schutz-Einstellungen](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) von GitHub gemäß der angegebenen Konfiguration korrekt eingerichtet sind. Der Issue-Text beschreibt, welche Einstellung falsch ist. Siehe [GitHub-Dokumentation](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) zum Korrigieren der Einstellungen.
Die `fix`-Aktion ändert die Branch-Schutz-Einstellungen so, dass sie der angegebenen Richtlinienkonfiguration entsprechen.
### Binäre Artefakte
Die Konfigurationsdatei dieser Richtlinie heißt `binary_artifacts.yaml`, und die [Konfigurationsdefinitionen befinden sich hier](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig).
Diese Richtlinie integriert den [Check von Scorecard](https://github.com/ossf/scorecard/#scorecard-checks). Entfernen Sie das binäre Artefakt aus dem Repository, um die Konformität zu erreichen. Da die Scorecard-Ergebnisse ausführlich sein können, müssen Sie möglicherweise [Scorecard selbst](https://github.com/ossf/scorecard) ausführen, um alle detaillierten Informationen zu sehen.
### CODEOWNERS
Die Konfigurationsdatei dieser Richtlinie heißt `codeowners.yaml`, und die [Konfigurationsdefinitionen befinden sich hier](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig).
Diese Richtlinie prüft das Vorhandensein einer [`CODEOWNERS`-Datei](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) in Ihren Repositorys.
### Externe Mitarbeiter
Die Konfigurationsdatei dieser Richtlinie heißt `outside.yaml`, und die [Konfigurationsdefinitionen befinden sich hier](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/outside#OrgConfig).
Diese Richtlinie prüft, ob [externe Mitarbeiter](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization) entweder Administrator- (Standard) oder Push- (optional) Zugriff auf das Repository haben. Nur Organisationsmitglieder sollten diesen Zugriff haben, da andernfalls nicht vertrauenswürdige Mitglieder Admin-Einstellungen ändern und bösartigen Code committen können.
### SECURITY.md
Die Konfigurationsdatei dieser Richtlinie heißt `security.yaml`, und die [Konfigurationsdefinitionen befinden sich hier](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/security#OrgConfig).
Diese Richtlinie prüft, ob das Repository eine Sicherheitsrichtliniendatei in `SECURITY.md` enthält und diese nicht leer ist. Der erstellte Issue enthält einen Link zum [GitHub-Tab](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository), der Ihnen hilft, eine Sicherheitsrichtlinie in Ihr Repository zu committen.
### Gefährlicher Workflow
Die Konfigurationsdatei dieser Richtlinie heißt `dangerous_workflow.yaml`, und die [Konfigurationsdefinitionen befinden sich hier](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig).
Diese Richtlinie wird auf **alle** Branches angewendet, siehe Begründung [hier](https://github.com/ossf/allstar/issues/569).
Diese Richtlinie prüft die GitHub Actions Workflow-Konfigurationsdateien (`.github/workflows`) auf Muster, die auf bekanntes gefährliches Verhalten hinweisen. Weitere Informationen zu dieser Prüfung finden Sie in der [OpenSSF Scorecard-Dokumentation](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow).
### Generischer Scorecard-Check
Die Konfigurationsdatei dieser Richtlinie heißt `scorecard.yaml`, und die [Konfigurationsdefinitionen befinden sich hier](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig).
Diese Richtlinie führt jeden Scorecard-Check aus, der in der `checks`-Konfiguration aufgeführt ist. Alle ausgeführten Prüfungen müssen einen Wert haben, der dem `threshold`-Wert entspricht oder darüber liegt. Weitere Informationen zu den einzelnen Prüfungen finden Sie in der [OpenSSF Scorecard-Dokumentation](https://github.com/ossf/scorecard/blob/main/docs/checks.md).
#### SARIF-Upload
Die Scorecard-Richtlinie kann optional Ergebnisse als [SARIF](https://sarifweb.azurewebsites.net/) in den **Security > Code Scanning**-Tab jedes Repositorys hochladen. Dies gibt Organisationsadministratoren Einblick in Scorecard-Ergebnisse zusammen mit anderen Sicherheitstools (CodeQL, Dependabot usw.), ohne dass ein repository-spezifisches Workflow-Setup erforderlich ist.
Um den SARIF-Upload zu aktivieren, fügen Sie das `upload`-Feld zu Ihrer `scorecard.yaml` hinzu:```yaml
optConfig:
optOutStrategy: true
action: issue
checks:
- Binary-Artifacts
- Signed-Releases
threshold: 8
upload:
sarif: true
Anforderungen:
security_events).
Selbst gehostete Betreiber müssen diese Berechtigung zu ihrer GitHub-App hinzufügen. Die
von OpenSSF betriebene öffentliche Allstar-App enthält diese Berechtigung noch nicht.Der SARIF-Upload funktioniert sowohl mit selbst gehosteten Bereitstellungsmodi: als Dienst-Daemon oder als GitHub Action.
Die Konfigurationsdatei dieser Richtlinie heißt actions.yaml, und die Konfigurationsdefinitionen befinden sich
hier.
Diese Richtlinie überprüft die Konfigurationsdateien für GitHub Actions-Workflows
(.github/workflows) (und in einigen Fällen Workflow-Läufe) in jedem Repository, um
sicherzustellen, dass sie mit den in der organisationsweiten Konfiguration für die
Richtlinie festgelegten Regeln (z. B. erforderlich, verbieten) übereinstimmen.
Die Konfigurationsdatei dieser Richtlinie heißt admin.yaml, und die Konfigurationsdefinitionen befinden sich
hier.
Diese Richtlinie stellt sicher, dass standardmäßig allen Repositorys ein Benutzer oder eine Gruppe als Administrator zugewiesen sein muss. Sie können optional konfigurieren, ob Benutzer Administratoren sein dürfen (im Gegensatz zu Teams).
Siehe dieses Repository als Beispiel für die Verwendung der Allstar-Konfiguration. Als Organisationsadministrator sollten Sie eine README.md mit Informationen darüber in Betracht ziehen, wie Allstar in Ihrer Organisation verwendet wird.
Standardmäßig werden Konfigurationsdateien auf Organisationsebene, wie die obige allstar.yaml-Datei,
in einem .allstar-Repository erwartet. Wenn dieses Repository nicht existiert, wird das
.github-Repository-Verzeichnis allstar als sekundärer Speicherort verwendet. Zur Verdeutlichung, für allstar.yaml:
| Priorität | Repository | Pfad |
|---|---|---|
| Primär | .allstar | allstar.yaml |
| Sekundär | .github | allstar/allstar.yaml |
Dies gilt auch für die Konfigurationsdateien auf Organisationsebene für die einzelnen Richtlinien, wie unten beschrieben.
Allstar sucht auch nach Repository-Richtlinienkonfigurationen im .allstar-Repository der
Organisation, im Verzeichnis mit demselben Namen wie das Repository. Diese Konfiguration wird
unabhängig davon verwendet, ob „repo override“ deaktiviert ist.
Zum Beispiel sucht Allstar die Richtlinienkonfiguration für ein gegebenes Repository
myapp in der folgenden Reihenfolge:
Für Allstar- und Richtlinienkonfigurationsdateien auf Organisationsebene können Sie das Feld
baseConfig angeben, um ein anderes Repository zu spezifizieren, das eine Basis-Allstar-Konfiguration
enthält. Dies wird am besten anhand eines Beispiels erklärt.
Angenommen, Sie haben mehrere GitHub-Organisationen, möchten aber eine einzige Allstar-Konfiguration
verwalten. Ihre Hauptorganisation ist "acme", und das Repository
acme/.allstar enthält allstar.yaml:```yaml
optConfig:
optOutStrategy: true
issueLabel: allstar-acme
issueFooter: Issue created by Acme security team.
Sie haben auch eine Satelliten-GitHub-Organisation namens "acme-sat". Sie möchten die Hauptkonfiguration wiederverwenden, aber einige Änderungen zusätzlich anwenden, indem Sie Allstar für bestimmte Repositorys deaktivieren. Das Repository `acme-sat/.allstar` enthält `allstar.yaml`:```yaml
baseConfig: acme/.allstar
optConfig:
optOutRepos:
- acmesat-one
- acmesat-two
Dies verwendet die gesamte Konfiguration aus acme/.allstar als Basiskonfiguration, wendet dann aber alle Änderungen in der aktuellen Datei zusätzlich zur Basiskonfiguration an. Die Methode wird als JSON Merge Patch beschrieben. Die baseConfig muss ein GitHub-Repository im Format <org>/<repository> sein.
Siehe CONTRIBUTING.md
| Opt-Out (Empfohlen) optOutStrategy = true | Opt-In optOutStrategy = false |
|---|
| Standardverhalten | Alle Repos sind aktiviert | Keine Repos sind aktiviert |
| Manuelles Hinzufügen von Repositories | Manuelles Hinzufügen von Repos deaktiviert Allstar auf diesen Repos | Manuelles Hinzufügen von Repos aktiviert Allstar auf diesen Repos |
| Zusätzliche Konfigurationen | optOutRepos: Allstar wird auf den aufgeführten Repos deaktiviert optOutPrivateRepos: wenn true, wird Allstar auf allen privaten Repos deaktiviert optOutPublicRepos: wenn true, wird Allstar auf allen öffentlichen Repos deaktiviert (optInRepos: diese Einstellung wird ignoriert) | optInRepos: Allstar wird auf den aufgeführten Repos aktiviert (optOutRepos: diese Einstellung wird ignoriert) |
| Repo-Override | Wenn true: Repos können sich von den Allstar-Durchsetzungen ihrer Organisation
abmelden, indem sie die Einstellungen in ihrer eigenen Repo-Datei verwenden.
Organisationsweite Opt-In-Einstellungen, die für dieses Repository gelten,
werden ignoriert. Wenn false: Repos können sich nicht von Allstar-Durchsetzungen abmelden, wie auf Organisationsebene konfiguriert. | Wenn true: Repos können sich in die Allstar-Durchsetzungen ihrer Organisation
einschreiben, auch wenn sie auf Organisationsebene nicht für das Repo
konfiguriert sind. Organisationsweite Opt-Out-Einstellungen, die für dieses
Repository gelten, werden ignoriert. Wenn false: Repos können sich nicht in Allstar-Durchsetzungen einschreiben, wenn sie nicht auf Organisationsebene konfiguriert sind. |
| Repository | Pfad | Bedingung |
|---|
myapp | .allstar/branch_protection.yaml | Wenn „repo override“ erlaubt ist. |
.allstar | myapp/branch_protection.yaml | Immer. |
.allstar | branch_protection.yaml | Immer. |
.github | allstar/myapp/branch_protection.yaml | Wenn das .allstar-Repository nicht existiert. |
.github | allstar/branch_protection.yaml | Wenn das .allstar-Repository nicht existiert. |