Allstar

Visão Geral

• O que é Allstar?

Novidades no Allstar

• whats-new.md

Desativando Problemas Indesejados

• Ajuda! Estou recebendo problemas criados pelo Allstar e não os quero!

Primeiros Passos

• Antecedentes
• Opções a Nível de Organização
• Opções de Instalação
  • Usando o aplicativo público Allstar
    • Instalação Rápida
    • Instalação Manual
  • Auto-hospedando Allstar
    • Executando Allstar como uma GitHub Action
    • Executando Allstar como um daemon de serviço

Políticas e Ações

• Ações
• Políticas

Avançado

• Definições de Configuração
• Exemplos de Configuração
• Execute Sua Própria Instância do Allstar

Contribuir

• Contribuindo

Visão Geral

O que é Allstar?

Allstar é um GitHub App que monitora continuamente organizações ou repositórios do GitHub quanto à adesão a práticas recomendadas de segurança. Se o Allstar detectar uma violação de política de segurança, ele cria um problema para alertar o proprietário do repositório ou da organização. Para algumas políticas de segurança, o Allstar também pode alterar automaticamente a configuração do projeto que causou a violação, revertendo-a para o estado esperado.

O objetivo do Allstar é dar a você controle finamente ajustado sobre os arquivos e configurações que afetam a segurança dos seus projetos. Você pode escolher quais políticas de segurança monitorar tanto no nível da organização quanto do repositório, e como lidar com violações de política. Você também pode desenvolver ou contribuir com novas políticas.

O Allstar é desenvolvido como parte do projeto OpenSSF Scorecard.

Novidades no Allstar

Desativando Problemas Indesejados

Se você está recebendo problemas indesejados criados pelo Allstar, siga estas instruções para optar por não participar.

Primeiros Passos

Antecedentes

Allstar é altamente configurável. Existem três níveis principais de controles:

• Nível de organização: Os administradores da organização podem optar por ativar o Allstar em:
  • todos os repositórios da org;
  • a maioria dos repositórios, exceto alguns que optaram por não participar;
  • apenas alguns repositórios que optaram por participar.

Essas configurações são feitas no repositório .allstar da organização.

• Nível de repositório: Os mantenedores de repositório em uma organização que usa o Allstar podem optar por incluir ou excluir seu repositório das aplicações de nível de organização. Nota: esses controles de nível de repositório só funcionam quando a "sobrescrita de repositório" é permitida nas configurações de nível de organização. Essas configurações são feitas no diretório .allstar do repositório.

• Nível de política: Administradores ou mantenedores podem escolher quais políticas estão habilitadas em repositórios específicos e quais ações o Allstar executa quando uma política é violada. Essas configurações são feitas em um arquivo yaml de política no repositório .allstar da organização (administradores) ou no diretório .allstar do repositório (mantenedores).

Opções a Nível de Organização

Antes de instalar o Allstar no nível da organização, você deve decidir aproximadamente em quantos repositórios deseja que o Allstar seja executado. Isso ajudará você a escolher entre as estratégias de Opt-In e Opt-Out.

• A estratégia Opt In permite que você adicione manualmente os repositórios nos quais deseja que o Allstar seja executado. Se você não especificar nenhum repositório, o Allstar não será executado, apesar de estar instalado. Escolha a estratégia Opt In se quiser aplicar políticas em apenas um pequeno número de seus repositórios totais, ou quiser experimentar o Allstar em um único repositório antes de ativá-lo em mais. Desde o lançamento v4.3, globs são suportados para facilitar a adição de vários repositórios com um nome semelhante.

• A estratégia Opt Out (recomendada) ativa o Allstar em todos os repositórios e permite que você selecione manualmente os repositórios para excluir das aplicações do Allstar. Você também pode optar por excluir todos os repositórios públicos, ou todos os repositórios privados. Escolha esta opção se quiser executar o Allstar em todos os repositórios de uma organização, ou se quiser excluir apenas um pequeno número de repositórios ou um tipo específico (por exemplo, público vs. privado) de repositório. Desde o lançamento v4.3, globs são suportados para facilitar a adição de vários repositórios com um nome semelhante.

Opções de Instalação

Tanto a opção Instalação Rápida quanto a Instalação Manual envolvem a instalação do aplicativo Allstar na sua Organização do GitHub. O aplicativo Allstar é operado pela OpenSSF e é uma boa escolha para a maioria dos repositórios de código aberto. Você pode revisar as permissões solicitadas. O aplicativo solicita acesso de leitura à maioria das configurações e conteúdos de arquivos para detectar conformidade de segurança. Ele solicita acesso de escrita a problemas e verificações para que possa criar problemas e permitir a ação block.

