Endpoints de análise

Grupo /analysis/* + /rulesets/compile — validação de regras/decoders, logtest nativo (predecoder → decoder → rule) e consulta do schema XML suportado pelo motor.

Todos os endpoints exigem o escopo analysis:run (ou sessão com permissão equivalente).

Tabela de endpoints

Método	Caminho	Escopo	Descrição
POST	/rulesets/compile	analysis:run	Alias histórico de /analysis/validate.
POST	/analysis/validate	analysis:run	Compila e valida um ruleset, retorna diagnósticos.
GET	/analysis/schema	analysis:run	Retorna o schema XML aceito (tags, atributos, valores).
POST	/analysis/logtest-native	analysis:run	Roda um evento contra o ruleset e retorna trace completo.
POST	/analysis/full	analysis:run	Idêntico ao logtest-native + análise estática adicional.

/rulesets/compile e /analysis/validate aceitam o mesmo request/response. Use /analysis/validate — o outro existe por compatibilidade.

POST /analysis/validate

Compila um conjunto de rules/decoders e devolve diagnósticos. Usado para validar antes de publicar, ou no CI como gate de qualidade.

Auth: escopo analysis:run.

Query parameters:

Nome	Tipo	Default	Descrição
include_baseline	bool	false	Quando true, diagnostics[] inclui também itens originados do baseline Wazuh (source_scope="default"). Por padrão a API entrega só os achados do seu conteúdo — baseline_issue_count continua refletindo o total. Use true se quiser inspecionar os warnings do baseline (ex.: debugging local, comparação com a UI).

Request body (ValidationRequest):

{
  "include_disk_defaults": true,
  "include_disk_custom": true,
  "files": [
    {
      "filename": "local_rules.xml",
      "kind": "rules",
      "scope": "adhoc",
      "content": "<group name=\"local\"><rule id=\"100010\" level=\"3\">...</rule></group>"
    },
    {
      "filename": "local_decoders.xml",
      "kind": "decoders",
      "scope": "adhoc",
      "content": "<decoder name=\"custom\">...</decoder>"
    }
  ]
}

• include_disk_defaults (bool, default true) — inclui as rules/decoders Wazuh embarcados no servidor.
• include_disk_custom (bool, default true) — inclui as rules/decoders da pasta data/custom da instância.
• files[] — conteúdo extra enviado in-line. Cada arquivo:
  • filename (string, 1–255 chars) — nome lógico; usado em mensagens de erro.
  • kind — "rules" ou "decoders".
  • scope — "default", "custom" ou "adhoc" (o normal para conteúdo enviado pelo cliente).
  • content — XML cru.

Response 200 (ValidationResponse):

{
  "ok": true,
  "summary": {
    "total_rule_files": 12,
    "total_decoder_files": 8,
    "total_rules": 8621,
    "total_decoders": 623,
    "compiled_hash": "abc123…",
    "loaded_from_disk": true
  },
  "diagnostics": [
    {
      "severity": "warning",
      "source": "rules",
      "code": "rule_overlapping_level",
      "message": "Rule 100010 shadows rule 5716",
      "filename": "local_rules.xml",
      "line": 3,
      "column": 5,
      "hint": "Considere usar um ID fora da faixa do baseline",
      "evidence": "<rule id=\"100010\">",
      "source_scope": "adhoc"
    }
  ],
  "performance": {
    "source_build_ms": 45.2,
    "compile_ms": 120.5,
    "total_ms": 165.7,
    "cache_hit": false
  },
  "baseline_issue_count": 0
}

• ok — true se nenhum diagnóstico com severity="error" foi encontrado no seu conteúdo (erros do baseline não bloqueiam o gate, mesmo quando include_baseline=true).
• diagnostics[] — por default, apenas diagnósticos do conteúdo do cliente (arquivos com scope="custom" ou "adhoc"). Problemas no baseline Wazuh são ocultados e contabilizados em baseline_issue_count. Para incluir os do baseline, passe ?include_baseline=true.
• performance.cache_hit — true quando o compiled_hash já estava em cache.

Diagnostic

Cada item de diagnostics[]:

Campo	Valores possíveis
severity	error, warning, info, success
source	xml, rules, decoders, engine, session, filesystem
code	Identificador do tipo de erro (ex.: decoder_missing_parent, regex_invalid, rule_duplicate_id).
message	Mensagem legível.
filename	Arquivo de origem (se aplicável).
line, column	Posição no arquivo (1-indexed).
hint	Sugestão de ação.
evidence	Trecho do XML que disparou o diagnóstico.
source_scope	default, custom, adhoc ou null.

Efeitos colaterais

• Emite webhook validation.completed com {ok, diagnostic_count, total_rules, total_decoders}.
• Conta contra o plano da organização (métrica analysis_runs — embora /validate específico atualmente não consuma run; o consumo é em logtest-native e full).

Exemplo curl (resposta limpa, só achados do seu conteúdo):

# RF_BASE sem barra final — evita //analysis/validate, que alguns proxies não normalizam.
RF_BASE="https://www.ruleforge.cloud/api/v1"

curl -X POST "$RF_BASE/analysis/validate" \
  -H "X-API-Key: $RF_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

Para inspecionar também os warnings do baseline Wazuh (ex.: debugging local, comparar com a UI):

curl -X POST "$RF_BASE/analysis/validate?include_baseline=true" \
  -H "X-API-Key: $RF_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

GET /analysis/schema

Retorna o schema declarativo das tags XML aceitas — tags, atributos, valores permitidos. Usado pelo editor do frontend para autocomplete/validação; pode ser útil para geradores de conteúdo.

Auth: escopo analysis:run.

Response 200 (ValidationSchemaResponse):

{
  "version": "4.10",
  "references": ["https://documentation.wazuh.com/…"],
  "decoders": {
    "top_level_tags": ["decoder"],
    "wrapper_tags": [],
    "elements": [
      {
        "name": "decoder",
        "context": "root",
        "description": "Root decoder element",
        "runtime_supported": true,
        "attributes": [
          {
            "name": "name",
            "required": true,
            "allowed_values": [],
            "description": "Unique decoder identifier"
          }
        ],
        "child_tags": ["program_name", "prematch", "regex", "order"],
        "allowed_values": []
      }
    ],
    "root_attributes": [],
    "group_attributes": [],
    "mitre_elements": []
  },
  "rules": { "...": "..." }
}

POST /analysis/logtest-native

Roda o pipeline completo sobre um único evento: predecoder → decoder → rule → insights. Retorna o trace de execução para depuração.

Auth: escopo analysis:run. Consome 1 unidade do plano (analysis_runs).

Request body (LogtestRequest):

{
  "include_disk_defaults": true,
  "include_disk_custom": false,
  "files": [],
  "input": {
    "event": "Jan 10 12:00:01 web01 sshd[1234]: Failed password for root from 10.0.0.5",
    "log_format": "syslog",
    "location": "/var/log/auth.log",
    "session_id": "correlation-123"
  }
}

• Tudo de ValidationRequest é aceito (ruleset).
• input.event — string do evento (1 byte a 8 MB).
• input.log_format — auto, syslog, json, eventchannel, plain.
• input.location — opcional, 0–512 chars; usado por decoders que dependem de path.
• input.session_id — opcional, 0–128 chars; agrupa eventos para rules de correlação/frequência.

Response 200 (LogtestResponse):

{
  "ok": true,
  "summary": { "total_rules": 8621, "...": "..." },
  "diagnostics": [],
  "performance": {
    "source_build_ms": 0,
    "compile_ms": 0,
    "predecode_ms": 0.8,
    "decode_ms": 2.1,
    "rule_ms": 6.4,
    "total_ms": 10.1,
    "cache_hit": true
  },
  "predecoded": {
    "timestamp": "Jan 10 12:00:01",
    "hostname": "web01",
    "program_name": "sshd",
    "location": "/var/log/auth.log",
    "raw_message": "Failed password for root from 10.0.0.5",
    "detected_format": "syslog"
  },
  "decoder": {
    "name": "sshd",
    "parent": null,
    "order": ["srcip", "dstuser"]
  },
  "rule": {
    "id": "5716",
    "level": 5,
    "description": "sshd: authentication failed.",
    "groups": ["syslog", "sshd", "authentication_failed"],
    "mitre_ids": ["T1110"],
    "matched": true
  },
  "matched_rules": [
    { "id": "5716", "matched": true, "...": "..." }
  ],
  "extracted_fields": {
    "dstuser": "root",
    "srcip": "10.0.0.5"
  },
  "trace": [
    { "phase": "predecode", "name": "predecoder", "matched": true, "details": {} },
    { "phase": "decode", "name": "sshd", "matched": true, "line": 42, "filename": "0100-pam_decoders.xml", "details": {} },
    { "phase": "rule", "name": "5716", "matched": true, "line": 105, "filename": "0025-sshd_rules.xml", "details": {} }
  ],
  "insights": [
    "Rule 5716 matched based on decoded field dstuser='root'.",
    "Consider correlating with rule 5720 to detect brute-force."
  ]
}

• rule — a regra de maior severidade que casou (pode ser null).
• matched_rules — todas as regras que casaram, em ordem de avaliação.
• trace — cada passo executado; o phase diz em que camada. Útil para entender por que uma regra não casou (ex.: decoder não casou antes).
• insights — dicas em linguagem natural.

Efeitos colaterais

• Emite webhook logtest.completed com {ok, matched_rule_id, matched_rules}.
• Consome 1 unidade de analysis_runs da organização.

POST /analysis/full

Idêntico a logtest-native em input e output — é um endpoint distinto que reserva espaço para ampliar com análise estática adicional (complexidade de decoder, duplicatas, etc.). Hoje retorna o mesmo LogtestResponse.

Recomendação: use /analysis/logtest-native. Este endpoint existe para quando recursos adicionais forem habilitados.

POST /rulesets/compile

Alias histórico de /analysis/validate com mesmo request/response. Mantido por compatibilidade.

Erros comuns

Código	code	Causa
400	bad_request	files[].content não é XML válido.
403	forbidden	Escopo insuficiente.
413	payload_too_large	Ruleset > 8 MB — divida os arquivos.
422	validation_failed	Schema do body inválido.
429	rate_limited	> 120 req/min ou quota de plano esgotada.

Links relacionados

• Quickstart
• Editor e validação
• Rulesets e regressão