Mascaramento de segredos no Ansible
Os playbooks do Ansible costumam precisar de senhas e tokens de API para se conectar a servidores e implantar aplicações. Esses valores também podem aparecer na saída das tarefas, por exemplo, quando um comando retorna um erro que contém uma senha.
O Ansible está adicionando o mascaramento de segredos para ajudar a resolver esse problema. Ele substitui valores secretos conhecidos por $REDACTED$ na saída, mantendo o restante da mensagem legível. As tarefas continuam usando os valores originais.
O recurso foi adicionado pelo pull request da Secret Masking API, integrado em 10 de setembro de 2026. No momento da publicação, ele está disponível nas versões de desenvolvimento do ansible-core 2.22. Ainda não faz parte de uma versão estável.
Vamos ver um playbook simples e, depois, como planejamos usar esse recurso no Semaphore UI.
Primeiro, registre um segredo
O Ansible precisa saber quais valores mascarar. A nova API registra valores de fontes de segredos conhecidas, como variáveis criptografadas com o Vault e parâmetros de módulos marcados com no_log.
Para uma variável comum, podemos usar o filtro register_secret. Uma variável passada por --extra-vars também precisa ser registrada; chamá-la de db_password não é suficiente.
Neste exemplo, usaremos uma senha de banco de dados fictícia. Crie um playbook chamado masking.yml:
- name: Try secret masking
hosts: localhost
gather_facts: false
vars:
db_password: "example-db-password-123456"
tasks:
- name: Register the password before using it
ansible.builtin.set_fact:
db_password: "{{ db_password | ansible.builtin.register_secret }}"
- name: Show a message containing the password
ansible.builtin.debug:
msg: "Connecting to db.internal with password={{ db_password }}"
A primeira tarefa registra a senha. O filtro retorna o valor original, então o playbook ainda pode usá-lo para se conectar ao banco de dados. O registro deve acontecer antes que qualquer tarefa exiba o valor.
Execute o playbook com uma versão de desenvolvimento do ansible-core 2.22:
ansible-playbook -i localhost, -c local masking.yml
A segunda tarefa exibirá esta mensagem:
Connecting to db.internal with password=$REDACTED$
Aqui exibimos a senha apenas para demonstrar o mascaramento. Em um playbook real, obtenha a senha da sua fonte de segredos e evite exibir credenciais deliberadamente.
Integração com o Semaphore UI
O Semaphore UI já sabe quais variáveis você marcou como secretas. Planejamos usar essa informação em versões futuras para registrar esses valores no Ansible automaticamente.
Para isso, usaremos a opção _SECRETS_INPUT_FILES do Ansible. Ela é configurada pela variável de ambiente _ANSIBLE_SECRETS_INPUT_FILES e permite que o Ansible leia uma lista de segredos antes de iniciar um playbook.
A entrada pode estar em YAML ou JSON. Um documento com a senha do nosso exemplo fica assim:
version: 1
secrets:
- example-db-password-123456
Essa lista informa ao Ansible o que deve ser mascarado. As próprias variáveis continuam sendo passadas separadamente ao playbook.
A integração planejada cobrirá valores secretos de:
- Grupos de variáveis (Variable Groups) — segredos salvos para uso nas suas tarefas.
- Questionários (Surveys) — respostas secretas inseridas ao iniciar uma tarefa.
Para esses valores, você não precisaria adicionar uma tarefa com register_secret a cada playbook.
Testamos essa abordagem em uma versão de desenvolvimento do ansible-core 2.22. Os valores registrados foram mascarados nas mensagens de debug, nos resultados dos comandos, nas mensagens de erro, na saída detalhada e no arquivo de log do Ansible. A passagem da lista por um pipe também funcionou, sem gravar um arquivo de segredos separado em disco.
A opção é interna no momento e pode mudar. O suporte no Semaphore UI está planejado para uma versão futura e exigirá uma versão compatível do Ansible.
Exemplo: implantar uma aplicação
Suponha que temos um modelo de tarefa (Task Template) que implanta uma aplicação. O script de implantação usa um token de API salvo como segredo em um grupo de variáveis.
Com a integração planejada, a tarefa funcionará assim:
- O Semaphore UI passa o token ao playbook.
- Antes da execução, ele também fornece o token à lista de mascaramento do Ansible por
_SECRETS_INPUT_FILES. - O playbook executa o script de implantação com o token real.
- Se o script incluir esse token na saída, o Ansible o mascara no resultado exibido.
Por exemplo, um token expirado poderia gerar esta mensagem no log da tarefa:
Deployment rejected: service=payments environment=staging token=$REDACTED$ reason=token expired
Podemos ver qual implantação falhou e por quê, sem mostrar o token a todos que leem o log. O mesmo fluxo se aplicará a um token temporário inserido em um campo secreto de um questionário.
Limitações
O mascaramento funciona com valores registrados. A implementação de desenvolvimento ignora segredos com menos de quatro caracteres, e um valor codificado ou transformado de outra forma pode precisar de um registro separado.
Ele também não protege credenciais em argumentos de processos, em arquivos escritos por um playbook ou em logs produzidos fora do Ansible. Continue usando no_log: true nas tarefas cuja saída inteira deve permanecer privada.
Com essa integração, os segredos marcados no Semaphore UI também serão conhecidos pelo sistema de mascaramento do Ansible. Isso ajudará a manter credenciais fora dos logs das tarefas, preservando informações úteis para solucionar problemas.