Coletar registros do Microsoft PowerShell

Compatível com:

Google SecOps SIEM

Neste documento, explicamos como ingerir registros do Microsoft PowerShell no Google Security Operations usando o agente do Bindplane.

O Microsoft PowerShell é um framework de gerenciamento de configuração e automação de tarefas da Microsoft, composto por um shell de linha de comando e uma linguagem de script. Os registros do PowerShell capturam a execução de scripts, a atividade de módulos e as invocações de comandos, oferecendo visibilidade das operações do PowerShell para monitoramento de segurança e análise forense.

Antes de começar

Verifique se você tem os pré-requisitos a seguir:

• Instância do Google SecOps
• Windows Server 2016 ou mais recente
• Conectividade de rede entre o host do Windows e o Google SecOps
• Se estiver em execução atrás de um proxy, verifique se as portas do firewall estão abertas de acordo com os requisitos do agente do Bindplane.
• Acesso administrativo ao host do Windows para configurar a geração de registros do PowerShell e instalar o agente do BindPlane

Configurar a geração de registros do PowerShell

A geração de registros do PowerShell precisa ser ativada em hosts Windows antes que os registros possam ser coletados. Por padrão, o registro do PowerShell é mínimo. Ative o registro de blocos de script para capturar atividades detalhadas do PowerShell.

Ativar o registro de bloqueio de script usando a política de grupo

1. Abra o Editor de Política de Grupo Local executando gpedit.msc como administrador.
2. Acesse Configuração do Computador > Modelos Administrativos > Componentes do Windows > Windows PowerShell.
3. Clique duas vezes em Ativar o registro em log de blocos de script do PowerShell.
4. Selecione Ativado.
5. Se quiser, marque Registrar eventos de início / parada de invocação de bloco de script para capturar eventos de início e parada de cada bloco de script. Essa opção gera um grande volume de registros.
6. Clique em OK.
7. Abra o Prompt de comando como administrador e execute gpupdate /force para aplicar a política imediatamente.

Ativar o registro de bloqueio de script usando o registro

Como alternativa, é possível ativar o registro de bloqueio de script definindo o seguinte valor de registro:

1. Abra o Editor do Registro executando regedit como administrador.
2. Acesse HKLM\SOFTWARE\Policies\Microsoft\Windows\PowerShell\ScriptBlockLogging.
3. Se a chave não existir, crie-a.
4. Crie um novo Valor DWORD (32 bits) chamado EnableScriptBlockLogging e defina o valor como 1.
5. Reinicie as sessões do PowerShell para que a mudança entre em vigor.

O registro em bloco de scripts do PowerShell grava eventos no canal de log de eventos Microsoft-Windows-PowerShell/Operational com o ID de evento 4104.

Opcional: ativar a geração de registros do módulo

O Module Logging registra detalhes da execução do pipeline para módulos especificados. Para ativar a geração de registros de todos os módulos, faça o seguinte:

1. No Editor de Política de Grupo Local, acesse Configuração do Computador > Modelos Administrativos > Componentes do Windows > Windows PowerShell.
2. Clique duas vezes em Ativar o registro de módulos.
3. Selecione Ativado.
4. Clique em Mostrar ao lado de Nomes dos módulos.
5. Digite * para registrar todos os módulos.
6. Clique em OK na janela Module Names.
7. Clique em OK na janela Module Logging.
8. Execute gpupdate /force para aplicar a política.

Os eventos de registro de módulo são gravados no log de eventos do Windows PowerShell com o ID de evento 4103.

Opcional: ativar a transcrição

A transcrição cria um registro baseado em texto de todas as entradas e saídas da sessão do PowerShell. Para ativar a transcrição, faça o seguinte:

1. No Editor de Política de Grupo Local, acesse Configuração do computador > Modelos administrativos > Componentes do Windows > Windows PowerShell.
2. Clique duas vezes em Ativar a transcrição do PowerShell.
3. Selecione Ativado.
4. Se quiser, especifique um diretório de saída da transcrição. Se ficar em branco, as transcrições serão salvas na pasta Documentos de cada usuário.
5. Marque Incluir cabeçalhos de invocação para adicionar carimbos de data/hora e metadados.
6. Clique em OK.
7. Execute gpupdate /force para aplicar a política.

As transcrições são gravadas em arquivos de texto com nomes que começam com PowerShell_transcript.

Receber credenciais do Google SecOps para o agente do BindPlane

Para autenticar o agente do Bindplane no Google SecOps, escolha um dos seguintes métodos:

• Novas implantações: use a API Chronicle (opção 1).
• Implantações legadas: continue usando o arquivo de autenticação de ingestão (opção 2) até que a API Ingestion seja desativada em 20 de julho de 2027.

Opção 1: criar uma conta de serviço para a API Chronicle (recomendado)

1. Faça login no console doGoogle Cloud e selecione o projeto do Google Cloud vinculado à sua instância do Google SecOps.
2. Acesse IAM e administrador > Contas de serviço.
3. Clique em Criar conta de serviço.
4. Informe os seguintes detalhes de configuração:
   • Nome da conta de serviço: insira um nome para a conta (por exemplo, bindplane-ingest).
   • Descrição da conta de serviço: insira uma descrição (por exemplo, Bindplane agent log ingestion).
5. Clique em Criar e continuar.
6. Na seção Conceder a essa conta de serviço acesso ao projeto, clique em Selecionar um papel e escolha Editor do Chronicle.
7. Clique em Continuar e depois em Concluído.
8. Clique na conta de serviço que você criou e acesse a guia Chaves.
9. Clique em Adicionar chave > Criar nova chave.
10. Selecione JSON e clique em Criar. O arquivo de chave é baixado para o computador.
11. Salve o arquivo de chave como ingestion-auth.json no diretório do coletor do BindPlane (/opt/observiq-otel-collector/ingestion-auth.json no Linux ou C:\Program Files\observIQ OpenTelemetry Collector\ingestion-auth.json no Windows) ou atualize creds_file_path em config.yaml para corresponder ao caminho em que você o salvou.
12. Acesse IAM e administrador > Configurações e copie o número do projeto. Você vai precisar dele para configurar o exportador.

Observação: a chave JSON é uma credencial. Restrinja o acesso ao arquivo no host do BindPlane e alterne a chave de acordo com a política da sua organização.

Opção 2: baixar o arquivo de autenticação de ingestão (legado)

1. Faça login no console do Google SecOps.
2. Acesse Configurações do SIEM > Agentes de coleta.
3. Baixe o arquivo de autenticação de ingestão.
4. Salve o arquivo com segurança no sistema em que o agente do Bindplane será instalado.

Observação: esse arquivo autentica o agente na API Ingestion legada (malachiteingestion-pa.googleapis.com), que o Google programou para ser desativada em 20 de julho de 2027. Planeje migrar para a opção 1 antes dessa data.

Receber o ID de cliente do Google SecOps

1. Faça login no console do Google SecOps.
2. Acesse Configurações do SIEM > Perfil.

3. Copie e salve o ID de cliente na seção Detalhes da organização.

   Observação: o ID do cliente é necessário para configurar o exportador do agente Bindplane.

Instalar o agente do BindPlane

Instale o agente do Bindplane no host do Windows de acordo com as instruções a seguir.

Instalação do Windows

1. Abra o Prompt de comando ou o PowerShell como administrador.

2. Execute este comando:

   msiexec /i "https://github.com/observIQ/bindplane-agent/releases/latest/download/observiq-otel-collector.msi" /quiet
   

3. Aguarde a conclusão da instalação.

4. Execute o seguinte comando para confirmar a instalação:

   sc query observiq-otel-collector
   

   O serviço precisa aparecer como RUNNING.

Outros recursos de instalação

Para mais opções de instalação e solução de problemas, consulte o guia de instalação do agente do Bindplane.

Observação: a configuração do exportador da API Chronicle requer o coletor do Bindplane v1.106.0 ou mais recente. Os comandos anteriores instalam a versão mais recente. Se você estiver atualizando uma instalação atual, faça upgrade do coletor antes de mudar a configuração.

Configurar o agente do Bindplane para coletar registros do PowerShell

Localizar o arquivo de configuração do Windows

• Localize o arquivo de configuração do Windows da seguinte maneira:

  notepad "C:\Program Files\observIQ OpenTelemetry Collector\config.yaml"
  

Editar o arquivo de configuração