Se você não quiser usar o aplicativo Allstar operado pela OpenSSF, pode auto-hospedar o Allstar, criando seu próprio aplicativo Allstar. Isso fornece controle direto do aplicativo, com a contrapartida de precisar configurar, proteger, monitorar e manter o aplicativo.

Usando o aplicativo Allstar

A instalação Rápida ou Manual é recomendada, a menos que você tenha restrições específicas de segurança ou conformidade que impeçam o uso do aplicativo Allstar gerenciado pela OpenSSF.

Instalação Rápida

Esta opção de instalação ativará o Allstar usando a estratégia Opt Out em todos os repositórios da sua organização. Todas as políticas atuais serão ativadas, e o Allstar alertará você sobre violações de política abrindo um problema. Esta é a maneira mais rápida e fácil de começar a usar o Allstar, e você ainda pode alterar quaisquer configurações depois.

Esforço: muito fácil

Passos:

1. Instale o aplicativo Allstar
   1. Abra a página de instalação e clique em Configure
   2. Se você tiver várias organizações, selecione aquela em que deseja instalar o Allstar
   3. Selecione "All Repositories" em Repository Access, mesmo que você planeje desativar o Allstar em alguns repositórios depois
2. Faça um fork do repositório de exemplo
   1. Abra o repositório de exemplo e clique no botão "Use this template"
   2. No campo Repository Name, digite .allstar
   3. Clique em "Create repository from template"

É isso! Todas as políticas atuais do Allstar estão agora ativadas em todos os seus repositórios. O Allstar criará um problema se uma política for violada.

Para alterar quaisquer configurações, consulte as instruções de instalação manual.

Instalação Manual

Esta opção de instalação irá guiá-lo na criação de arquivos de configuração de acordo com a estratégia Opt In ou Opt Out. Esta opção fornece controle mais granular sobre as configurações desde o início.

Esforço: moderado

Passos:

1. Instale o aplicativo Allstar (escolha "All Repositories" em Repository Access, mesmo que você não planeje usar o Allstar em todos os seus repositórios)
2. Siga as instruções de instalação manual para criar arquivos de configuração do Allstar de nível de organização ou de repositório e arquivos de política individuais.

Auto-hospedando Allstar

Auto-hospede apenas se for necessário! O aplicativo Allstar requer configuração, proteção e manutenção contínua. Quando uma nova versão do Allstar for lançada, você precisará atualizar sua solução auto-hospedada.

Duas abordagens de auto-hospedagem são descritas:

• Executando Allstar como uma GitHub Action - Esta opção é relativamente leve e aproveita o GitHub Actions para executar verificações do Allstar.
• Executando Allstar como um daemon de serviço - Esta opção tem o mais alto nível de controle e assume que você pode executar um serviço persistente em um servidor confiável ou orquestrador de contêineres.

Executando Allstar como uma GitHub Action

Esta opção de instalação executa o Allstar como um trabalho agendado usando GitHub Actions.

Esforço: alto

Siga as instruções de instalação do GitHub Actions para:

1. Criar um novo GitHub App para uso do Allstar.
2. Criar um repositório de controle .allstar de nível de organização conforme descrito em instalação rápida ou instalação manual. (Ignore os passos para instalar o aplicativo Allstar gerenciado pela OpenSSF na sua organização.)
3. Configurar uma GitHub Action recorrente em .allstar para executar o Allstar em modo batch.
4. Monitorar a atividade e os resultados do trabalho.

Executando Allstar como um daemon de serviço

Esta opção de instalação executa o Allstar como um processo persistente.

Esforço: muito alto

Consulte Instruções para operador para mais informações, incluindo criação de um aplicativo Allstar, gerenciamento de segredos e variáveis de ambiente disponíveis.

Políticas e Ações

Ações

Cada política pode ser configurada com uma ação que o Allstar executará quando detectar que um repositório está fora de conformidade.

• log: Esta é a ação padrão, e na verdade ocorre para todas as ações. Todos os resultados de execução de política e detalhes são registrados. Os logs atualmente são visíveis apenas para o operador do aplicativo; planos para expô-los estão em discussão.
• issue: Esta ação cria um problema do GitHub. Apenas um problema é criado por política, e o texto descreve os detalhes da violação da política. Se o problema já estiver aberto, ele é cutucado com um comentário a cada 24 horas sem atualizações (atualmente não configurável pelo usuário). Se o resultado da política mudar, um novo comentário será deixado no problema e vinculado no corpo do problema. Uma vez que a violação seja resolvida, o problema será automaticamente fechado pelo Allstar dentro de 5 a 10 minutos.
• fix: Esta ação é específica da política. A política fará as alterações nas configurações do GitHub para corrigir a violação da política. Nem todas as políticas poderão suportar isso (veja abaixo).

Ações propostas, mas ainda não implementadas. Definições serão adicionadas no futuro.

