Coletar registros de auditoria do ServiceNow

Compatível com:

Google SecOps SIEM

Observação: esse recurso é coberto pelos Termos de produtos pré-GA dos Termos específicos de serviço do Google Security Operations. Os recursos pré-GA podem ter suporte limitado, e as mudanças realizadas podem não ser compatíveis com outras versões pré-GA. Para mais informações, consulte as diretrizes do serviço de suporte técnico do Google SecOps e os Termos específicos de serviço do Google SecOps.

Este documento explica como ingerir registros de auditoria do ServiceNow no Google Security Operations usando vários métodos.

Opção A: AWS S3 com Lambda

Esse método usa o AWS Lambda para consultar periodicamente a API REST do ServiceNow em busca de registros de auditoria e armazená-los em um bucket do S3. Em seguida, o Google Security Operations coleta os registros do bucket do S3.

Antes de começar

• Uma instância do Google SecOps
• Acesso privilegiado ao locatário ou à API do ServiceNow
• Acesso privilegiado à AWS (S3, IAM, Lambda, EventBridge)

Coletar os pré-requisitos do ServiceNow (IDs, chaves de API, IDs da organização, tokens)

1. Faça login no ServiceNow Admin Console.
2. Acesse Segurança do sistema > Usuários e grupos > Usuários.
3. Crie um usuário ou selecione um com as permissões adequadas para acessar os registros de auditoria.
4. Copie e salve em um local seguro os seguintes detalhes:
   • Nome de usuário
   • Senha
   • URL da instância (por exemplo, https://instance.service-now.com)

Configurar o bucket do AWS S3 e o IAM para o Google SecOps

1. Crie um bucket do Amazon S3 seguindo este guia do usuário: Como criar um bucket
2. Salve o Nome e a Região do bucket para referência futura (por exemplo, servicenow-audit-logs).
3. Crie um usuário seguindo este guia: Como criar um usuário do IAM.
4. Selecione o usuário criado.
5. Selecione a guia Credenciais de segurança.
6. Clique em Criar chave de acesso na seção Chaves de acesso.
7. Selecione Serviço de terceiros como o Caso de uso.
8. Clique em Próxima.
9. Opcional: adicione uma tag de descrição.
10. Clique em Criar chave de acesso.
11. Clique em Fazer o download do arquivo CSV para salvar a chave de acesso e a chave de acesso secreta para uso posterior.
12. Clique em Concluído.
13. Selecione a guia Permissões.
14. Clique em Adicionar permissões na seção Políticas de permissões .
15. Selecione Adicionar permissões.
16. Selecione Anexar políticas diretamente.
17. Pesquise e selecione a política AmazonS3FullAccess.
18. Clique em Próxima.
19. Clique em Adicionar permissões

Configurar a política e o papel do IAM para uploads do S3

1. No console da AWS, acesse IAM > Políticas > Criar política > guia JSON.

2. Copie e cole a política abaixo.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "AllowPutObjects",
         "Effect": "Allow",
         "Action": "s3:PutObject",
         "Resource": "arn:aws:s3:::servicenow-audit-logs/*"
       },
       {
         "Sid": "AllowGetStateObject",
         "Effect": "Allow",
         "Action": "s3:GetObject",
         "Resource": "arn:aws:s3:::servicenow-audit-logs/audit-logs/state.json"
       }
     ]
   }
   

   • Substitua servicenow-audit-logs se você tiver inserido um nome de bucket diferente.

3. Clique em Próxima > Criar política.

4. Acesse IAM > Funções > Criar função > Serviço da AWS > Lambda.

5. Anexe a política recém-criada.

6. Nomeie a função como servicenow-audit-lambda-role e clique em Criar função.

Criar a função Lambda

1. No console da AWS, acesse Lambda > Functions > Create function.
2. Clique em Criar do zero.

3. Informe os seguintes detalhes de configuração:

   Configuração	Valor
   Nome	servicenow-audit-collector
   Ambiente de execução	Python 3.13
   Arquitetura	x86_64
   Função de execução	servicenow-audit-lambda-role