• Substitua todo o conteúdo de config.yaml pela seguinte configuração:

  receivers:
    windowseventlog/powershell:
      channel: Microsoft-Windows-PowerShell/Operational
      max_reads: 100
      poll_interval: 5s
      raw: true
      start_at: end
  
  processors:
    batch:
  
  exporters:
    chronicle/powershell:
      protocol: https
      # Region of your instance, for example us, europe, asia-southeast1
      location: <LOCATION>
      # Project number of the Google Cloud project linked to the instance
      project: '<PROJECT_NUMBER>'
      compression: gzip
      creds_file_path: 'C:\Program Files\observIQ OpenTelemetry Collector\ingestion-auth.json'
      customer_id: '<CUSTOMER_ID>'
      endpoint: chronicle.googleapis.com
      log_type: 'POWERSHELL'
      raw_log_field: body
      override_log_type: false
  
  service:
    pipelines:
      logs/powershell:
        receivers:
          - windowseventlog/powershell
        processors:
          - batch
        exporters:
          - chronicle/powershell
  

Parâmetros de configuração

Substitua os seguintes marcadores de posição:

• Configuração do receptor:

  • channel: o canal do log de eventos do Windows a ser coletado. Para o registro em blocos de script do PowerShell, use Microsoft-Windows-PowerShell/Operational. Para a geração de registros de módulo, use Windows PowerShell.
  • raw: defina como true para enviar o XML bruto do log de eventos do Windows para o Google SecOps.
  • start_at: defina como end para coletar apenas eventos novos depois que o agente for iniciado. Defina como beginning para coletar todos os eventos atuais.

• Configuração do exportador:

  • <CUSTOMER_ID>: substitua pelo ID do cliente da etapa anterior.
  • creds_file_path: caminho completo para o arquivo de chave JSON da conta de serviço (opção 1). Copie o arquivo de credenciais para esse local.
  • location: substitua <LOCATION> pela região da sua instância do Google SecOps (por exemplo, us, europe ou asia-southeast1). O exportador prefixa chronicle.googleapis.com com esse valor. Consulte Endpoints regionais para ver a lista completa.
  • project: substitua <PROJECT_NUMBER> pelo número do projeto em IAM e administrador > Configurações.

  • endpoint: mantenha definido como chronicle.googleapis.com.

  • log_type: defina como POWERSHELL para usar o analisador do PowerShell.

Exportador da API de ingestão legada

• Se você usar o arquivo de autenticação de ingestão da opção 2, substitua o bloco exporters pelo seguinte. Defina creds_file_path como o caminho para o arquivo de autenticação de ingestão e, se a instância estiver fora dos EUA, substitua malachiteingestion-pa.googleapis.com pelo endpoint regional (por exemplo, europe-malachiteingestion-pa.googleapis.com).

  exporters:
    chronicle/powershell:
      compression: gzip
      creds_file_path: 'C:\Program Files\observIQ OpenTelemetry Collector\ingestion-auth.json'
      customer_id: '<CUSTOMER_ID>'
      endpoint: malachiteingestion-pa.googleapis.com
      log_type: 'POWERSHELL'
      raw_log_field: body
      override_log_type: false
  

Observação: esse exportador vai parar de funcionar quando a API Ingestion for desativada em 20 de julho de 2027.

Salvar o arquivo de configuração

Depois de editar, salve o arquivo clicando em Arquivo > Salvar.

Reinicie o agente do Bindplane para aplicar as mudanças:

Windows

• Usando o prompt de comando ou o PowerShell como administrador:

  net stop observiq-otel-collector && net start observiq-otel-collector
  

• Ou usando o console de Serviços:

  1. Pressione Win+R, digite services.msc e pressione Enter.
  2. Localize o Coletor do OpenTelemetry da observIQ.
  3. Clique com o botão direito do mouse e selecione Reiniciar.

  4. Verifique se o serviço está em execução:

     sc query observiq-otel-collector
     

  5. Verifique se há erros nos registros:

     type "C:\Program Files\observIQ OpenTelemetry Collector\log\collector.log"
     

Verificar a ingestão de registros

Depois de configurar o agente do Bindplane e reiniciar o serviço, os registros do PowerShell vão começar a fluir para o Google SecOps.

1. Faça login no console do Google SecOps.
2. Acesse Investigar > Pesquisar.

3. Execute a seguinte pesquisa para verificar se os registros do PowerShell estão sendo ingeridos:

   metadata.log_type = "POWERSHELL"
   

4. Verifique se os eventos aparecem com carimbos de data/hora recentes.

Os eventos de registro de blocos de script do PowerShell (ID do evento 4104) vão aparecer com detalhes dos blocos de script executados, incluindo o conteúdo do script, o ID do bloco de script e o contexto de execução.

Tabela de mapeamento de UDM

Campo de registro	Mapeamento de UDM	Lógica
HostId	principal.resource.product_object_id	Identificador exclusivo do objeto de produto associado ao recurso principal
System.Version	metadata.product_version	Versão do produto que gerou o evento
System.EventId, EventID, winlog.event_id	metadata.product_event_type	Tipo de evento, conforme definido pelo produto
Computer, System.Computer, computer, winlog.computer_name	principal.hostname	Nome do host da entidade principal
Computer, System.Computer, computer, winlog.computer_name	principal.asset.hostname	Nome do host do recurso associado ao principal
System.EventRecordID, RecordNumber, winlog.record_id	metadata.product_log_id	Identificador exclusivo da entrada de registro no sistema de registro do produto
System.Opcode, opcode, winlog.opcode	metadata.description	Descrição do evento ou contexto adicional
ProviderGuid, winlog.provider_guid	metadata.product_deployment_id	Identificador exclusivo para a implantação do produto
System.ProcessID, ProcessID, ExecutionProcessID, execution.process_id, winlog.process.pid	principal.process.pid	ID de processo do processo principal
SourceModuleName	principal.resource.name	Nome do recurso associado ao principal
SourceModuleType	principal.resource.resource_subtype	Subtipo do recurso associado ao principal
security.user_id, UserID, winlog.user.identifier	principal.user.windows_sid	Identificador de segurança (SID) do Windows para o usuário principal.
	metadata.event_type	Tipo de evento (por exemplo, USER_LOGIN, NETWORK_CONNECTION)
SourceName, winlog.provider_name	metadata.product_name	Nome do produto que gerou o evento
AccountName, Username, UserName, winlog.user.name	principal.user.userid	ID do usuário principal
Domínio, winlog.user.domain	principal.administrative_domain	Domínio administrativo do principal
Path, target_file, ScriptName, script_name, ContextInfo_Script Name, file_path	target.process.file.full_path	Caminho completo para o arquivo associado ao processo de destino
HostName, powershell.Host Name, ContextInfo_Host Name	target.hostname	Nome do host da entidade de destino
HostName, powershell.Host Name, ContextInfo_Host Name	target.asset.hostname	Nome do host do recurso associado ao destino
ID do host, HostID, ContextInfo_Host ID	target.asset.asset_id	Identificador exclusivo do recurso de destino
Nombre_de_comando, ContextInfo_Command Name, CommandName	target.application	Nome do aplicativo associado ao destino
HostApplication, ContextInfo_Host Application	target.process.command_line	Linha de comando usada para iniciar o processo de destino
ScriptBlockText	target.process.command_line	Linha de comando usada para iniciar o processo de destino
MessageSourceAddress	principal.ip	Endereço IP do principal
MessageSourceAddress	principal.asset.ip	Endereço IP do recurso associado ao principal
Nombre_de_host	principal.application	Nome do aplicativo associado ao principal
Version_de_host	principal.platform_version	Versão da plataforma associada ao principal
Id_de_host	principal.resource.id	Identificador exclusivo do recurso principal
Application_host	principal.process.file.full_path	Caminho completo para o arquivo associado ao processo principal
HostApplication	principal.process.command_line	Linha de comando usada para iniciar o processo principal
Usuario, admin_domain	principal.user.userid	ID do usuário principal
Usuario, admin_domain	principal.administrative_domain	Domínio administrativo do principal
CommandLine	principal.process.command_line	Linha de comando usada para iniciar o processo principal
Máquina, machine_id	principal.asset.asset_id	Identificador exclusivo do recurso principal
Machine, platform_software	principal.asset.platform_software.platform	Tipo de plataforma do recurso (por exemplo, WINDOWS, LINUX)
Máquina, platform_software	principal.asset.platform_software.platform_version	Versão do software da plataforma no recurso
MessageSourceAddress	intermediary.ip	Endereço IP da entidade intermediária
MessageSourceAddress, Hostname	intermediary.hostname	Nome do host da entidade intermediária
MessageSourceAddress, Hostname	intermediary.asset.hostname	Nome do host do recurso associado ao intermediário
MessageSourceAddress	intermediary.port	Número da porta usada pelo intermediário.
HostApplication	target.process.command_line	Linha de comando usada para iniciar o processo de destino
HostId	target.asset.asset_id	Identificador exclusivo do recurso de destino
SequenceNumber, ContextInfo_Sequence Number, Sequence Number	security_result.detection_fields	Pares de chave-valor de informações de detecção adicionais
ProviderName	principal.resource.attribute.labels	Rótulos ou atributos associados ao recurso principal
NewEngineState	additional.fields	Outros campos personalizados não cobertos pelo esquema UDM padrão
PreviousEngineState	additional.fields	Campos personalizados adicionais não cobertos pelo esquema padrão do UDM
ScriptName	additional.fields	Campos personalizados adicionais não cobertos pelo esquema padrão do UDM
ManagementGroupName	additional.fields	Campos personalizados adicionais não cobertos pelo esquema padrão do UDM
Origem	additional.fields	Campos personalizados adicionais não cobertos pelo esquema padrão do UDM
RenderedDescription	security_result.description	Descrição do resultado de segurança ou da ação realizada
TenantId	additional.fields	Campos personalizados adicionais não cobertos pelo esquema padrão do UDM
Nome de usuário	principal.user.userid	ID do usuário principal
ActivityID	security_result.detection_fields	Pares de chave-valor de outras informações de detecção
ExecutionThreadID, execution.thread_id, winlog.process.thread.id	security_result.detection_fields	Pares de chave-valor de informações de detecção adicionais
Saída	security_result.detection_fields	Pares de chave-valor de outras informações de detecção
Dados	security_result.detection_fields	Pares de chave-valor de outras informações de detecção
Data_1	additional.fields	Outros campos personalizados não cobertos pelo esquema UDM padrão
data_1	security_result.detection_fields	Pares de chave-valor de outras informações de detecção
Data_2	security_result.detection_fields	Pares de chave-valor de outras informações de detecção
winlog.activity_id	security_result.detection_fields	Pares de chave-valor de informações de detecção adicionais
winlog.api	additional.fields	Campos personalizados adicionais não cobertos pelo esquema padrão do UDM
winlog.channel	principal.resource.attribute.labels	Rótulos ou atributos associados ao recurso principal
Deslocamento	additional.fields	Campos personalizados adicionais não cobertos pelo esquema padrão do UDM
SeverityValue	security_result.detection_fields	Pares de chave-valor de outras informações de detecção
intermediário	intermediário	Detalhes sobre entidades intermediárias envolvidas no evento
security_result	security_result	Resultado geral de segurança, incluindo ações, gravidades e detecções
	metadata.vendor_name	Nome do fornecedor que produziu o evento
