Allstar

[!IMPORTANT] L'app GitHub Allstar ospitata da OpenSSF è stata ritirata. Allstar, il sottoprogetto OpenSSF Scorecard, continua comunque a essere mantenuto — ora devi eseguirlo tu stesso, sia come GitHub Action sia come demone di servizio.

Vedi ossf/allstar#881 per maggiori dettagli.

Se la tua organizzazione faceva affidamento sull'app ospitata, vedi Migrazione dall'app ospitata.

Panoramica

• Cos'è Allstar?

Novità di Allstar

• whats-new.md

Disattivazione di problemi indesiderati

• Aiuto! Allstar crea problemi che non voglio!

Per iniziare

• Contesto
• Opzioni a livello di organizzazione
• Opzioni di installazione
  • Crea la tua GitHub App
  • Crea il tuo repository di controllo .allstar
  • Eseguire Allstar come GitHub Action
  • Eseguire Allstar come demone di servizio
• Migrazione dall'app ospitata

Policy e azioni

• Azioni
• Policy

Avanzato

• Definizioni di configurazione
• Configurazioni di esempio
• Esegui la tua istanza di Allstar

Contribuisci

• Contribuire

Panoramica

Cos'è Allstar?

Allstar è una GitHub App che monitora continuamente organizzazioni o repository GitHub per verificare l'aderenza alle best practice di sicurezza. Se Allstar rileva una violazione di una policy di sicurezza, crea un problema per avvisare il proprietario del repository o dell'organizzazione. Per alcune policy di sicurezza, Allstar può anche modificare automaticamente l'impostazione del progetto che ha causato la violazione, ripristinandola allo stato previsto.

L'obiettivo di Allstar è darti un controllo finemente calibrato sui file e sulle impostazioni che influiscono sulla sicurezza dei tuoi progetti. Puoi scegliere quali policy di sicurezza monitorare sia a livello di organizzazione sia a livello di repository, e come gestire le violazioni delle policy. Puoi anche sviluppare o contribuire con nuove policy.

Allstar è sviluppato come parte del progetto OpenSSF Scorecard.

Novità di Allstar

Disattivazione di problemi indesiderati

Se Allstar crea problemi indesiderati, segui queste istruzioni per disattivarlo.

Per iniziare

Contesto

Allstar è altamente configurabile. Ci sono tre livelli principali di controlli:

• Livello organizzazione: Gli amministratori dell'organizzazione possono scegliere di abilitare Allstar su:
  • tutti i repository dell'organizzazione;
  • la maggior parte dei repository, tranne alcuni che hanno scelto di escludersi;
  • solo alcuni repository che hanno scelto di includersi.

Queste configurazioni vengono effettuate nel repository .allstar dell'organizzazione.

• Livello repository: I manutentori dei repository in un'organizzazione che usa Allstar possono scegliere di includere o escludere il proprio repository dalle applicazioni a livello di organizzazione. Nota: questi controlli a livello di repository funzionano solo quando "repo override" è consentito nelle impostazioni a livello di organizzazione. Queste configurazioni vengono effettuate nella directory .allstar del repository.

• Livello policy: Gli amministratori o i manutentori possono scegliere quali policy sono abilitate su repository specifici e quali azioni Allstar intraprende quando una policy viene violata. Queste configurazioni vengono effettuate in un file yaml di policy nel repository .allstar dell'organizzazione (amministratori) o nella directory .allstar del repository (manutentori).

Opzioni a livello di organizzazione

Prima di installare Allstar a livello di organizzazione, dovresti decidere approssimativamente su quanti repository vuoi che Allstar operi. Questo ti aiuterà a scegliere tra le strategie Opt-In e Opt-Out.

• La strategia Opt In ti consente di aggiungere manualmente i repository su cui vuoi che Allstar operi. Se non specifichi alcun repository, Allstar non verrà eseguito nonostante sia installato. Scegli la strategia Opt In se vuoi applicare policy solo su un numero limitato dei tuoi repository totali, o se vuoi provare Allstar su un singolo repository prima di abilitarlo su altri. Dalla release v4.3, sono supportati i glob per aggiungere facilmente più repository con un nome simile.

• La strategia Opt Out (consigliata) abilita Allstar su tutti i repository e ti consente di selezionare manualmente i repository da escludere dalle applicazioni di Allstar. Puoi anche scegliere di escludere tutti i repository pubblici, o tutti i repository privati. Scegli questa opzione se vuoi eseguire Allstar su tutti i repository di un'organizzazione, o se vuoi escludere solo un numero limitato di repository o un tipo specifico (ad es., pubblico vs. privato) di repository. Dalla release v4.3, sono supportati i glob per aggiungere facilmente più repository con un nome simile.

Opzioni di installazione

Allstar agisce sulla tua organizzazione come una GitHub App: crei l'app e esegui il processo che si autentica come essa. La configurazione è quindi composta da due passaggi comuni a ogni distribuzione — crea l'app e crea il repository di controllo — e poi una scelta su come eseguirla:

L'Action è l'opzione con il minor overhead delle due ed è da lì che la maggior parte delle organizzazioni dovrebbe iniziare; puoi passare a un demone in seguito senza modificare alcuna configurazione di policy.

Crea la tua GitHub App

Un'App è un'identità simile a un utente con un insieme di permessi nella tua organizzazione. Allstar necessita di accesso in lettura alla maggior parte delle impostazioni e dei contenuti dei file per rilevare la conformità, e accesso in scrittura a problemi e check per aprire problemi e supportare l'azione block.

Segui Istruzioni per l'operatore - Crea una GitHub App e registra l'ID App e la chiave privata. Entrambe le modalità di esecuzione ne hanno bisogno.

Crea il tuo repository di controllo .allstar

Allstar legge la sua configurazione da un repository chiamato .allstar nella tua organizzazione.

Il modo più rapido per crearne uno è partire dal modello:

1. Apri il repository di esempio e clicca sul pulsante "Use this template"
2. Nel campo per il Nome Repository, digita .allstar
3. Clicca su "Create repository from template"

Questo abilita tutte le attuali policy di Allstar su tutti i repository usando la strategia Opt Out, con l'azione issue. Puoi modificare tutto in seguito.

Per un controllo granulare fin dall'inizio — scegliendo la strategia Opt In o Opt Out e scrivendo tu stesso i singoli file di policy — segui invece le istruzioni di installazione manuale.

Eseguire Allstar come GitHub Action

Questa opzione esegue Allstar come job pianificato usando GitHub Actions, quindi non c'è infrastruttura da gestire oltre a GitHub stesso.

Segui le istruzioni di installazione per GitHub Actions per configurare un'Action ricorrente nel tuo repository .allstar, rafforzarla e monitorarne i risultati.

Eseguire Allstar come demone di servizio

Questa opzione esegue Allstar come processo persistente, che rileva e risolve le violazioni in modo continuo anziché secondo una pianificazione.

Vedi Istruzioni per l'operatore per eseguire il processo, gestire i segreti, il dimensionamento e le variabili d'ambiente disponibili.

Migrazione dall'app ospitata

Se la tua organizzazione usava l'app ospitata da OpenSSF, la tua configurazione viene trasferita così com'è. Il repository di controllo .allstar, allstar.yaml e ogni file di policy continuano a funzionare invariati; ciò che sostituisci è solo il processo che li legge.

Per migrare:

1. Crea la tua GitHub App e installala sulla tua organizzazione con lo stesso accesso ai repository che aveva l'app ospitata.
2. Mantieni il tuo repository .allstar esistente esattamente com'è.
3. Esegui Allstar come Action o come demone.
4. Disinstalla allstar-app dalla tua organizzazione, se appare ancora sotto Impostazioni -> GitHub Apps.

I problemi precedentemente aperti dall'app ospitata rimangono nei tuoi repository. La tua istanza identifica i suoi problemi tramite la stessa etichetta allstar (o la tua issueLabel configurata), quindi li adotterà e li chiuderà man mano che le violazioni vengono risolte, anziché aprire duplicati.

Policy e azioni

Azioni

Ogni policy può essere configurata con un'azione che Allstar intraprenderà quando rileva che un repository non è conforme.

