Coletar conjuntos de dados principais do Code42 Incydr

Compatível com:

Google SecOps SIEM

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 Cloud Storage ativada
Permissões para criar e gerenciar buckets 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

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

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 com base nas 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

Clique em Criar.

Coletar credenciais da API do Code42 Incydr

Criar cliente de API

Faça login no console da Web do Code42 Incydr.
Acesse Administração > Integrações > Clientes de API.
Clique em Criar cliente de API.
Na caixa de diálogo Criar novo cliente da API, insira um nome para o cliente (por exemplo, Google Security Operations Integration).
Copie e salve os seguintes detalhes em um local seguro:
- ID do cliente: o identificador do cliente da API.
- Chave secreta: a chave secreta do cliente da API.
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 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:

No console do Code42 Incydr, acesse Administração > Integrações > Clientes da API.
Clique no nome do cliente de API que você criou.
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.
Observação :se essas opções não aparecerem ou se você não conseguir acessar determinados endpoints, entre em contato com o administrador do Code42 para conceder as permissões necessárias. Verifique se o cliente da API tem o nível de acesso necessário da API do Incydr (acesso total ou básico), conforme descrito na documentação do nível de acesso da API do Code42 Incydr.

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

No Console do GCP, acesse IAM e administrador > Contas de serviço.
Clique em Criar conta de serviço.
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.
Clique em Criar e continuar.
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.
Clique em Continuar.
Clique em Concluído.

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

Administrador de objetos do Storage: grava registros em um 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:

Acesse Cloud Storage > Buckets.
Clique no nome do bucket (por exemplo, code42-incydr-logs).
Acesse a guia Permissões.
Clique em Conceder acesso.
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.
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.

No Console do GCP, acesse Pub/Sub > Tópicos.
Selecione Criar tópico.
Informe os seguintes detalhes de configuração:
- ID do tópico: insira code42-incydr-trigger.
- Não altere as outras configurações.
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.

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

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.

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.
Na seção Autenticação:
1. Selecione Exigir autenticação.
2. Confira o Identity and Access Management (IAM).
Observação: o Pub/Sub processa automaticamente a autenticação ao invocar a função.
Role a tela para baixo e abra Contêineres, rede, segurança.
Acesse a guia Segurança:
- Conta de serviço: selecione a conta de serviço code42-incydr-collector-sa.

Acesse a guia Contêineres:

Clique em Variáveis e secrets.
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 de 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: JSON de consulta de eventos de arquivo
`FE_PAGE_SIZE`	`1000`	Opcional: tamanho da página de eventos de arquivo

Role a tela para baixo na guia Variáveis e secrets até Solicitações:
- Tempo limite da solicitação: insira 600 segundos (10 minutos).
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.
Role até Ambiente de execução:
- Selecione Padrão (recomendado).
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.
Clique em Criar.
Aguarde a criação do serviço (1 a 2 minutos).
Depois que o serviço é criado, o editor de código inline é aberto automaticamente.

Adicionar código da função

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

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

Clique em Implantar para salvar e implantar a função.
Aguarde a conclusão da implantação (2 a 3 minutos).

Observação: a configuração do acionador do Pub/Sub cria automaticamente as assinaturas e permissões necessárias.

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.

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

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)

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
Diário	`0 0 * * *`	Coleta de dados históricos

Testar o job do programador

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

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}

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 novamente 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

Acesse Configurações do SIEM > Feeds.
Clique em Adicionar novo feed.
Clique em Configurar um único feed.
No campo Nome do feed, insira um nome para o feed (por exemplo, Code42 Incydr Datasets).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione Code42 Incydr como o Tipo de registro.
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
```
Copie esse endereço de e-mail para usar na próxima etapa.

Observação: cada instância do Google SecOps tem uma conta de serviço exclusiva. Não use contas de serviço de outras documentações ou exemplos.

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

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

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

Observação: se você planeja usar a opção de exclusão "Excluir arquivos transferidos" ou "Excluir arquivos transferidos e diretórios vazios", conceda o papel Administrador de objetos do Storage em vez de Leitor de objetos do Storage.

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

Acesse Configurações do SIEM > Feeds.
Clique em Adicionar novo feed.
Clique em Configurar um único feed.
No campo Nome do feed, insira um nome para o feed (por exemplo, Code42 Incydr Datasets).
Selecione Google Cloud Storage V2 como o Tipo de origem.
Selecione Code42 Incydr como o Tipo de registro.
Clique em Próxima.
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/
Observação: sempre inclua a barra (/) no final do URI.
- 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.
  Observação: se você selecionar uma opção de exclusão, a conta de serviço precisará ter o papel Administrador de objetos do Storage em vez de Leitor de objetos do Storage. Atualize as permissões do IAM de acordo com a necessidade.
- Idade máxima do arquivo: inclui arquivos modificados no último número de 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.
Clique em Próxima.
Revise a nova configuração do feed na tela Finalizar e clique em Enviar.

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