How Skaldhall works

What is the Skaldhall architecture?

Skaldhall separates collection, durable transport, transformation, storage, detection, and investigation. This keeps the data plane observable and lets operators replace infrastructure such as OpenSearch or external NATS without changing the event contract.

1. Collect: Vector tails matching Kubernetes workloads selected by a LogSource custom resource.
2. Buffer: raw envelopes are published to NATS JetStream for durable, replayable delivery.
3. Normalize: the Bragi operator resolves a manual, registry, or generated VRL pipeline and emits OCSF events.
4. Detect: OpenSearch Security Analytics evaluates Sigma rules written against normalized OCSF fields.
5. Investigate: the Skaldhall console and MCP server expose search, triage, incidents, topology, and response operations under RBAC.

How does Skaldhall onboard a new log source?

Apply a LogSource resource with a workload selector and source identifier. The operator fingerprints repeated line shapes, collects representative samples, and first checks the community registry. If no known parser matches and LLM generation is enabled, the parser generator proposes Vector Remap Language and an OCSF mapping. Validation gates test parse yield and class consistency before a pipeline is promoted.

Manual pipelines have highest precedence, followed by community registry pipelines, then generated pipelines. Teams can disable automatic approval and review generated drafts before they touch the live data plane.

How do OCSF and Sigma work together?

OCSF is the event contract. Every promoted parser clears the original event object and emits a normalized class, timestamp, severity, metadata, and stable event identifier. Sigma rules then target the normalized OCSF paths rather than each vendor's original field names. This lets one rule operate across sources that represent the same security behavior.

Rules must use the actual OCSF field mapping. String paths do not rely on a .keyword suffix, and numeric fields use exact numeric comparisons rather than string wildcards.

What does a Skaldhall deployment require?

How do I install Skaldhall?

Start with the Bragi pipeline chart. Pre-create the OpenAI secret when parser generation is enabled and point the chart at your OpenSearch endpoint. The complete production values and current image tags are maintained in the Bragi repository.

helm install bragi \
  oci://ghcr.io/skaldhall/bragi/charts/bragi \
  --namespace siem --create-namespace \
  --set openai.existingSecret=bragi-openai \
  --set opensearch.url=https://opensearch.example:9200

Read the authoritative Bragi installation guide before deploying to production.

Can Skaldhall run in an air-gapped cluster?

Yes. Mirror the OCI charts and images into an internal registry, disable LLM generation, and enable the operator's air-gapped registry mode. Known parser definitions, OCSF classes, Sigma rules, and IP-enrichment data are embedded into release images. The deployment still requires an accessible OpenSearch cluster and NATS JetStream inside the disconnected environment.

Where is the authoritative technical documentation?

• Bragi pipeline and operator — architecture, CRDs, configuration, installation, and development.
• Skaldhall console — API, RBAC, triage, incidents, and frontend.
• Parser registry — pipeline schema, samples, validation, and contribution workflow.
• Sigma rule bundle — rule requirements and OCSF field conventions.
• MCP server — tools, transports, caller authentication, and live testing.

Last reviewed: September 20, 2026.