Protegendo endpoints com firewall de pacotes do GitHub

Proteger instalações de dependência nos computadores dos desenvolvedores, agentes de IA e executores de CI com GitHub package firewall.

Neste artigo

Observação

Esse recurso está atualmente dentro prévia pública e está sujeito a alterações.

Sobre GitHub package firewall

O GitHub package firewall fica entre seus endpoints e registries de pacotes. Ele avalia os downloads de pacotes em relação a políticas como idade mínima do pacote e avisos de malware e bloqueia downloads que não atendem a essas políticas. Você pode usá-lo para proteger instalações de dependência em builds de CI, sessões de agente de IA e desenvolvimento local.

Para usar o firewall, configure os controles de política da sua empresa e configure seus endpoints para solicitar pacotes por meio do firewall, em vez de diretamente de um registro. Você também pode conceder acesso para gerenciar a política por meio de uma função personalizada.

Configurando controles de política

Os gerentes de segurança da empresa e os administradores corporativos podem configurar controles de política.

  1. Navegue até sua empresa. Por exemplo, na página Enterprises em GitHub.com.
  2. Na parte superior da página, clique em Políticas.
  3. Na barra lateral, clique em Package firewall.
  4. Configure os controles de política descritos nas seções a seguir. Esses controles se aplicam a todas as solicitações que passam pelo firewall.

Bloquear malware conhecido

Quando habilitado, esse controle verifica o GitHub Advisory Database em busca de avisos de malware ativos e bloqueia pacotes com um aviso correspondente. Esse controle usa como padrão Ativado.

Avisos de vulnerabilidade bloqueados

Esse controle verifica o GitHub Advisory Database quanto a vulnerabilidades que afetam a versão do pacote solicitada. Selecione a severidade mínima do aviso que bloqueia uma instalação: somente crítica, alta ou superior, média ou superior ou qualquer gravidade. Esse controle usa como padrão somente Crítico.

Rebaixamentos de atestação de bloco

Esse controle compara as atestações da versão do pacote solicitada com as das versões anteriores. Se o pacote anteriormente tinha atestados SLSA, mas a versão solicitada não tem, o firewall bloqueará o download. Atestações ausentes podem indicar um processo de publicação comprometido. Para obter mais informações sobre atestações, consulte Atestados de artefatos. Esse controle usa como padrão Ativado.

Bloquear scripts de instalação recém-introduzidos

Esse controle verifica se o pacote adicionou recentemente scripts que são executados durante a instalação, como preinstall ou postinstall scripts. Esses scripts podem executar comandos arbitrários em seu sistema e podem ser usados para roubar credenciais. Esse controle usa como padrão Ativado.

Tempo mínimo de existência do pacote

Esse controle define um período de resfriamento para versões de pacote recém-publicadas. O firewall bloqueia versões mais recentes do que o período mínimo configurado, permitindo tempo para que as ameaças sejam descobertas antes de instalá-las.

Defina a idade mínima como um valor entre 1 e 365 dias ou defina-a como 0 para desabilitar o controle. O padrão é 1 dia.

Configurando endpoints para usar Package firewall

Configure o gerenciador de pacotes para buscar pacotes da URL do firewall em vez do registro público padrão.

Token de autenticação

A URL do Registro é específica para sua empresa. Cada solicitação deve incluir um token de autenticação associado a uma conta de usuário ou bot que seja membro da organização. O token não precisa de nenhuma permissão elevada além do acesso somente leitura a repositórios públicos. Para obter mais informações, consulte Gerenciar seus tokens de acesso pessoal.

Configurando o npm

Use o arquivo .npmrc no nível do usuário para configurar o npm. Nos exemplos, substitua ENTERPRISE pelo slug da empresa. Defina a variável de GITHUB_TOKEN ambiente como um GitHub token com acesso à sua empresa. Armazene o token com segurança, como em um segredo de CI, e não faça commit dele em um repositório.

  1. Adicione a seguinte configuração ao arquivo .npmrc em nível de usuário:

    registry=https://package-firewall.githubapp.com/npm/enterprises/ENTERPRISE
//package-firewall.githubapp.com/npm/enterprises/ENTERPRISE/:_authToken=${GITHUB_TOKEN}

Como alternativa, defina as mesmas configurações pela linha de comando:

npm config set registry \
  https://package-firewall.githubapp.com/npm/enterprises/ENTERPRISE
npm config set \
  '//package-firewall.githubapp.com/npm/enterprises/ENTERPRISE/:_authToken=${GITHUB_TOKEN}'

Configurando o Artifactory

