Allstar

[!IMPORTANT] Die von OpenSSF gehostete Allstar GitHub App wurde eingestellt. Allstar selbst, das Subprojekt von OpenSSF Scorecard, wird weiterhin gepflegt — Sie müssen es nun selbst ausführen, entweder als GitHub Action oder als Dienst-Daemon.

Weitere Details finden Sie unter ossf/allstar#881.

Wenn Ihre Organisation auf die gehostete App angewiesen war, lesen Sie Migration von der gehosteten App.

Übersicht

• Was ist Allstar?

Was gibt es Neues bei Allstar

• whats-new.md

Unerwünschte Issues deaktivieren

• Hilfe! Allstar erstellt Issues, die ich nicht möchte!

Erste Schritte

• Hintergrund
• Optionen auf Organisationsebene
• Installationsoptionen
  • Erstellen Sie Ihre GitHub App
  • Erstellen Sie Ihr .allstar-Kontroll-Repository
  • Allstar als GitHub Action ausführen
  • Allstar als Dienst-Daemon ausführen
• Migration von der gehosteten App

Richtlinien und Aktionen

• Aktionen
• Richtlinien

Erweitert

• Konfigurationsdefinitionen
• Beispielkonfigurationen
• Betreiben Sie Ihre eigene Allstar-Instanz

Mitwirken

• Mitwirken

Übersicht

Was ist Allstar?

Allstar ist eine GitHub App, die GitHub-Organisationen oder -Repositories kontinuierlich auf die Einhaltung von Sicherheits-Best Practices überwacht. Wenn Allstar eine Verletzung einer Sicherheitsrichtlinie erkennt, erstellt es ein Issue, um den Repository- oder Organisationsinhaber 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ückversetzen.

Das Ziel von Allstar ist es, Ihnen fein abgestimmte Kontrolle über die Dateien und Einstellungen zu geben, die die Sicherheit Ihrer Projekte beeinflussen. Sie können wählen, welche Sicherheitsrichtlinien sowohl auf Organisationsebene als auch auf Repository-Ebene überwacht werden sollen und wie mit Richtlinienverletzungen umgegangen werden soll. Sie können auch neue Richtlinien entwickeln oder dazu beitragen.

Allstar wird als Teil des OpenSSF Scorecard-Projekts entwickelt.

Was gibt es Neues bei Allstar

Unerwünschte Issues deaktivieren

Wenn Allstar unerwünschte Issues erstellt, folgen Sie diesen Anweisungen, um sich abzumelden.

Erste Schritte

Hintergrund

Allstar ist hochgradig konfigurierbar. Es gibt drei Hauptebenen der Kontrolle:

• Organisationsebene: Organisationsadministratoren können wählen, Allstar zu aktivieren für:
  • alle Repositories in der Organisation;
  • die meisten Repositories, außer einigen, die abgemeldet sind;
  • nur wenige Repositories, die angemeldet sind.

Diese Konfigurationen werden im .allstar-Repository der Organisation vorgenommen.

• Repository-Ebene: Repository-Maintainer in einer Organisation, die Allstar verwendet, können ihr Repository für Durchsetzungen auf Organisationsebene an- oder abmelden. Hinweis: Diese Steuerungen auf Repository-Ebene funktionieren nur, wenn "Repo Override" in den Einstellungen auf Organisationsebene erlaubt ist. Diese Konfigurationen werden im .allstar-Verzeichnis des Repositories vorgenommen.

• Richtlinienebene: Administratoren oder Maintainer können wählen, welche Richtlinien für bestimmte Repositories aktiviert sind und welche Aktionen Allstar ergreift, wenn eine Richtlinie verletzt wird. Diese Konfigurationen werden in einer Richtlinien-YAML-Datei entweder im .allstar-Repository der Organisation (Administratoren) oder im .allstar-Verzeichnis des Repositories (Maintainer) vorgenommen.

Optionen auf Organisationsebene

Bevor Sie Allstar auf Organisationsebene installieren, sollten Sie ungefähr entscheiden, auf wie vielen Repositories Allstar ausgeführt werden soll. Dies hilft Ihnen bei der Wahl zwischen den Opt-In- und Opt-Out-Strategien.

• Die Opt-In-Strategie ermöglicht es Ihnen, die Repositories manuell 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 auf einem einzelnen Repository ausprobieren möchten, bevor Sie es auf weiteren aktivieren. Seit Version v4.3 werden Globs unterstützt, um einfach mehrere Repositories mit ähnlichem Namen hinzuzufügen.