4. Depois que a função for criada, abra a guia Código, exclua o stub e insira o seguinte código (servicenow-audit-collector.py):

   import urllib3
   import json
   import os
   import datetime
   import boto3
   import base64
   
   def lambda_handler(event, context):
       # ServiceNow API details
       base_url = os.environ['API_BASE_URL']  # e.g., https://instance.service-now.com
       username = os.environ['API_USERNAME']
       password = os.environ['API_PASSWORD']
   
       # S3 details
       s3_bucket = os.environ['S3_BUCKET']
       s3_prefix = os.environ['S3_PREFIX']
   
       # State management
       state_key = os.environ.get('STATE_KEY', f"{s3_prefix}/state.json")
   
       # Pagination settings
       page_size = int(os.environ.get('PAGE_SIZE', '1000'))
       max_pages = int(os.environ.get('MAX_PAGES', '1000'))
   
       # Initialize S3 client
       s3 = boto3.client('s3')
   
       # Get last run timestamp from state file
       last_run_timestamp = get_last_run_timestamp(s3, s3_bucket, state_key)
   
       # Current timestamp for this run
       current_timestamp = datetime.datetime.now().isoformat()
   
       # Query ServiceNow API for audit logs with pagination
       audit_logs = get_audit_logs(base_url, username, password, last_run_timestamp, page_size, max_pages)
   
       if audit_logs:
           # Write logs to S3 in NDJSON format (newline-delimited JSON)
           timestamp = datetime.datetime.now().strftime('%Y-%m-%d-%H-%M-%S')
           s3_key = f"{s3_prefix}/servicenow-audit-{timestamp}.ndjson"
   
           # Format as NDJSON: one JSON object per line
           body = "\n".join(json.dumps(log) for log in audit_logs) + "\n"
   
           s3.put_object(
               Bucket=s3_bucket,
               Key=s3_key,
               Body=body,
               ContentType='application/x-ndjson'
           )
   
           # Update state file
           update_state_file(s3, s3_bucket, state_key, current_timestamp)
   
           return {
               'statusCode': 200,
               'body': json.dumps(f'Successfully exported {len(audit_logs)} audit logs to S3')
           }
       else:
           return {
               'statusCode': 200,
               'body': json.dumps('No new audit logs to export')
           }
   
   def get_last_run_timestamp(s3, bucket, key):
       try:
           response = s3.get_object(Bucket=bucket, Key=key)
           state = json.loads(response['Body'].read().decode('utf-8'))
           return state.get('last_run_timestamp', '1970-01-01T00:00:00')
       except:
           return '1970-01-01T00:00:00'
   
   def update_state_file(s3, bucket, key, timestamp):
       state = {'last_run_timestamp': timestamp}
       s3.put_object(
           Bucket=bucket,
           Key=key,
           Body=json.dumps(state),
           ContentType='application/json'
       )
   
   def get_audit_logs(base_url, username, password, last_run_timestamp, page_size=1000, max_pages=1000):
       """
       Query ServiceNow sys_audit table with proper pagination.
       Uses sys_created_on field for timestamp filtering.
       """
       # Encode credentials
       auth_string = f"{username}:{password}"
       auth_bytes = auth_string.encode('ascii')
       auth_encoded = base64.b64encode(auth_bytes).decode('ascii')
   
       # Setup HTTP client
       http = urllib3.PoolManager()
   
       headers = {
           'Authorization': f'Basic {auth_encoded}',
           'Accept': 'application/json'
       }
   
       results = []
       offset = 0
   
       for page in range(max_pages):
           # Build query with pagination
           # Use sys_created_on (not created_on) for timestamp filtering
           query_params = (
               f"sysparm_query=sys_created_onAFTER{last_run_timestamp}"
               f"&sysparm_display_value=true"
               f"&sysparm_limit={page_size}"
               f"&sysparm_offset={offset}"
           )
   
           url = f"{base_url}/api/now/table/sys_audit?{query_params}"
   
           try:
               response = http.request('GET', url, headers=headers)
   
               if response.status == 200:
                   data = json.loads(response.data.decode('utf-8'))
                   chunk = data.get('result', [])
                   results.extend(chunk)
   
                   # Stop if we got fewer records than page_size (last page)
                   if len(chunk) < page_size:
                       break
   
                   # Move to next page
                   offset += page_size
               else:
                   print(f"Error querying ServiceNow API: {response.status} - {response.data.decode('utf-8')}")
                   break
           except Exception as e:
               print(f"Exception querying ServiceNow API: {str(e)}")
               break
   
       return results
   