• block: O Allstar pode definir uma Verificação de Status do GitHub e bloquear qualquer PR no repositório de ser mesclado se a verificação falhar.
• email: O Allstar enviaria um email para o(s) administrador(es) do repositório.
• rpc: O Allstar enviaria um rpc para algum sistema específico da organização.

Configuração de ação

Duas configurações estão disponíveis para configurar a ação de issue:

• issueLabel está disponível no nível da organização e do repositório. Configurá-lo substituirá o rótulo padrão allstar usado pelo Allstar para identificar seus problemas.

• issueRepo está disponível no nível da organização. Configurá-lo forçará todos os problemas criados na organização a serem criados no repositório especificado.

Políticas

Semelhante à configuração de ativação do aplicativo Allstar, todas as políticas são ativadas e configuradas com um arquivo yaml no repositório .allstar da organização ou no diretório .allstar do repositório. Assim como no aplicativo, as políticas são opt-in por padrão, e a ação padrão log não produzirá resultados visíveis. Uma maneira simples de ativar todas as políticas é criar um arquivo yaml para cada política com o conteúdo:```yaml optConfig: optOutStrategy: true action: issue

Os detalhes de como a ação `fix` funciona para cada política são descritos abaixo. Se omitido abaixo, a ação `fix` não é aplicável.

### Proteção de Ramo

O arquivo de configuração desta política é denominado `branch_protection.yaml`, e as [definições de configuração estão aqui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/branch#OrgConfig).

A política de proteção de ramo verifica se as [configurações de proteção de ramo](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) do GitHub estão configuradas corretamente de acordo com a configuração especificada. O texto do problema descreverá qual configuração está incorreta. Consulte a [documentação do GitHub](https://docs.github.com/en/github/administering-a-repository/defining-the-mergeability-of-pull-requests/about-protected-branches) para corrigir as configurações.

A ação `fix` alterará as configurações de proteção de ramo para estar em conformidade com a configuração de política especificada.

### Artefatos Binários

O arquivo de configuração desta política é denominado `binary_artifacts.yaml`, e as [definições de configuração estão aqui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/binary#OrgConfig).

Esta política incorpora a [verificação do scorecard](https://github.com/ossf/scorecard/#scorecard-checks). Remova o artefato binário do repositório para obter conformidade. Como os resultados do scorecard podem ser verbosos, pode ser necessário executar o [próprio scorecard](https://github.com/ossf/scorecard) para ver todas as informações detalhadas.

### CODEOWNERS

O arquivo de configuração desta política é denominado `codeowners.yaml`, e as [definições de configuração estão aqui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/codeowners#OrgConfig).

Esta política verifica a presença de um arquivo [`CODEOWNERS`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) nos seus repositórios.

### Colaboradores Externos

O arquivo de configuração desta política é denominado `outside.yaml`, e as [definições de configuração estão aqui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/outside#OrgConfig).

Esta política verifica se algum [Colaborador Externo](https://docs.github.com/en/organizations/managing-access-to-your-organizations-repositories/adding-outside-collaborators-to-repositories-in-your-organization) tem acesso de administrador (padrão) ou push (opcional) ao repositório. Apenas membros da organização devem ter esse acesso, caso contrário, membros não confiáveis podem alterar configurações de nível de administrador e enviar código malicioso.

### SECURITY.md

O arquivo de configuração desta política é denominado `security.yaml`, e as [definições de configuração estão aqui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/security#OrgConfig).

Esta política verifica se o repositório possui um arquivo de política de segurança em `SECURITY.md` e se não está vazio. O problema criado terá um link para a [aba do GitHub](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository) que ajuda a confirmar uma política de segurança no seu repositório.

### Workflow Perigoso

O arquivo de configuração desta política é denominado `dangerous_workflow.yaml`, e as [definições de configuração estão aqui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/workflow#OrgConfig).

Esta política será executada em **todos** os ramos, veja a justificativa [aqui](https://github.com/ossf/allstar/issues/569).

Esta política verifica os arquivos de configuração do GitHub Actions Workflows (`.github/workflows`), em busca de padrões que correspondam a comportamentos perigosos conhecidos. Consulte a [documentação do OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md#dangerous-workflow) para mais informações sobre esta verificação.

### Verificação Genérica de Scorecard

O arquivo de configuração desta política é denominado `scorecard.yaml`, e as [definições de configuração estão aqui](https://pkg.go.dev/github.com/ossf/allstar/pkg/policies/scorecard#OrgConfig).

Esta política executa qualquer verificação de scorecard listada na configuração `checks`. Todas as verificações executadas devem ter uma pontuação igual ou acima da configuração `threshold`. Consulte a [documentação do OpenSSF Scorecard](https://github.com/ossf/scorecard/blob/main/docs/checks.md) para mais informações sobre cada verificação.

#### Upload SARIF

A política de Scorecard pode opcionalmente fazer upload dos resultados como [SARIF](https://sarifweb.azurewebsites.net/) para a aba **Segurança > Varredura de Código** de cada repositório. Isso dá aos administradores da organização visibilidade sobre as descobertas do Scorecard juntamente com outras ferramentas de segurança (CodeQL, Dependabot, etc.) sem exigir configuração de workflow por repositório.

Para ativar o upload SARIF, adicione o campo `upload` ao seu `scorecard.yaml`:```yaml
optConfig:
  optOutStrategy: true
action: issue
checks:
  - Binary-Artifacts
  - Signed-Releases
threshold: 8
upload:
  sarif: true

Requisitos:

• O GitHub App Allstar deve ter a permissão Code scanning alerts do repositório definida como Read & write (escopo da API: security_events). Operadores auto-hospedados precisam adicionar esta permissão ao seu GitHub App. O App Allstar público operado pela OpenSSF ainda não inclui esta permissão.
• O envio de SARIF não é bloqueante: se o envio falhar (por exemplo, devido a permissões ausentes), a verificação da política continua normalmente.
• A detecção de alterações compara o SHA do commit HEAD do repositório e ignora a verificação e o envio quando o repositório não recebeu push desde o último envio.

O envio de SARIF funciona com ambos os modos de implantação auto-hospedados: executando como um daemon de serviço ou como uma GitHub Action.

GitHub Actions

O arquivo de configuração desta política é nomeado actions.yaml, e as definições de configuração estão aqui.

Esta política verifica os arquivos de configuração dos workflows do GitHub Actions (.github/workflows) (e execuções de workflow em alguns casos) em cada repositório para garantir que estejam em conformidade com as regras (ex.: exigir, negar) definidas na configuração de nível de organização para a política.

Administradores de Repositórios

O arquivo de configuração desta política é nomeado admin.yaml, e as definições de configuração estão aqui.

Esta política verifica que, por padrão, todos os repositórios devem ter um usuário ou grupo designado como Administrador. Permite configurar opcionalmente se usuários podem ser administradores (em vez de equipes).

Políticas Futuras

• Garantir que o dependabot esteja ativado.
• Verificar se as dependências estão fixadas/congeladas.

Exemplo de Repositório de Configuração

Consulte este repositório como um exemplo do uso da configuração do Allstar. Como administrador da organização, considere um README.md com algumas informações sobre como o Allstar está sendo usado em sua organização.

Avançado

Definições de Configuração

• Configuração de habilitação em nível de organização
• Configuração de substituição de repositório

Localização secundária da configuração em nível de organização

Por padrão, os arquivos de configuração em nível de organização, como o allstar.yaml acima, são esperados em um repositório .allstar. Se este repositório não existir, o diretório allstar do repositório .github é usado como localização secundária. Para esclarecer, para allstar.yaml:

Isso também é verdadeiro para os arquivos de configuração em nível de organização das políticas individuais, conforme descrito abaixo.

Configurações de política de repositório no Repositório da Organização

O Allstar também procurará configurações de política em nível de repositório no repositório .allstar da organização, sob o diretório com o mesmo nome do repositório. Esta configuração é usada independentemente de "substituição de repositório" estar desabilitada.

Por exemplo, o Allstar consultará a configuração de política para um determinado repositório myapp na seguinte ordem:

Localização da Configuração Base e Mesclagem em Nível de Organização

Para arquivos de configuração de política e Allstar em nível de organização, você pode especificar o campo baseConfig para indicar outro repositório que contém a configuração base do Allstar. Isto é melhor explicado com um exemplo.

Suponha que você tenha várias organizações no GitHub, mas deseje manter uma única configuração do Allstar. Sua organização principal é "acme", e o repositório acme/.allstar contém allstar.yaml:```yaml optConfig: optOutStrategy: true issueLabel: allstar-acme issueFooter: Issue created by Acme security team.

Você também tem uma organização satélite no GitHub chamada "acme-sat". Você deseja reutilizar a configuração principal, mas aplicar algumas alterações adicionais desativando o Allstar em alguns repositórios. O repositório `acme-sat/.allstar` contém `allstar.yaml`:
```yaml```yaml
baseConfig: acme/.allstar
optConfig:
  optOutRepos:
  - acmesat-one
  - acmesat-two

Isto usará toda a configuração de acme/.allstar como configuração base, mas depois aplicará quaisquer alterações no arquivo atual sobre a configuração base. O método pelo qual isto é aplicado é descrito como um JSON Merge Patch. O baseConfig deve ser um GitHub <org>/<repository>.

Contribuindo

Veja CONTRIBUTING.md