Informazioni di base su Github

Reading time: 17 minutes

Struttura di base

La struttura base dell'ambiente github in una grande company consiste nell'avere una enterprise che possiede diverse organizations e ognuna di esse può contenere diversi repositories e diversi teams.. Aziende più piccole possono semplicemente possedere una sola organization e nessuna enterprise.

Dal punto di vista di un utente un user può essere member di diverse enterprises e organizations. All'interno di queste il user può avere diversi ruoli a livello enterprise, organization e repository.

Inoltre, un user può essere parte di diversi teams con diversi ruoli a livello enterprise, organization o repository.

Infine i repositories possono avere meccanismi di protezione speciali.

Privilegi

Enterprise Roles

• Enterprise owner: Le persone con questo ruolo possono gestire gli amministratori, gestire le organizations all'interno dell'enterprise, gestire le impostazioni dell'enterprise, imporre policy attraverso le organizations. Tuttavia, non possono accedere alle impostazioni o ai contenuti di un'organization a meno che non vengano nominati organization owner o non venga loro concesso accesso diretto a un repository di proprietà dell'organization.
• Enterprise members: I membri delle organizations possedute dalla tua enterprise sono automaticamente membri dell'enterprise.

Organization Roles

In un'organisation gli utenti possono avere ruoli differenti:

• Organization owners: Gli organization owners hanno accesso amministrativo completo all'organization. Questo ruolo dovrebbe essere limitato, ma non inferiore a due persone nell'organisation.
• Organization members: Il ruolo predefinito, non amministrativo, per le persone in un'organization è organization member. Per default, gli organization members hanno una serie di permessi.
• Billing managers: I billing managers sono utenti che possono gestire le impostazioni di fatturazione per la tua organization, come le informazioni di pagamento.
• Security Managers: È un ruolo che gli organization owners possono assegnare a qualsiasi team all'interno di un'organization. Quando applicato, dà a ogni membro del team i permessi per gestire security alerts e impostazioni in tutta l'organization, così come permessi di lettura per tutti i repositories nell'organization.
• Se la tua organization ha un security team, puoi usare il ruolo di security manager per dare ai membri del team il minimo accesso necessario all'organization.
• Github App managers: Per permettere ad altri utenti di gestire GitHub Apps possedute da un'organization, un owner può concedere loro i permessi di GitHub App manager.
• Outside collaborators: Un outside collaborator è una persona che ha accesso a uno o più repositories dell'organization ma non è esplicitamente membro dell'organization.

Puoi confrontare i permessi di questi ruoli in questa tabella: https://docs.github.com/en/organizations/managing-peoples-access-to-your-organization-with-roles/roles-in-an-organization#permissions-for-organization-roles

Members Privileges

In https://github.com/organizations/<org_name>/settings/member_privileges puoi vedere i permessi che gli utenti avranno solo per il fatto di far parte dell'organisation.

Le impostazioni qui configurate indicheranno i seguenti permessi dei membri dell'organization:

• Essere admin, writer, reader o non avere permessi su tutti i repositories dell'organization.
• Se i members possono creare repository private, internal o public.
• Se è possibile fare fork dei repositories.
• Se è possibile invitare outside collaborators.
• Se è possibile pubblicare siti public o private.
• I permessi che gli admins hanno sui repositories.
• Se i members possono creare nuovi teams.

Repository Roles

Per default sono creati i seguenti repository roles:

• Read: Raccomandato per non-code contributors che vogliono vedere o discutere il progetto.
• Triage: Raccomandato per contributor che devono gestire proattivamente issues e pull requests senza accesso in scrittura.
• Write: Raccomandato per contributor che attivamente pushano al progetto.
• Maintain: Raccomandato per project managers che devono gestire il repository senza accesso ad azioni sensibili o distruttive.
• Admin: Raccomandato per persone che necessitano di accesso completo al progetto, incluse azioni sensibili e distruttive come gestire security o eliminare un repository.

Puoi confrontare i permessi di ogni ruolo in questa tabella https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization#permissions-for-each-role

Puoi anche creare ruoli personalizzati in https://github.com/organizations/<org_name>/settings/roles

Teams

