Skip to content

docs: document and verify every sink use case (Loki/Grafana, Wazuh, HTTP, syslog) #32

Description

@onelrian

Overview

Document and verify every sink use case AuditBridge claims to support: Grafana Loki, Wazuh syslog, generic HTTP, and generic syslog. Each scenario needs a setup guide with its config and real, reproducible evidence that it works, not a single happy-path example.

Intent

The real intent of this issue is:

The repo claims four sink types, but only Wazuh got a partial write-up (UDP only, with an outline for the decoder and rules), and the others are one-liners or a variable table with no worked, verified example. A reader cannot tell whether HTTP or syslog delivery actually works, or what a configured Loki/Grafana flow looks like end to end.

Source of Truth

  • PR #31 adds a UDP example to docs/SINKS.md, a Wazuh-side setup outline (no actual decoder/ruleset config), and a committed screenshot docs/images/wazuh-netbird-alerts.png. It does not touch the other sinks.
  • docs/SINKS.md: the Loki section is two lines with no example; generic sinks are a variable table plus one HTTP webhook example with no evidence; syslog has no worked example; the Wazuh section covers UDP only.
  • README.md's Verified section commits screenshots for Loki delivery, a Loki query, and health/metrics, but no sink section pairs a complete guide with per-scenario evidence.
  • examples/local-demo/ exercises loki and wazuh together via docker compose up; the HTTP and syslog scenarios have nothing equivalent to build evidence from.
  • Precedent for the quality bar: #29 closed the gap where docs told a reader what to do without saying exactly how, and demanded real commands and real evidence.

Tasks

  • Loki/Grafana sink: config section (LOKI_URL and SINK_LOKI_URL, labels), a worked example, and evidence of delivery plus a Grafana query result
  • Wazuh syslog sink: cover TCP and UDP, full copyable decoder and ruleset config, verification steps, and evidence of an alert firing
  • Generic HTTP sink: worked example (webhook receiver) with config and evidence of delivery
  • Generic syslog sink: worked example for both transports with config and evidence of delivery
  • Reuse examples/local-demo/ as the reproducible base where it already exists; extend it or document a per-scenario recipe where it does not
  • Prefer text evidence (log lines, decoded events, query and response output) over committed screenshots; keep screenshots only for state that is genuinely visual and attach them via GitHub's native upload rather than committing image files
  • Rework the README Verified section to match: one verified scenario per sink type with its evidence, instead of the screenshot the reviewer does not accept

Acceptance Criteria

  • Every sink type the project supports (Loki/Grafana, Wazuh, HTTP, syslog) has a setup guide with complete config and a verification path
  • Evidence exists for every scenario, reproducible via the documented commands or examples/local-demo/, with real output shown
  • No documented sink is a one-liner without an example; no example claims success without evidence
  • The README no longer shows the screenshot the reviewer flagged
  • A first-time reader can set up and verify each sink from the docs alone

Definition of Done

  • Acceptance criteria satisfied
  • PR #31 reworked or extended to cover the full sink matrix and re-reviewed
  • No unresolved reviewer comment remains

Out of Scope

  • Changes to sink behavior or Rust code; this issue covers documentation and the README only

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions