# Informazioni di base su Github

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

## Struttura di base

La struttura di base dell'ambiente Github di una grande **azienda** è possedere una **enterprise** che a sua volta possiede **diverse organizzazioni** e ognuna di esse può contenere **diversi repository** e **diversi team**. Aziende più piccole possono semplicemente **possedere una sola organization e nessuna enterprise**.

Dal punto di vista di un utente, un **user** può essere **membro** di **diverse enterprise e organizzazioni**. All'interno di queste il user può avere **diversi ruoli a livello di enterprise, organizzazione e repository**.

Inoltre, un user può far parte di **diversi team** con differenti ruoli a livello di enterprise, organizzazione o repository.

Infine, **i repository possono avere meccanismi di protezione speciali**.

## Privilegi

### Enterprise Roles

- **Enterprise owner**: Le persone con questo ruolo possono **gestire gli amministratori, gestire le organization all'interno dell'enterprise, gestire le impostazioni dell'enterprise, applicare policy tra le organizzazioni**. Tuttavia, **non possono accedere alle impostazioni o ai contenuti di una organization** a meno che non vengano resi organization owner o non venga concesso loro accesso diretto a un repository di proprietà della organization.
- **Enterprise members**: I membri delle organization possedute dalla tua enterprise sono anche **automaticamente membri dell'enterprise**.

### Organization Roles

In una organization gli utenti possono avere ruoli diversi:

- **Organization owners**: Gli organization owners hanno **accesso amministrativo completo alla tua organization**. Questo ruolo dovrebbe essere limitato, ma non a meno di due persone nell'organizzazione.
- **Organization members**: Il ruolo **default**, non amministrativo per le **persone in un'organizzazione** è l'organization member. Di 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 in un'organizzazione. Quando applicato, dà a ogni membro del team i permessi per **gestire gli security alerts e le impostazioni in tutta l'organizzazione, oltre ai permessi di lettura per tutti i repository** dell'organizzazione.
- Se la tua organizzazione ha un security team, puoi usare il ruolo di security manager per dare ai membri del team il minimo accesso necessario all'organizzazione.
- **Github App managers**: Per consentire ad ulteriori utenti di **gestire i GitHub Apps posseduti da un'organizzazione**, 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ù repository dell'organizzazione ma non è esplicitamente un membro** dell'organizzazione.

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 essere parte dell'organizzazione**.

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

- Essere admin, writer, reader o nessun permesso su tutti i repository dell'organizzazione.
- Se i membri possono creare repository private, internal o public.
- Se è possibile effettuare fork dei repository.
- Se è possibile invitare outside collaborators.
- Se siti public o private possono essere pubblicati.
- I permessi che gli admin hanno sui repository.
- Se i membri possono creare nuovi team.

### Repository Roles

Per default i repository hanno creati i seguenti ruoli:

- **Read**: Raccomandato per **contributori non-code** che vogliono visualizzare o discutere il progetto.
- **Triage**: Raccomandato per **contributori che devono gestire proattivamente issues e pull request** senza accesso in scrittura.
- **Write**: Raccomandato per contributori che **inseriscono attivamente codice nel progetto**.
- **Maintain**: Raccomandato per **project manager 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 la sicurezza o cancellare 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 team creati in un'organizzazione** in _https://github.com/orgs/\<org_name>/teams_. Nota che per vedere i team che sono figli di altri team è necessario accedere a ogni team padre.

### Users

Gli utenti di un'organizzazione possono essere **elencati** in _https://github.com/orgs/\<org_name>/people._

Nelle informazioni di ogni user puoi vedere i **team di cui l'utente è membro**, e i **repo a cui l'utente ha accesso**.

## Github Authentication

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

### Web Access

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

### **SSH Keys**

Puoi configurare il tuo account con una o più chiavi pubbliche che permettono alla relativa **chiave privata 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 chiavi, ma se non le usi potrebbe essere possibile che **venga scoperto l'invio di commit senza firma**. Per saperne di più su vigilant mode leggi [qui](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 il **user** deve **specificare** i **permessi** che il **token** avrà. [https://github.com/settings/tokens](https://github.com/settings/tokens)

### Oauth Applications

