Skip to content

Add a web form alternative to the decoder YAML editor #482

Description

@Desvelao

Description

Decoders can currently only be created and edited through a raw YAML editor
(DecoderFormPage). This works well for advanced users but is unfriendly for
users who don't want to hand-write YAML or don't know the decoder document
shape by heart.

The plugin already validates decoder YAML against a JSON Schema
(common/schemas/wazuh-decoders.schema.json, generated from the Wazuh engine)
using Ajv in a Web Worker, but today that schema is used purely to produce
validation error messages after the fact — it never drives any part of the UI.

We want to add a second, form-based editor mode as an alternative to the YAML
editor, using the existing JSON Schema as the source of truth for the fields
and their validation, similar to the "Visual Editor / YAML Editor" toggle the
Rules page already offers for Sigma-style detection rules.

Given the decoder schema is a large, engine-generated artifact (~69k lines)
with a deep nested ECS field catalog and heavy $ref/oneOf/anyOf usage,
fully auto-generating a form from the whole schema (e.g. via a library such as
@rjsf or jsonforms, neither currently a dependency) is possible but would
likely require significant custom widget/config work to stay usable. The
proposed approach instead is a curated form for the common/core decoder
fields plus a YAML fallback for anything too complex to model, mirroring the
Rules editor pattern below. A fully dynamic schema-driven form remains a
valid alternative approach and can be reconsidered during implementation if
the curated approach proves too limiting.

Code references

  • public/pages/Decoders/containers/DecoderFormPage.tsxeditorTypes only
    declares 'yaml'; validateForm runs the JSON-schema validation against the
    parsed YAML.
  • public/components/YamlForm/components/YamlForm.tsx — the current YAML
    editor, with no schema wiring.
  • public/utils/jsonSchemaValidation.ts / jsonSchemaValidation.worker.ts
    existing Ajv-based validation against the decoder schema, including schema
    introspection helpers (schemaAtInstancePath, findPropertySchema) that
    could be reused for field-level validation in a form.
  • common/schemas/wazuh-decoders.schema.json — the decoder JSON Schema
    (generated by scripts/generate-engine-schemas.js from the
    wazuh/wazuh engine repo).
  • Precedent to mirror: public/pages/Rules/components/RuleEditor/RuleEditorForm.tsx,
    mappers.ts (mapFormToRule/mapRuleToForm), and
    RuleEditorFormModel.ts — the existing dual visual/YAML editor for a
    comparable YAML-backed resource, including a "switch to YAML" escape hatch
    in its nested DetectionVisualEditor.

Tasks

  • Define a flat decoder form model (fields for name, metadata
    (title/description/author/references), enabled, parents) and
    its default value, analogous to RuleEditorFormModel.ts.
  • Implement mapFormToDecoder/mapDecoderToForm mappers between the form
    model and the DecoderDocument shape, analogous to
    public/pages/Rules/components/RuleEditor/mappers.ts.
  • Build the visual form UI for the core fields above.
  • Build a structured sub-editor (or a scoped, curated subset of the schema)
    for the check/normalize blocks, with a "switch to YAML" escape hatch
    for cases the form can't express — mirroring DetectionVisualEditor's
    goToYamlEditor pattern.
  • Add a 'form' (or 'visual') option to editorTypes in
    DecoderFormPage.tsx alongside the existing 'yaml' option, and wire
    the toggle to keep both modes in sync.
  • Reuse the existing JSON Schema (decoderSchema) and
    validateWithJsonSchemaAsync for field-level validation in form mode
    where practical.
  • Wire form-mode submission through the existing
    DataStore.decoders.createDecoder/updateDecoder (already
    document-shape agnostic — no backend changes expected).
  • Add unit tests colocated with the new form model, mappers, and
    components.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions