Editor de mapeamento — referência de campos

O editor de mapeamento é onde você ensina o CentralOps a traduzir os eventos de um fornecedor para o padrão único da plataforma (OCSF). Cada regra que você cria diz: "pegue este campo do evento original e grave neste campo padronizado", aplicando conversões pelo caminho (texto para número, fuso de data, tabelas de tradução, etc.).

Você edita os mapeamentos na interface, sem escrever código de infraestrutura. O caminho é:

Menu Normaliza -> Mapeamentos para ver e editar todos os mapeamentos.
Ou, a partir de um conector específico, em Coleta -> Integrações, abra a integração e vá até a seção de mapeamento dela.

Cada mapeamento tem uma lista de regras. Cada regra grava um campo do evento normalizado. Você monta as regras pelo editor e valida o resultado antes de salvar.

Quando usar

Mexa no editor de mapeamento quando:

Um novo fornecedor entrou em produção e os campos chegam "crus". Você precisa apontar quais campos do produto viram severidade, horário, IP de origem, usuário, etc., para que os eventos cheguem corretos aos destinos, que é onde você depois pesquisa o evento (seu SIEM, data lake ou bucket).
O fornecedor manda severidade como texto e o padrão espera número. Ex.: o produto envia high, medium, low e o OCSF precisa de 4, 3, 2. Você cria uma tabela de tradução na regra (ver Tabela de tradução).
Eventos importantes estão indo parar na Quarentena por falta de um campo crítico. Você marca o campo como obrigatório para garantir que qualquer evento sem ele seja isolado para revisão em vez de passar pela metade (ver Campo obrigatório).
O fornecedor mudou o nome de um campo ou passou a mandar a mesma informação em lugares diferentes. Você adiciona fontes alternativas para a mesma regra (ver Fontes alternativas).

Antes de começar: validar antes de salvar

Sempre que terminar de montar ou ajustar regras, rode a validação (ensaio/dry-run) dentro do próprio editor antes de salvar. Ela aplica o mapeamento a eventos de exemplo e mostra, campo a campo, o que cada regra produziria. Use isso para conferir se as severidades, horários e demais campos estão saindo como você espera. Quando estiver satisfeito, salve a nova versão do mapeamento — o histórico de versões fica registrado e pode ser comparado.

Estrutura de uma regra

Cada regra responde duas perguntas: de onde vem o valor e para onde ele vai. As demais opções são transformações aplicadas no meio do caminho.

Opção na regra	O que faz	Obrigatória?
Campo de destino (`target`)	Para qual campo padronizado o valor vai	Sim
Campo de origem (`source`)	De qual campo do evento original o valor vem	Sim*
Valor fixo (`const`)	Um valor constante, igual para todos os eventos	Sim*
Valor padrão (`default`)	O que usar quando a origem vier vazia	Não
Conversão antes da tradução (`pre_cast`)	Converte o tipo antes de consultar a tabela de tradução	Não
Tabela de tradução (`value_map`)	Troca valores do fornecedor pelos valores padrão	Não
Conversão de tipo (`type_cast`)	Converte o formato final (data, número, texto)	Não
Campo obrigatório (`required`)	Isola o evento se este campo vier vazio	Não
Fontes alternativas (`fallback_source`)	Outros campos a tentar se o principal vier vazio	Não
Condição (`when`)	Só aplica a regra se uma condição for verdadeira	Não
Padrão esperado (`expected_always_default`)	Marca que é normal este campo cair sempre no valor padrão	Não

* Toda regra precisa de um campo de origem OU um valor fixo — nunca os dois ao mesmo tempo.

Campo de destino (`target`)

O que é: o campo padronizado (OCSF) que esta regra preenche.

Como informar: o caminho do campo separado por ponto, por exemplo:

normalized.class_uid
normalized.finding_info.title
normalized.device.name

Lembre-se: o campo de destino nunca fica em branco.

Campo de origem (`source`)

O que é: o campo do evento original (como o fornecedor enviou) de onde o valor é lido.

Como informar: o nome do campo. Pode ser um campo simples, um campo aninhado ou uma expressão de busca:

Exemplo	O que pega
`severity`	um campo simples na raiz do evento
`device.name`	um campo dentro de outro
`createdAt \|\| raisedAt`	tenta `createdAt`; se vazio, usa `raisedAt`

Comportamento:

Se a origem vier vazia, a regra passa para o valor padrão (se houver).
Uma lista vazia conta como valor preenchido — não é o mesmo que vazio.

Expressões avançadas (JMESPath completo)

