Netra

Standalone eBPF network observability and emergency network control for Linux/Kubernetes — with optional Cilium + Hubble enrichment.

📖 Read the full docs — quickstart, architecture, security model, and a product tour.

Netra does not require Cilium. The node agent owns its own programs and maps below /sys/fs/bpf/netra, attaches to Linux cgroup v2 for CNI-independent workload coverage, and can optionally attach TCX/XDP programs to selected interfaces. If Cilium/Hubble exists, Netra can still manage CiliumNetworkPolicy and display Hubble flows, but both integrations are opt-in.

Netra is observe-first. All custom enforcement is protected by a time-limited lease and automatically returns to observe when the lease expires, the agent cannot refresh controller state, the controller restarts, or HA leadership changes.

• Dashboard gallery
• Standalone eBPF capabilities
• Firewall dashboard page
• TCP Path Diagnostics
• Drop Diagnostics
• Kernel Network Diagnostics
• Packet Capture
• Behavior and Rate Insights
• Hook model
• Important visibility boundaries
• Optional Cilium / Hubble integration
• HTTPS default
• Signing in
• Suite placement (PacketWolf)
• Architecture
• Repository
• Continuous integration
• Prerequisites
• Build
• Standalone Helm install
• netractl CLI
• eBPF CLI examples
• Safety and persistence
• License

Live walkthrough — Overview, the Firewall page's unified rules table and NetPol v2 allow-list, then a real in-browser VNC console connected to a running KubeVirt VM — captured against a live lab deployment, not a mockup:

Live UI captures from a lab deployment (HTTPS :30870). Overview and Pods lockdown appear above and under Cilium integration; the rest of the console:

