allstar
v4.2
Allstar é um aplicativo GitHub que monitora continuamente organizações ou repositórios GitHub quanto à adesão às práticas recomendadas de segurança. Se o Allstar detectar uma violação da política de segurança, ele criará um problema para alertar o repositório ou o proprietário 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-o para o estado esperado.
O objetivo do Allstar é fornecer a você um controle preciso sobre os arquivos e configurações que afetam a segurança dos seus projetos. Você pode escolher quais políticas de segurança serão monitoradas no nível da organização e do repositório e como lidar com violações de políticas. Você também pode desenvolver ou contribuir com novas políticas.
Allstar é desenvolvido como parte do projeto OpenSSF Scorecard.
Se você estiver recebendo problemas indesejados criados pelo Allstar, siga estas instruções para cancelar.
Allstar é altamente configurável. Existem três níveis principais de controles:
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 Allstar podem optar por incluir ou não seu repositório nas imposições em nível de organização. Observação: esses controles no nível do repositório só funcionam quando a "substituição do repositório" é permitida nas configurações no nível da 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 serão habilitadas em repositórios específicos e quais ações a Allstar executará quando uma política for 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).
Antes de instalar o Allstar no nível organizacional, você deve decidir aproximadamente em quantos repositórios deseja que o Allstar seja executado. Isso o ajudará a escolher entre as estratégias 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 apenas a 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 a versão 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 cancelar as imposiçõ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 desejar executar o Allstar em todos os repositórios de uma organização ou desejar excluir apenas um pequeno número de repositórios ou um tipo específico (ou seja, público versus privado) de repositório. Desde a versão v4.3, globs são suportados para adicionar facilmente vários repositórios com um nome semelhante.
| Desativar (recomendado) optOutStrategy = verdadeiro | Ativar optOutStrategy = falso | |
|---|---|---|
| Comportamento padrão | Todos os repositórios estão habilitados | Nenhum repositório está ativado |
| Adicionando repositórios manualmente | Adicionar repositórios manualmente desativa o Allstar nesses repositórios | Adicionar repositórios manualmente habilita o Allstar nesses repositórios |
| Configurações adicionais | optOutRepos: Allstar será desabilitado nos repositórios listados optOutPrivateRepos: se for verdade, Allstar será desabilitado em todos os repositórios privados optOutPublicRepos: se verdadeiro, Allstar será desabilitado em todos os repositórios públicos (optInRepos: esta configuração será ignorada) | optInRepos: Allstar será habilitado nos repositórios listados (optOutRepos: esta configuração será ignorada) |
| Substituição do repositório | Se for verdade: os repositórios podem cancelar as imposições Allstar de sua organização usando as configurações em seu próprio arquivo de repositório. As configurações de aceitação no nível da organização que se aplicam a esse repositório são ignoradas. Se for falso: os repositórios não podem cancelar as imposições do Allstar conforme configurado no nível da organização. | Se for verdade: os repositórios podem aceitar as imposições Allstar da sua organização, mesmo que não estejam configurados para o repositório no nível da organização. As configurações de cancelamento no nível da organização que se aplicam a esse repositório são ignoradas. Se for falso: os repositórios não poderão aceitar as imposições Allstar se não estiverem configurados no nível da organização. |
As opções de início rápido e instalação manual envolvem a instalação do aplicativo Allstar. Você pode revisar as permissões solicitadas. O aplicativo solicita acesso de leitura à maioria das configurações e conteúdo de arquivos para detectar conformidade de segurança. Ele solicita acesso de gravação a problemas e verificações para poder criar problemas e permitir a ação block .
Esta opção de instalação habilitará o Allstar usando a estratégia Opt Out em todos os repositórios da sua organização. Todas as políticas atuais serão habilitadas e Allstar irá alertá-lo sobre violações de políticas registrando 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 posteriormente.
Esforço: muito fácil
Passos:
.allstarÉ isso! Todas as políticas Allstar atuais agora estão habilitadas em todos os seus repositórios. Allstar criará um problema se uma política for violada.
Para alterar qualquer configuração, consulte as instruções de instalação manual.
Esta opção de instalação orientará você 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:
Cada política pode ser configurada com uma ação que o Allstar executará ao 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. Atualmente, os registros são visíveis apenas para o operador do aplicativo. Os 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 receberá um ping 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 sobre o assunto e vinculado no corpo do problema. Assim que a violação for resolvida, o problema será automaticamente resolvido pela Allstar dentro de 5 a 10 minutos.fix : esta ação é específica da política. A política fará alterações nas configurações do GitHub para corrigir a violação da política. Nem todas as políticas serão capazes de apoiar isto (ver abaixo).Ações propostas, mas ainda não implementadas. As definições serão adicionadas no futuro.
block : Allstar pode definir uma verificação de status do GitHub e impedir que qualquer PR no repositório seja mesclado se a verificação falhar.email : Allstar enviaria um email para o(s) administrador(es) do repositório.rpc : Allstar enviaria um rpc para algum sistema específico da organização.Duas configurações estão disponíveis para configurar a ação do problema:
issueLabel está disponível no nível da organização e do repositório. A configuração substituirá o rótulo allstar padrão usado pelo Allstar para identificar seus problemas.
issueRepo está disponível no nível da organização. Defini-lo forçará todos os problemas criados na organização a serem criados no repositório especificado.
Semelhante à configuração de ativação do aplicativo 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. Tal como acontece com o aplicativo, as políticas são ativadas por padrão, e a ação log padrão também 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:
optConfig:
optOutStrategy: true
action: issue
Os detalhes de como funciona a ação fix para cada política são detalhados abaixo. Se omitido abaixo, a ação fix não será aplicável.
O arquivo de configuração desta política é denominado branch_protection.yaml e as definições de configuração estão aqui.
A política de proteção de branch verifica se as configurações de proteção de branch 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 para corrigir as configurações.
A ação fix alterará as configurações de proteção de ramificação para que estejam em conformidade com a configuração de política especificada.
O arquivo de configuração desta política é denominado binary_artifacts.yaml e as definições de configuração estão aqui.
Esta política incorpora a verificação do scorecard. Remova o artefato binário do repositório para obter conformidade. Como os resultados do scorecard podem ser detalhados, talvez seja necessário executar o próprio scorecard para ver todas as informações detalhadas.
O arquivo de configuração desta política é denominado codeowners.yaml e as definições de configuração estão aqui.
Esta política verifica a presença de um arquivo CODEOWNERS em seus repositórios.
O arquivo de configuração desta política é denominado outside.yaml e as definições de configuração estão aqui.
Esta política verifica se algum Colaborador Externo tem acesso de administrador (padrão) ou push (opcional) ao repositório. Somente membros da organização devem ter esse acesso, caso contrário, membros não confiáveis podem alterar as configurações de nível de administrador e cometer códigos maliciosos.
O arquivo de configuração desta política é denominado security.yaml e as definições de configuração estão aqui.
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 guia GitHub que ajuda você a enviar uma política de segurança para seu repositório.
O arquivo de configuração desta política é denominado dangerous_workflow.yaml e as definições de configuração estão aqui.
Esta política verifica os arquivos de configuração do fluxo de trabalho do GitHub Actions ( .github/workflows ) em busca de padrões que correspondam a comportamento perigoso conhecido. Consulte a documentação do OpenSSF Scorecard para obter mais informações sobre esta verificação.
O arquivo de configuração desta política é denominado scorecard.yaml e as definições de configuração estão aqui.
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 superior à configuração threshold . Consulte a documentação do OpenSSF Scorecard para obter mais informações sobre cada verificação.
O arquivo de configuração desta política é denominado actions.yaml e as definições de configuração estão aqui.
Esta política verifica os arquivos de configuração do fluxo de trabalho do GitHub Actions ( .github/workflows ) (e o fluxo de trabalho é executado em alguns casos) em cada repositório para garantir que estejam alinhados com as regras (por exemplo, require, deny) definidas na configuração no nível da organização para o política.
O arquivo de configuração desta política é denominado admin.yaml e as definições de configuração estão aqui.
Esta política verifica se por padrão todos os repositórios devem ter um usuário ou grupo atribuído como Administrador. Ele permite que você configure opcionalmente se os usuários podem ser administradores (em vez de equipes).
Veja este repositório como um exemplo de configuração do Allstar sendo usada. Como administrador da organização, considere um README.md com algumas informações sobre como o Allstar está sendo usado em sua organização.
Por padrão, espera-se que os arquivos de configuração em nível organizacional, como o arquivo allstar.yaml acima, estejam em um repositório .allstar . Se este repositório não existir, o diretório allstar do repositório .github será usado como local secundário. Para esclarecer, para allstar.yaml :
| Precedência | Repositório | Caminho |
|---|---|---|
| Primário | .allstar | allstar.yaml |
| Secundário | .github | allstar/allstar.yaml |
Isso também se aplica aos arquivos de configuração em nível organizacional para as políticas individuais, conforme descrito abaixo.
Allstar também procurará configurações de política em nível de repositório no repositório .allstar da organização, no diretório com o mesmo nome do repositório. Esta configuração é usada independentemente de a "substituição do repositório" estar desabilitada.
Por exemplo, Allstar pesquisará a configuração da política para um determinado repositório myapp na seguinte ordem:
| Repositório | Caminho | Doença |
|---|---|---|
myapp | .allstar/branch_protection.yaml | Quando a "substituição do repositório" é permitida. |
.allstar | myapp/branch_protection.yaml | Todos os tempos. |
.allstar | branch_protection.yaml | Todos os tempos. |
.github | allstar/myapp/branch_protection.yaml | Se o repositório .allstar não existir. |
.github | allstar/branch_protection.yaml | Se o repositório .allstar não existir. |
Para arquivos de configuração Allstar e de política em nível organizacional, você pode especificar o campo baseConfig para especificar 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 GitHub, mas queira manter uma única configuração Allstar. Sua organização principal é "acme" e o repositório acme/.allstar contém allstar.yaml :
optConfig :
optOutStrategy : true
issueLabel : allstar-acme
issueFooter : Issue created by Acme security team. Você também tem uma organização satélite do GitHub chamada "acme-sat". Você deseja reutilizar a configuração principal, mas aplique algumas alterações desabilitando o Allstar em determinados repositórios. O repositório acme-sat/.allstar contém allstar.yaml :
baseConfig : acme/.allstar
optConfig :
optOutRepos :
- acmesat-one
- acmesat-two Isso usará toda a configuração de acme/.allstar como configuração base, mas aplicará quaisquer alterações no arquivo atual sobre a configuração base. O método aplicado é descrito como JSON Merge Patch. O baseConfig deve ser um GitHub <org>/<repository> .
Veja CONTRIBUTING.md