O campo de origem não se limita aos três formatos acima. Ele é uma expressão JMESPath completa, e o motor não restringe nada: filtros, funções, pipes e seleções múltiplas funcionam todos.

Isso importa na prática porque fornecedores usam marcadores para "campo vazio" em vez de omitir o campo. O Windows, por exemplo, manda - e 0x0:

Expressão	Para que serve
`[data.win.eventdata.param2][?@!='-']\|[0]`	ignora o valor quando o Windows manda `-` (vazio)
`([data.win.eventdata.subStatus][?@!='0x0'&&@!='0x00000000']\|[0]) \|\| data.win.eventdata.status`	usa `subStatus` só se for significativo; senão cai para `status`
`to_number(data.win.eventdata.ipPort)`	converte texto para número dentro da própria expressão

Outras funções úteis: length(), join(), sort_by(), keys(), contains(). A especificação oficial do JMESPath vale integralmente.

Expressões avançadas custam desempenho

Só caminhos simples do tipo a.b.c (letras ASCII, números e _) usam o resolvedor rápido. Qualquer filtro, pipe ou função cai no interpretador completo do JMESPath — que já foi medido como 64% do tempo de normalização em um mapping grande.

Use as formas avançadas onde elas se pagam (como o filtro de - acima, que um caminho simples não consegue expressar) e prefira a.b.c quando os dois resolvem. Em um mapping com mais de 100 regras, a diferença é visível.

Ler o resultado do pré-processamento (`_`)

Uma origem que começa com _ não lê o evento original: lê o resultado das etapas de pré-processamento (preprocess). Use quando o valor precisa ser extraído antes — por exemplo, um JSON embutido dentro de um campo de texto.

Essa é uma convenção do CentralOps, não do JMESPath.

{ "target": "normalized.device.name", "source": "_parsed.hostname" }

Origem ou valor fixo, nunca os dois. Cada regra usa ou um campo de origem ou um valor fixo. Se você preencher os dois, a validação acusa erro (ver Quando algo dá errado).

Valor fixo (`const`)

O que é: um valor constante, gravado igual em todos os eventos daquele fornecedor — sem ler nada do evento original.

Quando usar: para campos OCSF que são sempre os mesmos para um fornecedor. Por exemplo, o código da classe do evento, ou um rótulo fixo como Detection Finding.

Comportamento: o valor fixo ainda passa pelas etapas de valor padrão, tabela de tradução e conversão de tipo, se você as configurar.

Valor padrão (`default`)

O que é: o que gravar quando a origem (ou o valor fixo) vier vazia.

Comportamento:

Se o valor estava vazio, ele vira o valor padrão.
Se o valor veio preenchido, o padrão é ignorado.

É a primeira coisa aplicada depois de ler a origem.

Conversão antes da tradução (`pre_cast`)

O que é: uma conversão de tipo aplicada antes de consultar a tabela de tradução.

Quando usar: o fornecedor manda o valor em um tipo, mas a sua tabela de tradução usa outro. Exemplo clássico: o produto envia a severidade como número (0 a 10), mas as chaves da sua tabela são texto (high, medium, low). Você converte número para texto antes da busca.

Os tipos de conversão disponíveis estão na Referência de operadores.

Tabela de tradução (`value_map`)

O que é: uma tabela que troca os valores do fornecedor pelos valores que o padrão exige.

Quando usar: o fornecedor envia categorias em texto e o OCSF espera códigos numéricos — o caso mais comum é severidade.

Valor do fornecedor	Valor padronizado
`critical`	`5`
`high`	`4`
`medium`	`3`
`low`	`2`
`info`	`1`

Comportamento:

Se o valor de entrada está na tabela, usa o valor traduzido.
Se não está, o valor passa sem alteração (ou cai no valor padrão, se você definir um).
A busca por texto não diferencia maiúsculas de minúsculas — high e HIGH são tratados igual.

Conversão de tipo (`type_cast`)

O que é: a conversão do formato final do valor, aplicada por último.

Exemplos de uso:

Converter uma data em texto (ISO) para o formato de horário do padrão.
Forçar um texto para maiúsculas.
Converter um texto numérico em número.

Os tipos de conversão disponíveis estão na Referência de operadores.

Campo obrigatório (`required`)

O que é: marca o campo como indispensável. Se o valor final vier vazio, o evento inteiro é isolado para revisão.

Quando usar: para campos OCSF que não podem faltar — por exemplo o horário do evento ou o identificador do achado. Marcando como obrigatório, qualquer evento sem esse campo vai para a Quarentena em vez de seguir incompleto, o que evita alertas "quebrados" nas telas de operação.