Puoi elencare i teams creati in un'organization in https://github.com/orgs/<org_name>/teams. Nota che per vedere i teams che sono figli di altri teams è necessario accedere a ciascun parent team.

Users

Gli utenti di un'organization possono essere elencati in https://github.com/orgs/<org_name>/people.

Nelle informazioni di ciascun user puoi vedere i teams di cui il user è membro, e i repos a cui il user ha accesso.

Github Authentication

Github offre diversi metodi per autenticarsi al tuo account ed eseguire azioni per tuo conto.

Web Access

Accedendo a github.com puoi login usando il tuo username e password (e una 2FA potenzialmente).

SSH Keys

Puoi configurare il tuo account con una o più public keys permettendo alla relativa private key di eseguire azioni per tuo conto. https://github.com/settings/keys

GPG Keys

Non puoi impersonare l'utente con queste keys ma se non le usi potrebbe essere possibile che tu venga scoperto per aver inviato commit senza una signature. Scopri di più su vigilant mode here.

Personal Access Tokens

Puoi generare personal access token per dare a un'applicazione accesso al tuo account. Quando crei un personal access token l'user deve specificare i permessi che il token avrà. https://github.com/settings/tokens

Oauth Applications

Oauth applications possono chiedere permessi per accedere a parte delle tue informazioni su github o per impersonarti per eseguire alcune azioni. Un esempio comune di questa funzionalità è il bottone login with github che potresti trovare in alcune piattaforme.

• Puoi creare le tue Oauth applications in https://github.com/settings/developers
• Puoi vedere tutte le Oauth applications che hanno accesso al tuo account in https://github.com/settings/applications
• Puoi vedere gli scopes che Oauth Apps possono richiedere in https://docs.github.com/en/developers/apps/building-oauth-apps/scopes-for-oauth-apps
• Puoi vedere l'accesso di terze parti delle applications in un'organization in https://github.com/organizations/<org_name>/settings/oauth_application_policy

Alcune raccomandazioni di sicurezza:

• Un OAuth App dovrebbe sempre agire come l'utente GitHub autenticato su tutto GitHub (per esempio, quando fornisce notifiche all'utente) e con accesso solo agli scopes specificati.
• Un OAuth App può essere usato come identity provider abilitando un "Login with GitHub" per l'utente autenticato.
• Non costruire un OAuth App se vuoi che la tua applicazione agisca su un singolo repository. Con lo scope repo, le OAuth Apps possono agire su tutti i repositories dell'utente autenticato.
• Non costruire un OAuth App per agire come applicazione per il tuo team o company. Le OAuth Apps si autenticano come un singolo user, quindi se una persona crea un OAuth App che la company usa e poi lascia l'azienda, nessun altro avrà accesso.
• Maggiori informazioni qui: https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-oauth-apps.

Github Applications

Github applications possono chiedere permessi per accedere alle tue informazioni su github o impersonarti per eseguire azioni specifiche su risorse specifiche. Nelle Github Apps devi specificare i repositories a cui l'app avrà accesso.

• Per installare una GitHub App, devi essere organisation owner o avere permessi admin in un repository.
• La GitHub App dovrebbe connettersi a un account personale o a un'organization.
• Puoi creare la tua Github application in https://github.com/settings/apps
• Puoi vedere tutte le Github applications che hanno accesso al tuo account in https://github.com/settings/apps/authorizations
• Questi sono gli API Endpoints per Github Applications https://docs.github.com/en/rest/overview/endpoints-available-for-github-app. A seconda dei permessi dell'App potrà accedere ad alcuni di essi.
• Puoi vedere le app installate in un'organization in https://github.com/organizations/<org_name>/settings/installations

Alcune raccomandazioni di sicurezza:

• Una GitHub App dovrebbe eseguire azioni indipendenti da un utente (a meno che l'app non stia usando un token user-to-server). Per mantenere più sicuri gli access token user-to-server, puoi usare token di accesso che scadono dopo 8 ore e un refresh token che può essere scambiato per un nuovo access token. Per maggiori informazioni, vedi "Refreshing user-to-server access tokens."
• Assicurati che la GitHub App si integri con repositories specifici.
• La GitHub App dovrebbe connettersi a un account personale o a un'organization.
• Non aspettarti che la GitHub App sappia e faccia tutto quello che un user può fare.
• Non usare una GitHub App se ti serve solo un servizio "Login with GitHub". Ma una GitHub App può usare un user identification flow per loggare gli utenti e fare altre cose.
• Non costruire una GitHub App se vuoi solo agire come un user GitHub e fare tutto ciò che quell'user può fare.
• Se stai usando la tua app con GitHub Actions e vuoi modificare workflow files, devi autenticarti per conto dell'utente con un OAuth token che includa lo scope workflow. L'utente deve avere permessi admin o write sul repository che contiene il workflow file. Per maggiori informazioni, vedi "Understanding scopes for OAuth apps."
• Maggiori informazioni qui: https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps.

Github Actions

Questo non è un metodo per autenticarsi in github, ma una malicious Github Action potrebbe ottenere accesso non autorizzato a github e a seconda dei privilegi assegnati all'Action possono essere compiuti diversi attacchi. Vedi sotto per più informazioni.

Git Actions

Git actions permette di automatizzare l'esecuzione di codice quando accade un evento. Di solito il codice eseguito è in qualche modo relativo al codice del repository (per esempio costruire un docker container o controllare che la PR non contenga secrets).

Configuration

In https://github.com/organizations/<org_name>/settings/actions è possibile controllare la configurazione delle github actions per l'organization.

È possibile disabilitare completamente l'uso delle github actions, allow all github actions, o permettere solo certe actions.

È anche possibile configurare chi necessita di approvazione per eseguire una Github Action e i permessi del GITHUB_TOKEN di una Github Action quando viene eseguita.

Git Secrets

Le Github Action solitamente necessitano di una sorta di secrets per interagire con github o applicazioni di terze parti. Per evitare di inserirli in chiaro nel repo, github permette di salvarli come Secrets.

Questi secrets possono essere configurati per il repo o per tutta l'organization. Poi, affinché l'Action possa accedere al secret devi dichiararlo così:

steps:
- name: Hello world action
with: # Set the secret as an input
super_secret:${{ secrets.SuperSecret }}
env: # Or as an environment variable
super_secret:${{ secrets.SuperSecret }}

Esempio con Bash

steps:
- shell: bash
env: SUPER_SECRET:${{ secrets.SuperSecret }}
run: |
example-command "$SUPER_SECRET"

Una volta configurati nel repo o nell'organizzazione, gli utenti di github non potranno più accedervi, potranno solo modificarli.

Pertanto, l'unico modo per rubare i github secrets è riuscire ad accedere alla macchina che sta eseguendo la Github Action (in quello scenario potrai accedere solo ai secrets dichiarati per l'Action).

Git Environments

Github permette di creare environments dove puoi salvare secrets. Poi, puoi dare al github action accesso ai secrets all'interno dell'environment con qualcosa del tipo:

jobs:
deployment:
runs-on: ubuntu-latest
environment: env_name

You can configure an environment to be accessed by all branches (default), only protected branches or specify which branches can access it.
Additionally, environment protections include:

• Required reviewers: gate jobs targeting the environment until approved. Enable Prevent self-review to enforce a proper four‑eyes principle on the approval itself.
• Deployment branches and tags: restrict which branches/tags may deploy to the environment. Prefer selecting specific branches/tags and ensure those branches are protected. Note: the "Protected branches only" option applies to classic branch protections and may not behave as expected if using rulesets.
• Wait timer: delay deployments for a configurable period.

Può anche impostare un numero di revisioni richieste prima di eseguire un action che usa un environment oppure attendere del tempo prima di permettere che le deployment procedano.

Git Action Runner

A Github Action può essere eseguita all'interno dell'environment di github oppure può essere eseguita in una infrastruttura di terze parti configurata dall'utente.

Diverse organizzazioni permettono di eseguire Github Actions in una infrastruttura di terze parti poiché solitamente risulta più economico.

Puoi elencare i self-hosted runners di un'organizzazione in https://github.com/organizations/<org_name>/settings/actions/runners

Il modo per trovare quali Github Actions vengono eseguite in infrastrutture non-github è cercare runs-on: self-hosted nel file di configurazione yaml della Github Action.

