O objetivo desta ferramenta é ajudar a habilitar o GitHub Advanced Security (GHAS) em vários repositórios de forma automatizada. Haverá momentos em que você precisará habilitar a verificação de código (CodeQL), a verificação de segredos, os alertas do Dependabot e/ou as atualizações de segurança do Dependabot em diversos repositórios, e não desejará clicar em botões manualmente ou adicionar um fluxo de trabalho do GitHub para CodeQL em cada repositório. Fazer isso manualmente é trabalhoso e demorado. O objetivo desta ferramenta é automatizar essas tarefas manuais.

A principal motivação para esta ferramenta é o CodeQL. Habilitar o CodeQL em vários repositórios é extremamente demorado. Além disso, nenhuma API permite acesso de escrita ao .github/workflow/diretório. Isso significa que as equipes precisam escrever vários scripts com resultados diferentes. Esta ferramenta oferece uma maneira testada e comprovada de fazer isso.

A verificação secreta e o Dependabot também são difíceis de habilitar se você quiser ativá-los apenas em repositórios específicos, em vez de em todos. Esta ferramenta permite que você faça isso facilmente.

Esta ferramenta realiza duas ações principais:

Parte Um:

O sistema coleta repositórios que possuem as funcionalidades de Análise de Código (CodeQL), Análise de Segredos, Proteção contra Envio de Segredos, Alertas do Pendabot, Atualizações de Segurança do Pendabot e Ações ativadas. Existem três maneiras principais de coletar esses repositórios.

• Colete os repositórios onde o idioma principal corresponde a um valor específico. Por exemplo, se você fornecer JavaScript, todos os repositórios onde o idioma principal é JavaScript serão coletados.
• Reúna os repositórios aos quais um usuário tem acesso administrativo ou aos quais um aplicativo do GitHub tem acesso.

Se você selecionar a opção 1, o script retornará todos os repositórios no idioma especificado (aos quais você tem acesso). Os repositórios coletados por este script serão armazenados em um repos.jsonarquivo. Se você selecionar a opção 2, o script retornará todos os repositórios nos quais você é administrador. A terceira opção é definir repos.jsonmanualmente. Não recomendamos esta opção, mas é possível. Se você optar por este caminho, primeiro execute uma das opções acima para coletar informações de repositório automaticamente, observe a estrutura e crie sua lista de repositórios com base no formato definido.

Parte Dois:

Percorre os repositórios encontrados no repos.jsonarquivo e habilita a verificação de código (CodeQL), a verificação de segredos, a proteção contra notificações push de verificação de segredos, os alertas do Pendabot e as atualizações de segurança do Pendabot.

• Se você selecionar Leitura de Código:
  • Percorre os repositórios encontrados no repos.jsonarquivo. Uma solicitação de pull request é criada nesse repositório com o arquivo codeql-analysis-${language}.ymlencontrado no bin/workflowsdiretório.
  • O idioma ${language}será substituído em tempo de execução pelo idioma principal do repositório.
  • Para sua conveniência, todas as solicitações de pull request feitas serão armazenadas no prs.txtarquivo, onde você poderá visualizá-las e revisá-las manualmente após a execução do script.
• Se você selecionar a opção de Varredura Secreta:
  • Percorre os repositórios encontrados no repos.jsonarquivo. Em seguida, a verificação de segredos é ativada nesses repositórios.
• Se você selecionar Proteções contra Impedimento:
  • Percorre os repositórios encontrados no repos.jsonarquivo. Em seguida, a Proteção Push de Varredura Secreta é ativada nesses repositórios.
• Se você selecionar os Alertas do Dependabot:
  • Percorre os repositórios encontrados no repos.jsonarquivo. Em seguida, o Dependabot Alerts é ativado nesses repositórios.
• Se você selecionar as atualizações de segurança do Dependabot:
  • Percorre os repositórios encontrados no repos.jsonarquivo. Em seguida, as atualizações de segurança do Dependabot são ativadas nesses repositórios.
• Se você selecionar Ações:
  • Percorre os repositórios encontrados no repos.jsonarquivo. Em seguida, as ações são habilitadas nesses repositórios.
  • Isso é útil se você quiser garantir que o fluxo de trabalho de verificação de código possa ser executado e que as Ações não estejam desativadas.
• Se você selecionar Criar Problema:
  • Percorre os repositórios encontrados no repos.jsonarquivo. Um problema será criado com o seguinte texto :
  • Isso notifica os mantenedores do repositório de que uma solicitação de pull request para o CodeQL foi criada, juntamente com outros recursos úteis.

