# NexaFabric eBPF helper contract

Agent 0.3.0 can call an optional helper binary at `/opt/nexafabric-agent/nexafabric-ebpf`.
The repository includes a dependency-free Go helper source at `nexafabric-ebpf.go`.

The first implementation uses Linux raw packet sockets on the selected VM/LXC interfaces and prints the same JSON contract that a tc/eBPF implementation should print. This keeps the helper installable on Proxmox immediately while preserving the agent integration point for a later kernel eBPF loader.

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": "af_packet_raw_socket",
    "interfaces_attached": ["tap100i0"]
  }
}
```

The Python agent merges these flows with firewall-log, packet, and conntrack fallback collectors.