Non è possibile eseguire una Github Action di un'organizzazione all'interno di una macchina self hosted appartenente a una diversa organizzazione perché un token univoco viene generato per il Runner durante la sua configurazione per identificarne l'appartenenza.

Se il custom Github Runner è configurato in una macchina dentro AWS o GCP, per esempio, l'Action potrebbe avere accesso al metadata endpoint e rubare il token dell'account di servizio con cui la macchina sta girando.

Git Action Compromise

Se tutte le action (o una action malevola) sono permesse, un utente potrebbe usare una Github action che è maligna e che comprometterà il container in cui viene eseguita.

Branch Protections

Le branch protections sono pensate per non dare il controllo completo su un repository agli utenti. L'obiettivo è inserire più metodi di protezione prima di poter scrivere codice su una branch.

Le branch protections di un repository possono essere trovate in https://github.com/<orgname>/<reponame>/settings/branches

Diverse protezioni possono essere applicate a una branch (come master):

• Puoi richiedere una PR prima del merge (quindi non puoi unire direttamente codice sulla branch). Se questo è selezionato, altre protezioni possono essere attive:
• Require a number of approvals. È molto comune richiedere 1 o 2 persone in più per approvare la PR in modo che un singolo utente non possa unire codice direttamente.
• Dismiss approvals when new commits are pushed. Altrimenti, un utente potrebbe approvare codice legittimo e poi aggiungere codice malevolo e unirlo.
• Require approval of the most recent reviewable push. Garantisce che qualsiasi nuovo commit dopo un'approvazione (inclusi push di altri collaboratori) riattivi la review così un attaccante non può pushare cambiamenti post-approvazione e fare merge.
• Require reviews from Code Owners. Almeno 1 code owner del repo deve approvare la PR (così utenti "a caso" non possono approvarla).
• Restrict who can dismiss pull request reviews. Puoi specificare persone o team autorizzati a revocare le review delle pull request.
• Allow specified actors to bypass pull request requirements. Questi utenti potranno bypassare le restrizioni precedenti.
• Require status checks to pass before merging. Alcuni check devono passare prima di poter unire il commit (come una GitHub App che riporta risultati SAST). Suggerimento: vincola i check richiesti a una specifica GitHub App; altrimenti qualsiasi app potrebbe falsare il check tramite la Checks API, e molti bot accettano direttive di skip (es., "@bot-name skip").
• Require conversation resolution before merging. Tutti i commenti sul codice devono essere risolti prima che la PR possa essere unita.
• Require signed commits. I commit devono essere firmati.
• Require linear history. Evita che merge commits vengano pushati sulle branch corrispondenti.
• Include administrators. Se non è abilitato, gli admin possono bypassare le restrizioni.
• Restrict who can push to matching branches. Restringe chi può inviare una PR.

Tag Protections

I tag (come latest, stable) sono mutabili di default. Per imporre un flusso four‑eyes sugli aggiornamenti dei tag, proteggi i tag e concatena le protezioni attraverso environment e branch:

1. Nella regola di protezione del tag, abilita Require deployments to succeed e richiedi una deployment di successo verso un environment protetto (es., prod).
2. Nell'environment target, restringi Deployment branches and tags alla release branch (es., main) e opzionalmente configura Required reviewers con Prevent self-review.
3. Sulla release branch, configura le branch protections per Require a pull request, imposta approvazioni ≥ 1, e abilita sia Dismiss approvals when new commits are pushed sia Require approval of the most recent reviewable push.

Questa catena impedisce a un singolo collaboratore di retaggare o forzare la pubblicazione di release modificando i workflow YAML, poiché le porte di deployment sono applicate al di fuori dei workflow.

References

• https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/repository-roles-for-an-organization
• https://docs.github.com/en/enterprise-server@3.3/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprisehttps://docs.github.com/en/enterprise-server
• https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github
• https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-github-user-account/managing-user-account-settings/permission-levels-for-user-owned-project-boards
• https://docs.github.com/en/actions/security-guides/encrypted-secrets
• https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
• https://securitylab.github.com/resources/github-actions-untrusted-input/
• https://docs.github.com/en/rest/checks/runs
• https://docs.github.com/en/apps
• GitHub Actions: A Cloudy Day for Security - Part 1