• IPv4 and IPv6 source:port → destination:port flow counters with packets, bytes and blocked counts.
• Ingress/egress and hook attribution (cgroup, optional tcx, optional xdp, socket hooks).
• TCP, UDP, ICMP and ICMPv6 visibility; TCP flag metadata for parsed TCP packets.
• Sampled flow-header events without application payload collection.
• Cleartext UDP/53 DNS query-name events.
• Socket context for new TCP connect / UDP sendmsg operations: PID, UID, cgroup ID and Linux process comm.
• Kubernetes attribution on cgroup traffic: namespace, pod, immediate owner, container ID and cgroup ID.
• Exact workload network topology derived from cgroup-attributed tuple counters.
• TCP connection health from cgroup sockops: active/passive establishes, closes, SRTT/min RTT, retransmissions, RTOs, congestion window, segments and byte counters.
• TCP path diagnostics from sockops: active connect-establishment latency, packets_out/snd_cwnd pressure, lost_out, retrans_out, cumulative retransmits, delivered-rate samples, MSS and TCP state.
• Exact TCP SYN/SYN-ACK/FIN/RST counters by cgroup.
• Cleartext UDP/53 DNS request/response latency, response-code and failure counters.
• Best-effort TLS ClientHello SNI metadata from single egress skbs, attributed to cgroup/workload.
• Best-effort cleartext HTTP/1 method + Host metadata from single egress skbs; no request body collection.
• Exact per-workload TCP-connect / UDP-sendmsg destination-attempt counters for fan-out and connection-health analysis.
• Deterministic network-health signals for high RTT, retransmit/RTO pressure, reset ratio, DNS failure ratio and DNS latency.
• Top destinations, top DNS names, top processes, block reasons and hook/protocol/direction summaries.
• Stale-agent detection and per-node hook coverage in the dashboard.
• Kernel skb drop-reason counters through an optional raw kfree_skb tracepoint, plus Linux softnet and interface drop/error counters.
• Prometheus control-plane/aggregate metrics at /metrics.
• Optional interval-driven anomaly alerting via multi-channel notify (webhook, email, Slack, Teams, Twilio SMS/WhatsApp, HTTP bridge), with severity-escalation-aware cooldown deduplication and concurrent per-channel delivery. Off by default; HA-aware (leader-only). Opt-in auto-capture on critical softnet/congestion/drop-spike signals persists PCAPs for download. See docs/alerting.md and docs/capture.md.
• Pull-based SIEM export of audit events, health anomalies, and incident clusters as JSON, JSONL, ArcSight CEF, RFC5424 syslog, or OTLP/HTTP JSON Logs (GET /api/v1/export/audit, GET /api/v1/export/events). Observe-only, stdlib-only, no payloads. See docs/siem-export.md.
• Point-in-time operator briefing (GET /api/v1/report, netractl report) combining health, drift, exposure, incidents, and recent audit into markdown or JSON for a ticket/handoff.
• Importable Grafana dashboard over the existing /metrics gauges (deploy/grafana/netra-dashboard.json).
• Review-only operator playbooks (GET /api/v1/playbooks), threat-intel preview plus live feed/hits/leased-apply (POST /api/v1/intel/preview, PUT/GET /api/v1/intel/feed, GET /api/v1/intel/hits, POST /api/v1/intel/apply — see docs/threat-intel.md), GenAI/MCP destination observe (GET /api/v1/ebpf/ai-destinations, docs/ai-destinations.md), optional volumetric auto-mitigation (NETRA_AUTOMITIGATE_ENABLED, docs/auto-mitigate.md), destination-flow SIEM export (GET /api/v1/export/flows), an actor/action/hour audit rollup (GET /api/v1/audit/summary), a per-node hook/program coverage matrix (GET /api/v1/ebpf/coverage, netractl ebpf coverage) — attached vs detached programs, missing maps, stale agents — and a read-only datapath map inventory (GET /api/v1/ebpf/maps, netractl ebpf maps, docs/ebpf-maps.md) — plus optional best-effort push sinks — syslog (NETRA_SYSLOG_ADDR) and Snowflake (NETRA_SNOWFLAKE_ACCOUNT, audit events only) — both off by default and leader-only in HA, alongside the pull-based SIEM export above. Dashboard Report page. See docs/siem-export.md. Perimeter NGFW fit gaps: docs/competitive-quantum.md.
• Optional /proc-derived process metadata (capabilities, seccomp, cgroup/pod attribution, kernel-thread/host/container/VM classification) for PIDs already attributed by the eBPF datapath. Off by default (agent.procMetaEnabled); resolved agent-side, never on the controller; never collects argv/cmdline content. See docs/process-metadata.md.
• netra-mcp, a Model Context Protocol server exposing the controller API as 180 stdio tools for AI agents (e.g. Hermes Agent) and other MCP clients. 120 read/generator tools (status, agents, pods/vms, flows, drops, eBPF diagnostics including map inventory, insights including shadow-SaaS/experience/destination-risk, AI brief/ask/agent/draft/digest/suggestions/explain, SIEM export, operator report, threat-intel, compliance, fleet clusters, policy list/history/build/lockdown-preview) are always available; 60 mutating tools (policy plan/apply/rollback/delete, eBPF rule add/delete, mode toggle, intel apply, AI destination deny, baseline capture/clear) require explicit opt-in (NETRA_MCP_ALLOW_MUTATIONS, off by default) and reuse Netra's existing bearer-token auth, single-use preflight tokens, self-reverting enforce-mode leases, and audit log unchanged — agent-driven mutations are tagged under a distinct actor label so they're distinguishable from human netractl use. Also advertises six MCP prompt templates and six read-only resources (prompts/list/get, resources/list/read) for canned triage/drops/rule-draft/on-call-digest/policy-review/incident-timeline workflows. Implemented stdlib-only (internal/mcpserver), no MCP SDK dependency. See docs/mcp-integration.md. Map inventory: docs/ebpf-maps.md.
• Built-in AI briefs: GET /api/v1/ai/brief, POST /api/v1/ai/ask (with optional short-lived, bounded multi-turn conversationId memory on web/ChatOps, cleared via POST /api/v1/ai/forget), POST /api/v1/ai/agent (in-process NL graph: classify → optional draft preview → synthesize; optional Python LangGraph companion in python/netra_langgraph/, see docs/langgraph.md), an on-call GET /api/v1/ai/digest (severity, incident fingerprint, copy-paste card, and — when the fingerprint changed — a deterministic whyChanged breakdown of exactly what moved plus an optional one-sentence LLM whyChangedProse), live GET /api/v1/ai/suggestions, a natural-language POST /api/v1/ai/draft rule previewer (never applies), and POST /api/v1/ai/explain for narrating one page finding — all turning live agent/health/insights aggregates into operator-facing text, heuristic by default (no vendor SDK, no extra process) with an optional OpenAI-compatible rewrite when NETRA_AI_API_KEY is set on the controller. Read-only — never flips enforce mode or applies policy; the snapshot it can see contains only aggregates and short findings, never payloads, argv, or secrets. The Overview dashboard page hosts a read-only Ask Netra card (now a real multi-turn thread) wired to all of this, the nav bar carries a live severity/fingerprint digest chip, and the Health/Drops/Path/Insights/Explain pages each get a per-finding Explain button (with an optional "draft a rule from this" preview when the finding names an IP/CIDR/DNS name) that narrates that one finding via /api/v1/ai/explain. See docs/ai.md.
• Optional ChatOps integration for Slack (slash commands + interactive confirmation buttons) and Microsoft Teams (bot messages): /netra status|health|audit|ask|forget|mode. Read commands reply immediately; the one mutating command (mode) always requires a second confirmation step, mirroring the web UI's own confirm dialogs. /netra ask shares the same AI layer as the web Ask Netra card, including per-channel-per-user conversation memory. Off by default; each provider needs its own signing secret/App ID to register its route at all. See docs/chatops.md and docs/chatops-teams.md.
• Cgroup-side TLS SNI / cleartext HTTP / DNS query-name observability runs in its own dedicated eBPF program (NETRA_L7=auto|off|required, attach-with-fallback), isolated from the conntrack/NetworkPolicy-deny program's verifier budget so the two can evolve independently. See docs/l7-metadata.md.
• IPv6 extension-header and fragmentation diagnostics (docs/ipv6-diagnostics.md), per-interface flow attribution for TC/TCX-attached NICs (docs/interface-flow-attribution.md), and XDP Shield per-class/per-source breakdowns (docs/tcx-and-shield.md) — all additive counters over data the eBPF datapath already computed internally.
• Kernel drop attribution: which connection's packets the kernel dropped, why (reason names come from the running kernel, whose numbering changes between versions) and which kernel function dropped them (docs/drop-info.md, needs BTF); TCP retransmit / reset / state-change events per flow (docs/tcp-events.md); TCP accept-queue depth per listener (docs/listen-queues.md); and a read-only record of host link, address, route and neighbor changes over netlink, with overflow counted rather than hidden (docs/netlink-recorder.md). Each is its own optional sensor: a node that cannot run one reports why instead of failing.
• Opt-in sampled application-protocol observation (Redis commands, SQL verbs, Kafka APIs, HTTP/2 and gRPC methods, HTTP status; counts only, never payload, docs/l7-sampling.md) and, separately and more sensitive, opt-in TLS plaintext sampling for HTTPS through OpenSSL uprobes limited by process name (docs/tls-plaintext.md). Both are off by default.
• Export and access: OTLP push (docs/otlp-push.md), Loki push (docs/loki-push.md), per-workload metrics with a hard cardinality cap plus a ServiceMonitor, PrometheusRule and SLOs (docs/workload-metrics-slo.md), OIDC login with viewer/operator/admin roles and an optional token-gated /metrics (docs/auth-oidc-rbac.md), and optional mutual TLS between agents and the controller (docs/agent-mtls.md, off by default).

