ossf/allstarGitHub App per impostare e applicare policy di sicurezza
Allstar è un'app GitHub che monitora continuamente organizzazioni o repository GitHub per l'aderenza alle migliori pratiche di sicurezza. Se Allstar rileva una violazione di una politica di sicurezza, crea un problema per avvisare il proprietario del repository o dell'organizzazione. Per alcune politiche di sicurezza, Allstar può anche cambiare automaticamente l'impostazione del progetto che ha causato la violazione, riportandola allo stato previsto.
L'obiettivo di Allstar è fornire un controllo finemente sintonizzato su file e impostazioni che influenzano la sicurezza dei tuoi progetti. Puoi scegliere quali politiche di sicurezza monitorare sia a livello di organizzazione che di repository, e come gestire le violazioni delle politiche. Puoi anche sviluppare o contribuire con nuove politiche.
Allstar è sviluppato come parte del progetto OpenSSF Scorecard.
Se Allstar sta creando problemi indesiderati, segui queste istruzioni per rinunciare.
Allstar è altamente configurabile. Ci sono tre livelli principali di controlli:
Queste configurazioni vengono effettuate nel repository .allstar dell'organizzazione.
Livello repository: I manutentori di repository in un'organizzazione che utilizza Allstar possono scegliere di aderire o rinunciare alle applicazioni a livello di organizzazione. Nota: questi controlli a livello di repository sono funzionali solo quando è consentita la "sostituzione del repository" nelle impostazioni a livello di organizzazione. Queste configurazioni vengono effettuate nella directory .allstar del repository.
Livello di politica: Amministratori o manutentori possono scegliere quali politiche sono abilitate su specifici repo e quali azioni Allstar intraprende quando una politica viene violata. Queste configurazioni vengono effettuate in un file yaml di politica nel repository .allstar dell'organizzazione (amministratori) o nella directory .allstar del repository (manutentori).
Prima di installare Allstar a livello di organizzazione, dovresti decidere approssimativamente su quanti repository vuoi che Allstar venga eseguito. 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 desideri che Allstar venga eseguito. Se non specifichi alcun repository, Allstar non verrà eseguito nonostante sia installato. Scegli la strategia Opt In se vuoi applicare politiche solo su un piccolo numero dei tuoi repository totali, o se vuoi provare Allstar su un singolo repository prima di abilitarlo su più repository. Dalla versione 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 repo pubblici o tutti i repo privati. Scegli questa opzione se vuoi eseguire Allstar su tutti i repository di un'organizzazione, o se vuoi escludere solo un piccolo numero di repository o un tipo specifico (ad es., pubblico vs. privato) di repository. Dalla versione v4.3, sono supportati i glob per aggiungere facilmente più repository con un nome simile.
Entrambe le opzioni Installazione rapida e Installazione manuale prevedono l'installazione dell'app Allstar nella tua organizzazione GitHub. L'app Allstar è gestita da OpenSSF ed è una buona scelta per la maggior parte dei repository open source. È possibile rivedere le autorizzazioni richieste. L'app richiede accesso in lettura alla maggior parte delle impostazioni e dei contenuti dei file per rilevare la conformità della sicurezza. Richiede accesso in scrittura a problemi e controlli in modo da poter creare problemi e consentire l'azione block.
Se non si desidera utilizzare l'app Allstar gestita da OpenSSF è possibile auto-ospitare Allstar, creando la propria app Allstar. Questo fornisce il controllo diretto dell'app con il compromesso di dover configurare, proteggere, monitorare e mantenere l'app.
L'installazione rapida o manuale sono consigliate a meno che non si abbiano vincoli specifici di sicurezza o conformità che impediscono di utilizzare l'app Allstar gestita da OpenSSF.
Questa opzione di installazione abiliterà Allstar utilizzando la strategia Opt Out su tutti i repository della tua organizzazione. Tutte le politiche attuali saranno abilitate e Allstar ti avviserà delle violazioni delle politiche aprendo un problema. Questo è il modo più rapido e semplice per iniziare a utilizzare Allstar e puoi comunque modificare qualsiasi configurazione in seguito.
Impegno: molto facile
Passaggi:
.allstarEcco fatto! Tutte le attuali politiche di Allstar sono ora abilitate su tutti i tuoi repository. Allstar creerà un problema se una politica viene violata.
Per modificare qualsiasi configurazione, consulta le istruzioni per l'installazione manuale.
Questa opzione di installazione ti guiderà nella creazione di file di configurazione secondo la strategia Opt In o Opt Out. Questa opzione fornisce un controllo più granulare sulle configurazioni fin dall'inizio.
Impegno: moderato
Passaggi:
Auto-ospita solo se necessario! L'app Allstar richiede configurazione, protezione e manutenzione continua. Quando viene rilasciata una nuova versione di Allstar, dovrai aggiornare la tua soluzione auto-ospitata.
Vengono descritti due approcci di auto-hosting:
Questa opzione di installazione esegue Allstar come job programmato utilizzando GitHub Actions.
Impegno: alto
Segui le istruzioni per l'installazione di GitHub Actions per:
.allstar a livello di organizzazione come descritto in installazione rapida o installazione manuale. (Ignora i passaggi per installare l'app Allstar gestita da OpenSSF nella tua organizzazione.).allstar per eseguire Allstar in modalità batch.Questa opzione di installazione esegue Allstar come processo persistente.
Impegno: molto alto
Consulta le istruzioni per l'operatore per ulteriori informazioni, inclusa la creazione di un'app Allstar, la gestione dei segreti e le variabili d'ambiente disponibili.
Ogni politica 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 dell'esecuzione delle politiche vengono registrati. I log sono attualmente visibili solo all'operatore dell'app, i piani per renderli accessibili sono in discussione.issue: Questa azione crea un problema su GitHub. Viene creato un solo problema per politica e il testo descrive i dettagli della violazione della politica. Se il problema è già aperto, viene sollecitato con un commento ogni 24 ore senza aggiornamenti (attualmente non configurabile dall'utente). Se il risultato della politica cambia, viene lasciato un nuovo commento sul problema e collegato nel corpo del problema. Una volta risolta la violazione, il problema verrà chiuso automaticamente da Allstar entro 5-10 minuti.fix: Questa azione è specifica per la politica. La politica apporterà le modifiche alle impostazioni di GitHub per correggere la violazione della politica. Non tutte le politiche possono supportarlo (vedi sotto).Azioni proposte, ma non ancora implementate. Le definizioni saranno aggiunte in futuro.
block: Allstar può impostare un controllo dello stato di GitHub e bloccare qualsiasi PR nel repository dall'essere unito se il controllo fallisce.email: Allstar invierebbe un'email agli amministratori del repository.rpc: Allstar invierebbe una rpc a un sistema specifico dell'organizzazione.Due impostazioni sono disponibili per configurare l'azione issue:
issueLabel è disponibile a livello di organizzazione e repository. Impostandola si sovrascriverà l'etichetta predefinita allstar utilizzata da Allstar per identificare i suoi problemi.
issueRepo è disponibile a livello di organizzazione. Impostandola forzerà la creazione di tutti i problemi creati nell'organizzazione nel repository specificato.
Analogamente alla configurazione di abilitazione dell'app Allstar, tutte le politiche sono abilitate e configurate con un file yaml nel repository .allstar dell'organizzazione o nella directory .allstar del repository. Come per l'app, le politiche sono opt-in per impostazione predefinita, anche l'azione predefinita log non produce risultati visibili. Un modo semplice per abilitare tutte le politiche è creare un file yaml per ogni politica 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 del ramo
Il file di configurazione di questa policy è denominato `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 del ramo verifica che le [impostazioni di protezione del ramo](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 dell'issue descriverà quale impostazione è errata. 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 del ramo per renderle conformi alla configurazione policy specificata.
### Manufatti binari
Il file di configurazione di questa policy è denominato `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 il manufatto binario dal repository per raggiungere la conformità. Poiché i risultati di scorecard possono essere verbosi, potrebbe essere necessario eseguire [scorecard stesso](https://github.com/ossf/scorecard) per visualizzare tutte le informazioni dettagliate.
### CODEOWNERS
Il file di configurazione di questa policy è denominato `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 è denominato `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 qualche [Collaboratore esterno](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization) ha accesso come amministratore (predefinito) o push (opzionale) al repository. Solo i membri dell'organizzazione dovrebbero avere questo accesso, altrimenti utenti non fidati possono modificare le impostazioni a livello di amministratore e committare codice malevolo.
### SECURITY.md
Il file di configurazione di questa policy è denominato `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. L'issue 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 è denominato `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 logica [qui](https://github.com/ossf/allstar/issues/569).
Questa policy controlla i file di configurazione del workflow di GitHub Actions (`.github/workflows`) per rilevare pattern che corrispondono 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.
### Verifica Scorecard generica
Il file di configurazione di questa policy è denominato `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 di 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.
#### Caricamento SARIF
La policy di 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 del workflow per repository.
Per abilitare il caricamento 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:
security_events). Gli operatori self-hosted devono aggiungere questo permesso alla loro App GitHub. L'App pubblica Allstar gestita da OpenSSF non include ancora questo permesso.Il caricamento SARIF funziona con entrambe le modalità di distribuzione self-hosted: in esecuzione come demone di servizio o come GitHub Action.
Il file di configurazione di questa policy è actions.yaml e le definizioni di configurazione sono qui.
Questa policy controlla i file di configurazione dei workflow di GitHub Actions (.github/workflows) (e in alcuni casi le esecuzioni dei workflow) in ogni repository per assicurarsi che siano conformi alle regole (ad esempio, require, deny) definite nella configurazione a livello di organizzazione per la policy.
Il file di configurazione di questa policy è admin.yaml e le definizioni di configurazione sono qui.
Questa policy controlla che per impostazione predefinita tutti i repository debbano avere un utente o un gruppo assegnato come Amministratore. Consente di configurare facoltativamente se agli utenti è consentito essere amministratori (in contrapposizione ai team).
Vedi questo repository come esempio di configurazione di Allstar in uso. Come amministratore dell'organizzazione, considera un README.md con alcune informazioni su come Allstar viene utilizzato nella tua 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 come posizione secondaria la directory allstar del repository .github. Per chiarire, per allstar.yaml:
| Precedenza | Repository | Percorso |
|---|---|---|
| Primaria | .allstar | allstar.yaml |
| Secondaria | .github | allstar/allstar.yaml |
Questo vale anche per i file di configurazione a livello di organizzazione per le singole policy, come descritto di seguito.
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 repository myapp nel seguente ordine:
Per i file di configurazione di Allstar e delle policy a livello di organizzazione, è possibile specificare il campo baseConfig per indicare un altro repository che contiene la configurazione di base di Allstar. Questo è meglio spiegato con un esempio.
Supponiamo di avere più organizzazioni GitHub, ma di voler mantenere una singola configurazione di 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.
Hai anche un'organizzazione GitHub satellite denominata "acme-sat". Vuoi
riutilizzare la configurazione principale, ma applicare alcune modifiche sopra disabilitando Allstar su
alcuni repository. Il repository `acme-sat/.allstar` contiene
`allstar.yaml`:```yaml
baseConfig: acme/.allstar
optConfig:
optOutRepos:
- acmesat-one
- acmesat-two
Questo utilizzerà tutta la configurazione da acme/.allstar come configurazione base, ma poi applicherà eventuali modifiche nel file corrente sopra la configurazione base. Il metodo con cui viene applicato è descritto come JSON Merge Patch. Il baseConfig deve essere un repository GitHub <org>/<repository>.
Vedi CONTRIBUTING.md
| Opt Out (Consigliato) optOutStrategy = true | Opt In optOutStrategy = false |
|---|
| Comportamento predefinito | Tutti i repo sono abilitati | Nessun repo è abilitato |
| Aggiunta manuale di repository | L'aggiunta manuale di repo disabilita Allstar su quei repo | L'aggiunta manuale di repo abilita Allstar su quei repo |
| Configurazioni aggiuntive | optOutRepos: Allstar verrà disabilitato sui repo elencati optOutPrivateRepos: se true, Allstar verrà disabilitato su tutti i repo privati optOutPublicRepos: se true, Allstar verrà disabilitato su tutti i repo pubblici (optInRepos: questa impostazione verrà ignorata) | optInRepos: Allstar verrà abilitato sui repo elencati (optOutRepos: questa impostazione verrà ignorata) |
| Override del repository | Se true: i repo possono rinunciare alle applicazioni di Allstar della propria organizzazione utilizzando le impostazioni nel proprio file repo. Le impostazioni di opt-in a livello di organizzazione che si applicano a quel repository vengono ignorate. Se false: i repo non possono rinunciare alle applicazioni di Allstar come configurate a livello di organizzazione. | Se true: i repo possono aderire alle applicazioni di Allstar della propria organizzazione anche se non sono configurati per il repo a livello di organizzazione. Le impostazioni di opt-out a livello di organizzazione che si applicano a quel repository vengono ignorate. Se false: i repo non possono aderire alle applicazioni di Allstar se non sono configurati a livello di organizzazione. |
| Repository | Percorso | Condizione |
|---|
myapp | .allstar/branch_protection.yaml | Quando "repo override" è consentito. |
.allstar | myapp/branch_protection.yaml | Sempre. |
.allstar | branch_protection.yaml | Sempre. |
.github | allstar/myapp/branch_protection.yaml | Se il repository .allstar non esiste. |
.github | allstar/branch_protection.yaml | Se il repository .allstar non esiste. |