Coletar conjuntos de dados principais do Code42 Incydr

Versão do analisador:3.0

Compatível com:

Este documento explica como ingerir conjuntos de dados principais do Code42 Incydr (usuários, auditoria, casos e, opcionalmente, eventos de arquivo) no Google Security Operations usando o Google Cloud Storage.

O Code42 Incydr é uma solução de gerenciamento de riscos internos que detecta, investiga e responde à exfiltração de dados em dispositivos monitorando a atividade de arquivos em tempo real em endpoints, serviços de nuvem e e-mail.

Antes de começar

Verifique se você atende os seguintes pré-requisitos:

  • Uma instância do Google SecOps
  • Um projeto do GCP com a API Storage ativada
  • Permissões para criar e gerenciar intervalos do GCS
  • Permissões para gerenciar políticas do IAM em buckets do GCS
  • Permissões para criar serviços do Cloud Run, tópicos do Pub/Sub e jobs do Cloud Scheduler
  • Acesso privilegiado à API do Code42 Incydr ou ao Admin Console com a função de administrador de risco interno

Criar um bucket do Google Cloud Storage

  1. Acesse o Console do Google Cloud.
  2. Selecione um projeto ou crie um novo.
  3. No menu de navegação, acesse Cloud Storage > Buckets.
  4. Clique em Criar bucket.

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

    Configuração Valor
    Nomeie seu bucket Insira um nome exclusivo globalmente, por exemplo, code42-incydr-logs.
    Tipo de local Escolha de acordo com suas necessidades (região, birregional, multirregional)
    Local Selecione o local (por exemplo, us-central1).
    Classe de armazenamento Padrão (recomendado para registros acessados com frequência)
    Controle de acesso Uniforme (recomendado)
    Ferramentas de proteção Opcional: ativar o controle de versões de objetos ou a política de retenção

  6. Clique em Criar.

Coletar credenciais da API do Code42 Incydr

Criar cliente de API

  1. Faça login no console da Web do Code42 Incydr.
  2. Acesse Administração > Integrações > Clientes de API.
  3. Clique em Criar cliente de API.
  4. Na caixa de diálogo Criar novo cliente de API, insira um nome para o cliente (por exemplo, Google Security Operations Integration).
  5. Copie e salve os seguintes detalhes em um local seguro:
    • ID do cliente: o identificador do cliente da API.
    • Secret: a chave secreta do cliente da API.
  6. Clique em Criar.

Determinar o URL base da API

O URL base da API depende do URL do console do Code42 Incydr. Verifique o URL do gateway de API no portal para desenvolvedores do Incydr ou na documentação do ambiente do seu locatário.

  • Padrões comuns:

    URL do console URL base da API
    https://console.us.code42.com https://api.us.code42.com
    https://console.us2.code42.com https://api.us2.code42.com
    https://console.ie.code42.com https://api.ie.code42.com
    https://console.gov.code42.com https://api.gov.code42.com

Verificar as permissões do cliente de API

O cliente da API precisa ter as permissões adequadas para acessar os endpoints necessários:

  1. No console do Code42 Incydr, acesse Administração > Integrações > Clientes da API.
  2. Clique no nome do cliente de API que você criou.

  3. Verifique se o cliente da API tem acesso aos seguintes escopos:

    • Usuários: acesso de leitura aos dados do usuário
    • Registro de auditoria: acesso de leitura aos registros de auditoria
    • Casos: acesso de leitura aos dados de casos
    • Eventos de arquivo (opcional): acesso de leitura aos dados de eventos de arquivo.

Testar o acesso à API

  • Teste suas credenciais antes de prosseguir com a integração:

    # Replace with your actual credentials
CLIENT_ID="your-client-id"
CLIENT_SECRET="your-client-secret"
API_BASE="https://api.us.code42.com"