• Die Opt-Out-Strategie (empfohlen) aktiviert Allstar auf allen Repositories und ermöglicht es Ihnen, die Repositories manuell auszuwählen, die von Allstar-Durchsetzungen abgemeldet werden sollen. Sie können auch alle öffentlichen Repos oder alle privaten Repos abmelden. 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 (d. h. öffentlich vs. privat) von Repository abmelden möchten. Seit Version v4.3 werden Globs unterstützt, um einfach mehrere Repositories mit ähnlichem Namen hinzuzufügen.

Installationsoptionen

Allstar agiert in Ihrer Organisation als GitHub App: Sie erstellen die App und führen den Prozess aus, der sich als sie authentifiziert. Die Einrichtung besteht daher aus zwei Schritten, die für jede Bereitstellung gleich sind — App erstellen und Kontroll-Repository erstellen — und dann einer Wahl, wie sie ausgeführt werden soll:

Die Action ist die Option mit geringerem Aufwand und der beste Startpunkt für die meisten Organisationen; Sie können später zu einem Daemon wechseln, ohne die Richtlinienkonfiguration zu ändern.

Erstellen Sie Ihre GitHub App

Eine App ist eine benutzerähnliche Identität mit einem Satz von Berechtigungen in Ihrer Organisation. Allstar benötigt Lesezugriff auf die meisten Einstellungen und Dateiinhalte, um die Einhaltung zu erkennen, sowie Schreibzugriff auf Issues und Checks, um Issues zu erstellen und die block-Aktion zu unterstützen.

Folgen Sie den Operator-Anweisungen - GitHub App erstellen und notieren Sie die App-ID und den privaten Schlüssel. Beide Ausführungsmodi benötigen sie.

Erstellen Sie Ihr .allstar-Kontroll-Repository

Allstar liest seine Konfiguration aus einem Repository namens .allstar in Ihrer Organisation.

Der schnellste Weg, eines zu erstellen, ist aus dem Beispiel:

1. Öffnen Sie das Beispiel-Repository und klicken Sie auf die Schaltfläche "Use this template"
2. Geben Sie im Feld für den Repository-Namen .allstar ein
3. Klicken Sie auf "Create repository from template"

Dies aktiviert alle aktuellen Allstar-Richtlinien auf allen Repositories unter Verwendung der Opt-Out-Strategie mit der issue-Aktion. Sie können alles später ändern.

Für granulare Kontrolle von Anfang an — Wahl der Opt-In- oder Opt-Out-Strategie und eigenständiges Schreiben einzelner Richtliniendateien — folgen Sie stattdessen den manuellen Installationsanweisungen.

Allstar als GitHub Action ausführen

Diese Option führt Allstar als geplanten Job mit GitHub Actions aus, sodass keine Infrastruktur über GitHub hinaus betrieben werden muss.

Folgen Sie den Installationsanweisungen für GitHub Actions, um eine wiederkehrende Action in Ihrem .allstar-Repository einzurichten, sie zu härten und ihre Ergebnisse zu überwachen.

Allstar als Dienst-Daemon ausführen

Diese Option führt Allstar als dauerhaften Prozess aus, der Verstöße kontinuierlich erkennt und behebt, anstatt nach einem Zeitplan.

Siehe Operator-Anweisungen für die Ausführung des Prozesses, die Verwaltung von Geheimnissen, die Dimensionierung und die verfügbaren Umgebungsvariablen.

Migration von der gehosteten App

Wenn Ihre Organisation die von OpenSSF gehostete App verwendet hat, wird Ihre Konfiguration unverändert übernommen. Das .allstar-Kontroll-Repository, allstar.yaml und jede Richtliniendatei funktionieren unverändert weiter; was Sie ersetzen, ist nur der Prozess, der sie liest.

Zur Migration:

1. Erstellen Sie Ihre eigene GitHub App und installieren Sie sie in Ihrer Organisation mit demselben Repository-Zugriff, den die gehostete App hatte.
2. Lassen Sie Ihr bestehendes .allstar-Repository genau so, wie es ist.
3. Führen Sie Allstar als Action oder als Daemon aus.
4. Deinstallieren Sie allstar-app aus Ihrer Organisation, falls es weiterhin unter Einstellungen -> GitHub Apps erscheint.

Zuvor von der gehosteten App erstellte Issues bleiben in Ihren Repositories. Ihre eigene Instanz identifiziert ihre Issues über dasselbe allstar-Label (oder Ihr konfiguriertes issueLabel), sodass sie diese übernimmt und schließt, wenn Verstöße behoben werden, anstatt Duplikate zu erstellen.

