feat: add eBPF flow collector with helper binary contract and agent integration

Add EBPF_HELPER_CONTRACT.md documenting helper binary invocation with --json/--limit/--duration/--interfaces parameters and expected JSON output format with flows/diagnostics, implement collect_ebpf_flows to invoke helper binary with configurable timeout/window/interfaces and normalize flow fields (source_ip/destination_ip/protocol/ports/packets/bytes/state), add executable_exists and flow_int helpers for binary validation
2026-07-10 14:15:15 +02:00
parent af68949e07
commit e6c9a92ff0
4 changed files with 148 additions and 3 deletions
@@ -0,0 +1,37 @@
+# NexaFabric eBPF helper contract
+
+Agent 0.3.0 can call an optional helper binary at `/opt/nexafabric-agent/nexafabric-ebpf`.
+
+The helper is invoked as:
+
+```sh
+nexafabric-ebpf --json --limit 1500 --duration 10 --interfaces tap100i0,fwln100i0
+```
+
+It must print JSON to stdout:
+
+```json
+{
+  "flows": [
+    {
+      "source_ip": "172.16.0.10",
+      "destination_ip": "172.16.0.20",
+      "protocol": "tcp",
+      "source_port": 443,
+      "destination_port": 53020,
+      "packets": 10,
+      "bytes": 14800,
+      "vmid": "100",
+      "interface": "tap100i0",
+      "direction": "ingress",
+      "state": "observed"
+    }
+  ],
+  "diagnostics": {
+    "attach_mode": "tc",
+    "interfaces_attached": ["tap100i0"]
+  }
+}
+```
+
+The Python agent merges these flows with firewall-log, packet, and conntrack fallback collectors.