Le Oauth applications possono chiederti permessi **per accedere a parte delle tue informazioni su github o per impersonarti** per eseguire alcune azioni. Un esempio comune di questa funzionalità è il pulsante **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 le 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 applicazioni 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 repository autenticati dell'utente.
- **Non** costruire un OAuth App per agire come applicazione per il tuo **team o azienda**. Le OAuth Apps autenticano come **singolo utente**, quindi se una persona crea un OAuth App per l'azienda e poi lascia l'azienda, nessun altro avrà accesso.
- **Altro** in [qui](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-oauth-apps).

### Github Applications

Le 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 repository 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'organizzazione**.
- 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 i **API Endpoints per le 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 i token user-to-server, puoi usare access token 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 **repository specifici**.
- La GitHub App dovrebbe **connettersi a un account personale o a un'organizzazione**.
- Non aspettarti che la GitHub App sappia e faccia tutto ciò che un utente 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 autenticare gli utenti _e_ fare altre cose.
- Non costruire una GitHub App se vuoi _solo_ agire come un utente GitHub e fare tutto ciò che quell'utente può fare.
- Se stai usando la tua app con GitHub Actions e vuoi modificare i 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 file di workflow. 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)."
- **Altro** in [qui](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps).

### Github Actions

Questo **non è un modo per autenticarsi in github**, ma una **malicious** Github Action potrebbe ottenere **accesso non autorizzato a github** e **a seconda** dei **privilegi** concessi all'Action si potrebbero compiere **diversi attacchi**. Vedi sotto per maggiori informazioni.

## Git Actions

