DPDK Graph Firewall

A high-performance firewall built with DPDK graph nodes and a runtime CLI policy engine.

It is currently set up for AF_PACKET virtual devices inside a VM or container-friendly Linux environment using DPDK EAL arguments such as --no-pci --vdev=net_af_packet0,iface=eth0.

Features

• Graph-based packet pipeline
• Runtime firewall policy updates from a CLI thread
• Stateful connection tracking
• Per-flow accounting in the conntrack table
• Drop-reason logging
• Trace mode for firewall decisions

Project Architecture

High-level flow

+---------------------+
| Runtime CLI Thread  |
| allow/reject/trace  |
+----------+----------+
           |
           v
+----------------------+
| Runtime Policy       |
| + Trace State        |
+----------+-----------+
           |
           v
+-----------+     +----------------+     +-----------------+     +-------------------+     +------------------+     +----------------+     +---------+
| AF_PACKET  | --> | rx_node        | --> | eth_parse_node  | --> | ipv4_parse_node   | --> | firewall_acl_    | --> | conntrack_node | --> | tx_node |
| / NIC port |     | burst receive  |     | IPv4 gate       |     | tuple parsing     |     | node             |     | flow updates   |     |         |
+-----------+     +----------------+     +-----------------+     +-------------------+     +--------+---------+     +--------+-------+     +----+----+
                                                                                                        |                          |                  |
                                                                                                        v                          v                  v
                                                                                                  +-----------------------------------------------+
                                                                                                  | drop_node                                     |
                                                                                                  | malformed, denied, unsupported, tx-failed     |
                                                                                                  +-----------------------------------------------+

How packets move through the graph

1. rx_node pulls a burst of packets from DPDK port 0.
2. eth_parse_node accepts only IPv4 Ethernet frames.
3. ipv4_parse_node parses the IPv4 packet and 5-tuple.
4. firewall_acl_node evaluates runtime policy and trace state.
5. Allowed packets go to conntrack_node for flow accounting.
6. tx_node transmits accepted packets.
7. Any parse, policy, or transmit failure is sent to drop_node.

Control-plane components

• main.c: initializes DPDK EAL, mempool, port, graph, ACL loader, and CLI thread
• firewall/runtime_policy.c: runtime policy engine for allow, reject, trace, and show
• conntrack/flow_table.c: stateful flow table and byte/packet counters
• firewall/acl_rules.c: ACL file loading support used during startup and reload

Repository Layout

• main.c: app bootstrap and CLI thread
• graph.c: graph creation from the registered DPDK nodes
• nodes/: packet-processing graph nodes
• firewall/: runtime policy engine and ACL loading
• conntrack/: flow table implementation
• include/: shared packet and firewall structures
• Dockerfile: container image for building the project
• Makefile: build, clean, and package commands

Build

Build the binary from the repository root:

make

This creates:

./graphshield

Run Locally

Example with AF_PACKET on eth0:

sudo ./graphshield -l 0-1 -n 4 --no-pci --vdev=net_af_packet0,iface=eth0 -- rules.txt

Notes:

• rules.txt is optional for the current runtime-policy path.
• If the ACL file cannot be loaded, the app still starts in runtime CLI policy mode.
• In AF_PACKET mode, the Linux kernel network stack can still see traffic on the same interface.

Build And Run With Docker

Build the image:

docker build -t graphshield .

Start a shell inside the built image:

docker run --rm -it graphshield

If you want to run the firewall from the container, pass the needed network and privilege options for your environment and then execute ./graphshield with the required DPDK arguments inside the container.

Create A Source Package

Create a distributable source archive of the repository:

make package

This creates:

graphshield-src.tar.gz

To extract it somewhere else:

tar -xzf graphshield-src.tar.gz

Policy Model

Default behavior on startup is deny-all.

A flow is allowed only when the runtime policy permits it.

Runtime allow logic

For runtime allow, both of these dimensions must match:

1. Protocol dimension: allow tcp, allow udp, allow icmp, or allow any
2. Destination IP dimension: allow ip 1.2.3.4 or allow ip any

If either dimension does not match, the packet is dropped.

Reject precedence

Explicit rejects are checked first:

• reject any
• reject tcp
• reject udp
• reject icmp
• reject ip <addr>
• reject ip any

Conntrack behavior

• Conntrack is used for stateful flow tracking and the fast path.
• When policy changes through the CLI, the conntrack table is cleared.
• trace also clears conntrack first so the observed decision path is fresh.

CLI Commands

Core commands

• help
• show
• show trace
• trace

Allow commands

• allow tcp
• allow udp
• allow icmp
• allow any
• allow ip <IPv4>
• allow ip any
• accept ... is treated the same as allow ...

Reject commands

• reject tcp
• reject udp
• reject icmp
• reject any
• reject ip <IPv4>
• reject ip any
• deny ... and drop ... are aliases for reject ...

Reset helper

• clear any

This clears the broad allow any and reject any style toggles, but does not remove specific protocol or IP entries.

Trace Mode

Command:

trace

Behavior:

• Starts a blocking trace session in the CLI.
• Ends when either:
  • 10 allowed packets are observed, or
  • 20 rejected packets are observed first.
• The CLI prompt returns after the trace session completes.

Example trace outputs:

TRACE allowed path=runtime proto=6 src=... dst=... len=... progress=...
TRACE done: observed 20 rejected packets before 10 allowed. Firewall rules blocked traffic.

Practical Command Recipes

Default deny

No command is required. Startup policy is already deny-all.

Allow TCP to any destination

clear any
allow ip any
allow tcp
show

Allow only UDP

clear any
reject tcp
reject icmp
allow ip any
allow udp
show

Allow TCP only to one destination IP

clear any
allow ip 104.30.136.45
allow tcp
show

Test trace with live traffic

Firewall terminal:

trace

Traffic generator terminal:

curl -4 https://example.com >/dev/null 2>&1

Drop Logging

drop_node logs aggregated reasons over time:

• non-ipv4
• malformed
• unsupported-l4
• acl-deny
• tx-failed

Example:

drop reason=acl-deny count=4097

ACL Module Status

firewall/acl_rules.c still exists and is initialized from main.c, but the active packet decision path is centered on the runtime policy engine. If ACL file loading fails, the application continues in runtime CLI policy mode.

Troubleshooting

trace finishes with only rejects

This means no packet matched your current allow rules before the reject threshold.

Check:

1. show output
2. Whether both protocol and destination IP dimensions are allowed
3. Whether you generated matching traffic immediately after starting trace

A protocol still seems allowed unexpectedly

Explicitly reject protocols you do not want:

reject tcp
reject udp
reject icmp

Then re-allow only the protocol you want.

allow ip 8.8.8.8 still blocks ping

You must also allow ICMP:

allow ip 8.8.8.8
allow icmp

Arrow keys show ^[[A

The current CLI is line-based and does not provide shell-like history support.

Performance Notes

• DPDK graph nodes keep the data plane modular and fast.
• Burst RX/TX reduces per-packet overhead.
• Conntrack uses a DPDK hash table for efficient flow lookup and updates.