Richtlinien und Aktionen

Aktionen

Jede Richtlinie kann mit einer Aktion konfiguriert werden, die Allstar ergreift, wenn es ein Repository als nicht konform erkennt.

• 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 Updates 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 die Änderungen an den GitHub-Einstellungen vor, um die Richtlinienverletzung zu korrigieren. Nicht alle Richtlinien werden dies unterstützen können (siehe unten).

Vorgeschlagene, aber noch nicht implementierte Aktionen. Definitionen werden in der Zukunft hinzugefügt.

• block: Allstar kann einen GitHub-Status- Check setzen und jeden PR im Repository daran hindern, zusammengeführt zu werden, 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.

Aktionskonfiguration

Zwei Einstellungen sind verfügbar, um die Issue-Aktion zu konfigurieren:

• issueLabel ist auf Organisationsebene und Repository-Ebene verfügbar. Wenn Sie es setzen, wird das standardmäßige allstar-Label überschrieben, das Allstar zur Identifizierung seiner Issues verwendet.

• issueRepo ist auf Organisationsebene verfügbar. Wenn Sie es setzen, werden alle in der Organisation erstellten Issues im angegebenen Repository erstellt.

Richtlinien

Ähnlich wie bei der Aktivierungskonfiguration der Allstar-App werden alle Richtlinien mit einer YAML-Datei entweder im .allstar-Repository der Organisation oder im .allstar-Verzeichnis des Repositories aktiviert und konfiguriert. Wie bei der App sind Richtlinien standardmäßig Opt-in, auch die Standardaktion log erzeugt keine sichtbaren Ergebnisse. 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 Details 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 Protection

Die Konfigurationsdatei dieser Richtlinie heißt `branch_protection.yaml`, und die [Konfigurationsdefinitionen finden Sie
hier](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig).

Die Branch-Protection-Richtlinie prüft, ob die [Branch-Protection-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)
zur Korrektur der Einstellungen.

Die `fix`-Aktion ändert die Branch-Protection-Einstellungen so, dass sie der angegebenen Richtlinienkonfiguration entsprechen.

### Binary Artifacts