• Exact IPv4 and IPv6 deny for egress, ingress, or both. Optional SYN-drop mode, per exact-IP entry or CIDR: block only new TCP connection attempts, allow other traffic for that address/range through. See docs/syn-drop.md.
• Exact IPv4/IPv6 allow-exception, evaluated before deny/CIDR/port/rate — does not itself enable enforce mode.
• IPv4/IPv6 CIDR deny for ingress, egress or both using BPF LPM tries.
• IPv4/IPv6 CIDR allow-exception for ingress, egress or both — same precedence as the exact-IP allow-exception.
• TCP/UDP/ANY destination-port deny for ingress, egress or both.
• TCP/UDP/ANY destination-port allow-exception for ingress, egress or both — same precedence as the exact-IP allow-exception.
• Linux UID deny for new socket operations.
• Linux UID allow-exception for new socket operations — skips UID/comm deny at the socket hook.
• Linux process-comm deny for new socket operations.
• Linux process-comm allow-exception for new socket operations — skips UID/comm deny at the socket hook.
• Capability-gated socket deny (CAP_NET_RAW/CAP_NET_ADMIN) for new connect/sendmsg operations — agent-sourced from a periodic /proc scan, TOCTOU-caveated, not a live kernel credential read.
• Exact cleartext DNS-name deny for UDP/53 queries.
• Exact TLS SNI deny when an ordinary ClientHello SNI is successfully parsed in the current egress skb.
• Exact IPv4/IPv6 destination PPS and/or independent BPS ceiling using a simple fixed one-second window.
• Per-workload new-TCP-connection-rate ceiling (namespace/pod/owner/labels selector, checked on connect() only; UDP excluded).
• Optional XDP early-ingress CIDR/port drop on explicitly selected interfaces.
• Workload-scoped enforcement by namespace, pod, immediate owner, exact labels, or cgroup ID.
• Review-only deny blast-radius preview (POST /api/v1/ebpf/deny/preview, netractl ebpf deny-preview) matching a proposed IP/CIDR/port/DNS/SNI/process deny against live non-stale agent counters. Applies nothing. See docs/deny-preview.md.
• Optional, off-by-default metadata-only DNS anomaly detection (tunneling, DGA, beaconing, NXDOMAIN/SERVFAIL storms — NETRA_DNSDETECT_ENABLED, GET /api/v1/ebpf/dns-findings, netractl ebpf dns-findings) and port-scan/fan-out/lateral-movement/SYN-flood detection (NETRA_SCANDETECT_ENABLED, GET /api/v1/ebpf/scan-findings, netractl ebpf scan-findings). Both are continuously-running, observe-only detectors — never enforcement. See docs/dns-detect.md and docs/scan-detect.md.
• Scope preview plus per-node selected-cgroup coverage before enforcement.
• Observe/enforce lease, controller failsafe and local node failsafe.

These controls are intentionally an emergency/containment layer, not a replacement for a full CNI policy engine, QoS system, L7 proxy or IDS/IPS.

Netra v0.13 added a dedicated Path Diagnostics surface independent of Cilium. It measures active TCP connect establishment latency and exports current Linux TCP transport pressure (snd_cwnd, packets_out, retrans_out, lost_out, total_retrans, delivered-rate samples and state) per cgroup/workload and remote tuple. The feature is observe-only and uses new maps without resizing earlier pinned-map ABIs. See docs/path-diagnostics.md.

A standalone TCX observer adds edge-observed handshake/RTT histograms and retransmit/RST/FIN counters alongside the socket-observed data above — pre-NAT-visible, seeing forwarded/NAT'd flows the local socket layer never attaches to. See docs/edge-tcp-intel.md.

Health and Explain now explain native DNS response events, including NXDOMAIN, SERVFAIL, REFUSED, and malformed-request errors, with resolver details and next checks. Use netractl explain --pod NS/POD --dns NAME. See DNS response diagnostics.

