# Informações Básicas do Github

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

## Estrutura Básica

A estrutura básica do ambiente do github de uma grande **empresa** é possuir uma **empresa** que possui **várias organizações** e cada uma delas pode conter **vários repositórios** e **várias equipes**. Empresas menores podem **possuir apenas uma organização e nenhuma empresa**.

Do ponto de vista do usuário, um **usuário** pode ser um **membro** de **diferentes empresas e organizações**. Dentro delas, o usuário pode ter **diferentes funções de empresa, organização e repositório**.

Além disso, um usuário pode ser **parte de diferentes equipes** com diferentes funções de empresa, organização ou repositório.

E finalmente, **os repositórios podem ter mecanismos de proteção especiais**.

## Privilégios

### Funções de Empresa

- **Proprietário da empresa**: Pessoas com essa função podem **gerenciar administradores, gerenciar organizações dentro da empresa, gerenciar configurações da empresa, impor políticas entre organizações**. No entanto, eles **não podem acessar configurações ou conteúdo da organização** a menos que sejam designados como proprietários da organização ou tenham acesso direto a um repositório de propriedade da organização.
- **Membros da empresa**: Membros de organizações pertencentes à sua empresa também são **automaticamente membros da empresa**.

### Funções de Organização

Em uma organização, os usuários podem ter diferentes funções:

- **Proprietários da organização**: Proprietários da organização têm **acesso administrativo completo à sua organização**. Essa função deve ser limitada, mas não a menos de duas pessoas, em sua organização.
- **Membros da organização**: A função **padrão**, não administrativa para **pessoas em uma organização** é o membro da organização. Por padrão, os membros da organização **têm um número de permissões**.
- **Gerentes de cobrança**: Gerentes de cobrança são usuários que podem **gerenciar as configurações de cobrança da sua organização**, como informações de pagamento.
- **Gerentes de Segurança**: É uma função que os proprietários da organização podem atribuir a qualquer equipe em uma organização. Quando aplicada, dá a cada membro da equipe permissões para **gerenciar alertas e configurações de segurança em sua organização, bem como permissões de leitura para todos os repositórios** na organização.
- Se sua organização tiver uma equipe de segurança, você pode usar a função de gerente de segurança para dar aos membros da equipe o menor acesso necessário à organização.
- **Gerentes de Aplicativos do Github**: Para permitir que usuários adicionais **gerenciem Aplicativos do GitHub de propriedade de uma organização**, um proprietário pode conceder a eles permissões de gerente de Aplicativos do GitHub.
- **Colaboradores externos**: Um colaborador externo é uma pessoa que tem **acesso a um ou mais repositórios da organização, mas não é explicitamente um membro** da organização.

Você pode **comparar as permissões** dessas funções nesta tabela: [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)

### Privilégios dos Membros

Em _https://github.com/organizations/\<org_name>/settings/member_privileges_ você pode ver as **permissões que os usuários terão apenas por serem parte da organização**.

As configurações aqui configuradas indicarão as seguintes permissões dos membros da organização:

- Ser administrador, escritor, leitor ou sem permissão sobre todos os repositórios da organização.
- Se os membros podem criar repositórios privados, internos ou públicos.
- Se o fork de repositórios é possível.
- Se é possível convidar colaboradores externos.
- Se sites públicos ou privados podem ser publicados.
- As permissões que os administradores têm sobre os repositórios.
- Se os membros podem criar novas equipes.

### Funções de Repositório

Por padrão, as funções de repositório são criadas:

- **Leitura**: Recomendado para **contribuidores não de código** que desejam visualizar ou discutir seu projeto.
- **Triagem**: Recomendado para **contribuidores que precisam gerenciar proativamente problemas e pull requests** sem acesso de escrita.
- **Escrita**: Recomendado para contribuintes que **enviam ativamente para seu projeto**.
- **Manutenção**: Recomendado para **gerentes de projeto que precisam gerenciar o repositório** sem acesso a ações sensíveis ou destrutivas.
- **Admin**: Recomendado para pessoas que precisam de **acesso total ao projeto**, incluindo ações sensíveis e destrutivas, como gerenciar segurança ou excluir um repositório.

Você pode **comparar as permissões** de cada função nesta tabela [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)

Você também pode **criar suas próprias funções** em _https://github.com/organizations/\<org_name>/settings/roles_

### Equipes

