Compartilhar via


Como usar variáveis e parâmetros com segurança em seu pipeline

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2020

Este artigo discute como usar variáveis e parâmetros com segurança para coletar entradas de usuários de pipeline. Se você quiser saber mais sobre como usar variáveis e parâmetros, confira:

Tenha cuidado com as variáveis secretas. As maneiras recomendadas de definir variáveis secretas estão na interface do usuário, em um grupo de variáveis e em um grupo de variáveis do Azure Key Vault. Para obter mais informações, consulte definir variáveis de ambiente.

Variáveis

As variáveis podem ser uma maneira conveniente de coletar informações do usuário antecipadamente. Você também pode usar variáveis para passar dados de etapa em etapa em um pipeline.

Mas use variáveis com cuidado. As variáveis recém-criadas, sejam elas definidas em YAML ou escritas por um script, são de leitura/gravação por padrão. Uma etapa downstream pode alterar o valor de uma variável de uma maneira que você não espera.

Por exemplo, seu script diz:

msbuild.exe myproj.proj -property:Configuration=$(MyConfig)

Uma etapa anterior poderia definir MyConfig como Debug & deltree /y c:. Embora este exemplo exclua apenas o conteúdo do agente de build, você pode imaginar como essa configuração poderia facilmente se tornar muito mais perigosa.

Você pode tornar as variáveis somente leitura. Variáveis do sistema como Build.SourcesDirectory, variáveis de saída de tarefa e variáveis de tempo de espera são sempre somente leitura. Variáveis criadas no YAML ou criadas em tempo de execução por um script podem ser designadas como somente leitura. Quando um script ou tarefa cria uma variável, ele pode passar o sinalizador isReadonly=true no próprio comando de registro em log para tornar a variável somente leitura.

No YAML, você pode especificar variáveis somente leitura usando uma chave específica:

variables:
- name: myReadOnlyVar
  value: myValue
  readonly: true

Variáveis de tempo de espera

Ao definir uma variável no editor de interface do usuário do Pipelines, você pode optar por permitir que os usuários substituam o valor dela ao executar o pipeline. Chamamos essa variável de tempo de espera. As variáveis de tempo de espera são sempre definidas no editor de interface do usuário de Pipelines.

Captura de tela da definição de uma variável de tempo de espera.

As variáveis de tempo de espera são expostas ao usuário final quando executam manualmente um pipeline e podem alterar seus valores. Captura de tela da atualização do valor de uma variável de tempo de espera.

Os usuários precisam de permissão para editar a configuração de enfileiramento de builds no pipeline e especificar as variáveis definidas de tempo de espera.

Limitar as variáveis que podem ser definidas no momento da colocação na fila

A interface do usuário e a API REST usadas para executar um pipeline fornecem meios para os usuários definirem novas variáveis durante o tempo de espera.

Captura de tela da adição de uma variável de tempo de espera pouco antes de executar o pipeline.

Nos primeiros dias do Azure Pipelines, essa funcionalidade tinha alguns problemas:

  • Ela permitia que os usuários definissem novas variáveis que não são explicitamente definidas pelo autor do pipeline na definição.
  • Ela permitia que os usuários substituíssem as variáveis do sistema.

Para corrigir esses problemas, definimos uma configuração para limitar as variáveis que podem ser definidas no momento da fila. Com essa configuração habilitada, somente as variáveis que são explicitamente marcadas como "Configuráveis no tempo de fila" podem ser definidas. Em outras palavras, você pode definir todas as variáveis no momento da fila, a menos que essa configuração esteja habilitada.