5. Acesse Configuração > Variáveis de ambiente > Editar > Adicionar nova variável de ambiente.

6. Insira as seguintes variáveis de ambiente, substituindo pelos seus valores.

   Chave	Valor de exemplo
   S3_BUCKET	servicenow-audit-logs
   S3_PREFIX	audit-logs/
   STATE_KEY	audit-logs/state.json
   API_BASE_URL	https://instance.service-now.com
   API_USERNAME	<your-username>
   API_PASSWORD	<your-password>
   PAGE_SIZE	1000
   MAX_PAGES	1000

   Observação: para ambientes de produção, é altamente recomendável armazenar credenciais no AWS Secrets Manager em vez de variáveis de ambiente e referenciá-las no código do Lambda.

7. Depois que a função for criada, permaneça na página dela ou abra Lambda > Functions > servicenow-audit-collector.

8. Selecione a guia Configuração.

9. No painel Configuração geral, clique em Editar.

10. Mude Tempo limite para 5 minutos (300 segundos) e clique em Salvar.

    Observação: o tempo limite é um limite superior fixo. Isso significa que, se a função ainda estiver em execução quando o timer atingir 5 minutos, o AWS Lambda vai encerrá-la. Execuções mais curtas terminam normalmente, e você só recebe cobranças pelo tempo de execução real.

Criar uma programação do EventBridge

1. Acesse Amazon EventBridge > Scheduler > Criar programação.
2. Informe os seguintes detalhes de configuração:
   • Programação recorrente: Taxa (1 hour).
   • Destino: sua função Lambda servicenow-audit-collector.
   • Nome: servicenow-audit-collector-1h.
3. Clique em Criar programação.

Configurar um feed no Google SecOps para ingerir registros de auditoria do ServiceNow

1. Acesse Configurações do SIEM > Feeds.
2. Clique em + Adicionar novo feed.
3. No campo Nome do feed, insira um nome para o feed (por exemplo, ServiceNow Audit logs).
4. Selecione Amazon S3 V2 como o Tipo de origem.
5. Selecione Auditoria do ServiceNow como o Tipo de registro.
6. Clique em Próxima.
7. Especifique valores para os seguintes parâmetros de entrada:
   • URI do S3: s3://servicenow-audit-logs/audit-logs/
   • Opções de exclusão da fonte: selecione a opção de exclusão de acordo com sua preferência.
   • Idade máxima do arquivo: inclui arquivos modificados no último número de dias. O padrão é de 180 dias.
   • ID da chave de acesso: chave de acesso do usuário com acesso ao bucket do S3.
   • Chave de acesso secreta: chave secreta do usuário com acesso ao bucket do S3.
   • Namespace do recurso: o namespace do recurso.
   • Rótulos de ingestão: o rótulo aplicado aos eventos deste feed.
8. Clique em Próxima.
9. Revise a nova configuração do feed na tela Finalizar e clique em Enviar.

Opção B: agente do Bindplane com syslog

Esse método usa um agente do Bindplane para coletar registros de auditoria do ServiceNow e encaminhá-los para as Operações de Segurança do Google. Como o ServiceNow não oferece suporte nativo ao syslog para registros de auditoria, vamos usar um script para consultar a API REST do ServiceNow e encaminhar os registros ao agente do Bindplane via syslog.

Antes de começar

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

• Uma instância do Google SecOps
• Um host Windows 2016 ou mais recente ou Linux com systemd
• Se você estiver executando por trás de um proxy, verifique se as portas do firewall estão abertas de acordo com os requisitos do agente Bindplane.
• Acesso privilegiado ao console ou dispositivo de gerenciamento do ServiceNow

