From d81017008a653f16d33ebdee0aa6adbb1b9aac86 Mon Sep 17 00:00:00 2001
From: ErenAri <erenari27@gmail.com>
Date: Wed, 12 Aug 2026 13:53:41 +0300
Subject: [PATCH] docs(integrations): add Fluent Bit integration (in_aegisbpf)

Docs + example config for streaming AegisBPF OCSF events into any Fluent Bit
output via the native `aegisbpf` input plugin. Links the upstream plugin PR
(fluent/fluent-bit#12272) and docs PR (fluent/fluent-bit-docs#2670), with a
generic-input fallback until the plugin ships in a release.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/CHANGELOG.md                       |  8 ++++
 integrations/fluent-bit/README.md       | 55 +++++++++++++++++++++++++
 integrations/fluent-bit/fluent-bit.conf | 25 +++++++++++
 3 files changed, 88 insertions(+)
 create mode 100644 integrations/fluent-bit/README.md
 create mode 100644 integrations/fluent-bit/fluent-bit.conf

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index a885bbc..605800b 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added — Fluent Bit integration
+- **`integrations/fluent-bit/`** — docs + example config for streaming AegisBPF's
+  OCSF events into any Fluent Bit output via the native `aegisbpf` input plugin
+  (connects to the control socket, `GET /events`, forwards each event as a
+  record). Plugin proposed upstream at fluent/fluent-bit#12272 (docs at
+  fluent/fluent-bit-docs#2670); a generic-input fallback is documented until it
+  ships in a release.
+
 ### Added — Nix packaging + hermetic BPF builds
 - **`packaging/nix/`** — a hermetic Nix build of the agent (`package.nix`,
   `test-default.nix`, `README.md`), the basis for the `NixOS/nixpkgs` submission.
diff --git a/integrations/fluent-bit/README.md b/integrations/fluent-bit/README.md
new file mode 100644
index 0000000..3a6a4c0
--- /dev/null
+++ b/integrations/fluent-bit/README.md
@@ -0,0 +1,55 @@
+# Fluent Bit → AegisBPF events
+
+Stream AegisBPF's runtime-security (OCSF) events into any [Fluent Bit](https://fluentbit.io)
+output — Splunk, Elasticsearch/OpenSearch, Loki, Kafka, S3, an OTLP endpoint, and
+so on — via the native **`aegisbpf`** input plugin.
+
+```
+AegisBPF agent ──(control socket, GET /events)──► Fluent Bit in_aegisbpf ──► any output
+   OCSF JSON, newline-delimited                     records                  Splunk / ES / Loki / ...
+```
+
+## Status
+
+The `in_aegisbpf` input plugin is proposed upstream:
+
+- Plugin: **[fluent/fluent-bit#12272](https://github.com/fluent/fluent-bit/pull/12272)**
+- Docs: **[fluent/fluent-bit-docs#2670](https://github.com/fluent/fluent-bit-docs/pull/2670)**
+
+Until it ships in a Fluent Bit release you can build Fluent Bit from that branch,
+or use the generic-input fallback below.
+
+## Prerequisites
+
+Run the agent with its control socket enabled:
+
+```bash
+AEGIS_API_SOCKET=/var/run/aegisbpf/aegisbpf.sock aegisbpf run --enforce
+```
+
+The socket is `0600` root-owned, so Fluent Bit must run as the same user (root).
+AegisBPF emits OCSF-formatted events by default (`--event-format ocsf`).
+
+## Native plugin
+
+```ini
+[INPUT]
+    name         aegisbpf
+    socket_path  /var/run/aegisbpf/aegisbpf.sock
+
+[OUTPUT]
+    name         stdout
+    match        *
+```
+
+| Key | Description | Default |
+|---|---|---|
+| `socket_path` | AegisBPF control socket path | `/var/run/aegisbpf/aegisbpf.sock` |
+| `reconnect_sec` | Reconnect interval (seconds) | `2` |
+
+The plugin connects out to the socket, sends `GET /events`, skips the streaming
+ack, and forwards each subsequent JSON line as one record (event-driven — it
+drains promptly because the agent drops slow readers).
+
+See [`fluent-bit.conf`](fluent-bit.conf) for a fuller example (ships events to an
+HTTP/OTLP sink).
diff --git a/integrations/fluent-bit/fluent-bit.conf b/integrations/fluent-bit/fluent-bit.conf
new file mode 100644
index 0000000..9ff3a8b
--- /dev/null
+++ b/integrations/fluent-bit/fluent-bit.conf
@@ -0,0 +1,25 @@
+# Example: ship AegisBPF runtime-security events to an HTTP/OTLP sink via Fluent Bit.
+# Requires the in_aegisbpf plugin (fluent/fluent-bit#12272). Run Fluent Bit as
+# root so it can read the 0600 control socket.
+
+[SERVICE]
+    flush        1
+    log_level    info
+
+[INPUT]
+    name          aegisbpf
+    socket_path   /var/run/aegisbpf/aegisbpf.sock
+    reconnect_sec 2
+
+# Tag every event so downstream routing/filtering is easy.
+[FILTER]
+    name    modify
+    match   *
+    add     source aegisbpf
+
+# Swap this OUTPUT for your SIEM/data-lake of choice (es, splunk, loki, kafka,
+# s3, opentelemetry, ...). stdout is shown for a quick local smoke test.
+[OUTPUT]
+    name    stdout
+    match   *
+    format  json_lines