O que acontece quando falta: o evento aparece em Normaliza -> Quarentena, com o motivo indicando que faltou um campo do mapeamento. De lá você revisa o evento, corrige o mapeamento e reprocessa.

Fontes alternativas (`fallback_source`)

O que é: uma lista de outros campos a tentar, em ordem, se o campo de origem principal vier vazio.

Quando usar: o fornecedor coloca a mesma informação em campos diferentes dependendo do tipo de evento, ou mudou o nome do campo entre versões. Você lista as alternativas e a plataforma tenta uma a uma.

Comportamento:

Tenta o campo de origem principal.
Se vier vazio, tenta a primeira alternativa.
Continua até achar um valor preenchido.
Se todas vierem vazias, usa o valor padrão.

Condição (`when`)

O que é: um filtro que faz a regra rodar só quando uma condição for verdadeira.

Quando usar: você só quer preencher um campo em certos eventos. Por exemplo, gravar o e-mail do remetente apenas quando o evento realmente tiver um remetente.

Comportamento: se a condição não for atendida, a regra é pulada por completo — o campo de destino fica sem ser escrito (diferente de gravar vazio).

As condições disponíveis estão na Referência de operadores.

Padrão esperado (`expected_always_default`)

O que é: uma marcação informativa. Diz que é normal este campo sempre cair no valor padrão, porque o fornecedor simplesmente não fornece essa informação.

Quando usar: durante a validação, a plataforma avisa quando uma regra está sempre usando o valor padrão (sinal de que pode estar mal configurada). Se você sabe que é esperado — o fornecedor não tem aquele dado — marque esta opção para que o aviso não apareça.

Importante: essa marcação não muda o resultado da regra. Ela só silencia o aviso de validação para casos conhecidos.

Etapas de preparação (preprocess)

Alguns fornecedores entregam parte da informação "embrulhada" — por exemplo, um campo de texto que na verdade contém outro evento em formato JSON. As etapas de preparação rodam uma vez por evento, antes de qualquer regra, para "desembrulhar" esse conteúdo e deixá-lo disponível para as regras lerem.

Hoje a operação de preparação disponível é a leitura de um campo de texto que contém JSON, transformando-o em campos navegáveis. Depois da preparação, suas regras conseguem apontar para os campos de dentro desse conteúdo.

O que você informa	Significado
A operação	Qual preparação aplicar (atualmente, ler texto JSON)
O campo de origem	De onde vem o conteúdo embrulhado, no evento original
O destino interno	Onde guardar o resultado para as regras usarem
Tolerância a erro	Se ligada, conteúdo malformado é ignorado em silêncio em vez de falhar

As operações de preparação disponíveis estão na Referência de operadores.

Redução do evento bruto (`raw_reduction`)

Todo evento entregue leva, além do evento normalizado (OCSF), uma cópia do payload que o fornecedor mandou. Essa cópia é útil para perícia — e é também a maior parte do volume que você paga no destino.

O bloco raw_reduction poda essa cópia. Ele é irmão das regras (fica no mesmo nível de preprocess e rules) e roda depois que todas as regras já leram o payload completo, de modo que a normalização nunca perde fidelidade por causa da poda.

Operação	O que faz
`max_bytes`	Encurta um texto longo para N bytes. O JSON continua válido — só o valor fica menor.
`max_items`	Mantém apenas os N primeiros itens de uma lista.
`drop`	Remove o campo inteiro. Use no que virou lixo depois da extração.
`keep_only`	Mantém só os filhos listados sob o caminho e remove os demais — inclusive campos que o fornecedor adicionar no futuro.
`drop_nulls`	Remove todos os campos de valor nulo, em qualquer profundidade. É global: não recebe caminho.

Um caminho pode atravessar listas com []: alerts[].evidences aplica a operação ao campo evidences de cada item da lista alerts.

Exemplo

{
  "raw_reduction": [
    { "path": "rawData.lineage", "drop": true },
    { "path": "full_log", "max_bytes": 16384 },
    { "path": "alerts[].evidences", "drop": true },
    { "drop_nulls": true }
  ]
}

Esse é o padrão que os mapeamentos de fábrica usam: descartar as subárvores que o pré-processamento já extraiu (elas viram duplicata pura), encurtar os textos gigantes e limpar os campos nulos.

Onde este bloco é editado

O raw_reduction não aparece no editor visual de mapeamento — ele vive na definição JSON, alterada por quem administra a plataforma. Se um campo que você esperava sumiu do payload bruto, é aqui que se verifica.

Poda por mapeamento x descarte por rota