Receber o arquivo de autenticação de ingestão do Google SecOps

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. Salve o arquivo de forma segura no sistema em que o Bindplane será instalado.

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 do cliente na seção Detalhes da organização.

Instalar o agente do Bindplane

Instale o agente do Bindplane no seu sistema operacional Windows ou Linux de acordo com as instruções a seguir.

Instalação do Linux

1. Abra um terminal com privilégios de root ou sudo.

2. Execute este comando:

   sudo sh -c "$(curl -fsSlL https://github.com/observiq/bindplane-agent/releases/latest/download/install_unix.sh)" install_unix.sh
   

Outros recursos de instalação

• Para mais opções de instalação, consulte este guia de instalação.

Configurar o agente do Bindplane para ingerir o Syslog e enviar ao Google SecOps

1. Acesse o arquivo de configuração:

   1. Localize o arquivo config.yaml. Normalmente, ele fica no diretório /etc/bindplane-agent/ no Linux ou no diretório de instalação no Windows.
   2. Abra o arquivo usando um editor de texto (por exemplo, nano, vi ou Bloco de Notas).

2. Edite o arquivo config.yaml da seguinte forma:

   receivers:
     udplog:
       # Replace the port and IP address as required
       listen_address: "0.0.0.0:514"
   
   exporters:
     chronicle/chronicle_w_labels:
       compression: gzip
       # Adjust the path to the credentials file you downloaded in Step 1
       creds_file_path: '/path/to/ingestion-authentication-file.json'
       # Replace with your actual customer ID from Step 2
       customer_id: <YOUR_CUSTOMER_ID>
       # Replace with the appropriate regional endpoint
       endpoint: <CUSTOMER_REGION_ENDPOINT>
       # Add optional ingestion labels for better organization
       log_type: 'SERVICENOW_AUDIT'
       raw_log_field: body
       ingestion_labels:
   
   service:
     pipelines:
       logs/source0__chronicle_w_labels-0:
         receivers:
           - udplog
         exporters:
           - chronicle/chronicle_w_labels
   

• Substitua a porta e o endereço IP conforme necessário na sua infraestrutura.
• Substitua <YOUR_CUSTOMER_ID> pelo ID de cliente real.
• Substitua <CUSTOMER_REGION_ENDPOINT> pelo endpoint regional adequado na documentação de endpoints regionais.
• Atualize /path/to/ingestion-authentication-file.json para o caminho em que o arquivo de autenticação foi salvo na seção Receber arquivo de autenticação de ingestão do Google SecOps.

Reinicie o agente do Bindplane para aplicar as mudanças

• Para reiniciar o agente do Bindplane no Linux, execute o seguinte comando:

  sudo systemctl restart bindplane-agent
  

• Para reiniciar o agente do Bindplane no Windows, use o console Serviços ou insira o seguinte comando:

  net stop BindPlaneAgent && net start BindPlaneAgent
  

Criar um script para encaminhar registros de auditoria do ServiceNow para o syslog

Como o ServiceNow não oferece suporte nativo ao syslog para registros de auditoria, vamos criar um script que consulta a API REST do ServiceNow e encaminha os registros para o syslog. É possível programar a execução periódica desse script.

Exemplo de script do Python (Linux)