The Health and Explain pages now surface IPv4/IPv6 MTU, unreachable-destination, time-exceeded, and parameter errors observed by Netra’s TC hooks. Use netractl explain --node NODE for suggested checks. Evidence stays node/interface-scoped; advertised MTUs are peer claims. See ICMP diagnostics. Local Docker-name diagnosis is available with netractl explain --node NODE --docker NAME; see Explain.

Netra v0.19 adds a dedicated Drop Diagnostics surface independent of Cilium. When the host exposes a modern kfree_skb drop-reason tracepoint, the agent attaches an optional raw tracepoint and counts kernel skb drop reasons. It also reports /proc/net/softnet_stat backlog drops/time-squeeze events and per-interface receive/transmit drop/error/missed/no-handler counters. Drop-reason counters are intentionally node-level because the kernel tracepoint does not provide a trustworthy Kubernetes workload identity. See docs/drop-diagnostics.md.

Netra now correlates Linux network-buffer and congestion sysctls with windowed deltas from /proc/net/snmp and /proc/net/netstat plus the existing softnet, interface and qdisc counters. GET /api/v1/ebpf/kernel-network?window=5m and netractl ebpf kernel-network 5m explain where loss is occurring and provide review-only, reversible canary guidance. The Drops dashboard renders the same per-node findings, rates, reset/warm-up state and full collected tunable inventory. Netra never writes a sysctl. See docs/kernel-network-diagnostics.md.

The Congestion Map dashboard page turns this into a pictorial, cluster-wide view: every layer of the Linux network stack as a stage card across ingress/shared/egress columns, colored by the worst finding right now — a full tinted background per severity (ok/warming/warning/critical), not just a border, so a healthy cluster reads as a field of green instead of flat gray. Click a stage to drill into per-node detail, a trend sparkline, and a one-click "Capture on {node}" button that jumps straight into a live packet capture on the offending node.

The Capture dashboard page starts a filtered, time-bounded packet capture on one node or, in one click, a bulk capture across many — streamed live as a macOS-terminal-styled feed, color-coded by protocol and direction. Click any packet for a Wireshark-style layered breakdown (Ethernet II / IP / TCP or UDP or ICMP, each its own color) plus a hex dump, all decoded client-side. Endpoints are labeled automatically when they match a known pod or VM IP, filterable alongside protocol/direction/text. A live packets/sec and bytes/sec sparkline, named filter presets, .json/.csv export next to the existing .pcap download, ended-session history, and a direct line from the Congestion Map (either a manual "Capture on {node}" click or an automatic "Suggested capture" banner when a node has a live critical finding) round it out.

Opt-in auto-capture (NETRA_AUTO_CAPTURE / Helm alerting.autoCapture) starts the same filtered capture automatically on critical softnet drops, Congestion Map findings, and drop-rate spikes, and persists classic PCAPs under NETRA_AUTO_CAPTURE_DIR with Download links in capture history. See docs/capture.md (backends, auto-capture, and the Linux scripts/ci-auto-capture-veth.sh / GitHub auto-capture-veth smoke).

Full workflow — a Congestion Map finding to a live, decoded, color-coded capture on the offending node:

Netra extends the controller-side behavior layer with real time-window deltas on top of exact eBPF metadata:

• Kubernetes-aware workload dependency graph with Pod and Service resolution;
• persistent known-good behavior baseline;
• drift detection for newly observed destinations, DNS names, TLS SNI, HTTP hosts and remote ports;
• review-only CiliumNetworkPolicy drafts derived from observed workload egress;
• low-cardinality Prometheus gauges for baseline entries, drift findings and dependency edges;
• delta-based packets/bytes/connections/DNS/TLS/HTTP rates over 30s–2h windows;
• a persisted traffic-rate baseline with deterministic 2×/5×/10× drift thresholds;
• workload exposure scoring that combines external dependencies, behavior drift and rate drift;
• review-only remediation proposals for investigation or staged containment.

The behavior baseline remains an inventory anchor while the rate baseline is a separate time-window anchor. Rolling samples intentionally warm up again after controller restart/HA failover. Netra never auto-applies learned policy or remediation. See docs/behavior-insights.md and docs/rate-insights.md.

The default agent can therefore run cgroup-only: no cilium_host, no Cilium maps, and no assumption about the Kubernetes CNI.

Scope warning: scopeMode=all attaches enforcement broadly to descendant root-cgroup traffic and can affect Kubernetes workloads plus host/system services. Netra includes scopeMode=selected; use it to enforce only resolved workload cgroups after previewing the matching Pods. Traffic whose workload identity cannot be resolved fails open in selected mode, and optional TCX/XDP remain observe-only there.

By default Netra does not copy packet payloads to userspace; the two opt-in sensors (sampled L7, off by default, and TLS plaintext sampling through OpenSSL uprobes, off by default and limitable to named processes in the kernel) copy the first bytes of selected payloads to the agent, parse them there into allowlisted operation counts, and never export them (docs/l7-sampling.md, docs/tls-plaintext.md). DNS parsing is deliberately limited to ordinary UDP/53 queries. TLS metadata parsing is best-effort and limited to ordinary ClientHello SNI found in a single egress skb; there is no TCP stream reassembly, ECH decryption, QUIC parsing, or certificate inspection. Cleartext HTTP metadata is limited to an HTTP/1 method and Host header visible in one skb; request paths/bodies are not exported. It does not inspect DoH, DoT or TCP DNS. IPv6 extension-header walking is implemented (see docs/ipv6-extension-headers.md) but does not decrypt ESP payloads, does not trust L4 ports/L7 metadata on non-first fragments, and suppresses L4/L7 parsing on chains deeper than six extension headers. Process-name rules use Linux comm (maximum 15 visible bytes) and affect new connect/sendmsg operations; they do not terminate already-established sockets. The PPS guard is an emergency fixed-window limiter, not traffic shaping.