Die Konfigurationsdatei dieser Richtlinie heißt `binary_artifacts.yaml`, und die [Konfigurationsdefinitionen finden Sie
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 finden Sie
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 Repositories.

### Outside Collaborators

Die Konfigurationsdatei dieser Richtlinie heißt `outside.yaml`, und die [Konfigurationsdefinitionen finden Sie
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-Zugriff (optional) auf das
Repository haben. Nur Organisationsmitglieder sollten diesen Zugriff haben, da
andernfalls nicht vertrauenswürdige Mitglieder Einstellungen auf Admin-Ebene ändern und bösartigen Code committen können.

### SECURITY.md

Die Konfigurationsdatei dieser Richtlinie heißt `security.yaml`, und die [Konfigurationsdefinitionen finden Sie
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` hat und dass 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.

### Dangerous Workflow

Die Konfigurationsdatei dieser Richtlinie heißt `dangerous_workflow.yaml`, und die [Konfigurationsdefinitionen finden Sie
hier](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig).

Diese Richtlinie wird gegen **alle** Branches ausgeführt, siehe Begründung [hier](https://github.com/ossf/allstar/issues/569).

Diese Richtlinie prüft die Konfigurationsdateien der GitHub Actions Workflows
(`.github/workflows`) auf Muster, die bekanntem gefährlichem
Verhalten entsprechen. Siehe die [OpenSSF-Scorecard-Dokumentation](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow)
für weitere Informationen zu diesem Check.

### Generic Scorecard Check

Die Konfigurationsdatei dieser Richtlinie heißt `scorecard.yaml`, und die [Konfigurationsdefinitionen finden Sie
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 Checks müssen eine Punktzahl haben, die gleich oder über der `threshold`-Einstellung liegt. Bitte lesen Sie die
[OpenSSF-Scorecard-Dokumentation](https://github.com/ossf/scorecard/blob/main/docs/checks.md)
für weitere Informationen zu jedem Check.

#### SARIF-Upload

Die Scorecard-Richtlinie kann optional Ergebnisse als
[SARIF](https://sarifweb.azurewebsites.net/) in den Tab **Security > Code Scanning** jedes Repositories
hochladen. Dies gibt Organisationsadministratoren
Einblick in Scorecard-Ergebnisse neben anderen Sicherheitstools (CodeQL,
Dependabot usw.), ohne dass eine Einrichtung pro Repository-Workflow erforderlich ist.

Um den SARIF-Upload zu aktivieren, fügen Sie das Feld `upload` zu Ihrer `scorecard.yaml` hinzu:```yaml
optConfig:
  optOutStrategy: true
action: issue
checks:
  - Binary-Artifacts
  - Signed-Releases
threshold: 8
upload:
  sarif: true

Anforderungen:

• Die Allstar GitHub App muss die Repository-Berechtigung Code scanning alerts auf Read & write gesetzt haben (API-Bereich: security_events). Dies gehört nicht zu den Berechtigungen, die Allstar sonst benötigt, also fügen Sie es Ihrer App hinzu, bevor Sie den SARIF-Upload aktivieren.
• Der SARIF-Upload ist nicht blockierend: Wenn der Upload fehlschlägt (z. B. aufgrund fehlender Berechtigungen), wird die Richtlinienprüfung normal fortgesetzt.
• Die Änderungserkennung vergleicht den HEAD-Commit-SHA des Repositorys und überspringt den Scan und Upload, wenn seit dem letzten Upload keine Änderungen an das Repo gepusht wurden.

Der SARIF-Upload funktioniert mit beiden Arten, Allstar auszuführen: als Service-Daemon oder als GitHub Action.

GitHub Actions

Die Konfigurationsdatei dieser Richtlinie heißt actions.yaml, und die Konfigurationsdefinitionen finden Sie hier.

Diese Richtlinie prüft die GitHub-Actions-Workflow-Konfigurationsdateien (.github/workflows) (und in einigen Fällen Workflow-Ausführungen) in jedem Repository, um sicherzustellen, dass sie den Regeln (z. B. erfordern, verbieten) entsprechen, die in der organisationsweiten Konfiguration für die Richtlinie definiert sind.

Repository-Administratoren

Die Konfigurationsdatei dieser Richtlinie heißt admin.yaml, und die Konfigurationsdefinitionen finden Sie hier.

Diese Richtlinie prüft, dass standardmäßig alle Repositorys einen Benutzer oder eine Gruppe als Administrator zugewiesen haben müssen. Sie können optional konfigurieren, ob Benutzer Administratoren sein dürfen (im Gegensatz zu Teams).

Zukünftige Richtlinien

• Sicherstellen, dass dependabot aktiviert ist.
• Prüfen, dass Abhängigkeiten gepinnt/eingefroren sind.

Beispiel-Konfigurations-Repository

Siehe dieses Repo als Beispiel für die Verwendung der Allstar-Konfiguration. Als Organisationsadministrator sollten Sie eine README.md mit einigen Informationen darüber in Betracht ziehen, wie Allstar in Ihrer Organisation verwendet wird.

Erweitert

Konfigurationsdefinitionen

• Organisationsweite Aktivierungskonfiguration
• Repository-Override-Aktivierungskonfiguration

Sekundärer Speicherort für organisationsweite Konfiguration

Standardmäßig werden organisationsweite Konfigurationsdateien, wie die oben genannte allstar.yaml, in einem .allstar-Repository erwartet. Wenn dieses Repository nicht existiert, wird das allstar-Verzeichnis des .github-Repositorys als sekundärer Speicherort verwendet. Zur Verdeutlichung für allstar.yaml:

Dies gilt auch für die organisationsweiten Konfigurationsdateien der einzelnen Richtlinien, wie unten beschrieben.

Repo-Richtlinienkonfigurationen im Org-Repo

Allstar sucht auch nach Repository-Ebene-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.

Beispielsweise sucht Allstar die Richtlinienkonfiguration für ein bestimmtes Repository myapp in der folgenden Reihenfolge:

Speicherort für organisationsweite Basis- und Merge-Konfiguration

Für organisationsweite Allstar- und Richtlinienkonfigurationsdateien können Sie das Feld baseConfig angeben, um ein anderes Repository zu spezifizieren, das die Basis-Allstar-Konfiguration enthält. Dies lässt sich am besten anhand eines Beispiels erklären.

Angenommen, Sie haben mehrere GitHub-Organisationen, möchten aber eine einzige Allstar-Konfiguration pflegen. 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.

You also have a satellite GitHub organization named "acme-sat". You want to
re-use the main config, but apply some changes on top by disabling Allstar on
certain repositories. The repository `acme-sat/.allstar` contains
`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, mit der dies angewendet wird, wird als JSON Merge Patch beschrieben. Die baseConfig muss ein GitHub <org>/<repository> sein.

Mitwirken

Siehe CONTRIBUTING.md