SourceName	metadata.product_name	Nome do produto que gerou o evento
syslog_host	event.idm.read_only_udm.intermediary.hostname	Mapeado do registro de alterações
Computer	event.idm.read_only_udm.intermediary.hostname	Mapeado do registro de alterações
Version	event.idm.read_only_udm.metadata.product_version	Mapeado do registro de alterações
Task	event.idm.read_only_udm.security_result.detection_fields	Mapeado do registro de alterações
OpcodeValue	event.idm.read_only_udm.security_result.detection_fields	Mapeado do registro de alterações
ThreadID	event.idm.read_only_udm.security_result.detection_fields	Mapeado do registro de alterações
AccountType	event.idm.read_only_udm.security_result.detection_fields	Mapeado do registro de alterações
Offset	event1.idm.read_only_udm.additional.fields	Mapeado do registro de alterações
SeverityValue	event1.idm.read_only_udm.additional.fields	Mapeado do registro de alterações
NewEngineState", "PreviousEngineState", "HostVersion", "RunspaceId", "SequenceNumber", "EngineVersion" and "PipelineId	additional.fields	Mapeado do registro de alterações
Payload	security_result.detection_fields	Mapeado do registro de alterações
Script Name	target.file.full_path	Mapeado do registro de alterações
SystemTime	metadata.event_timestamp	Mapeado do registro de alterações
channel", "keywords", "MessageNumber", "MessageTotal", and "ScriptBlockId	security_result.detection_fields	Mapeado do registro de alterações
System.ProviderName	principal.resource.attribute.labels	Mapeado do registro de alterações
HostVersion", "RunspaceId", "PipelineId", "EngineVersion", "DetailSequence", "DetailTotal", "SequenceNumber", and "ScriptName	additional.fields	Mapeado do registro de alterações
System.EventRecordID", "System.Task", "System.Keywords", "System.Opcode", and "System.ThreadID	security.detection_fields	Mapeado do registro de alterações
EventLevelName	security_result.severity	Mapeado do registro de alterações
ManagementGroupName", "Source", "TenantId	additional_fields	Mapeado do registro de alterações

Registro de alterações

Confira o registro de alterações deste analisador

Precisa de mais ajuda? Receba respostas de membros da comunidade e profissionais do Google SecOps.