• Node v20 ou superior instalado.
• Fio *
• TypeScript
• O Git está instalado na máquina (do usuário) que executa esta ferramenta.
• Um Token de Acesso Pessoal (PAT) que tenha pelo menos acesso de administrador aos repositórios nos quais você deseja habilitar a verificação de código, ou credenciais do aplicativo GitHub que tenham acesso aos repositórios nos quais você deseja habilitar a verificação de código.
• Algumas habilidades básicas de desenvolvimento de software, como, por exemplo, saber navegar em um terminal ou prompt de comando.

• Você pode usar npm, mas para fins deste exemplo README.md, vamos padronizar os comandos no Yarn. Estes são facilmente substituíveis por outros npmcomandos.

1. Clone este repositório para sua máquina local.

   git clone https://github.com/NickLiffen/ghas-enablement.git

2. Altere o diretório para o repositório que você acabou de instalar.

   cd ghas-enablement

3. Gere a estratégia de autenticação escolhida. Você pode usar um aplicativo GitHub ou um Token de Acesso Pessoal (PAT) . O aplicativo GitHub precisa ter as permissões ` read and write<nome_do_aplicativo> ` , …. O PAT do GitHub precisa de acesso somente às permissões `<nome_do_aplicativo>`, `<nome_do_aplicativo>` e `<nome_do_aplicativo>`. (Se você estiver executando o GitHub App, administrationtambém precisará Code scanning alertsdo escopo ` <nome_do_aplicativo> ` ).contentsissuespull requestsworkflowsrepoworkflowread:orgyarn run getOrgsread:enterprise

4. Copie o .env.sampleconteúdo para o diretório .env. No Mac, isso pode ser feito através do seguinte comando no terminal:

   cp .env.sample .env

5. Atualize o campo .envcom os valores necessários. Selecione um dos métodos de autenticação para interagir com o GitHub. Você pode preencher o campo GITHUB_API_TOKENcom um PAT que tenha acesso à organização OU preencher todos os valores necessários para um aplicativo do GitHub. Observação : recomenda-se escolher a opção de aplicativo do GitHub se estiver executando em milhares de repositórios, pois isso oferece mais solicitações de API em comparação com um PAT.

   • Se estiver usando um aplicativo do GitHub, cole o valor exatamente como está no APP_PRIVATE_KEYcampo entre aspas duplas (a chave ocupará várias linhas) ou converta a chave privada em uma única linha entre aspas duplas, substituindo o caractere de nova linha por \n(no VS Code para Mac, você pode usar ⌃ + Enterpara localizar/substituir o caractere de nova linha).

6. Atualize o GITHUB_ORGvalor encontrado em ` .env. Remova o ` XXXXe substitua-o pelo nome da organização do GitHub que você deseja usar neste script. NOTA : Se você estiver executando este script em várias organizações dentro de uma empresa, não poderá definir a GITHUB_ORGvariável `organizations`, mas sim a GITHUB_ENTERPRISEvariável com o nome da empresa. Em seguida yarn run getOrgs, você poderá executar `./organizations`, que coletará todas as organizações dinamicamente. Isso significa que você não precisará definir uma organização manualmente. No entanto, para a maioria dos casos, basta definir manualmente a organização específica na GITHUB_ORGvariável `organizations` onde você deseja que o script seja executado.

7. Atualize o LANGUAGE_TO_CHECKvalor encontrado em .env. Remova o XXXXe substitua-o pelo idioma que você gostaria de usar como filtro ao coletar repositórios. Observação : certifique-se de que esses valores estejam em letras minúsculas, como: javascript, typescript, python, go, ruby, c#, c++, java, oukotlin

8. Decida o que deseja habilitar. Atualize o ENABLE_ONvalor para escolher o que deseja habilitar nos repositórios encontrados em repos.json. Isso pode ser um ou vários valores. Se você estiver habilitando apenas a verificação de código (CodeQL), precisará definir ENABLE_ON=codescanning; se estiver habilitando tudo, precisará definir ENABLE_ON=codescanning,secretscanning,pushprotection,dependabot,dependabotupdates,actions. Você pode escolher um, dois ou três. O formato é uma lista separada por vírgulas.

9. OPCIONAL : Atualize o CREATE_ISSUEvalor true/falsedependendo se você deseja criar uma issue explicando o propósito do PR. Recomendamos isso, pois ajudará a explicar por que o PR foi criado e fornecerá algum contexto. No entanto, isso é opcional. O texto que está na issue pode ser modificado e encontrado aqui : ./src/utils/text/.

10. OPCIONAL : Se você for um cliente GHES, precisará definir a GHESvariável de ambiente truee, em seguida, definir GHES_SERVER_BASE_URLa URL da sua instância GHES. Exemplo https://octodemo.com:

11. OPCIONAL : Se você planeja habilitar recursos no nível da organização, yarn run enableOrgtambém terá a opção ENABLE_ON=...,automaticde configurá-los Automatically enable for new repositoriespara cada produto individualmente.

12. Se você estiver habilitando a Análise de Código (CodeQL), verifique o codeql-analysis.ymlarquivo. Este é um arquivo de exemplo; configure-o de acordo com as necessidades do seu repositório.

13. Execute `npm install` yarn installou ` npm installnpm install`, que instalará as dependências necessárias.

14. Execute `npm run build` yarn run buildou `npm npm run buildrun build`, que criará o pacote JavaScript a partir do TypeScript.

Existem dois passos simples para executar:

O primeiro passo é coletar os repositórios nos quais você deseja executar este script. Você tem três opções, como mencionado acima. A Opção 1 é automatizada e encontra todos os repositórios dentro de uma organização na qual você tem acesso de administrador. A Opção 2 também é automatizada e encontra todos os repositórios dentro de uma organização com base no idioma que você especificar. Ou, a Opção 3, que consiste na inserção manual dos repositórios nos quais você deseja executar este script. Veja mais informações abaixo.

OPÇÃO 1 (Preferencial)

# In the `.env` set the `LANGUAGE_TO_CHECK=` to the language. E.G.: `javascript`, `typescript`, `python`, `go`, `ruby`, `c#`, `c++`, `java`, or `kotlin`
yarn run getRepos # or npm run getRepos

Ao usar o GitHub Actions, geralmente constatamos (principalmente para linguagens que não são de compilação, como JavaScript) que o codeql-analysis.ymlarquivo é repetível e consistente em vários repositórios da mesma linguagem. Em cerca de 80% dos casos, as equipes podem reutilizar os mesmos arquivos de fluxo de trabalho para a mesma linguagem. Para Java e C++, esse número cai para cerca de 60%. Recomendamos habilitar a verificação de código em lote por linguagem porque o codeql-analysis.ymlarquivo proposto na solicitação de pull tem a maior probabilidade de ser o mais preciso. Mesmo que o arquivo precise ser alterado, a equipe que revisar a solicitação provavelmente precisará fazer apenas pequenas alterações. Recomendamos que você execute este comando primeiro para obter uma lista de repositórios para habilitar a verificação de código. Após executar o comando, você pode modificar o ./bin/repos.jsonarquivo. Apenas certifique-se de que seja um arquivo JSON válido antes de salvar.

Este script retorna apenas repositórios onde os resultados do CodeQL ainda não foram enviados para a verificação de código. Se algum resultado do CodeQL já tiver sido enviado para a verificação de código de um repositório, esse repositório não será retornado a esta lista. A motivação por trás disso é evitar a criação de pull requests em repositórios onde o CodeQL já foi habilitado.

OPÇÃO 2

# In the `.env` leave the `LANGUAGE_TO_CHECK=` empty to pull in all repos
yarn run getRepos # or npm run getRepos

Semelhante ao primeiro passo, outra abordagem automatizada é habilitar o acesso por usuário (ou seja, habilitar para todos os repositórios aos quais o usuário/PAT possui acesso administrativo). Essa abordagem será um pouco menos precisa, pois o codeql-analysis.ymlarquivo certamente precisará ser alterado entre um projeto Python e um projeto Java (caso você esteja habilitando o CodeQL). Mas o arquivo que você propôs será um bom ponto de partida. Após executar o comando, você poderá modificar o ./bin/repos.jsonarquivo. Apenas certifique-se de que seja um arquivo JSON válido antes de salvar.

Este script retorna apenas repositórios onde os resultados do CodeQL ainda não foram enviados para a verificação de código. Se algum resultado do CodeQL já tiver sido enviado para a verificação de código de um repositório, esse repositório não será retornado a esta lista. A motivação por trás disso é evitar a criação de pull requests em repositórios onde o CodeQL já foi habilitado.

OPÇÃO 3

Crie um arquivo chamado ` organization.json` repos.jsondentro do ./bin/diretório. Este arquivo precisa conter um array de objetos de organização, cada um com seu próprio array de objetos de repositório. A estrutura dos objetos deve ser semelhante a esta:

[
  {
    "login": "string <org>",
    "repos":
    [
      {
        "createIssue": "boolean",
        "enableCodeScanning": "boolean",
        "enableDependabot": "boolean",
        "enableDependabotUpdates": "boolean",
        "enablePushProtection": "boolean",
        "enableSecretScanning": "boolean",
        "enableActions": "boolean",
        "repo": "string <org/repo>",
      }
    ]
  }
]

Como você pode ver, o objeto aceita várias chaves booleanas: createIssue`true` enableCodeScanning, enableDependabot`false`, enableDependabotUpdates`false`, ` enablePushProtectionfalse`, `false` enableSecretScanninge ​​`true`, enableActionsalém de uma única chave de string, `repository` repo. Defina ` reporepository` como o nome do repositório onde você deseja executar este script. Defina ` enableDependabottrue` truese você também deseja habilitar os Alertas do Dependabot nesse repositório; defina como `false` falsese não quiser habilitá-los. O mesmo vale enableDependabotUpdatespara `dependabot_security_updates`, enableSecretScanning`dependabot_secret_scanning`, pushprotection`dependabot_secret_scanning_push_protection`, enableCodeScanning`dependabot_code_scanning_code_scanning_code_ql` e `dependabot_actions` enableActionspara habilitar as Ações. Por fim, defina createIssue`true` truese você deseja criar uma issue no repositório com o texto encontrado no ./src/utils/text/issueText.ts arquivo para complementar o PR.

NOTA: A conta que gerou o PAT precisa ter writeacesso ou privilégios superiores a qualquer repositório incluído na reposchave.

Execute o script que habilita a verificação de código (e/ou alertas do Dependabot/atualizações de segurança do Dependabot/verificação de segredos) em seu repositório, executando o seguinte comando:

yarn run start // or npm run start

Isso executará um script e você deverá ver o texto de saída aparecer na sua tela.

Após a execução do script, acesse o ~/Desktopdiretório do seu computador e exclua a tempGitLocationspasta que foi criada automaticamente.

Este cli.shé um script Bash que encapsula as funcionalidades desta ferramenta. Ele visa ampliar a funcionalidade da ferramenta e torná-la mais fácil de usar, a fim de alcançar uma implementação controlada do GHAS. O script está localizado no diretório raiz deste repositório.

A interface de linha de comando (CLI) ajuda a atender os seguintes casos de uso:

1. Crie um token de acesso pessoal (PAT) do GitHub.
2. Inicie a CLI executando o comando ./cli.shno diretório raiz deste repositório.
3. Selecione a opção 5. Configure optionpara criar o seu.env

• Preencha o PAT
• Preencha as funcionalidades do GHAS que você gostaria de ativar.
• Preencha os campos de programação que deseja filtrar (opcional)
• Se você estiver usando um servidor GitHub Enterprise, preencha o URL da sua instância (deixe em branco se estiver usando o GitHub.com).
• Selecione seu diretório temporário (ou deixe que a ferramenta o crie).

4. Selecione a 1. Get Organizations in your Enterpriseopção para obter uma lista de todas as suas organizações.
5. Selecione a 2. Enable features for Organization - For all repos at onceopção para ativar os recursos GHAS selecionados.
6. Ao ser solicitado a selecionar uma organização, digite allpara selecionar todas as organizações.
7. Selecione a 4. Print progressopção para verificar o progresso e confirmar se todas as organizações foram processadas.

1. Crie um token de acesso pessoal (PAT) do GitHub.
2. Inicie a CLI executando o comando ./cli.shno diretório raiz deste repositório.
3. Selecione a opção 5. Configure optionpara criar o seu.env

• Preencha o PAT
• Preencha as funcionalidades do GHAS que você gostaria de ativar.
• Preencha os campos de programação que deseja filtrar (opcional)
• Se você estiver usando um servidor GitHub Enterprise, preencha o URL da sua instância (deixe em branco se estiver usando o GitHub.com).
• Selecione seu diretório temporário (ou deixe que a ferramenta o crie).

4. Selecione a 1. Get Organizations in your Enterpriseopção para obter uma lista de todas as suas organizações.
5. Selecione a 2. Enable features for Organization - For all repos at onceopção para ativar os recursos GHAS selecionados.
6. Ao ser solicitado a selecionar uma organização, digite nextpara ver as próximas 10 organizações nas quais o GHAS ainda não foi ativado.
7. Digite o nome da organização na qual você deseja ativar os recursos GHAS selecionados.
8. Selecione a 4. Print progressopção para verificar o progresso e confirmar se todas as organizações foram processadas.
9. Repita os passos 5 a 7 até que todas as organizações tenham sido processadas.

