Pular para o conteúdo principal

Quickstart com curl

Um roteiro mínimo para quem quer começar a usar a API em poucos minutos.

Pré-requisitos​

  • Acesso a uma instância do RuleForge (URL + organização).
  • Papel que permita criar API keys (org_admin ou equivalente).
  • curl instalado.

Definimos variáveis de ambiente para o exemplo:

export RF_BASE="http://localhost:8000/api/v1"
export RF_KEY="rfk_SUA_CHAVE_AQUI"

1. Criar uma API key​

Pela UI: Configurações → Chaves de API → Nova chave. Escolha pelo menos os escopos analysis:run e projects:read. O valor completo aparece uma vez — copie e salve em $RF_KEY.

Por API (se você já tem autenticação admin):

curl -X POST "$RF_BASE/platform/organizations/$ORG_ID/api-keys" \
  -H "X-API-Key: $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI pipeline",
    "scopes": ["analysis:run", "projects:read"],
    "expires_at": "2027-04-24T00:00:00Z"
  }'

Resposta inclui api_key com o segredo. Use no lugar de $RF_KEY.

2. Confirmar que a chave funciona​

curl -s "$RF_BASE/health" -H "X-API-Key: $RF_KEY"
# => {"status":"ok"}

Se vier 401, a chave está errada ou expirada. Se vier 200, siga.

3. Validar um ruleset​

O endpoint mais comum: POST /analysis/validate. Ele compila um conjunto de regras/decoders (incluindo os baselines do disco, se você quiser) e retorna diagnósticos.

curl -X POST "$RF_BASE/analysis/validate" \
  -H "X-API-Key: $RF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "include_disk_defaults": true,
    "include_disk_custom": false,
    "files": [
      {
        "filename": "local_rules.xml",
        "kind": "rules",
        "scope": "adhoc",
        "content": "<group name=\"local\"><rule id=\"100010\" level=\"3\"><description>Teste manual</description><group>local_test</group></rule></group>"
      }
    ]
  }'

Resposta resumida:

{
  "ok": true,
  "summary": {
    "total_rule_files": 1,
    "total_decoder_files": 0,
    "total_rules": 8621,
    "total_decoders": 623,
    "compiled_hash": "abc123…",
    "loaded_from_disk": true
  },
  "diagnostics": [],
  "baseline_issue_count": 0,
  "performance": {
    "source_build_ms": 45.2,
    "compile_ms": 120.5,
    "total_ms": 165.7,
    "cache_hit": false
  }
}
  • ok: true → ruleset válido.
  • diagnostics[] lista erros e avisos do seu conteúdo (baseline é ocultado por padrão; baseline_issue_count mostra quantos foram filtrados).

Se ok: false, leia diagnostics[].message e diagnostics[].line para encontrar o problema.

4. Testar um evento contra o ruleset​

POST /analysis/logtest-native roda o pipeline completo (predecoder → decoder → rule) sobre um único evento.

curl -X POST "$RF_BASE/analysis/logtest-native" \
  -H "X-API-Key: $RF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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 port 44218 ssh2",
      "log_format": "syslog"
    }
  }'

Resposta (resumida):

{
  "ok": true,
  "predecoded": {
    "timestamp": "Jan 10 12:00:01",
    "hostname": "web01",
    "program_name": "sshd",
    "raw_message": "Failed password for root from 10.0.0.5 port 44218 ssh2",
    "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"],
    "matched": true
  },
  "extracted_fields": { "dstuser": "root", "srcip": "10.0.0.5" },
  "trace": [
    { "phase": "predecode", "name": "predecoder", "matched": true },
    { "phase": "decode", "name": "sshd", "matched": true },
    { "phase": "rule", "name": "5716", "matched": true }
  ]
}

Leia:

  • rule → a regra que casou (pode ser null quando nada casa).
  • matched_rules → lista completa quando múltiplas regras casam.
  • extracted_fields → valores que o decoder extraiu.
  • trace → passos executados, útil para depurar decoder que não casa.
  • insights → dicas em linguagem natural geradas pelo backend.

5. Criar um projeto​

Se você vai automatizar o ciclo de conteúdo, comece criando um projeto:

curl -X POST "$RF_BASE/platform/projects" \
  -H "X-API-Key: $RF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Edge rules",
    "description": "Regras customizadas do time de edge",
    "ruleset_version": "baseline-4.10"
  }'

Guarde o id retornado — você vai usar em todas as chamadas seguintes.

6. Criar um caso de teste​

Casos são eventos + expectativas que rodam em regressão:

curl -X POST "$RF_BASE/platform/projects/$PROJECT_ID/cases" \
  -H "X-API-Key: $RF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "SSH brute force",
    "event": "Jan 10 12:00:01 web01 sshd[1234]: Failed password for root from 10.0.0.5",
    "log_format": "syslog",
    "expected_rule_id": "5716",
    "expected_level": 5
  }'

7. Rodar todos os casos de uma vez​

curl -X POST "$RF_BASE/platform/projects/$PROJECT_ID/cases/run" \
  -H "X-API-Key: $RF_KEY"

Resposta inclui passed, failed, e a lista detalhada de cada caso.

Script de exemplo completo​

#!/usr/bin/env bash
set -euo pipefail

: "${RF_BASE:?}"
: "${RF_KEY:?}"

# 1. validar
curl -fsS -X POST "$RF_BASE/analysis/validate" \
  -H "X-API-Key: $RF_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq '{ok, diagnostic_count: (.diagnostics | length)}'

# 2. logtest
curl -fsS -X POST "$RF_BASE/analysis/logtest-native" \
  -H "X-API-Key: $RF_KEY" \
  -H "Content-Type: application/json" \
  -d @logtest.json | jq '{rule: .rule.id, matched: .rule.matched}'

Próximos passos​

Dicas​

  • Envie x-locale: en-US se quer mensagens em inglês.
  • O header X-Request-Id da resposta ajuda no suporte.
  • include_disk_defaults=true usa o ruleset Wazuh embarcado no servidor — você não precisa enviar os baselines junto.
  • Em pipeline CI, valide antes de rodar logtest: valide falhou → pare ali.