Zwall
Talk to an Engineer
Talk to an Engineer
Documentation
Docs Home › Security › Rules

Rules

SharedStatus: SUPPORTED (implemented object types). UID/GID is not a stable customer contract.Audience: security engineer

Purpose

Manager-stored firewall rules that Virtualization Agents enforce via XDP/TC. Hosting observation Agents cannot receive rules (API 409).

Rules are distinct from the ephemeral blocked-IP set. zwallctl deny creates a rule; zwallctl list reads blocked-ips.

Object types (implemented)

IP/CIDR allow/deny, port/protocol blocks, MAC, BPDU, DHCP guard, port-scan detect, rate-limit, DNS hostname→IP (not a DNS WAF). Default priorities come from GetDefaultPriority for types such as BLOCK_IP_INBOUND, BLOCK_IP_OUTBOUND, DETECT_PORT_SCAN.

Scope used by zwallctl: global, agent, group. Assign with POST /api/v1/rules/:id/assign body {"agent_id":1}.

Operator path 

zwallctl login --manager-url https://manager.example.com:8443 --username admin
zwallctl deny 203.0.113.10
zwallctl list-rules
zwallctl rule-info 1

API: Rules. Validate (Enterprise): POST /api/v1/rules/validate returns is_valid, errors, warnings.

UID/GID

/api/v1/rules/uid-gid and ebpf.enable_uid_gid_filtering exist. They authorize covered TCP/UDP socket operations by real UID / primary real GID — not packet filtering. Example YAML may enable it; do not treat UID/GID as a supported customer ABI until a stable customer contract is published. Do not claim UID/GID numbers as a stable public contract.

Verification

  • Rule appears in GET /api/v1/rules
  • Virtualization Agent online with eBPF loaded (GET /api/v1/dashboard/ebpf-health on Enterprise)
  • Packet drops only on Virtualization Agents
  • Hosting assign → 409 Hosting observation Agents cannot receive rules

Failure modes

400 dedicated cgroup path required; 403 license; 409 hosting; Agent offline → rule stored but not yet on the wire.

Security

Flush/disable is fleet-wide. Do not leave testing mode on. Unknown JSON fields from CLI are ignored — do not assume extra keys are stored.