Logging em scripts de administração: logger e systemd-cat no Linux, Write-EventLog/New-WinEvent e Start-Transcript no Windows

Objetivo

Enviar o andamento e o resultado de um script de administração para um local de log durável e consultável, adequado à plataforma, sem nunca gravar credenciais, tokens ou senhas nesse log.

Pré-requisitos

No Linux, logger (util-linux) ou, em um host com systemd, systemd-cat. No Windows, para usar Write-EventLog é preciso já existir uma origem (source) personalizada do Event Log, registrada uma única vez e com antecedência em uma sessão elevada; esse cmdlet existe apenas no Windows PowerShell 5.1 e foi removido a partir do PowerShell 6. A alternativa é New-WinEvent (5.1 e 7.x) com um manifesto de provider registrado.

Passos

1. No Linux, identifique cada mensagem com uma tag para poder filtrá-la depois: logger -t my-admin-script "starting cleanup of /var/tmp". O logger(1) é descrito como um utilitário que cria entradas no log do sistema, que podem ser lidas depois com journalctl -t my-admin-script ou em /var/log/syslog, conforme a configuração de logging do sistema.
2. Quando toda a stdout/stderr do script deve ir para o journal sem adicionar chamadas a logger por toda parte, execute-o com systemd-cat -t my-admin-script ./script.sh. O systemd-cat é descrito como o utilitário que conecta "the standard input and" output (a entrada e a saída padrão) de um processo, ou filtra um pipeline, ao journal — útil para encapsular um script existente sem modificá-lo.
3. No Windows PowerShell 5.1, se já existir uma origem registrada no Event Log para o script, use Write-EventLog -LogName Application -Source MyAdminScript -EventId 1000 -Message "..." para gerar entradas estruturadas sobre as quais uma ferramenta de monitoramento possa emitir alertas. O Write-EventLog exige que a origem seja criada com antecedência (New-EventLog, executado uma vez, com privilégios elevados); não crie a origem dentro do fluxo normal de execução não supervisionada do script. No PowerShell 7, use New-WinEvent ou [System.Diagnostics.EventLog]::WriteEntry(...).
4. Para o logging mais recente baseado em eventos, associado a um provider ETW e a um manifesto, use New-WinEvent -ProviderName <name> -Id <id> -Payload <values>, que grava um evento estruturado por meio do provider registrado, em vez de uma entrada de log clássica baseada em origem.
5. Para obter uma transcrição completa e sem filtros de tudo o que a sessão PowerShell do script exibiu (útil para depurar depois uma execução não supervisionada), envolva o script em Start-Transcript -Path $logPath; ...; Stop-Transcript. Como a transcrição captura literalmente tudo o que é exibido no host, proteja o arquivo de saída com o mesmo controle de acesso dos demais logs do script. A transcrição e o script block logging também podem ser ativados em toda a máquina por Group Policy; assim, um segredo escrito como literal no script ou exibido no host pode acabar em uma transcrição ou no event log mesmo sem Start-Transcript.
6. Antes de registrar qualquer valor, compare-o com uma lista curta de bloqueio (deny-list) com os nomes de variáveis que o seu script usa para segredos (password, token, key, connectionstring); substitua esses valores por um marcador fixo antes da chamada de log e nunca conte com a lembrança de omiti-los caso a caso.

Resultado esperado

É possível reconstruir depois a execução de um script a partir do journalctl ou do Event Viewer, sem executá-lo de novo, e a revisão do log de qualquer execução não mostra nenhuma credencial em texto puro, independentemente do que o script tenha manipulado.

Limites e base de verificação

O destino exato do logger (daemon syslog, journal ou ambos) depende da configuração de logging do host, não do próprio logger. O Write-EventLog falha se a origem nunca foi registrada ou se foi registrada sob outro nome de log; depois de uma execução, verifique com Get-WinEvent -FilterHashtable @{LogName='Application'; ProviderName='MyAdminScript'} -MaxEvents 1, e não apenas pelo valor de retorno da chamada de escrita. O Start-Transcript não oculta nada: um comando que exiba um segredo durante uma sessão transcrita continua aparecendo no arquivo de transcrição.