Git actions permette di automatizzare la **esecuzione di codice quando accade un evento**. Solitamente il codice eseguito è **in qualche modo legato al codice del repository** (per esempio costruire un container docker o verificare 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'organizzazione.

È possibile disabilitare completamente l'uso di github actions, **consentire tutte le github actions**, o permettere solo certe actions.

È inoltre possibile configurare **chi necessita 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 qualche tipo di secret per interagire con github o applicazioni di terze parti. Per **evitare di metterli in chiaro** nel repo, github permette di salvarli come **Secrets**.

Questi secrets possono essere configurati **per il repo o per l'intera organizzazione**. Poi, affinché l'**Action possa accedere al secret** è necessario 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 usando 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 **sono accessibili solo dalle Github Actions** che li hanno dichiarati.
>
> Una volta configurati nel repo o nell'organizzazione **gli utenti di github non potranno più accedervi**, potranno solamente **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).

### Ambienti Git

Github permette di creare **ambienti** dove puoi salvare **secrets**. Poi, puoi permettere al github action di accedere ai secrets all'interno dell'ambiente con qualcosa del tipo:
```yaml
jobs:
deployment:
runs-on: ubuntu-latest
environment: env_name
```
Puoi configurare un environment in modo che sia **accessed** da **all branches** (default), **only protected** branches o **specify** which branches can access it.\
Inoltre, le protezioni dell'environment includono:
- **Required reviewers**: bloccare job che targettano l'environment finché non vengono approvati. Abilita **Prevent self-review** per applicare un corretto principio delle quattro occhi sull'approvazione stessa.
- **Deployment branches and tags**: restringere quali branch/tag possono deployare nell'environment. Preferisci selezionare branch/tag specifici e assicurati che quei branch siano protetti. Nota: l'opzione "Protected branches only" si applica alle protezioni di branch classiche e potrebbe non comportarsi come previsto se si usano rulesets.
- **Wait timer**: ritardare i deployment per un periodo configurabile.

Può anche impostare un **number of required reviews** prima di **executing** un **action** usando un **environment** o **wait** qualche **time** prima di permettere ai deployment di procedere.
### Git Action Runner

A Github Action può essere **executed inside the github environment** oppure può essere eseguita in una **third party infrastructure** configurata dall'utente.

Diverse organizzazioni permettono di eseguire Github Actions in una **third party infrastructure** perché spesso risulta **cheaper**.

Puoi **list the self-hosted runners** di un'organizzazione in _https://github.com/organizations/\<org_name>/settings/actions/runners_

Il modo per trovare quali **Github Actions are being executed in non-github infrastructure** è cercare `runs-on: self-hosted` nella configurazione yaml della Github Action.

Non è **possible to run a Github Action of an organization inside a self hosted box** di un'organizzazione diversa perché **a unique token is generated for the Runner** quando lo si configura per far sapere a quale runner appartiene.

Se il custom **Github Runner is configured in a machine inside AWS or GCP** per esempio, l'Action **could have access to the metadata endpoint** e **steal the token of the service account** con cui la macchina è eseguita.

### Git Action Compromise

Se tutte le action (o una action malevola) sono consentite, un utente potrebbe usare una **Github action** che è **malicious** e che **compromette** il **container** dove viene eseguita.

> [!CAUTION]
> Una **malicious Github Action** run potrebbe essere **abused** dall'attaccante per:
>
> - **Steal all the secrets** a cui l'Action ha accesso
> - **Move laterally** se l'Action viene eseguita dentro una **third party infrastructure** dove il SA token usato per eseguire la macchina può essere accessibile (probabilmente via il metadata service)
> - **Abuse the token** usato dal **workflow** per **steal the code of the repo** dove l'Action è eseguita o **even modify it**.

## Branch Protections

Le branch protections sono progettate per **not give complete control of a repository** agli utenti. L'obiettivo è **put several protection methods before being able to write code inside some branch**.

Le **branch protections of a repository** possono essere trovate in _https://github.com/\<orgname>/\<reponame>/settings/branches_

> [!NOTE]
> Non è **possible to set a branch protection at organization level**. Quindi tutte devono essere dichiarate su ogni repo.

Differenti protezioni possono essere applicate a un branch (ad esempio master):

- Puoi **require a PR before merging** (quindi non puoi direttamente mergiare codice sul branch). Se questo è selezionato possono essere in vigore altre protezioni:
- **Require a number of approvals**. È molto comune richiedere 1 o 2 persone in più per approvare la tua PR così un singolo utente non può mergiare codice direttamente.
- **Dismiss approvals when new commits are pushed**. Se non abilitato, un utente potrebbe approvare codice legittimo e poi aggiungere codice malevolo e mergiarlo.
- **Require approval of the most recent reviewable push**. Garantisce che qualsiasi nuovo commit dopo un'approvazione (inclusi push da altri collaboratori) riattivi la review in modo che un attaccante non possa pushare cambiamenti post-approvazione e mergiarli.
- **Require reviews from Code Owners**. Almeno 1 code owner del repo deve approvare la PR (così utenti "random" non possono approvarla)
- **Restrict who can dismiss pull request reviews.** Puoi specificare persone o team autorizzati a dismissare le review delle pull request.
- **Allow specified actors to bypass pull request requirements**. Questi utenti saranno in grado di bypassare le restrizioni precedenti.
- **Require status checks to pass before merging.** Alcuni check devono passare prima di poter mergiare il commit (come un GitHub App che riporta risultati SAST). Suggerimento: vincola i check richiesti a una specifica GitHub App; altrimenti qualsiasi app potrebbe spoofare il check via le 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 mergiata.
- **Require signed commits**. I commit devono essere firmati.
- **Require linear history.** Impedisce che merge commits vengano pushati ai branch che corrispondono alla regola.
- **Include administrators**. Se non impostato, 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 sei riuscito a ottenere alcune credenziali di un utente, **repos might be protected avoiding you to pushing code to master** per esempio per compromettere la CI/CD pipeline.

## Tag Protections

I tag (come latest, stable) sono mutabili di default. Per imporre un flusso a quattro occhi sugli aggiornamenti dei tag, proteggi i tag e incatena le protezioni attraverso environment e branch:

1) Sulla rule di protezione del tag, abilita **Require deployments to succeed** e richiedi un deployment riuscito a un environment protetto (es., prod).
2) Nell'environment target, restringi **Deployment branches and tags** al release branch (es., main) e opzionalmente configura **Required reviewers** con **Prevent self-review**.
3) Sul release branch, configura le branch protections per **Require a pull request**, imposta approvals ≥ 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 force-publishare release modificando il workflow YAML, poiché i gate di deployment vengono applicati 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}}