Você pode configurar o JFrog Artifactory para recuperar pacotes por meio do firewall. Seus pontos de extremidade continuam a usar o Artifactory, que permite combinar pacotes públicos e privados ao aplicar políticas de firewall a pacotes recuperados por meio do firewall.

Você deve ter privilégios de administrador em sua instância do Artifactory.

Observação

O suporte ao Artifactory é experimental. Para compartilhar sugestões ou preocupações sobre o suporte do Artifactory, consulte a discussão da comunidade.

  1. No Artifactory, clique na guia Administração e, em seguida, clique em Criar um repositório.
  2. Selecione Remoto como o tipo de repositório e selecione npm como o tipo de pacote.
  3. No campo "Chave do Repositório", digite um nome como gh-package-firewall.
  4. No campo "URL", digite https://package-firewall.githubapp.com/npm/enterprises/ENTERPRISE, substituindo ENTERPRISE pelo slug da empresa.
  5. No campo "Senha / Token de Acesso", cole um personal access token válido e selecione Habilitar Autenticação de Token.
  6. Selecione o Stage em que você deseja usar o firewall, com base na configuração do Artifactory.
  7. No campo "Padrão", digite **/* para incluir todos os caminhos do pacote.
  8. Clique em Salvar.
  9. Crie ou atualize um repositório npm virtual para incluir este remoto e seus repositórios npm privados. Exclua os remotos que buscam pacotes diretamente do registro npm público para que eles não possam ignorar o firewall.
  10. Siga as instruções Configurar do repositório virtual para configurar seus endpoints.

Permissões refinadas

Por padrão, os administradores corporativos e os gerentes de segurança da empresa podem modificar a política de firewall. Para conceder a outros usuários acesso para exibir e alterar a política, adicione a permissão granular "Editar política de firewall de pacote no nível empresarial" a uma função personalizada e, em seguida, atribua essa função a uma equipe ou indivíduo.

Gerenciando exceções

Se o firewall bloquear um pacote necessário, você poderá solicitar uma exceção à política. Por exemplo, uma nova versão do pacote que inclui uma correção de segurança pode ser bloqueada pela política de idade mínima do pacote.

Solicitando uma exceção

Quando o firewall bloqueia um pacote, a saída npm ou o log de CI/CD inclui uma URL para solicitar uma exceção. Por exemplo:

npm notice testcontainers: 1 version blocked by package-firewall due to security policies (version cooldown). Request an override: https://github.com/enterprises/octocats/security/bypass-requests/package-firewall/new?ecosystem=npm&package=testcontainers

  1. Abra a URL no navegador.

  2. Examine os campos pré-preenchidos e forneça as informações ausentes:

    • "Repositório": o repositório em que o bloco ocorreu
    • "Ecossistema": o ecossistema de pacotes (atualmente, há suporte apenas para npm)
    • "Nome do pacote": o nome do pacote, incluindo o @scope prefixo, se aplicável
    • "Versão": a versão que você tentou instalar
    • "Motivo": por que o pacote deve ser desbloqueado
    • "Adicionar um comentário": contexto adicional para revisores

  3. Envie a solicitação.

Revisão e aprovação de solicitações de exceção

Os administradores corporativos e os gerentes de segurança da empresa podem examinar as solicitações de exceção.

  1. Navegue até sua empresa. Por exemplo, na página Enterprises em GitHub.com.
  2. Na parte superior da página, clique em Security and quality.
  3. Na barra lateral, clique em Package firewall bypass.
  4. Na lista "Solicitações de bypass do firewall de pacote", use a barra de pesquisa para localizar uma solicitação e clique na solicitação.
  5. Na caixa de diálogo "Revisar substituição permitida de pacote", examine a exceção solicitada.
  6. Opcionalmente, para permitir todas as versões do pacote, substitua a versão solicitada no campo "Versão ou intervalo para permitir" por *. Isso amplia a exceção além da versão solicitada.
  7. Adicione um comentário explicando sua decisão e clique em Aprovar solicitação.

Por exemplo, você pode permitir todas as versões de um pacote pertencente à empresa em vez de exigir uma exceção separada sempre que a política mínima de idade do pacote bloquear uma nova versão.

Gerenciando aprovações

As solicitações de bypass aprovadas são adicionadas à política de firewall. Os administradores corporativos e os gerentes de segurança da empresa podem examinar e remover exceções desatualizadas ou indesejadas, incluindo exceções adicionadas manualmente.

  1. Navegue até sua empresa. Por exemplo, na página Enterprises em GitHub.com.
  2. Na parte superior da página, clique em Políticas.
  3. Na barra lateral, clique em Package firewall.
  4. Em "Sobrescritas", clique em Sobrescritas de pacote.
  5. Para remover uma exceção da política, ao lado da exceção, clique em .

Leitura adicional