# azrakrgll/xdp_internship architecture

> Architecture diagram of the GitHub repository azrakrgll/xdp_internship, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/azrakrgll/xdp_internship
- Repository: https://github.com/azrakrgll/xdp_internship

## Overview

This repository’s documented product is an XDP/eBPF Linux network firewall with a Python control and monitoring plane. Its main workflow is packet inspection and enforcement in the kernel, flow-stat collection by the userspace firewall process, then log processing and presentation through the web backend. Rule updates travel separately from the rules file through the Python rule engine into pinned kernel maps. The README also describes rate limiting, trusted-IP/port exceptions, MAC anti-spoofing, and SQLite-backed monitoring. Several other C/eBPF files appear to be standalone examples, so they are not included as firewall components; dashboard frontend files are not present in the supplied tree.

Main entry points: [`app.py`](https://github.com/azrakrgll/xdp_internship/blob/main/app.py) (Web backend), [`firewall.c`](https://github.com/azrakrgll/xdp_internship/blob/main/firewall.c) (Firewall runner), [`firewall.bpf.c`](https://github.com/azrakrgll/xdp_internship/blob/main/firewall.bpf.c) (XDP firewall), [`rule_engine.py`](https://github.com/azrakrgll/xdp_internship/blob/main/rule_engine.py) (Rule engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_enforcement["Packet enforcement"]
  node_firewall_bpf["XDP firewall<br/>[firewall.bpf.c]"]
  node_firewall_runner["Firewall runner<br/>[firewall.c]"]
  node_flow_maps[("Pinned BPF maps<br/>[firewall.bpf.c]")]
end

subgraph group_control["Rule control"]
  node_rules_file["Firewall rules"]
  node_rule_engine["Rule engine<br/>[rule_engine.py]"]
end

subgraph group_monitoring["Monitoring and UI"]
  node_socket["Unix socket<br/>[app.py]"]
  node_backend["Web backend<br/>[app.py]"]
  node_log_store[("SQLite logs<br/>[db_manager.py]")]
  node_web_dashboard["Web dashboard"]
end

node_traffic(("Network traffic"))
node_kernel["Linux kernel"]
node_dashboard_user(("Dashboard user"))

node_traffic -->|"enters"| node_kernel
node_kernel -->|"invokes XDP"| node_firewall_bpf
node_firewall_bpf -->|"updates rules and stats"| node_flow_maps
node_firewall_bpf -->|"passes or drops"| node_kernel
node_firewall_runner -->|"loads and attaches"| node_firewall_bpf
node_firewall_runner -->|"pins maps"| node_flow_maps
node_rules_file -->|"provides rules"| node_rule_engine
node_rule_engine -->|"updates pinned maps"| node_flow_maps
node_firewall_runner -->|"reads flow stats"| node_flow_maps
node_firewall_runner -->|"sends log batches"| node_socket
node_socket -->|"delivers batches"| node_backend
node_backend -->|"writes logs"| node_log_store
node_backend -->|"queries history and stats"| node_log_store
node_dashboard_user -->|"views monitoring"| node_web_dashboard
node_web_dashboard -->|"requests data"| node_backend
node_backend -->|"serves live updates"| node_web_dashboard

click node_firewall_bpf "https://github.com/azrakrgll/xdp_internship/blob/main/firewall.bpf.c"
click node_firewall_runner "https://github.com/azrakrgll/xdp_internship/blob/main/firewall.c"
click node_flow_maps "https://github.com/azrakrgll/xdp_internship/blob/main/firewall.bpf.c"
click node_rule_engine "https://github.com/azrakrgll/xdp_internship/blob/main/rule_engine.py"
click node_socket "https://github.com/azrakrgll/xdp_internship/blob/main/app.py"
click node_backend "https://github.com/azrakrgll/xdp_internship/blob/main/app.py"
click node_log_store "https://github.com/azrakrgll/xdp_internship/blob/main/db_manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_firewall_bpf,node_firewall_runner,node_flow_maps,node_dashboard_user toneBlue
class node_rules_file,node_rule_engine toneAmber
class node_socket,node_backend,node_log_store,node_web_dashboard toneMint
class node_traffic,node_kernel toneIndigo
```

## Components

### Packet enforcement

- [XDP firewall](https://github.com/azrakrgll/xdp_internship/blob/main/firewall.bpf.c): `firewall.bpf.c`
- [Firewall runner](https://github.com/azrakrgll/xdp_internship/blob/main/firewall.c): `firewall.c`
- [Pinned BPF maps](https://github.com/azrakrgll/xdp_internship/blob/main/firewall.bpf.c): `firewall.bpf.c`

### Rule control

- **Firewall rules**
- [Rule engine](https://github.com/azrakrgll/xdp_internship/blob/main/rule_engine.py): `rule_engine.py`

### Monitoring and UI

- [Unix socket](https://github.com/azrakrgll/xdp_internship/blob/main/app.py): `app.py`
- [Web backend](https://github.com/azrakrgll/xdp_internship/blob/main/app.py): `app.py`
- [SQLite logs](https://github.com/azrakrgll/xdp_internship/blob/main/db_manager.py): `db_manager.py`
- **Web dashboard**

### Other components

- **Network traffic**
- **Linux kernel**
- **Dashboard user**

## Connections

- Network traffic → Linux kernel: enters
- Linux kernel → XDP firewall: invokes XDP
- XDP firewall → Pinned BPF maps: updates rules and stats
- XDP firewall → Linux kernel: passes or drops
- Firewall runner → XDP firewall: loads and attaches
- Firewall runner → Pinned BPF maps: pins maps
- Firewall rules → Rule engine: provides rules
- Rule engine → Pinned BPF maps: updates pinned maps
- Firewall runner → Pinned BPF maps: reads flow stats
- Firewall runner → Unix socket: sends log batches
- Unix socket → Web backend: delivers batches
- Web backend → SQLite logs: writes logs
- Web backend → SQLite logs: queries history and stats
- Dashboard user → Web dashboard: views monitoring
- Web dashboard → Web backend: requests data
- Web backend → Web dashboard: serves live updates