Datapath map inventory
Read-only view of what Netra intends to keep in its BPF maps under
/sys/fs/bpf/netra.
This is the controller desired state that every netra-agent reconciles
into pinned maps. It answers “what deny/allow/rate/policy entries are
configured right now?” without requiring node SSH or bpftool.
It is not a raw dump of kernel map memory. Observability maps that the agent reads for counters (flows, TCP health, TLS SNI stats, …) are not listed here — only control-plane inventory (rules the operator can stage).
Quick start
netractl ebpf maps # human-readable board
netractl ebpf maps --json # same payload as the API
GET /api/v1/ebpf/maps
Authorization: Bearer <NETRA_API_KEY>
MCP (read-only): netra_ebpf_maps → same JSON as the API.
Resource: netra://ebpf/maps. Console: #page=ebpf-maps (web/src/pages/EbpfMaps.tsx).
What you see
| Field | Meaning |
|---|---|
mode | Fast-path mode (observe / enforce) |
revision | Config generation agents sync against |
pinRoot | Always /sys/fs/bpf/netra |
filledMaps / emptyMaps / totalEntries | Rollup across inventory families |
maps[] | One object per logical map family |
Each maps[] entry:
| Field | Meaning |
|---|---|
id | Stable inventory id (blocked_v4, rate, …) |
title | Operator label |
group | deny · allow · rate · syn-drop · capability · policy · scope |
bpfMap | Pin name(s) under the pin root (may be v4/v6 pair) |
count / limit | Live size vs compile-time max_entries |
entries | Human strings (IPs, CIDR (direction), TCP/443 (egress), …), capped at 200 |
Human board layout
Netra datapath maps (controller view)
Mode observe · revision 21 · pin /sys/fs/bpf/netra
…
2 filled · 23 empty · 2 total entries
DENY
Deny IPv4 (egress) [blocked_v4] 1/4096
· 203.0.113.9
Deny DNS name [blocked_dns] 1/4096
· evil.example
Empty maps (23): allowed_v4, blocked_ports, …
Filled groups print first; empty pins are summarized at the bottom so capacity is visible without drowning the board.
Map families covered
| Group | Inventory ids | BPF pins (typical) |
|---|---|---|
| Deny | blocked_v4/v6, blocked_ingress_v4/v6, blocked_cidr, blocked_ports, blocked_uids, blocked_dns, blocked_sni, blocked_comms | blocked_* |
| Allow | allowed_v4/v6, allowed_cidr, allowed_ports, allowed_uids, allowed_comms | allowed_* |
| Rate | rate, conn_rate_limits | rate_v4/v6, conn_rate_limits |
| SYN-drop | syndrop, syndrop_cidr | syndrop_* (flags on existing denies) |
| Capability | capgate | capgate_pids (via deniedCapabilities) |
| Policy | netpol_deny, netpol_rules, netpol_default | netpol_* |
| Scope | scope | scope_mode + enforced_cgroups |
Limits match bpf/netra_tc.c max_entries (also exposed on
GET /api/v1/ebpf/capabilities → limits). Raising a limit requires a BPF
rebuild and agent roll — not a runtime knob.
How this differs from nearby commands
| Command / API | Returns entries? | Purpose |
|---|---|---|
ebpf maps / GET /api/v1/ebpf/maps | Yes (inventory) | Operator-readable desired contents |
ebpf census / GET /api/v1/ebpf/census | No (counts only) | Compact deny/allow sizes |
ebpf scope show / GET /api/v1/ebpf/config | Raw config JSON | Full wire shape agents poll |
ebpf rules list | Durable rule IDs | Edit/history/rollback by stable id |
ebpf coverage | Programs / missing pins | Node health — not entry lists |
bpftool map dump on the node | Kernel memory | Break-glass; not what CI/operators use day-to-day |
Observe vs enforce
Maps stay populated in observe mode; verdicts stay allow until a leased
enforce period. Inventory is therefore useful before flipping mode: stage
rules, review ebpf maps, then ebpf mode enforce 15m.
Privacy and safety
- Read-only. No mutate path on this endpoint or CLI.
- No application payloads, argv/cmdline, or Secret contents.
- Entries are the same metadata already stored in controller state (IPs,
CIDRs, DNS names, SNI, ports, UIDs, process
comm, selectors). - Not a substitute for node-local forensics when pins are missing — use
ebpf coverage/netra-doctorfor pin health.
Implementation
- Builder:
internal/ebpfmaps - API:
GET /api/v1/ebpf/maps(internal/api) - CLI:
netractl ebpf maps [--json](cmd/netractl/maps.go) - MCP:
netra_ebpf_maps - Catalog / CI: included in
cmd/netractl/commands_catalog.go
Related
bpf/README.md— pin inventory and program liststandalone-ebpf.md— hooks, fail-open, enforcement tablefirewall.md— dashboard Firewall pageworkload-scoping.md—scope/enforced_cgroupsnetractl.md— CLI install and TLS defaultsmcp-integration.md— MCP tool table