# Get OAuth token
TOKEN=$(curl -s -X POST "${API_BASE}/v1/oauth/token" \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" | jq -r '.access_token')

# Test API access
curl -v -H "Authorization: Bearer ${TOKEN}" "${API_BASE}/v1/users?pageSize=1"

Criar uma conta de serviço para a função do Cloud Run

A função do Cloud Run precisa de uma conta de serviço com permissões para gravar no bucket do GCS e ser invocada pelo Pub/Sub.

Criar conta de serviço

  1. No Console do GCP, acesse IAM e administrador > Contas de serviço.
  2. Clique em Criar conta de serviço.
  3. Informe os seguintes detalhes de configuração:
    • Nome da conta de serviço: insira code42-incydr-collector-sa.
    • Descrição da conta de serviço: insira Service account for Cloud Run function to collect Code42 Incydr logs.
  4. Clique em Criar e continuar.
  5. Na seção Conceder acesso a essa conta de serviço ao projeto, adicione os seguintes papéis:
    1. Clique em Selecionar papel.
    2. Pesquise e selecione Administrador de objetos do Storage.
    3. Clique em + Adicionar outro papel.
    4. Pesquise e selecione Invocador do Cloud Run.
    5. Clique em + Adicionar outro papel.
    6. Pesquise e selecione Invocador do Cloud Functions.
  6. Clique em Continuar.
  7. Clique em Concluído.

Esses papéis são necessários para:

  • Administrador de objetos do Storage: grava registros no bucket do GCS e gerencia arquivos de estado.
  • Invocador do Cloud Run: permite que o Pub/Sub invoque a função.
  • Invocador do Cloud Functions: permite a invocação de funções

Conceder permissões do IAM no bucket do GCS

Conceda permissões de gravação à conta de serviço no bucket do GCS:

  1. Acesse Cloud Storage > Buckets.
  2. Clique no nome do bucket (por exemplo, code42-incydr-logs).
  3. Acesse a guia Permissões.
  4. Clique em Conceder acesso.
  5. Informe os seguintes detalhes de configuração:
    • Adicionar principais: insira o e-mail da conta de serviço (por exemplo, code42-incydr-collector-sa@your-project.iam.gserviceaccount.com).
    • Atribuir papéis: selecione Administrador de objetos do Storage.
  6. Clique em Salvar.

Criar tópico Pub/Sub

Crie um tópico do Pub/Sub em que o Cloud Scheduler vai publicar e a função do Cloud Run vai se inscrever.

  1. No Console do GCP, acesse Pub/Sub > Tópicos.
  2. Selecione Criar tópico.
  3. Informe os seguintes detalhes de configuração:
    • ID do tópico: insira code42-incydr-trigger.
    • Não altere as outras configurações.
  4. Clique em Criar.

Criar uma função do Cloud Run para coletar registros

A função do Cloud Run é acionada por mensagens do Pub/Sub do Cloud Scheduler para buscar registros da API Code42 Incydr e gravá-los no GCS.

  1. No console do GCP, acesse o Cloud Run.
  2. Clique em Criar serviço.
  3. Selecione Função (use um editor in-line para criar uma função).

  4. Na seção Configurar, forneça os seguintes detalhes de configuração:

    Configuração Valor
    Nome do serviço code42-incydr-collector
    Região Selecione a região que corresponde ao seu bucket do GCS (por exemplo, us-central1).
    Ambiente de execução Selecione Python 3.12 ou uma versão mais recente.

  5. Na seção Acionador (opcional):

    1. Clique em + Adicionar gatilho.
    2. Selecione Cloud Pub/Sub.
    3. Em Selecionar um tópico do Cloud Pub/Sub, escolha o tópico code42-incydr-trigger.
    4. Clique em Salvar.

  6. Na seção Autenticação:

    1. Selecione Exigir autenticação.
    2. Confira o Identity and Access Management (IAM).

  7. Role a tela para baixo e expanda Contêineres, rede, segurança.

  8. Acesse a guia Segurança:

    • Conta de serviço: selecione a conta de serviço code42-incydr-collector-sa.

  9. Acesse a guia Contêineres:

    1. Clique em Variáveis e secrets.
    2. Clique em + Adicionar variável para cada variável de ambiente:
    Nome da variável Valor de exemplo Descrição
    INCYDR_BASE_URL https://api.us.code42.com URL base da API do seu locatário
    INCYDR_CLIENT_ID your-client-id ID do cliente da API
    INCYDR_CLIENT_SECRET your-client-secret Chave secreta do cliente da API
    GCS_BUCKET code42-incydr-logs Nome do bucket do GCS
    GCS_PREFIX code42/ Prefixo para arquivos de registro
    PAGE_SIZE 500 Registros por página
    LOOKBACK_MINUTES 60 Período de lookback inicial
    STREAMS users,audit,cases Fluxos de dados separados por vírgulas
    FE_QUERY_JSON `` Opcional: consulta JSON de eventos de arquivo
    FE_PAGE_SIZE 1000 Opcional: tamanho da página de eventos de arquivo

  10. Role a tela para baixo na guia Variáveis e secrets até Solicitações:

    • Tempo limite da solicitação: insira 600 segundos (10 minutos).

  11. Acesse a guia Configurações em Contêineres:

    • Na seção Recursos:
      • Memória: selecione 1024 MiB ou mais.
      • CPU: selecione 1.
    • Clique em Concluído.

  12. Role até Ambiente de execução:

    • Selecione Padrão (recomendado).

  13. Na seção Escalonamento de revisão:

    • Número mínimo de instâncias: insira 0.
    • Número máximo de instâncias: insira 100 ou ajuste com base na carga esperada.

  14. Clique em Criar.

  15. Aguarde a criação do serviço (1 a 2 minutos).

  16. Depois que o serviço é criado, o editor de código inline é aberto automaticamente.

Adicionar código da função

  1. Insira main em Ponto de entrada da função.

  2. No editor de código em linha, crie dois arquivos:

    • Primeiro arquivo: main.py:
    import functions_framework
from google.cloud import storage
import json
import os
import urllib3
from datetime import datetime, timedelta, timezone
import time

# Initialize HTTP client
http = urllib3.PoolManager(
    timeout=urllib3.Timeout(connect=5.0, read=30.0),
    retries=False,
)

# Initialize Storage client
storage_client = storage.Client()

# Environment variables
BASE = os.environ.get("INCYDR_BASE_URL", "").rstrip("/")
CID = os.environ.get("INCYDR_CLIENT_ID", "")
CSECRET = os.environ.get("INCYDR_CLIENT_SECRET", "")
BUCKET = os.environ.get("GCS_BUCKET", "")
PREFIX_BASE = os.environ.get("GCS_PREFIX", "code42/")
PAGE_SIZE = int(os.environ.get("PAGE_SIZE", "500"))
LOOKBACK_MINUTES = int(os.environ.get("LOOKBACK_MINUTES", "60"))
STREAMS = [s.strip() for s in os.environ.get("STREAMS", "users").split(",") if s.strip()]
FE_QUERY_JSON = os.environ.get("FE_QUERY_JSON", "").strip()
FE_PAGE_SIZE = int(os.environ.get("FE_PAGE_SIZE", "1000"))

def now_utc():
    return datetime.now(timezone.utc)

def iso_minus(minutes: int):
    return (now_utc() - timedelta(minutes=minutes)).strftime("%Y-%m-%dT%H:%M:%SZ")

def put_json(bucket, prefix: str, page_label: str, data):
    ts = now_utc().strftime("%Y/%m/%d/%H%M%S")
    key = f"{PREFIX_BASE}{prefix}{ts}-{page_label}.json"
    blob = bucket.blob(key)
    blob.upload_from_string(json.dumps(data), content_type='application/json')
    return key

def get_token():
    """Get OAuth 2.0 access token using client credentials flow."""
    token_url = f"{BASE}/v1/oauth/token"

    # Encode credentials
    import base64
    credentials = f"{CID}:{CSECRET}"
    encoded_credentials = base64.b64encode(credentials.encode('utf-8')).decode('utf-8')

    headers = {
        'Authorization': f'Basic {encoded_credentials}',
        'Content-Type': 'application/x-www-form-urlencoded',
        'Accept': 'application/json'
    }

    body = 'grant_type=client_credentials'

    backoff = 1.0
    max_retries = 3

    for attempt in range(max_retries):
        response = http.request('POST', token_url, body=body, headers=headers)

        if response.status == 429:
            retry_after = int(response.headers.get('Retry-After', str(int(backoff))))
            print(f"Rate limited (429) on token request. Retrying after {retry_after}s...")
            time.sleep(retry_after)
            backoff = min(backoff * 2, 30.0)
            continue

        if response.status != 200:
            raise RuntimeError(f"Failed to get access token: {response.status} - {response.data.decode('utf-8')}")

        data = json.loads(response.data.decode('utf-8'))
        return data['access_token']

    raise RuntimeError(f"Failed to get token after {max_retries} retries due to rate limiting")

def auth_header():
    token = get_token()
    return {
        "Authorization": f"Bearer {token}",
        "Accept": "application/json"
    }

def http_get(path: str, params: dict = None, headers: dict = None):
    url = f"{BASE}{path}"
    if params:
        from urllib.parse import urlencode
        url += "?" + urlencode(params)

    backoff = 1.0
    max_retries = 3

    for attempt in range(max_retries):
        response = http.request('GET', url, headers=headers)

        if response.status == 429:
            retry_after = int(response.headers.get('Retry-After', str(int(backoff))))
            print(f"Rate limited (429). Retrying after {retry_after}s...")
            time.sleep(retry_after)
            backoff = min(backoff * 2, 30.0)
            continue

        return response.data

    raise RuntimeError(f"Failed after {max_retries} retries due to rate limiting")

def http_post_json(path: str, body: dict, headers: dict = None):
    url = f"{BASE}{path}"

    backoff = 1.0
    max_retries = 3

    for attempt in range(max_retries):
        response = http.request(
            'POST',
            url,
            body=json.dumps(body),
            headers={**headers, 'Content-Type': 'application/json'}
        )

        if response.status == 429:
            retry_after = int(response.headers.get('Retry-After', str(int(backoff))))
            print(f"Rate limited (429). Retrying after {retry_after}s...")
            time.sleep(retry_after)
            backoff = min(backoff * 2, 30.0)
            continue

        return response.data

    raise RuntimeError(f"Failed after {max_retries} retries due to rate limiting")

# USERS (/v1/users)
def pull_users(bucket, hdrs):
    next_token = None
    pages = 0
    while True:
        params = {"active": "true", "blocked": "false", "pageSize": PAGE_SIZE}
        if next_token:
            params["pageToken"] = next_token
        raw = http_get("/v1/users", params, hdrs)
        data = json.loads(raw.decode('utf-8'))
        put_json(bucket, "users/", f"users-page-{pages}", data)
        pages += 1
        next_token = data.get("nextPageToken") or data.get("next_page_token")
        if not next_token:
            break
    return pages

# AUDIT LOG (/v1/audit/log)
def pull_audit(bucket, hdrs):
    start_iso = iso_minus(LOOKBACK_MINUTES)
    next_token = None
    pages = 0
    while True:
        params = {"startTime": start_iso, "pageSize": PAGE_SIZE}
        if next_token:
            params["pageToken"] = next_token
        raw = http_get("/v1/audit/log", params, hdrs)
        try:
            data = json.loads(raw.decode('utf-8'))
            put_json(bucket, "audit/", f"audit-page-{pages}", data)
            next_token = data.get("nextPageToken") or data.get("next_page_token")
            pages += 1
            if not next_token:
                break
        except Exception as e:
            print(f"Error parsing audit log response: {e}")
            # Save raw response
            ts = now_utc().strftime("%Y/%m/%d/%H%M%S")
            key = f"{PREFIX_BASE}audit/{ts}-audit-export.bin"
            blob = bucket.blob(key)
            blob.upload_from_string(raw, content_type='application/octet-stream')
            pages += 1
            break
    return pages

# CASES (/v1/cases)
def pull_cases(bucket, hdrs):
    next_token = None
    pages = 0
    while True:
        params = {"pageSize": PAGE_SIZE}
        if next_token:
            params["pageToken"] = next_token
        raw = http_get("/v1/cases", params, hdrs)
        data = json.loads(raw.decode('utf-8'))
        put_json(bucket, "cases/", f"cases-page-{pages}", data)
        pages += 1
        next_token = data.get("nextPageToken") or data.get("next_page_token")
        if not next_token:
            break
    return pages

# FILE EVENTS (/v2/file-events/search)
def pull_file_events(bucket, hdrs):
    if not FE_QUERY_JSON:
        return 0
    try:
        base_query = json.loads(FE_QUERY_JSON)
    except Exception as e:
        print(f"Error: FE_QUERY_JSON is not valid JSON: {e}")
        return 0

    pages = 0
    next_token = None
    while True:
        body = dict(base_query)
        body["pageSize"] = FE_PAGE_SIZE
        if next_token:
            body["pageToken"] = next_token
        raw = http_post_json("/v2/file-events/search", body, hdrs)
        data = json.loads(raw.decode('utf-8'))
        put_json(bucket, "file_events/", f"fileevents-page-{pages}", data)
        pages += 1
        next_token = (
            data.get("nextPageToken") or 
            data.get("next_page_token") or 
            (data.get("file_events") or {}).get("nextPageToken")
        )
        if not next_token:
            break
    return pages

@functions_framework.cloud_event
def main(cloud_event):
    """
    Cloud Run function triggered by Pub/Sub to fetch logs from Code42 Incydr API and write to GCS.

    Args:
        cloud_event: CloudEvent object containing Pub/Sub message
    """

    if not all([BASE, CID, CSECRET, BUCKET]):
        print('Error: Missing required environment variables')
        return

    try:
        bucket = storage_client.bucket(BUCKET)
        hdrs = auth_header()
        report = {}

        if "users" in STREAMS:
            print("Fetching users...")
            report["users_pages"] = pull_users(bucket, hdrs)
        if "audit" in STREAMS:
            print("Fetching audit logs...")
            report["audit_pages"] = pull_audit(bucket, hdrs)
        if "cases" in STREAMS:
            print("Fetching cases...")
            report["cases_pages"] = pull_cases(bucket, hdrs)
        if "file_events" in STREAMS:
            print("Fetching file events...")
            report["file_events_pages"] = pull_file_events(bucket, hdrs)

        print(f'Successfully processed logs: {json.dumps(report)}')

    except Exception as e:
        print(f'Error processing logs: {str(e)}')
        raise
    • Segundo arquivo: requirements.txt::
    functions-framework==3.*
google-cloud-storage==2.*
urllib3>=2.0.0

  3. Clique em Implantar para salvar e implantar a função.

  4. Aguarde a conclusão da implantação (2 a 3 minutos).

Criar o job do Cloud Scheduler

O Cloud Scheduler publica mensagens no tópico do Pub/Sub em intervalos regulares, acionando a função do Cloud Run.

  1. No Console do GCP, acesse o Cloud Scheduler.
  2. Clique em Criar job.

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

    Configuração Valor
    Nome code42-incydr-hourly
    Região Selecione a mesma região da função do Cloud Run
    Frequência 0 * * * * (a cada hora, na hora)
    Fuso horário Selecione o fuso horário (UTC recomendado)
    Tipo de destino Pub/Sub
    Tópico Selecione o tópico code42-incydr-trigger.
    Corpo da mensagem {} (objeto JSON vazio)

  4. Clique em Criar.

Opções de frequência de programação

  • Escolha a frequência com base no volume de registros e nos requisitos de latência:

    Frequência Expressão Cron Caso de uso
    A cada 5 minutos */5 * * * * Alto volume e baixa latência
    A cada 15 minutos */15 * * * * Volume médio
    A cada hora 0 * * * * Padrão (recomendado)
    A cada 6 horas 0 */6 * * * Baixo volume, processamento em lote
    Diariamente 0 0 * * * Coleta de dados históricos

Testar o job do programador

  1. No console do Cloud Scheduler, encontre seu job (code42-incydr-hourly).
  2. Clique em Forçar execução para acionar manualmente.
  3. Aguarde alguns segundos e acesse Cloud Run > Serviços > code42-incydr-collector > Registros.

  4. Verifique se a função foi executada com sucesso. Procure:

    Fetching users...
Fetching audit logs...
Fetching cases...
Successfully processed logs: {"users_pages": X, "audit_pages": Y, "cases_pages": Z}

  5. Verifique o bucket do GCS (code42-incydr-logs) para confirmar se os registros foram gravados.

Se você encontrar erros nos registros:

  • HTTP 401: verifique as credenciais da API nas variáveis de ambiente
  • HTTP 403: verifique se o cliente da API tem as permissões necessárias no console do Code42 Incydr.
  • HTTP 429: limitação de taxa. A função vai tentar de novo automaticamente com espera.
  • Não foi possível receber o token de acesso: verifique se INCYDR_BASE_URL, INCYDR_CLIENT_ID e INCYDR_CLIENT_SECRET estão corretos.

Recuperar a conta de serviço do Google SecOps

O Google SecOps usa uma conta de serviço exclusiva para ler dados do seu bucket do GCS. Você precisa conceder a essa conta de serviço acesso ao seu bucket.

Receber o e-mail da conta de serviço

  1. Acesse Configurações do SIEM > Feeds.
  2. Clique em Adicionar novo feed.
  3. Clique em Configurar um único feed.
  4. No campo Nome do feed, insira um nome para o feed (por exemplo, Code42 Incydr Datasets).
  5. Selecione Google Cloud Storage V2 como o Tipo de origem.
  6. Selecione Code42 Incydr como o Tipo de registro.

  7. Clique em Receber conta de serviço. Um e-mail exclusivo da conta de serviço será exibido, por exemplo:

    chronicle-12345678@chronicle-gcp-prod.iam.gserviceaccount.com

  8. Copie esse endereço de e-mail para usar na próxima etapa.

Conceder permissões do IAM à conta de serviço do Google SecOps

A conta de serviço do Google SecOps precisa do papel Leitor de objetos do Storage no seu bucket do GCS.

  1. Acesse Cloud Storage > Buckets.
  2. Clique no nome do bucket (code42-incydr-logs).
  3. Acesse a guia Permissões.
  4. Clique em Conceder acesso.
  5. Informe os seguintes detalhes de configuração:
    • Adicionar principais: cole o e-mail da conta de serviço do Google SecOps.
    • Atribuir papéis: selecione Leitor de objetos do Storage.

  6. Clique em Salvar.

Configurar um feed no Google SecOps para ingerir registros do Code42 Incydr

  1. Acesse Configurações do SIEM > Feeds.
  2. Clique em Adicionar novo feed.
  3. Clique em Configurar um único feed.
  4. No campo Nome do feed, insira um nome para o feed (por exemplo, Code42 Incydr Datasets).
  5. Selecione Google Cloud Storage V2 como o Tipo de origem.
  6. Selecione Code42 Incydr como o Tipo de registro.
  7. Clique em Próxima.

  8. Especifique valores para os seguintes parâmetros de entrada:

    • URL do bucket de armazenamento: insira o URI do bucket do GCS com o caminho do prefixo:

      gs://code42-incydr-logs/code42/

      • Substitua:

        • code42-incydr-logs: o nome do bucket do GCS.
        • code42/: prefixo/caminho da pasta opcional onde os registros são armazenados (deixe em branco para a raiz).

      • Exemplos:

        • Bucket raiz: gs://code42-incydr-logs/
        • Com prefixo: gs://code42-incydr-logs/code42/

    • Opção de exclusão da fonte: selecione a opção de exclusão de acordo com sua preferência:

      • Nunca: nunca exclui arquivos após as transferências (recomendado para testes).
      • Excluir arquivos transferidos: exclui os arquivos após a transferência bem-sucedida.
      • Excluir arquivos transferidos e diretórios vazios: exclui arquivos e diretórios vazios após a transferência bem-sucedida.

    • Idade máxima do arquivo: inclui arquivos modificados nos últimos dias. O padrão é de 180 dias.

    • Namespace do recurso: o namespace do recurso.

    • Rótulos de ingestão: o rótulo a ser aplicado aos eventos deste feed.

  9. Clique em Próxima.

  10. Revise a nova configuração do feed na tela Finalizar e clique em Enviar.

Registro de alterações

Ver o registro de alterações deste analisador

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