When enabled, the existing integrations remain available:

• guided and advanced CiliumNetworkPolicy authoring;
• live-policy comparison and risk-scored preflight;
• Kubernetes server-side dry-run;
• one-shot durable preflight receipts;
• CNP revision history and guarded rollback;
• native Hubble Relay gRPC flow streaming and drop explanation, with each flow row colored by verdict (forwarded/dropped/audit) and direction.

Cilium RBAC is not rendered by Helm unless cilium.enabled=true. Hubble is disabled by default with hubble.enabled=false.

When Cilium is enabled, the dashboard also exposes Pods and VMs (KubeVirt) pages: inventory, per-entity Hubble live flows, create/delete CNP rules pinned to the workload selector, and one-click lock down / unlock quarantine (netra-lockdown-*: deny-all ingress, DNS-only egress) through the same plan → receipt → apply path.

netrad listens on :30870 by default. Helm and plain manifests enable in-pod HTTPS by default and generate a self-signed P-256 certificate in an init container. The agent opts into certificate verification bypass for that generated internal certificate (tls.agentInsecureSkipVerify=true / NETRA_TLS_INSECURE=true); use a trusted certificate/CA path in hardened environments instead. Set tls.enabled=false (Helm) or remove NETRA_TLS_CERT/NETRA_TLS_KEY (plain) only when TLS is terminated by a trusted proxy/ingress.

CLI: netractl skips verify on loopback when NETRA_TLS_INSECURE is unset, and loads ~/.netra/env + ~/.netra/api-key automatically (deploy-remote.sh writes those). For NodePort over a public IP, set NETRA_TLS_INSECURE=true or use ~/.netra/env. See docs/netractl.md.

The dashboard sits behind a login screen (admin / Admin@321 by default) — see docs/dashboard-login.md for the full guide, including what the login maps to server-side and how to rotate the credential. The nav bar and login screen carry the Zyvor mark; Netra is Zyvor's eBPF observability product.

Netra and PacketWolf cover the same eBPF territory from opposite directions: PacketWolf is the Cilium-dependent suite flagship; Netra is the standalone standalone layer that works on cgroup v2 alone (Cilium/Hubble optional). They are counterparts, not a wired pipeline — no shared API, CRD, or install pair.

On a Cilium cluster both may run with clear ownership (PacketWolf for day-2 intelligence; Netra for short-lease deny and CNI-independent diagnostics). Full rules: docs/packetwolf.md · site: Suite placement.

                        Browser / netractl
                               |
                               v
                    +---------------------+
                    |      netrad        |
                    | API + UI + state    |
                    +----------+----------+
                               |
                 desired config| node reports
                               v
       +------------------------------------------------+
       |          netra-agent on every Linux node      |
       |                                                |
       | cgroup skb + socket hooks       optional TCX   |
       |          |                         optional XDP |
       |          +------ Netra maps/ring buffer ------+
       |                 /sys/fs/bpf/netra             |
       +------------------------------------------------+

         optional                         optional
  +-------------------+             +-------------------+
  | Kubernetes Cilium |             |   Hubble Relay    |
  | NetworkPolicy API |             | Observer.GetFlows |
  +-------------------+             +-------------------+