• log: Questa è l'azione predefinita e in realtà avviene per tutte le azioni. Tutti i risultati e i dettagli delle esecuzioni delle policy vengono registrati. I log sono attualmente visibili solo all'operatore dell'app; i piani per esporli sono in discussione.
• issue: Questa azione crea un problema GitHub. Viene creato un solo problema per policy e il testo descrive i dettagli della violazione della policy. Se il problema è già aperto, viene "pingato" con un commento ogni 24 ore senza aggiornamenti (attualmente non configurabile dall'utente). Se il risultato della policy cambia, un nuovo commento verrà lasciato sul problema e collegato nel corpo del problema. Una volta che la violazione viene affrontata, il problema verrà chiuso automaticamente da Allstar entro 5-10 minuti.
• fix: Questa azione è specifica della policy. La policy apporterà le modifiche alle impostazioni GitHub per correggere la violazione della policy. Non tutte le policy saranno in grado di supportarla (vedi sotto).

Azioni proposte ma non ancora implementate. Le definizioni verranno aggiunte in futuro.

• block: Allstar può impostare un GitHub Status Check e bloccare qualsiasi PR nel repository dall'essere unito se il check fallisce.
• email: Allstar invierebbe un'email agli amministratori del repository.
• rpc: Allstar invierebbe un rpc a qualche sistema specifico dell'organizzazione.

Configurazione dell'azione

Due impostazioni sono disponibili per configurare l'azione issue:

• issueLabel è disponibile a livello di organizzazione e di repository. Impostarla sovrascriverà l'etichetta allstar predefinita usata da Allstar per identificare i suoi problemi.

• issueRepo è disponibile a livello di organizzazione. Impostarla forzerà la creazione di tutti i problemi creati nell'organizzazione nel repository specificato.

Policy

Analogamente alla configurazione di abilitazione dell'app Allstar, tutte le policy sono abilitate e configurate con un file yaml nel repository .allstar dell'organizzazione o nella directory .allstar del repository. Come per l'app, le policy sono opt-in per impostazione predefinita; inoltre, l'azione log predefinita non produrrà risultati visibili. Un modo semplice per abilitare tutte le policy è creare un file yaml per ogni policy con il contenuto:```yaml optConfig: optOutStrategy: true action: issue

I dettagli di come funziona l'azione `fix` per ogni policy sono descritti di seguito. Se omesso di seguito, l'azione `fix` non è applicabile.

### Protezione dei rami

Il file di configurazione di questa policy si chiama `branch_protection.yaml`, e le [definizioni di configurazione sono qui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig).

La policy di protezione dei rami verifica che le [impostazioni di protezione dei rami](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) di GitHub siano configurate correttamente secondo la configurazione specificata. Il testo del problema descriverà quale impostazione non è corretta. Consulta la [documentazione di GitHub](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) per correggere le impostazioni.

L'azione `fix` modificherà le impostazioni di protezione dei rami per renderle conformi alla configurazione della policy specificata.

### Artefatti binari

Il file di configurazione di questa policy si chiama `binary_artifacts.yaml`, e le [definizioni di configurazione sono qui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig).

Questa policy incorpora il [controllo di scorecard](https://github.com/ossf/scorecard/#scorecard-checks). Rimuovi l'artefatto binario dal repository per raggiungere la conformità. Poiché i risultati di scorecard possono essere prolissi, potresti dover eseguire [scorecard stesso](https://github.com/ossf/scorecard) per vedere tutte le informazioni dettagliate.

### CODEOWNERS

Il file di configurazione di questa policy si chiama `codeowners.yaml`, e le [definizioni di configurazione sono qui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig).

Questa policy verifica la presenza di un [file `CODEOWNERS`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) nei tuoi repository.

### Collaboratori esterni

Il file di configurazione di questa policy si chiama `outside.yaml`, e le [definizioni di configurazione sono qui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/outside#OrgConfig).

Questa policy verifica se eventuali [Collaboratori esterni](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization) hanno accesso amministratore (predefinito) o push (opzionale) al repository. Solo i membri dell'organizzazione dovrebbero avere questo accesso, altrimenti membri non fidati possono modificare le impostazioni a livello di amministratore e committare codice dannoso.

### SECURITY.md

Il file di configurazione di questa policy si chiama `security.yaml`, e le [definizioni di configurazione sono qui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/security#OrgConfig).

Questa policy verifica che il repository abbia un file di policy di sicurezza in `SECURITY.md` e che non sia vuoto. Il problema creato avrà un collegamento alla [scheda di GitHub](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository) che ti aiuta a committare una policy di sicurezza nel tuo repository.

### Workflow pericoloso

Il file di configurazione di questa policy si chiama `dangerous_workflow.yaml`, e le [definizioni di configurazione sono qui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig).

Questa policy verrà eseguita su **tutti** i rami, vedi la motivazione [qui](https://github.com/ossf/allstar/issues/569).

Questa policy controlla i file di configurazione dei workflow di GitHub Actions (`.github/workflows`), per qualsiasi pattern che corrisponda a comportamenti pericolosi noti. Consulta la [documentazione di OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow) per maggiori informazioni su questo controllo.

### Controllo Scorecard generico

Il file di configurazione di questa policy si chiama `scorecard.yaml`, e le [definizioni di configurazione sono qui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig).

Questa policy esegue qualsiasi controllo scorecard elencato nella configurazione `checks`. Tutti i controlli eseguiti devono avere un punteggio uguale o superiore all'impostazione `threshold`. Consulta la [documentazione di OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md) per maggiori informazioni su ciascun controllo.

#### Upload SARIF

La policy Scorecard può opzionalmente caricare i risultati come [SARIF](https://sarifweb.azurewebsites.net/) nella scheda **Security > Code Scanning** di ciascun repository. Questo offre agli amministratori dell'organizzazione visibilità sui risultati di Scorecard insieme ad altri strumenti di sicurezza (CodeQL, Dependabot, ecc.) senza richiedere la configurazione di workflow per singolo repository.

Per abilitare l'upload SARIF, aggiungi il campo `upload` al tuo `scorecard.yaml`:```yaml
optConfig:
  optOutStrategy: true
action: issue
checks:
  - Binary-Artifacts
  - Signed-Releases
threshold: 8
upload:
  sarif: true

Requisiti:

• L'app GitHub Allstar deve avere il permesso Code scanning alerts del repository impostato su Read & write (ambito API: security_events). Questo non è tra i permessi che Allstar richiede altrimenti, quindi aggiungilo alla tua app prima di abilitare il caricamento SARIF.
• Il caricamento SARIF non è bloccante: se il caricamento fallisce (ad es., a causa di permessi mancanti), il controllo della policy continua normalmente.
• Il rilevamento delle modifiche confronta l'hash SHA del commit HEAD del repository e salta la scansione e il caricamento quando il repo non è stato aggiornato dall'ultimo caricamento.

Il caricamento SARIF funziona con entrambi i modi di eseguire Allstar: come daemon di servizio o come GitHub Action.

GitHub Actions

Il file di configurazione di questa policy si chiama actions.yaml, e le definizioni di configurazione sono qui.

Questa policy controlla i file di configurazione dei workflow GitHub Actions (.github/workflows) (e le esecuzioni dei workflow in alcuni casi) in ogni repo per garantire che siano in linea con le regole (ad es. richiedi, nega) definite nella configurazione a livello di organizzazione per la policy.

Repository Administrators

Il file di configurazione di questa policy si chiama admin.yaml, e le definizioni di configurazione sono qui.

Questa policy verifica che, per impostazione predefinita, tutti i repository debbano avere un utente o un gruppo assegnato come Amministratore. Ti consente di configurare opzionalmente se gli utenti possono essere amministratori (invece dei team).

Future Policies

• Garantire che dependabot sia abilitato.
• Verificare che le dipendenze siano bloccate/congelate.

Esempio di Repository di Configurazione

Vedi questo repo come esempio di configurazione Allstar in uso. Come amministratore dell'organizzazione, considera un README.md con alcune informazioni su come Allstar viene utilizzato nella tua organizzazione.

Avanzato

Definizioni di Configurazione

• Configurazione di abilitazione a livello di organizzazione
• Configurazione di abilitazione per override del repository

Posizione secondaria della configurazione a livello di organizzazione

Per impostazione predefinita, i file di configurazione a livello di organizzazione, come il file allstar.yaml sopra, sono previsti in un repository .allstar. Se questo repository non esiste, viene utilizzata la directory allstar del repository .github come posizione secondaria. Per chiarire, per allstar.yaml:

Questo vale anche per i file di configurazione a livello di organizzazione delle singole policy, come descritto di seguito.

Configurazioni delle policy del repo nel repo dell'organizzazione

Allstar cercherà anche le configurazioni delle policy a livello di repository nel repository .allstar dell'organizzazione, nella directory con lo stesso nome del repository. Questa configurazione viene utilizzata indipendentemente dal fatto che "repo override" sia disabilitato.

Ad esempio, Allstar cercherà la configurazione della policy per un dato repo myapp nel seguente ordine:

Posizione della configurazione Base e Merge a livello di organizzazione

Per i file di configurazione Allstar e delle policy a livello di organizzazione, puoi specificare il campo baseConfig per indicare un altro repository che contiene la configurazione Allstar di base. Questo si spiega meglio con un esempio.

Supponiamo che tu abbia più organizzazioni GitHub, ma voglia mantenere una singola configurazione Allstar. La tua organizzazione principale è "acme", e il repository acme/.allstar contiene 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

Questo utilizzerà tutta la configurazione da acme/.allstar come configurazione di base, ma poi applicherà le eventuali modifiche presenti nel file corrente sopra la configurazione di base. Il metodo con cui viene applicato è descritto come una JSON Merge Patch. Il baseConfig deve essere un <org>/<repository> di GitHub.

Contribuire

Vedi CONTRIBUTING.md