• Crie um arquivo chamado servicenow_audit_to_syslog.py com o conteúdo a seguir:

  import urllib3
  import json
  import datetime
  import base64
  import socket
  import time
  import os
  
  # ServiceNow API details
  BASE_URL = 'https://instance.service-now.com'  # Replace with your ServiceNow instance URL
  USERNAME = 'admin'  # Replace with your ServiceNow username
  PASSWORD = 'password'  # Replace with your ServiceNow password
  
  # Syslog details
  SYSLOG_SERVER = '127.0.0.1'  # Replace with your Bindplane agent IP
  SYSLOG_PORT = 514  # Replace with your Bindplane agent port
  
  # State file to keep track of last run
  STATE_FILE = '/tmp/servicenow_audit_last_run.txt'
  
  # Pagination settings
  PAGE_SIZE = 1000
  MAX_PAGES = 1000
  
  def get_last_run_timestamp():
      try:
          with open(STATE_FILE, 'r') as f:
              return f.read().strip()
      except:
          return '1970-01-01T00:00:00'
  
  def update_state_file(timestamp):
      with open(STATE_FILE, 'w') as f:
          f.write(timestamp)
  
  def send_to_syslog(message):
      sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
      sock.sendto(message.encode(), (SYSLOG_SERVER, SYSLOG_PORT))
      sock.close()
  
  def get_audit_logs(last_run_timestamp):
      """
      Query ServiceNow sys_audit table with proper pagination.
      Uses sys_created_on field for timestamp filtering.
      """
      # Encode credentials
      auth_string = f"{USERNAME}:{PASSWORD}"
      auth_bytes = auth_string.encode('ascii')
      auth_encoded = base64.b64encode(auth_bytes).decode('ascii')
  
      # Setup HTTP client
      http = urllib3.PoolManager()
  
      headers = {
          'Authorization': f'Basic {auth_encoded}',
          'Accept': 'application/json'
      }
  
      results = []
      offset = 0
  
      for page in range(MAX_PAGES):
          # Build query with pagination
          # Use sys_created_on (not created_on) for timestamp filtering
          query_params = (
              f"sysparm_query=sys_created_onAFTER{last_run_timestamp}"
              f"&sysparm_display_value=true"
              f"&sysparm_limit={PAGE_SIZE}"
              f"&sysparm_offset={offset}"
          )
  
          url = f"{BASE_URL}/api/now/table/sys_audit?{query_params}"
  
          try:
              response = http.request('GET', url, headers=headers)
  
              if response.status == 200:
                  data = json.loads(response.data.decode('utf-8'))
                  chunk = data.get('result', [])
                  results.extend(chunk)
  
                  # Stop if we got fewer records than PAGE_SIZE (last page)
                  if len(chunk) < PAGE_SIZE:
                      break
  
                  # Move to next page
                  offset += PAGE_SIZE
              else:
                  print(f"Error querying ServiceNow API: {response.status} - {response.data.decode('utf-8')}")
                  break
          except Exception as e:
              print(f"Exception querying ServiceNow API: {str(e)}")
              break
  
      return results
  
  def main():
      # Get last run timestamp
      last_run_timestamp = get_last_run_timestamp()
  
      # Current timestamp for this run
      current_timestamp = datetime.datetime.now().isoformat()
  
      # Query ServiceNow API for audit logs
      audit_logs = get_audit_logs(last_run_timestamp)
  
      if audit_logs:
          # Send each log to syslog
          for log in audit_logs:
              # Format the log as JSON
              log_json = json.dumps(log)
  
              # Send to syslog
              send_to_syslog(log_json)
  
              # Sleep briefly to avoid flooding
              time.sleep(0.01)
  
          # Update state file
          update_state_file(current_timestamp)
  
          print(f"Successfully forwarded {len(audit_logs)} audit logs to syslog")
      else:
          print("No new audit logs to forward")
  
  if __name__ == "__main__":
      main()
  

Configurar a execução programada (Linux)

1. Torne o script executável:

   chmod +x servicenow_audit_to_syslog.py
   

2. Crie um cron job para executar o script a cada hora:

   crontab -e
   

3. Adicione a linha abaixo:

   0 * * * * /usr/bin/python3 /path/to/servicenow_audit_to_syslog.py >> /tmp/servicenow_audit_to_syslog.log 2>&1
   

Exemplo de script do PowerShell (Windows)