cmd/netrad/             controller/API/UI server
cmd/netractl/           operator CLI
cmd/netra-agent/        standalone privileged node agent
cmd/netra-doctor/       read-only host readiness preflight
cmd/netra-mcp/          MCP server: controller API as stdio tools + prompts for AI agents
cmd/netra-ci-*/         CI helpers: capture client (the browser's side of a capture), synthetic feeder, fake OIDC provider
internal/ai/             heuristic briefs + optional OpenAI-compatible rewrite
internal/agent/          BPF loading, hook attachment and reporting
internal/doctor/         host readiness checks used by netra-doctor
internal/observability/  standalone eBPF summaries and workload topology
internal/health/          TCP/DNS/connect health scoring and anomaly signals
internal/l7/              TLS SNI / HTTP Host / socket-attempt aggregation
internal/insights/         dependency graph, behavior/rate baselines, drift, exposure and drafts
internal/cgroupmeta/     cgroup-v2 Kubernetes path/inode discovery
internal/workload/       workload selector matching and cgroup joins
internal/api/            REST/SSE API
internal/store/          durable state, audit and preflight receipts
internal/siem/           CEF/syslog/JSONL/OTLP formatters + optional syslog push
internal/report/         point-in-time operator briefing builder
internal/playbook/       review-only operator steps from a report snapshot
internal/intel/          threat-intel preview + live feed (apply is lease-gated)
internal/ainet/          GenAI/MCP SaaS destination catalog (metadata observe)
internal/automitigate/   optional leased volumetric auto-mitigation
internal/auditstats/     actor/action/hour rollup of the audit log
internal/coverage/       per-node hook/program coverage matrix
internal/ebpfmaps/       read-only desired map inventory (CLI/API)
internal/denycensus/     deny/allow entry counts (no entry echo)
internal/ha/             active/passive controller leader election
internal/kube/           direct Kubernetes REST client
internal/hubble/         optional native Hubble gRPC client
internal/policy/         optional CiliumNetworkPolicy planning
internal/tcpevents/      TCP retransmit / reset / state-change tracepoints (bpf/netra_tcpevents.c), layouts read from the kernel
internal/dropinfo/       per-connection kernel drop attribution: tuple, reason, dropping function (bpf/netra_dropinfo.c, needs BTF)
internal/tpformat/       tracepoint `format` parser (record layouts and reason tables are read from the running kernel)
internal/ksym/           kernel address to symbol through /proc/kallsyms
internal/kmsg/           bounded, scrubbed view of kernel log lines
internal/listenq/        TCP accept-queue depth per listener through inet_diag
internal/mapscan/        cheap full scans of BPF hash maps (batched reads, bounded top-N)
internal/l7sample/       sampled protocol observation: Redis, Postgres, MySQL, Kafka, HTTP/1, HTTP/2, gRPC (bpf/netra_l7sample.c)
internal/sslprobe/       opt-in TLS plaintext sampling through OpenSSL uprobes (bpf/netra_ssl.c)
internal/mtls/           optional mutual TLS between agent and controller
internal/oidcauth/       OIDC/JWT verification and role mapping (viewer/operator/admin)
internal/otlppush/       OTLP/HTTP push of metrics, logs and spans
internal/lokipush/       Loki push of audit and block events
internal/pushfeed/       delivery logic shared by the push sinks (watermarks, bounded batches)
internal/slo/            network SLOs and burn rates
internal/workloadobs/    per-workload counters with a hard cardinality cap
bpf/netra_tc.c          standalone eBPF programs/maps (the core datapath)
bpf/netra_*.c           optional sensors, each its own object: edge_intel, capture, tlsfp, tcpevents, dropinfo, l7sample, ssl
scripts/ci-*.sh         one script per CI job (real controller, agent, kernel, cluster or browser); docs/ci.md maps them
scripts/lib/veth-lab.sh shared controller + agent + veth setup for the real-agent CI scripts
web/                     React/Vite dashboard
helm/netra/             Helm chart
deploy/                  plain manifests
docs/packetwolf.md       suite placement vs PacketWolf (counterparts, not a pipeline)
docs/standalone-ebpf.md  eBPF hook/map/limitation reference
docs/ebpf-maps.md         read-only map inventory (`netractl ebpf maps`)
docs/workload-scoping.md workload attribution/scoping runbook
docs/netractl.md          operator CLI: install, TLS, status, features, maps
docs/l7-metadata.md      metadata-only L7 behavior and limitations
docs/behavior-insights.md dependency/inventory-baseline/drift/recommendation runbook
docs/rate-insights.md     time-window rate baseline, exposure and remediation runbook
docs/high-availability.md HA runbook
docs/host-readiness.md    netra-doctor host readiness runbook
docs/drop-detective.md    conntrack + policy Drop Detective
docs/kernel-network-diagnostics.md sysctl/counter correlation and safe tuning workflow
docs/tcx-and-shield.md    TCX modes + XDP Shield
docs/native-netpol.md     optional native NetPol maps: v1 deny-list + v2 allow-list/default-deny
docs/fluxvm-borrow-backlog.md deferred FluxVM eBPF patterns
docs/alerting.md          multi-channel notify + alert poller; opt-in auto-capture env
docs/siem-export.md       pull-based SIEM encodings + operator report
deploy/grafana/           Prometheus dashboard JSON for the existing /metrics gauges
docs/process-metadata.md  optional /proc-derived process metadata (agent-side, hostPID opt-in)
docs/mcp-integration.md   MCP server runbook: tool reference, security, plan/apply flow, troubleshooting
docs/ai.md                heuristic briefs + optional LLM rewrite: HTTP/CLI/MCP surface, safety boundaries
docs/ipv6-diagnostics.md  IPv6 extension-header/fragmentation counters and anomalies
docs/interface-flow-attribution.md per-interface flow counters (TC/TCX hooks only)
docs/chatops.md           Slack ChatOps: slash commands, confirmation flow, Ask Netra integration
docs/chatops-teams.md     Microsoft Teams ChatOps: bot setup, confirm-by-reply flow, validation status
docs/syn-drop.md          SYN-drop mode: exact-IP and CIDR variants, kernel-verified CI coverage
docs/edge-tcp-intel.md    standalone TCX edge observer: handshake/RTT histograms, retransmit/RST/FIN counters
docs/capture.md           packet capture: eBPF vs AF_PACKET, auto-capture PCAPs, veth+iperf3 CI smoke
docs/tutorials/drop-incident-context.md  walkthrough: enable drop context, read it, reproduce with iperf3
docs/tls-fingerprints.md  JA3/JA4 datapath + encrypted DNS; openssl+iperf3 CI smoke
docs/p0-p5-surfaces.md    P0–P5 observe surface catalog (what / how / UX / APIs)
docs/p5-surfaces.md       P5 residual boards (JA3 risk, ECH, exfil, lateral, …)
docs/sales/               buyer guide + PDFs/PPTX + the brochure source (`brochure/`) — also on GitHub Pages /resources
docs/sales/buyers-guide.md evaluation narrative for buyers (P0–P5 + checklist)
docs/flow-log.md              queryable 7-day flow history, RED, inferred traces, stacks, kernel notes, pod warnings
docs/agent-map-reads.md           How the agent reads its BPF maps
docs/agent-mtls.md                Agent ↔ controller mutual TLS
docs/app-categories.md            App / category catalog
docs/auth-oidc-rbac.md            OIDC login, roles, and a locked-down `/metrics`
docs/blast-radius.md              Multi-hop blast radius (`internal/insights.BlastRadius`)
docs/capability-gated-deny.md     Capability-gated socket deny
docs/competitive-sse.md           Cloud SSE / Zero Trust → Netra feature gaps
docs/compliance.md                Compliance packs
docs/destination-risk.md          Destination risk scoring
docs/drop-explain.md              Unified Drop Explain
docs/drop-info.md                 Kernel drop attribution
docs/experience.md                Workload digital experience
docs/exporter-tetragon-borrow-backlog.md Patterns borrowed from Cloudflare ebpf_exporter and Cilium Tetragon
docs/fleet-clusters.md            Multi-cluster fleet (read-only)
docs/fleet-tenants.md             Fleet tenants (partner / MSSP read views)
docs/gitops.md                    Policy-as-code / GitOps reconciliation (`internal/gitops`)
docs/identity-drafts.md           Identity drafts (ServiceAccount join)
docs/investigation-ux.md          Native investigation UX
docs/l7-sampling.md               Sampled L7 protocol observation
docs/listen-queues.md             TCP listen-queue pressure
docs/netlink-recorder.md          Route / link / address / neighbor change recorder (read-only)
docs/bpf-attachments.md           BPF programs attached per interface + Netra hook drift (read-only)
docs/loki-push.md                 Loki push export
docs/microseg.md                  East-west microsegmentation guidance
docs/network-health.md            Netra Network Health — v0.10
docs/node-resources.md            Node Resources
docs/otlp-push.md                 OTLP push export
docs/policy-packs.md              Sanctioned-app policy packs
docs/prevention-report.md         Prevention coverage report
docs/protocol-downgrade.md        TLS→cleartext protocol-downgrade correlation
docs/quic-observed.md             QUIC-observed traffic counter
docs/shadow-saas.md               Shadow SaaS (CASB-lite)
docs/snowflake-export.md          Snowflake export
docs/sysctl-audit.md              Netra Sysctl Audit
docs/tcp-events.md                TCP event tracepoints
docs/tls-plaintext.md             TLS plaintext sampling (OpenSSL uprobes)
docs/udp-flow-health.md           UDP flow health beyond DNS
docs/workload-metrics-slo.md      Per-workload metrics, SLOs, and Prometheus Operator objects
docs/zero-trust.md                Zero Trust suggestions (review-only)
docs/competitive-observability.md  shipped observe versus Hubble-class and eBPF APM peers
docs/ci.md                     every CI job, the use case it proves, its script and how to run it locally

• Buyers guide (markdown): docs/sales/buyers-guide.md
• Feature catalog: docs/p0-p5-surfaces.md
• Product Perspective (PDF, PPTX) and Brochure (PDF): docs/sales/
• GitHub Pages: https://zyvorai.github.io/netra/resources

Standalone mode requires Linux with cgroup v2, bpffs at /sys/fs/bpf, and kernel BPF support. The ring-buffer-based implementation has a practical Linux 5.8+ baseline; use a modern LTS kernel in production. TCX is optional and has a newer kernel requirement (Linux 6.6+ is the practical baseline used by this project). XDP support depends on the selected interface/driver and is off unless explicitly configured.

Before deploying the privileged node agent, run netra-doctor (see docs/host-readiness.md) to verify cgroup v2, bpffs, BTF, tracefs and related host gates. Use --require-tcx / --require-drop-reasons when those optional features are mandatory.

Build requirements are Go 1.27, Node 22 and Clang/LLVM with a BPF target.

make build            # web + binaries into ./bin
make install          # netractl → /usr/local/bin (or PREFIX=$HOME/.local)
make uninstall
# or manually:
npm --prefix web install
npm --prefix web run build
go mod tidy
go test ./...
go build ./cmd/netrad ./cmd/netractl ./cmd/netra-agent
make bpf

Container images:

docker build -t ghcr.io/zyvorai/netra:0.28.5 .
docker build -f Dockerfile.agent -t ghcr.io/zyvorai/netra-agent:0.28.5 .

Tagged releases publish both images (linux/amd64 and linux/arm64) to ghcr.io/zyvorai/netra and ghcr.io/zyvorai/netra-agent, signed with keyless cosign. To install a release rather than build one, see Install from a release.

Generate independent API and agent credentials. The privileged node agent DaemonSet is on by default (one pod per node, tolerations: Exists — same coverage idea as a CNI agent). Opt out with --set agent.enabled=false for a controller-only install.

# Install netractl onto PATH, then install the cluster:
make install                          # → /usr/local/bin/netractl (or PREFIX=$HOME/.local)
netractl install --namespace netra-system
# netractl install also copies itself onto PATH (use --skip-cli to opt out).
# or classic Helm:
helm upgrade --install netra ./helm/netra \
  --namespace netra-system --create-namespace \
  --set auth.apiKey="$(openssl rand -hex 32)" \
  --set auth.agentKey="$(openssl rand -hex 32)"

Then:

# After make install / deploy-remote, netractl reads ~/.netra/env + api-key.
# Loopback skips self-signed verify automatically; NodePort needs:
#   export NETRA_TLS_INSECURE=true   # or use ~/.netra/env from deploy
netractl status
netractl features list
netractl features enable dns-detect --yes

See docs/netractl.md (CLI, TLS, ~/.netra) and docs/features.md (feature catalog / API / UX). This uses cgroup hooks and requires neither Cilium nor a configured interface. TCX can be enabled for explicit interfaces or all up non-loopback interfaces:

--set agent.interfaces=eth0
# or
--set agent.interfaces=auto

XDP is deliberately explicit:

--set agent.xdpInterfaces=eth0

Do not enable XDP blindly across interfaces; validate driver/kernel compatibility and desired policy scope first.

Upgrades are tested. CI (scripts/ci-kind-lifecycle.sh) installs the previous release, writes rules and a baseline, runs helm upgrade --reset-then-reuse-values to the checkout, and asserts the state, the API key and the mode (observe) survive, the agent DaemonSet starts and reports, a controller pod restart keeps the state, and helm rollback returns to the previous release with its state still readable.

helm upgrade --install netra ./helm/netra \
  --namespace netra-system --reuse-values \
  --set cilium.enabled=true \
  --set hubble.enabled=true

cilium.enabled=true renders CiliumNetworkPolicy RBAC. hubble.enabled=true makes the controller connect to hubble-relay.kube-system.svc:80 unless hubble.address is overridden.

For plain manifests, see deploy/README.md. deploy/rbac-cilium.yaml is intentionally separate and optional.

# After make install / deploy-remote, netractl reads ~/.netra/env + api-key.
# Chart TLS is self-signed: loopback skips verify automatically; or:
#   export NETRA_TLS_INSECURE=true
#   export NETRA_URL=https://<node-ip>:30870
#   export NETRA_API_KEY=$(cat ~/.netra/api-key)

netractl ebpf summary
netractl ebpf maps              # human map inventory (desired deny/allow/…)
netractl ebpf maps --json
netractl ebpf census            # counts only
netractl ebpf coverage          # programs / missing pins
netractl ebpf capabilities
netractl ebpf health
netractl ebpf workloads
netractl ebpf scope show

# preview/select workload scope before enforcement
netractl ebpf scope selected --namespace payments --label app=checkout

# rules can be staged while observe-only
netractl ebpf deny add 203.0.113.10
netractl ebpf deny add 2001:db8::10
netractl ebpf cidr add 10.0.0.0/8 egress
netractl ebpf port add TCP 22 both
netractl ebpf uid add 1000
netractl ebpf process add curl
netractl ebpf dns add telemetry.example.com
netractl ebpf rate set 203.0.113.50 1500

# enforcement is leased, never permanent by default
netractl ebpf mode enforce 15m
netractl ebpf mode observe

The same controls are available in the Firewall dashboard page, including workload scope preview, discovered workloads, per-node selected-cgroup coverage and workload topology.

Behavior Insights CLI:

netractl insights summary
netractl insights dependencies
netractl insights baseline capture
netractl insights drift
netractl insights recommendations prod checkout

# time-window rate intelligence
netractl insights rates 5m
netractl insights rate-baseline capture 5m
netractl insights rate-drift 5m
netractl insights exposure 5m
netractl insights remediations 5m

AI briefs (heuristic by default; see docs/ai.md):

netractl ai status
netractl ai brief
netractl ai digest
netractl ai draft deny dns malware.example
netractl ai explain dns-failure high SERVFAIL ratio
netractl ai ask why is DNS failing in kube-system?

Netra is secure-by-default: the controller requires independent API and agent credentials unless NETRA_ALLOW_UNAUTHENTICATED=true is explicitly set for local development. The privileged agent uses a tokenless ServiceAccount. The controller alone receives read-only get/list RBAC for Pods and Services to provide workload attribution and dependency resolution; Cilium RBAC remains opt-in.

Controller state is restart-durable when NETRA_STATE_FILE is configured. Active/passive HA uses Kubernetes Lease election plus a shared state-file lock. A leader transition or controller restart never resurrects an old eBPF enforcement lease: the datapath returns to observe first.

See the Security docs page, docs/standalone-ebpf.md, docs/workload-scoping.md, docs/behavior-insights.md, docs/rate-insights.md, and docs/high-availability.md before production deployment. CI (.github/workflows/ci.yml) runs the current, living validation checks (Go build/vet/test, web typecheck/test/build, Helm lint/render, and a real clang BPF compile check) on every push.

Licensed under the Zyvor Production License v1.0.

• Free for development, testing, evaluation, research, education, and non-production labs
• Paid commercial license required for production, customer workloads, SaaS, managed services, OEM, redistribution, and other revenue-generating use

Commercial terms are issued separately: https://zyvor.dev.