Bem-vindo à aula 90 do curso de PowerShell! Hoje vamos explorar um tópico essencial para qualquer profissional que automatiza tarefas: o gerenciamento de segredos. Em muitos scripts, precisamos lidar com senhas, chaves de API, tokens e outras informações sensíveis. Armazená-los em texto puro ou embuti-los no código é um risco de segurança enorme. Nesta aula, você aprenderá a usar o módulo Microsoft.PowerShell.SecretManagement para armazenar e recuperar segredos de forma segura, além de entender o conceito de vaults e as boas práticas recomendadas.

O módulo SecretManagement foi introduzido no PowerShell 5.1 e aprimorado no PowerShell 7, e fornece uma interface unificada para interagir com diferentes sistemas de armazenamento de segredos, como o Windows Credential Manager, o KeePass, o Azure Key Vault, entre outros. Ele permite que seus scripts acessem segredos sem expô-los em código ou logs, centralizando a gestão e facilitando a rotação de credenciais.

Módulo SecretManagement

O módulo Microsoft.PowerShell.SecretManagement é a base para o gerenciamento de segredos no PowerShell. Ele fornece cmdlets como Get-Secret, Set-Secret, Remove-Secret, Get-SecretInfo e Register-SecretVault. Para começar, você precisa instalar o módulo a partir da PowerShell Gallery. Em versões recentes do PowerShell (7.3+), ele já vem incluso, mas é sempre bom verificar e atualizar.

O módulo define um padrão para que provedores de vault possam se integrar. Você pode instalar também módulos de extensão específicos para cada serviço, como Microsoft.PowerShell.SecretStore (vault local padrão) ou Az.KeyVault para Azure. O SecretManagement cuida da lógica de enumeração e recuperação, enquanto o provedor cuida do armazenamento físico.

Vamos ver como instalar e listar os módulos relacionados:

# Instalar o módulo SecretManagement (se não tiver)
Install-Module -Name Microsoft.PowerShell.SecretManagement -Force

# Instalar o módulo SecretStore (vault local padrão)
Install-Module -Name Microsoft.PowerShell.SecretStore -Force

# Verificar os módulos instalados
Get-Module -ListAvailable Microsoft.PowerShell.Secret*

O SecretStore é um vault local que armazena os segredos em um arquivo criptografado no seu computador. Ele é uma boa opção para desenvolvimento e uso pessoal. Para uso em produção, você pode optar por vaults mais robustos, como Azure Key Vault ou HashiCorp Vault, mas os princípios são os mesmos.

Vaults

Um vault é um repositório seguro onde os segredos são armazenados. O SecretManagement permite que você registre um ou mais vaults e use o nome do vault para especificar onde deseja armazenar ou recuperar um segredo. Cada vault tem um nome único e é associado a um módulo de extensão (provedor).

Para registrar um novo vault, você usa o cmdlet Register-SecretVault. O SecretStore, por exemplo, é registrado automaticamente na primeira vez que você o usa, mas você pode registrar manualmente. Vamos ver um exemplo prático:

# Registrar um novo vault usando o SecretStore
Register-SecretVault -Name "MeuVault" -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault

# Listar todos os vaults registrados
Get-SecretVault

O parâmetro -DefaultVault define esse vault como o padrão, ou seja, você não precisa especificar o nome toda vez. Você pode ter vários vaults, por exemplo, um para desenvolvimento e outro para produção. Para armazenar um segredo em um vault específico, use o parâmetro -Vault no cmdlet Set-Secret.

O SecretStore cria um arquivo chamado secrets.json no diretório do usuário, protegido pela API de criptografia do Windows (DPAPI) ou por uma senha que você define. Quando você registra um vault com o SecretStore, ele pergunta se você deseja criar uma senha para proteger o arquivo. Se você optar por uma senha, precisará digitá-la toda vez que o PowerShell precisar acessar o vault. Caso contrário, ele usa a conta do usuário Windows para criptografar.

Vamos ver como criar um vault com senha:

# Criar um vault com senha (interativo)
Register-SecretVault -Name "VaultComSenha" -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault
# O PowerShell solicitará uma senha para o vault

Lembre-se de que a senha do vault é diferente da sua senha do Windows. Ela é usada para descriptografar o arquivo de segredos. Se você perder essa senha, não será possível recuperar os segredos, então guarde-a em um local seguro (como um gerenciador de senhas).

Recuperando segredos

Agora que temos um vault configurado, vamos aprender a armazenar e recuperar segredos. O cmdlet Set-Secret cria ou atualiza um segredo. O segredo pode ser uma string simples, um objeto PSCredential, um byte array ou até mesmo um objeto complexo. Vamos ver exemplos:

# Armazenar uma string simples
Set-Secret -Name "ApiKey" -Secret "12345-abcdef"

# Armazenar uma credencial (usuário e senha)
$cred = Get-Credential
Set-Secret -Name "CredencialBanco" -Secret $cred

# Armazenar um byte array (por exemplo, uma chave de criptografia)
$key = [byte[]] (0x01, 0x02, 0x03, 0x04)
Set-Secret -Name "ChaveCripto" -Secret $key