O raw_reduction remove o que é lixo para todos os destinos — é conhecimento sobre o fornecedor. Para decidir se um destino específico recebe ou não o payload bruto (o data lake quer, o SIEM cobrado por volume talvez não), use a opção Descartar o evento bruto da regra de roteamento. Veja Roteamento.

Em que ordem as transformações acontecem

Para cada regra, a plataforma aplica as opções nesta ordem:

Lê a origem (ou usa o valor fixo).
Valor padrão — se vier vazio, usa o padrão.
Conversão antes da tradução — ajusta o tipo para a tabela.
Tabela de tradução — troca o valor pelo padronizado.
Conversão de tipo — ajusta o formato final.
Grava no campo de destino.

Saber essa ordem ajuda a entender por que, por exemplo, a conversão de número para texto precisa vir antes da tabela de tradução de severidade.

Construir listas de observáveis

Há um tipo especial de regra para montar listas de observáveis (IPs, e-mails, hashes, etc.) a partir de vários campos do evento de uma vez. Em vez de uma regra por item, você descreve cada observável que quer extrair e a plataforma monta a lista.

Para cada item você informa:

O que você informa	Significado
Nome e tipo	Como identificar o observável (ex.: "endereço IP", "endereço de e-mail")
O campo de origem	De onde ler o valor no evento
Expandir lista	Se o campo já é uma lista (ex.: vários destinatários), gera um observável por item

No nível da regra você ainda pode:

Omitir vazios — não cria observáveis sem valor.
Remover duplicados — descarta repetições, mantendo a primeira ocorrência.

Para um passo a passo, veja o Cookbook e os Casos de uso.

Quando algo dá errado

Você descobre problemas de mapeamento em dois momentos.

Ao salvar (problema na definição da regra)

Se uma regra estiver mal montada, a plataforma bloqueia o salvamento e mostra um aviso de validação na tela do editor, indicando qual regra ou campo está com erro. Os casos mais comuns são:

A expressão do campo de origem está escrita de forma inválida.
Um nome de conversão de tipo não existe.
A regra tem campo de origem e valor fixo ao mesmo tempo.
Faltou um campo obrigatório na própria regra.

O que fazer: corrija a regra apontada pelo aviso e rode a validação novamente antes de salvar. Você sempre acessa o editor por Normaliza -> Mapeamentos (ou pela seção de mapeamento da integração em Coleta -> Integrações).

Ao processar eventos (problema com um evento real)

Mesmo com o mapeamento salvo e válido, um evento específico pode falhar — por exemplo, um campo obrigatório veio vazio, ou um valor não pôde ser convertido (texto onde se esperava número). Nesses casos o evento vai para a Quarentena.

O que fazer:

Abra Normaliza -> Quarentena para ver os eventos isolados e o motivo de cada um.
Use o motivo para identificar qual regra precisa de ajuste (campo obrigatório, conversão, etc.).
Corrija o mapeamento no editor e reprocesse os eventos isolados.

Para um guia detalhado, veja Resolução de problemas.

Quando usar​

Antes de começar: validar antes de salvar​

Estrutura de uma regra​

Campo de destino (target)​

Campo de origem (source)​

Expressões avançadas (JMESPath completo)​

Ler o resultado do pré-processamento (_)​

Valor fixo (const)​

Valor padrão (default)​

Conversão antes da tradução (pre_cast)​

Tabela de tradução (value_map)​

Conversão de tipo (type_cast)​

Campo obrigatório (required)​

Fontes alternativas (fallback_source)​

Condição (when)​

Padrão esperado (expected_always_default)​

Etapas de preparação (preprocess)​

Redução do evento bruto (raw_reduction)​

Exemplo​

Em que ordem as transformações acontecem​

Construir listas de observáveis​

Quando algo dá errado​

Ao salvar (problema na definição da regra)​

Ao processar eventos (problema com um evento real)​

Quando usar

Antes de começar: validar antes de salvar

Estrutura de uma regra

Campo de destino (`target`)

Campo de origem (`source`)

Expressões avançadas (JMESPath completo)

Ler o resultado do pré-processamento (`_`)

Valor fixo (`const`)

Valor padrão (`default`)

Conversão antes da tradução (`pre_cast`)

Tabela de tradução (`value_map`)

Conversão de tipo (`type_cast`)

Campo obrigatório (`required`)

Fontes alternativas (`fallback_source`)

Condição (`when`)

Padrão esperado (`expected_always_default`)

Etapas de preparação (preprocess)

Redução do evento bruto (`raw_reduction`)

Exemplo

Em que ordem as transformações acontecem

Construir listas de observáveis

Quando algo dá errado

Ao salvar (problema na definição da regra)

Ao processar eventos (problema com um evento real)