• Crie um arquivo chamado ServiceNow-Audit-To-Syslog.ps1 com o conteúdo a seguir:

  # ServiceNow API details
  $BaseUrl = 'https://instance.service-now.com'  # Replace with your ServiceNow instance URL
  $Username = 'admin'  # Replace with your ServiceNow username
  $Password = 'password'  # Replace with your ServiceNow password
  
  # Syslog details
  $SyslogServer = '127.0.0.1'  # Replace with your Bindplane agent IP
  $SyslogPort = 514  # Replace with your Bindplane agent port
  
  # State file to keep track of last run
  $StateFile = "$env:TEMP\ServiceNowAuditLastRun.txt"
  
  # Pagination settings
  $PageSize = 1000
  $MaxPages = 1000
  
  function Get-LastRunTimestamp {
      try {
          if (Test-Path $StateFile) {
              return Get-Content $StateFile
          }
          else {
              return '1970-01-01T00:00:00'
          }
      }
      catch {
          return '1970-01-01T00:00:00'
      }
  }
  
  function Update-StateFile {
      param (
          [string]$Timestamp
      )
  
      Set-Content -Path $StateFile -Value $Timestamp
  }
  
  function Send-ToSyslog {
      param (
          [string]$Message
      )
  
      $UdpClient = New-Object System.Net.Sockets.UdpClient
      $UdpClient.Connect($SyslogServer, $SyslogPort)
  
      $Encoding = [System.Text.Encoding]::ASCII
      $Bytes = $Encoding.GetBytes($Message)
  
      $UdpClient.Send($Bytes, $Bytes.Length)
      $UdpClient.Close()
  }
  
  function Get-AuditLogs {
      param (
          [string]$LastRunTimestamp
      )
  
      # Create auth header
      $Auth = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("${Username}:${Password}"))
  
      $Headers = @{
          Authorization = "Basic ${Auth}"
          Accept = 'application/json'
      }
  
      $Results = @()
      $Offset = 0
  
      for ($page = 0; $page -lt $MaxPages; $page++) {
          # Build query with pagination
          # Use sys_created_on (not created_on) for timestamp filtering
          $QueryParams = "sysparm_query=sys_created_onAFTER${LastRunTimestamp}&sysparm_display_value=true&sysparm_limit=${PageSize}&sysparm_offset=${Offset}"
  
          $Url = "${BaseUrl}/api/now/table/sys_audit?${QueryParams}"
  
          try {
              $Response = Invoke-RestMethod -Uri $Url -Headers $Headers -Method Get
              $Chunk = $Response.result
  
              $Results += $Chunk
  
              # Stop if we got fewer records than PageSize (last page)
              if ($Chunk.Count -lt $PageSize) {
                  break
              }
  
              # Move to next page
              $Offset += $PageSize
          }
          catch {
              Write-Error "Error querying ServiceNow API: $_"
              break
          }
      }
  
      return $Results
  }
  
  # Main execution
  $LastRunTimestamp = Get-LastRunTimestamp
  $CurrentTimestamp = (Get-Date).ToString('yyyy-MM-ddTHH:mm:ss')
  
  $AuditLogs = Get-AuditLogs -LastRunTimestamp $LastRunTimestamp
  
  if ($AuditLogs -and $AuditLogs.Count -gt 0) {
      # Send each log to syslog
      foreach ($Log in $AuditLogs) {
          # Format the log as JSON
          $LogJson = $Log | ConvertTo-Json -Compress
  
          # Send to syslog
          Send-ToSyslog -Message $LogJson
  
          # Sleep briefly to avoid flooding
          Start-Sleep -Milliseconds 10
      }
  
      # Update state file
      Update-StateFile -Timestamp $CurrentTimestamp
  
      Write-Output "Successfully forwarded $($AuditLogs.Count) audit logs to syslog"
  }
  else {
      Write-Output "No new audit logs to forward"
  }
  

Configurar a execução programada (Windows)

1. Abra o Agendador de tarefas.
2. Clique em Criar tarefa.
3. Forneça a seguinte configuração:
   • Nome: ServiceNowAuditToSyslog
   • Opções de segurança: executar se o usuário estiver conectado ou não
4. Acesse a guia Gatilhos.
5. Clique em Novo e defina para execução a cada hora.
6. Acesse a guia Ações.
7. Clique em Novo e defina:
   • Ação: iniciar um programa
   • Programa/script: powershell.exe
   • Argumentos: -ExecutionPolicy Bypass -File "C:\path\to\ServiceNow-Audit-To-Syslog.ps1"
8. Clique em OK para salvar a tarefa.

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