Para recuperar um segredo, usamos Get-Secret. O tipo de retorno depende do que foi armazenado. Se for uma string, retorna uma string; se for um PSCredential, retorna um objeto PSCredential. Veja:

# Recuperar a string
$apiKey = Get-Secret -Name "ApiKey"
Write-Host "A chave é: $apiKey"

# Recuperar a credencial
$credBanco = Get-Secret -Name "CredencialBanco"
$user = $credBanco.UserName
$pass = $credBanco.GetNetworkCredential().Password

# Recuperar o byte array
$chave = Get-Secret -Name "ChaveCripto"

Note que Get-Secret retorna o segredo em texto claro para o script. Isso é necessário para usar a credencial, mas você deve ter cuidado para não exibir ou logar esse valor desnecessariamente. O PowerShell não exibe segredos automaticamente, mas se você fizer Write-Host $apiKey, ele aparecerá no console.

Para listar todos os segredos em um vault, use Get-SecretInfo:

# Listar informações dos segredos (nomes, tipos, etc.)
Get-SecretInfo -Vault "MeuVault"

E para remover um segredo, use Remove-Secret:

# Remover um segredo
Remove-Secret -Name "ApiKey" -Vault "MeuVault"

Boas práticas

Gerenciar segredos corretamente é uma responsabilidade. Aqui estão algumas boas práticas que você deve seguir sempre:

  • Nunca armazene segredos em texto puro em arquivos de script ou configuração. Sempre use o SecretManagement ou outro cofre.
  • Use o escopo de variável mais restrito possível para armazenar segredos em memória. Por exemplo, evite variáveis globais e prefira locais ou de script.
  • Evite imprimir segredos no console ou em logs. Se precisar debugar, use técnicas que mascararem o valor (como substituir por asteriscos).
  • Defina uma política de rotação de segredos e automatize a troca quando possível.
  • Use vaults separados para ambientes (dev, staging, produção). Isso impede que segredos de produção sejam usados em desenvolvimento.
  • Proteja o acesso ao vault: se você usar o SecretStore com senha, nunca a compartilhe. Em equipe, prefira vaults centrais como Azure Key Vault.
  • Revogue segredos imediatamente quando suspeitar de vazamento.
  • Prefira usar identidades gerenciadas quando estiver na nuvem, em vez de armazenar credenciais.

Além disso, quando você usa Get-Credential em scripts, pode combiná-lo com o SecretManagement para não ter que digitar a senha toda vez. Por exemplo:

# Se a credencial já existir no vault, use-a; senão, solicite ao usuário e armazene
$cred = Get-Secret -Name "CredencialBanco" -ErrorAction SilentlyContinue
if (-not $cred) {
    $cred = Get-Credential -Message "Digite as credenciais do banco"
    Set-Secret -Name "CredencialBanco" -Secret $cred
}

Referências

Exercícios

  1. Instale os módulos SecretManagement e SecretStore e registre um vault chamado "Treinamento" como padrão.

    2. ✓ Resposta: 
    Install-Module -Name Microsoft.PowerShell.SecretManagement -Force
Install-Module -Name Microsoft.PowerShell.SecretStore -Force
Register-SecretVault -Name "Treinamento" -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault
  2. Armazene uma string chamada "SenhaTeste" com o valor "P@ssw0rd" no vault "Treinamento".

    3. ✓ Resposta: 
    Set-Secret -Name "SenhaTeste" -Secret "P@ssw0rd" -Vault "Treinamento"
  3. Recupere a string "SenhaTeste" e mostre apenas o comprimento dela (não o valor) no console.

    4. ✓ Resposta: 
    $segredo = Get-Secret -Name "SenhaTeste" -Vault "Treinamento"
Write-Host "Comprimento: $($segredo.Length)"
  4. Crie um script que verifique se uma credencial chamada "MinhaCred" existe no vault. Se não existir, solicite ao usuário com Get-Credential e armazene. Se existir, apenas exiba o nome do usuário.

    5. ✓ Resposta: 
    $cred = Get-Secret -Name "MinhaCred" -Vault "Treinamento" -ErrorAction SilentlyContinue
if (-not $cred) {
    $cred = Get-Credential -Message "Informe as credenciais"
    Set-Secret -Name "MinhaCred" -Secret $cred -Vault "Treinamento"
} else {
    Write-Host "Usuário: $($cred.UserName)"
}
  5. Liste todos os segredos no vault "Treinamento" e remova aquele chamado "SenhaTeste".

    6. ✓ Resposta: 
    Get-SecretInfo -Vault "Treinamento" | Format-Table Name,Type
Remove-Secret -Name "SenhaTeste" -Vault "Treinamento"

Observações finais: O SecretManagement é uma ferramenta poderosa, mas a segurança começa com boas práticas no dia a dia. Sempre use o vault para armazenar segredos, evite colocá-los em variáveis que persistem por muito tempo e lembre-se de que, ao compartilhar scripts, você nunca deve incluir segredos reais. No próximo módulo, exploraremos como integrar o SecretManagement com serviços de nuvem, como o Azure Key Vault, para gerenciar segredos em escala.