A configuração foi projetada para funcionar nos níveis de organização e projeto.

  1. Nível de organização Quando a configuração está ativada, ela impõe que, para todos os pipelines em todos os projetos da organização, somente as variáveis que são explicitamente marcadas como "Definível no tempo de espera" podem ser definidas. Quando a configuração está desativada, cada projeto pode optar por restringir ou não as variáveis definidas no tempo de espera. A configuração é uma alternância em Configurações da Organização – > Pipelines –> Configurações. Somente administradores de coleção de projetos podem habilitar ou desabilitar essa configuração. Captura de tela das variáveis limitantes que podem ser definidas no tempo de espera no nível da organização.
  2. Nível de projeto. Quando a configuração está ativada, ela impõe que, para todos os pipelines do projeto, somente as variáveis marcadas explicitamente como "Definíveis no tempo de espera" podem ser definidas. Se a configuração estiver ativada no nível da organização, ela estará ativada para todos os projetos e não poderá ser desativada. A configuração é uma alternância em Configurações da organização –> Pipelines –> Configurações. Somente os administradores do projeto podem habilitar ou desabilitar essa configuração. Captura de tela de limitação de variáveis que podem ser definidas no tempo de espera no nível de projeto.

Vejamos um exemplo. Digamos que a configuração esteja ativada e que o pipeline defina uma variável chamada my_variable que não é configurável em tempo de espera. Captura de tela da definição de uma variável em um pipeline clássico.

Em seguida, suponha que você deseja executar o pipeline. O painel Variáveis não mostra nenhuma variável e o botão Adicionar variável está ausente.

Captura de tela do painel variáveis com a configuração ativada.

O uso das chamadas à API REST Builds – Fila e Execuções – Executar Pipeline para enfileirar uma execução de pipeline e definir o valor de my_variable ou de uma nova variável falhará com um erro semelhante ao mostrado a seguir.

{
  "$id": "1",
  "innerException": null,
  "message": "You can't set the following variables (my_variable). If you want to be able to set these variables, then edit the pipeline and select Settable at queue time on the variables tab of the pipeline editor.",
  "typeName": "Microsoft.Azure.Pipelines.WebApi.PipelineValidationException, Microsoft.Azure.Pipelines.WebApi",
  "typeKey": "PipelineValidationException",
  "errorCode": 0,
  "eventId": 3000
}

Parâmetros

Ao contrário das variáveis, os parâmetros do pipeline não podem ser alterados por um pipeline durante a execução. Os parâmetros têm tipos de dados como number e string e podem ser restritos a um subconjunto de valores. Restringir os parâmetros é útil quando uma parte do pipeline configurável pelo usuário deve obter um valor somente de uma lista restrita. A configuração garante que o pipeline não receba dados arbitrários.

Habilitar a validação de parâmetros de argumentos de tarefas do shell

Pipelines podem fazer referência a tarefas executadas no pipeline. Várias tarefas incluídas no Azure DevOps têm um parâmetro arguments que permite especificar mais opções para a tarefa.

Quando a configuração Habilitar validação de parâmetro de argumentos de tarefas do shell está habilitada, o parâmetro arguments é revisado em busca de quaisquer caracteres que possam não ser executados corretamente pelo shell. Caracteres de exemplo incluem ponto-e-vírgula, aspas e parênteses.

Semelhante à opção Limitar variáveis que podem ser definidas no tempo de espera, a opção Habilitar validação do parâmetro de argumentos de tarefas do shell pode ser configurada no nível da organização em Configurações>Pipelines>Configurações ou no nível do projeto em Configurações>Pipelines>Configurações.

Quando habilitado, há um problema de validação detectado, uma mensagem de erro como a seguinte é registrada: Detected characters in arguments that may not be executed correctly by the shell. Please escape special characters using backtick (`).

Para resolver o problema, ajuste os argumentos escapando caracteres especiais, conforme indicado na mensagem de erro.

Quando a oopção Habilitar validação do parâmetro de argumentos de tarefas do shell está habilitada, a validação é aplicada ao parâmetro arguments nas tarefas a seguir.

  • PowerShell
  • BatchScript
  • Bash
  • SSH
  • AzureFileCopy
  • WindowsMachineFileCopy

Próximas etapas

Depois de proteger suas entradas, você também precisa proteger sua infraestrutura compartilhada.