Notas:

• A CLI criará automaticamente um .envarquivo no diretório raiz deste repositório. Este arquivo contém a configuração da ferramenta. Você pode editar este arquivo para alterar a configuração da ferramenta manualmente. Não é necessário executar o comando 5. Configure optionpara alterar a configuração.
• Você pode optar por usar ` 3. Enable features for Organization - Per repo–repository` em vez de `–repository` 2. Enable features for Organization - For all repos at once. Essa opção fará mais chamadas à API, pois habilita os recursos por repositório. O resultado será o mesmo se você for um usuário do GHEC; no entanto, se você for um usuário do GHES, não poderá habilitar dependabotupdateso recurso com `–repository` 3. Enable features for Organization - Per repo.
• Funciona 2. Enable features for Organization - For all repos at oncecom GHES 3.7 e versões superiores.
• Habilitar codescanningessa 2. Enable features for Organization - For all repos at onceopção usará a configuração padrão de verificação de código (Code Scanning Default Setup) [ https://github.blog/2023-01-09-default-setup-a-new-way-to-enable-github-code-scanning/ ]. Isso ainda não está disponível no GHES.

Existem alguns pontos importantes que você precisará levar em consideração se estiver executando este script em um Codespace do GitHub:

1. Você precisará adicionar o seguinte trecho ao arquivo .devcontainer/devcontainer.json:

  "codespaces": {
    "repositories": [
      {
        "name": "<ORG_NAME>/*",
        "permissions": "write-all"
      }
    ]
  }

O motivo pelo qual você precisa disso no seu .devcontainer/devcontainer.jsonarquivo é que GITHUB_TOKENo Codespace vinculado precisará acessar outros repositórios dentro da sua organização, com os quais este script pode interagir. Você precisará criar um novo Codespace depois de adicionar o código acima e enviá-lo para o seu repositório.

Você não precisa fazer o que foi descrito acima se não estiver executando o código a partir de um Codespace.

Como essa ferramenta utiliza um PAT (Personal Access Token) ou autenticação de aplicativo do GitHub sempre que a autenticação for necessária, ela pode ser executada de forma automatizada. Você pode ver no exemplo abaixo como executar a ferramenta em um fluxo de trabalho agendado do GitHub. Em vez de usar o .env arquivo, você pode configurar todas as variáveis .env.sample​​diretamente como variáveis ​​de ambiente. Isso permitirá que você utilize (facilmente) segredos de ações do GitHub para as credenciais do PAT ou do aplicativo do GitHub.

on:
  schedule:
    - cron: "5 16 * * 1"

env:
  APP_ID: ${{ secrets.GHAS_ENABLEMENT_APP_ID }}
  APP_CLIENT_ID: ${{ secrets.GHAS_ENABLEMENT_APP_CLIENT_ID }}
  APP_CLIENT_SECRET: ${{ secrets.GHAS_ENABLEMENT_APP_CLIENT_SECRET }}
  APP_PRIVATE_KEY: ${{ secrets.GHAS_ENABLEMENT_APP_PRIVATE_KEY }}
  ENABLE_ON: "codescanning,secretscanning,pushprotection,dependabot,dependabotupdates,actions"
  DEBUG: "ghas:*"
  CREATE_ISSUE: "false"
  GHES: "false"
  # Organization specific variables
  APP_INSTALLATION_ID: "12345678"
  GITHUB_ORG: "my-target-org"

jobs:
  enable-security-javascript:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          repository: NickLiffen/ghas-enablement
      - name: Get dependencies and configure
        run: |
          yarn
          git config --global user.name "ghas-enablement"
          git config --global user.email "ghas.enablement@example.com"
      - name: Enable security on organization (javascript)
        run: |
          npm run getRepos
          npm run start
        env:
          LANGUAGE_TO_CHECK: "javascript"
          TEMP_DIR: ${{ github.workspace }}

Você pode duplicar a última etapa para os outros idiomas comumente usados ​​em sua empresa/organização. Se você não configurou a ferramenta como um aplicativo do GitHub, pode remover todas as APP_*configurações e definir o arquivo GITHUB_API_TOKENde exemplo. Acima, utilizamos o arquivo CodeQL de exemplo para JavaScript incluído neste repositório. Como alternativa, você pode adicionar este fluxo de trabalho a um repositório contendo seus arquivos CodeQL personalizados e usá-los para substituir os exemplos.