• Contexto
• Opções de nível de organização
• Opções de instalação
  • Crie seu GitHub App
  • Crie seu repositório de controle .allstar
  • Executando o Allstar como uma GitHub Action
  • Executando o Allstar como um daemon de serviço
• Migrando do app hospedado

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

Contribua

• Contribuindo

Visão geral

O que é o Allstar?

O 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 no nível 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 do Allstar

Desativando problemas indesejados

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

Começando

Contexto

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

• Nível da organização: Administradores da organização podem optar por habilitar o Allstar em:
  • todos os repositórios da organização;
  • 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 do repositório: Mantenedores de repositórios 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. Observação: esses controles de nível de repositório só funcionam quando a "substituição 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 toma 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 de nível de organização

Antes de instalar o Allstar no nível da organização, você deve decidir aproximadamente quantos repositórios deseja que o Allstar execute. 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 execute. 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 do total de seus repositórios, ou quiser testar o Allstar em um único repositório antes de habilitá-lo em mais. Desde o lançamento v4.3, globs são suportados para adicionar facilmente vários repositórios com um nome semelhante.

• A estratégia Opt Out (recomendada) habilita o Allstar em todos os repositórios e permite que você selecione manualmente os repositórios para optar por não participar 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 quiser optar por não participar apenas de um pequeno número de repositórios ou de um tipo específico (ou seja, público vs. privado) de repositório. Desde o lançamento v4.3, globs são suportados para adicionar facilmente vários repositórios com um nome semelhante.

Opções de instalação

O Allstar atua na sua organização como um GitHub App: você cria o app e executa o processo que se autentica como ele. A configuração, portanto, consiste em duas etapas comuns a todas as implantações — crie o app e crie o repositório de controle — e depois uma escolha de como executá-lo:

A Action é a opção de menor sobrecarga das duas e é por onde a maioria das organizações deve começar; você pode migrar para um daemon mais tarde sem alterar nenhuma configuração de política.

Crie seu GitHub App

Um App é uma identidade semelhante a um usuário com um conjunto de permissões na sua organização. O Allstar precisa de acesso de leitura à maioria das configurações e conteúdos de arquivos para detectar conformidade, e acesso de escrita a problemas e verificações para registrar problemas e suportar a ação block.

Siga as Instruções do operador - Crie um GitHub App e registre o ID do App e a chave privada. Ambos os modos de execução precisam deles.

Crie seu repositório de controle .allstar

O Allstar lê sua configuração de um repositório chamado .allstar na sua organização.

A maneira mais rápida de criar um é a partir do exemplo:

1. Abra o repositório de exemplo e clique no botão "Use this template"
2. No campo Nome do Repositório, digite .allstar
3. Clique em "Create repository from template"

Isso habilita todas as políticas atuais do Allstar em todos os repositórios usando a estratégia Opt Out, com a ação issue. Você pode alterar qualquer coisa depois.

Para controle granular desde o início — escolhendo a estratégia Opt In ou Opt Out e escrevendo arquivos de política individuais você mesmo — siga as instruções de instalação manual em vez disso.

Executando o Allstar como uma GitHub Action

Esta opção executa o Allstar como uma tarefa agendada usando GitHub Actions, portanto não há infraestrutura para operar além do próprio GitHub.

Siga as instruções de instalação do GitHub Actions para configurar uma Action recorrente no seu repositório .allstar, protegê-la e monitorar seus resultados.

Executando o Allstar como um daemon de serviço

Esta opção executa o Allstar como um processo persistente, que detecta e resolve violações continuamente em vez de em um cronograma.

Consulte as Instruções do operador para executar o processo, gerenciar segredos, dimensionamento e as variáveis de ambiente disponíveis.

Migrando do app hospedado

Se sua organização usava o app hospedado pela OpenSSF, sua configuração é mantida como está. O repositório de controle .allstar, o allstar.yaml e cada arquivo de política continuam funcionando sem alterações; o que você está substituindo é apenas o processo que os lê.

Para migrar:

1. Crie seu próprio GitHub App e instale-o na sua organização com o mesmo acesso a repositórios que o app hospedado tinha.
2. Mantenha seu repositório .allstar existente exatamente como está.
3. Execute o Allstar como uma Action ou como um daemon.
4. Desinstale o allstar-app da sua organização, se ele ainda aparecer em Configurações -> GitHub Apps.

Os problemas registrados anteriormente pelo app hospedado permanecem nos seus repositórios. Sua própria instância identifica seus problemas pelo mesmo rótulo allstar (ou seu issueLabel configurado), portanto ela os adotará e fechará conforme as violações forem resolvidas, em vez de registrar duplicatas.

Políticas e ações

Ações

Cada política pode ser configurada com uma ação que o Allstar tomará 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 e detalhes da execução da política são registrados. Os logs atualmente são visíveis apenas para o operador do app; planos para expô-los estão em discussão.
• issue: Esta ação cria um problema no 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 é notificado 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á fechado automaticamente pelo Allstar em 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. As 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 e-mail ao(s) administrador(es) do repositório.
• rpc: O Allstar enviaria um rpc para algum sistema específico da organização.

Configuração da ação

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

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

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

Políticas

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

Requisitos:

• O GitHub App Allstar deve ter a permissão de repositório Code scanning alerts definida como Read & write (escopo da API: security_events). Esta não está entre as permissões que o Allstar normalmente precisa, então adicione-a ao seu app antes de habilitar o upload de SARIF.
• O upload de SARIF não é bloqueante: se o upload 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 upload quando o repositório não recebeu push desde o último upload.

O upload de SARIF funciona com ambas as formas de executar o Allstar: como um daemon de serviço ou como uma GitHub Action.

GitHub Actions

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

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

Administradores de Repositório

O arquivo de configuração desta política é chamado 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 atribuído como Administrador. Ela permite que você configure opcionalmente se usuários podem ser administradores (em vez de equipes).

Políticas Futuras

• Garantir que o dependabot esteja habilitado.
• 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 na sua organização.

Avançado

Definições de Configuração

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

Localização secundária de configuração de nível organizacional

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

Isso também se aplica aos arquivos de configuração de nível organizacional das políticas individuais, conforme descrito abaixo.

Configurações de políticas de repositório no repositório da organização

O Allstar também procurará configurações de políticas de 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 a "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 de Mesclagem de Nível Organizacional

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

Suponha que você tenha várias organizações no GitHub, mas queira 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.

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

Contribuindo

Consulte CONTRIBUTING.md