Você pode **listar as equipes criadas em uma organização** em _https://github.com/orgs/\<org_name>/teams_. Observe que para ver as equipes que são filhas de outras equipes, você precisa acessar cada equipe pai.

### Usuários

Os usuários de uma organização podem ser **listados** em _https://github.com/orgs/\<org_name>/people._

Nas informações de cada usuário, você pode ver as **equipes das quais o usuário é membro** e os **repositórios aos quais o usuário tem acesso**.

## Autenticação do Github

O Github oferece diferentes maneiras de autenticar sua conta e realizar ações em seu nome.

### Acesso Web

Acessando **github.com**, você pode fazer login usando seu **nome de usuário e senha** (e um **2FA potencialmente**).

### **Chaves SSH**

Você pode configurar sua conta com uma ou várias chaves públicas permitindo que a chave **privada relacionada realize ações em seu nome.** [https://github.com/settings/keys](https://github.com/settings/keys)

#### **Chaves GPG**

Você **não pode se passar pelo usuário com essas chaves**, mas se você não as usar, pode ser possível que você **seja descoberto por enviar commits sem uma assinatura**. Saiba mais sobre [modo vigilante aqui](https://docs.github.com/en/authentication/managing-commit-signature-verification/displaying-verification-statuses-for-all-of-your-commits#about-vigilant-mode).

### **Tokens de Acesso Pessoal**

Você pode gerar um token de acesso pessoal para **dar a um aplicativo acesso à sua conta**. Ao criar um token de acesso pessoal, o **usuário** precisa **especificar** as **permissões** que o **token** terá. [https://github.com/settings/tokens](https://github.com/settings/tokens)

### Aplicativos Oauth

Aplicativos Oauth podem solicitar permissões **para acessar parte das suas informações do github ou para se passar por você** para realizar algumas ações. Um exemplo comum dessa funcionalidade é o **botão de login com github** que você pode encontrar em algumas plataformas.

- Você pode **criar** seus próprios **aplicativos Oauth** em [https://github.com/settings/developers](https://github.com/settings/developers)
- Você pode ver todos os **aplicativos Oauth que têm acesso à sua conta** em [https://github.com/settings/applications](https://github.com/settings/applications)
- Você pode ver os **escopos que os Aplicativos Oauth podem solicitar** em [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)
- Você pode ver o acesso de terceiros de aplicativos em uma **organização** em _https://github.com/organizations/\<org_name>/settings/oauth_application_policy_

Algumas **recomendações de segurança**:

- Um **Aplicativo OAuth** deve sempre **agir como o usuário autenticado do GitHub em toda a plataforma GitHub** (por exemplo, ao fornecer notificações ao usuário) e com acesso apenas aos escopos especificados.
- Um Aplicativo OAuth pode ser usado como um provedor de identidade ao habilitar um "Login com GitHub" para o usuário autenticado.
- **Não** crie um **Aplicativo OAuth** se você quiser que seu aplicativo atue em um **único repositório**. Com o escopo `repo`, os Aplicativos OAuth podem **agir em \_todos**\_\*\* os repositórios do usuário autenticado\*\*.
- **Não** crie um Aplicativo OAuth para atuar como um aplicativo para sua **equipe ou empresa**. Aplicativos OAuth se autenticam como um **único usuário**, então se uma pessoa criar um Aplicativo OAuth para uma empresa usar, e depois ela deixar a empresa, ninguém mais terá acesso a ele.
- **Mais** em [aqui](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-oauth-apps).

### Aplicativos do Github

Aplicativos do Github podem solicitar permissões para **acessar suas informações do github ou se passar por você** para realizar ações específicas sobre recursos específicos. Nos Aplicativos do Github, você precisa especificar os repositórios aos quais o aplicativo terá acesso.

- Para instalar um Aplicativo do GitHub, você deve ser um **proprietário da organização ou ter permissões de administrador** em um repositório.
- O Aplicativo do GitHub deve **conectar-se a uma conta pessoal ou a uma organização**.
- Você pode criar seu próprio aplicativo do Github em [https://github.com/settings/apps](https://github.com/settings/apps)
- Você pode ver todos os **aplicativos do Github que têm acesso à sua conta** em [https://github.com/settings/apps/authorizations](https://github.com/settings/apps/authorizations)
- Estes são os **Endpoints da API para Aplicativos do Github** [https://docs.github.com/en/rest/overview/endpoints-available-for-github-app](https://docs.github.com/en/rest/overview/endpoints-available-for-github-apps). Dependendo das permissões do Aplicativo, ele poderá acessar alguns deles.
- Você pode ver aplicativos instalados em uma **organização** em _https://github.com/organizations/\<org_name>/settings/installations_

Algumas recomendações de segurança:

- Um Aplicativo do GitHub deve **realizar ações independentemente de um usuário** (a menos que o aplicativo esteja usando um token [de usuário para servidor](https://docs.github.com/en/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps#user-to-server-requests)). Para manter os tokens de acesso de usuário para servidor mais seguros, você pode usar tokens de acesso que expiram após 8 horas, e um token de atualização que pode ser trocado por um novo token de acesso. Para mais informações, veja "[Atualizando tokens de acesso de usuário para servidor](https://docs.github.com/en/apps/building-github-apps/refreshing-user-to-server-access-tokens)."
- Certifique-se de que o Aplicativo do GitHub se integre com **repositórios específicos**.
- O Aplicativo do GitHub deve **conectar-se a uma conta pessoal ou a uma organização**.
- Não espere que o Aplicativo do GitHub saiba e faça tudo o que um usuário pode.
- **Não use um Aplicativo do GitHub se você só precisa de um serviço de "Login com GitHub"**. Mas um Aplicativo do GitHub pode usar um [fluxo de identificação de usuário](https://docs.github.com/en/apps/building-github-apps/identifying-and-authorizing-users-for-github-apps) para fazer login de usuários _e_ fazer outras coisas.
- Não crie um Aplicativo do GitHub se você _apenas_ quiser agir como um usuário do GitHub e fazer tudo o que esse usuário pode fazer.
- Se você estiver usando seu aplicativo com GitHub Actions e quiser modificar arquivos de workflow, você deve se autenticar em nome do usuário com um token OAuth que inclua o escopo `workflow`. O usuário deve ter permissão de administrador ou escrita para o repositório que contém o arquivo de workflow. Para mais informações, veja "[Entendendo escopos para aplicativos OAuth](https://docs.github.com/en/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/#available-scopes)."
- **Mais** em [aqui](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps).

### Github Actions

Isso **não é uma maneira de autenticar no github**, mas uma **ação maliciosa** do Github poderia obter **acesso não autorizado ao github** e **dependendo** dos **privilégios** dados à Ação, vários **ataques diferentes** poderiam ser realizados. Veja abaixo para mais informações.

## Ações Git

As ações Git permitem automatizar a **execução de código quando um evento acontece**. Normalmente, o código executado está **de alguma forma relacionado ao código do repositório** (talvez construir um contêiner docker ou verificar se o PR não contém segredos).

### Configuração

Em _https://github.com/organizations/\<org_name>/settings/actions_ é possível verificar a **configuração das ações do github** para a organização.

É possível proibir completamente o uso de ações do github, **permitir todas as ações do github**, ou apenas permitir certas ações.

É também possível configurar **quem precisa de aprovação para executar uma Ação do Github** e as **permissões do GITHUB_TOKEN** de uma Ação do Github quando ela é executada.

### Segredos do Git

A Ação do Github geralmente precisa de algum tipo de segredos para interagir com o github ou aplicativos de terceiros. Para **evitar colocá-los em texto claro** no repositório, o github permite colocá-los como **Segredos**.

Esses segredos podem ser configurados **para o repositório ou para toda a organização**. Então, para que a **Ação possa acessar o segredo**, você precisa declará-lo como:
```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 }}
```
#### Exemplo 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]
> Segredos **só podem ser acessados a partir das Github Actions** que os têm declarados.

> Uma vez configurados no repositório ou nas organizações, **os usuários do github não poderão acessá-los novamente**, eles só poderão **alterá-los**.

Portanto, a **única maneira de roubar segredos do github é conseguir acessar a máquina que está executando a Github Action** (nesse cenário, você só poderá acessar os segredos declarados para a Action).

### Ambientes do Git

O Github permite criar **ambientes** onde você pode salvar **segredos**. Em seguida, você pode dar à ação do github acesso aos segredos dentro do ambiente com algo como:
```yaml
jobs:
deployment:
runs-on: ubuntu-latest
environment: env_name
```
Você pode configurar um ambiente para ser **acessado** por **todos os ramos** (padrão), **apenas ramos protegidos** ou **especificar** quais ramos podem acessá-lo.\
Também é possível definir um **número de revisões necessárias** antes de **executar** uma **ação** usando um **ambiente** ou **aguardar** algum **tempo** antes de permitir que os deployments prossigam.

### Git Action Runner

Uma Github Action pode ser **executada dentro do ambiente github** ou pode ser executada em uma **infraestrutura de terceiros** configurada pelo usuário.

Várias organizações permitirão a execução de Github Actions em uma **infraestrutura de terceiros**, pois costuma ser **mais barato**.

Você pode **listar os runners auto-hospedados** de uma organização em _https://github.com/organizations/\<org_name>/settings/actions/runners_

A maneira de descobrir quais **Github Actions estão sendo executadas em infraestrutura não github** é procurar por `runs-on: self-hosted` na configuração yaml da Github Action.

**Não é possível executar uma Github Action de uma organização dentro de uma caixa auto-hospedada** de uma organização diferente porque **um token único é gerado para o Runner** ao configurá-lo para saber a qual runner pertence.

Se o **Github Runner personalizado estiver configurado em uma máquina dentro da AWS ou GCP**, por exemplo, a Action **pode ter acesso ao endpoint de metadados** e **roubar o token da conta de serviço** com a qual a máquina está sendo executada.

### Comprometimento da Git Action

Se todas as ações (ou uma ação maliciosa) forem permitidas, um usuário poderia usar uma **Github action** que é **maliciosa** e irá **comprometer** o **container** onde está sendo executada.

> [!CAUTION]
> Uma **Github Action maliciosa** executada poderia ser **abusada** pelo atacante para:
>
> - **Roubar todos os segredos** aos quais a Action tem acesso
> - **Mover lateralmente** se a Action for executada dentro de uma **infraestrutura de terceiros** onde o token SA usado para executar a máquina pode ser acessado (provavelmente via o serviço de metadados)
> - **Abusar do token** usado pelo **workflow** para **roubar o código do repositório** onde a Action é executada ou **até mesmo modificá-lo**.

## Proteções de Ramo

As proteções de ramo são projetadas para **não dar controle total de um repositório** aos usuários. O objetivo é **implementar vários métodos de proteção antes de poder escrever código dentro de algum ramo**.

As **proteções de ramo de um repositório** podem ser encontradas em _https://github.com/\<orgname>/\<reponame>/settings/branches_

> [!NOTE]
> **Não é possível definir uma proteção de ramo em nível de organização**. Portanto, todas elas devem ser declaradas em cada repositório.

Diferentes proteções podem ser aplicadas a um ramo (como ao master):

- Você pode **exigir um PR antes de mesclar** (então você não pode mesclar código diretamente sobre o ramo). Se isso for selecionado, outras proteções podem estar em vigor:
- **Exigir um número de aprovações**. É muito comum exigir que 1 ou 2 pessoas adicionais aprovem seu PR, para que um único usuário não consiga mesclar código diretamente.
- **Desconsiderar aprovações quando novos commits são enviados**. Caso contrário, um usuário pode aprovar código legítimo e, em seguida, o usuário poderia adicionar código malicioso e mesclá-lo.
- **Exigir revisões de Proprietários de Código**. Pelo menos 1 proprietário de código do repositório precisa aprovar o PR (para que usuários "aleatórios" não possam aprová-lo)
- **Restringir quem pode desconsiderar revisões de pull request.** Você pode especificar pessoas ou equipes autorizadas a desconsiderar revisões de pull request.
- **Permitir que atores especificados contornem os requisitos de pull request**. Esses usuários poderão contornar restrições anteriores.
- **Exigir que verificações de status sejam aprovadas antes de mesclar.** Algumas verificações precisam ser aprovadas antes de poder mesclar o commit (como uma ação do github verificando se não há nenhum segredo em texto claro).
- **Exigir resolução de conversas antes de mesclar**. Todos os comentários sobre o código precisam ser resolvidos antes que o PR possa ser mesclado.
- **Exigir commits assinados**. Os commits precisam ser assinados.
- **Exigir histórico linear.** Impedir que commits de mesclagem sejam enviados para ramos correspondentes.
- **Incluir administradores**. Se isso não estiver definido, os administradores podem contornar as restrições.
- **Restringir quem pode enviar para ramos correspondentes**. Restringir quem pode enviar um PR.

> [!NOTE]
> Como você pode ver, mesmo que você consiga obter algumas credenciais de um usuário, **repositórios podem estar protegidos, evitando que você envie código para o master**, por exemplo, para comprometer o pipeline de CI/CD.

## Referências

- [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)

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