# Informazioni di base su Github

{{#include ../../banners/hacktricks-training.md}}

## 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](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](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](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](https://docs.github.com/en/authentication/managing-commit-signature-verification/displaying-verification-statuses-for-all-of-your-commits#about-vigilant-mode).

### **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](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](https://github.com/settings/developers)
- Puoi vedere tutte le **Oauth applications che hanno accesso al tuo account** in [https://github.com/settings/applications](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](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](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](https://github.com/settings/apps)
- Puoi vedere tutte le **Github applications che hanno accesso al tuo account** in [https://github.com/settings/apps/authorizations](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](https://docs.github.com/en/rest/overview/endpoints-available-for-github-apps). 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](https://docs.github.com/en/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps#user-to-server-requests)). 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](https://docs.github.com/en/apps/building-github-apps/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](https://docs.github.com/en/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps) 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](https://docs.github.com/en/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/#available-scopes)."
- **Maggiori informazioni** qui: [https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps](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ì:
```yaml
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 <a href="#example-using-bash" id="example-using-bash"></a>
```yaml
steps:
- shell: bash
env: SUPER_SECRET:${{ secrets.SuperSecret }}
run: |
example-command "$SUPER_SECRET"
```
> [!WARNING]
> Secrets **possono essere accessibili solo dalle Github Actions** in cui sono dichiarati.

> 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:
```yaml
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.

> [!CAUTION]
> Una **malicious Github Action** eseguita potrebbe essere **abusata** dall'attaccante per:
>
> - **Rubare tutti i secrets** a cui l'Action ha accesso
> - **Muoversi lateralmente** se l'Action è eseguita dentro una **infrastruttura di terze parti** dove il token SA usato per far girare la macchina è accessibile (probabilmente tramite il servizio metadata)
> - **Abusare del token** usato dal **workflow** per **rubare il codice del repo** dove l'Action è eseguita o **addirittura modificarlo**.

## 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_

> [!NOTE]
> Non è **possibile impostare una branch protection a livello di organization**. Quindi devono essere dichiarate in ogni repo.

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.

> [!NOTE]
> Come puoi vedere, anche se riesci a ottenere delle credenziali di un utente, **i repo potrebbero essere protetti impedendoti di pushare codice su master** per esempio per compromettere la pipeline CI/CD.

## 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/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-enterprise](https://docs.github.com/en/enterprise-server@3.3/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)[https://docs.github.com/en/enterprise-server](https://docs.github.com/en/enterprise-server@3.3/admin/user-management/managing-users-in-your-enterprise/roles-in-an-enterprise)
- [https://docs.github.com/en/get-started/learning-about-github/access-permissions-on-github](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/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/security-guides/encrypted-secrets)
- [https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions)
- [https://securitylab.github.com/resources/github-actions-untrusted-input/](https://securitylab.github.com/resources/github-actions-untrusted-input/)
- [https://docs.github.com/en/rest/checks/runs](https://docs.github.com/en/rest/checks/runs)
- [https://docs.github.com/en/apps](https://docs.github.com/en/apps)
- [GitHub Actions: A Cloudy Day for Security - Part 1](https://binarysecurity.no/posts/2025/08/securing-gh-actions-part1)

{{#include ../../banners/hacktricks-training.md}}
