https://github.com/al-oladko/ebpfilter
A lightweight firewall with stateful session tracking, L2–L4 filtering, DPI-based inspection, connection rate limiting, and NAT support.
https://github.com/al-oladko/ebpfilter
dpi ebpf firewall nat rate-limiting xdp
Last synced: about 2 months ago
JSON representation
A lightweight firewall with stateful session tracking, L2–L4 filtering, DPI-based inspection, connection rate limiting, and NAT support.
- Host: GitHub
- URL: https://github.com/al-oladko/ebpfilter
- Owner: al-oladko
- Created: 2025-05-28T21:46:54.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-06-13T20:40:45.000Z (about 1 year ago)
- Last Synced: 2025-06-13T21:31:51.779Z (about 1 year ago)
- Topics: dpi, ebpf, firewall, nat, rate-limiting, xdp
- Language: C
- Homepage:
- Size: 63.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ebpfilter
**ebpfilter** is an eBPF XDP-based stateful firewall with support for L7 (application-layer) traffic filtering using DPI (Deep Packet Inspection). It maintains connection state, so once a session is allowed, packets within that session do not need to be re-evaluated against the rules.
It supports standard L4-level firewall filtering options such as source and destination IP addresses, protocols, and port numbers. L7 protocol detection is performed using a lightweight DPI engine. DPI analysis is independent of destination port, and currently has the following limitation: the L7 protocol must be detected in the first packet carrying payload data.
#### Features
- Stateful session tracking
- Layer 3–4 packet filtering
- DPI-based filtering
- Rate limiting for new sessions
- Source NAT
- Support for IP fragmentation handling (the firewall applies the session policy to all fragments based on the first fragment, as subsequent fragments do not contain the Layer 4 header)
---
## Installation
To install ebpfilter, follow these steps:
```bash
git clone https://github.com/al-oladko/ebpfilter
./configure
make
sudo make install
````
---
## Usage
Use the `ebpfilter` utility to load, unload, and manage filtering rules.
### Load XDP program
Attach the XDP filter to a network interface:
```bash
ebpfilter load dev
```
### Show attached interfaces
List all interfaces where the XDP program is currently attached:
```bash
ebpfilter status
```
You can attach the program to multiple interfaces. Each interface maintains its own independent rule set.
### Unload XDP program
Unload the XDP program from a specific interface:
```bash
ebpfilter unload [dev ]
```
If `` is not specified, the program will be unloaded from all interfaces.
### Reload XDP program
Reattaching the XDP program while preserving the loaded rule set:
```bash
ebpfilter reload [dev ]
```
If `` is not specified, the program will be reloaded on all interfaces.
### View connection
View connection tracking table:
```bash
ebpfilter connection [dev ]
```
The 5-tuple of the session is displayed, along with the firewall rule that allowed the session and the session's expiration status.
---
## Managing Rules
### Set default policy
Specify the default action for packets that do not match any rule:
```bash
ebpfilter rule set default {accept|drop} [dev ]
```
### Add a rule
Add a new filtering rule:
```bash
ebpfilter rule add [dev ]
```
You may omit `ifname` if the program is attached to only one interface. If attached to multiple interfaces, `ifname` is required.
**Example L3 rule (IP-based filtering):**
```bash
ebpfilter rule add src 10.20.0.0/16 dst 192.168.1.0/24 action accept
```
**Example L7 rule (DPI-based protocol detection):**
```bash
ebpfilter rule add service tls action accept
```
This rule allows TLS traffic regardless of the destination port (not limited to port 443). L7 rules can be combined with L3/L4 filters:
```bash
ebpfilter rule add src any dst 192.168.1.1 tcp port 443 service tls action accept
```
**Setting connection limit**
```bash
ebpfilter rule add tcp port 443 connlimit 100/1s action accept
```
Limit of new connections for the rule. The format is [connections_per_period]/[period], where the period is specified in seconds, minutes, or hours, and must be indicated with the suffixes s, m, or h, respectively.
To get information about other options when adding a rule, see the help for the rule command.
### View help for rule syntax
```bash
ebpfilter rule help
```
### Show current policy
Display the currently loaded rule set:
```bash
ebpfilter rule show [dev ]
```
Each rule includes statistics on matches, such as packet and byte counts.
### Delete a rule
Remove a rule by its number:
```bash
ebpfilter rule delete [dev ]
```
### Flush all rules
Remove all rules from the policy:
```bash
ebpfilter rule flush [dev ]
```
---
## Example Policy
```bash
ebpfilter rule add udp port 53 service dns action accept
ebpfilter rule add service tls action accept
ebpfilter rule set default drop
```
This configuration allows:
* DNS traffic over UDP port 53
* TLS traffic on any port
* All other traffic will be dropped by default.
---
## Policy Management
The policy command is used to manage firewall policies. Each network interface has its own policy, which is configured separately and stored in a dedicated file. By default, policies are saved in YAML format, but you can also use the txt format by specifying the format parameter in the command.
### Save a Policy
Currently, firewall policy changes made using the rule or nat commands are not saved automatically. To save the current policy, run:
```bash
ebpfilter policy save
```
By default, the policy will be saved to the /etc/firewall directory. You can specify a different file name and path using the file parameter. For example:
```bash
ebpfilter policy save file policy_allow_http.yaml
```
Or save the policy in txt format:
```bash
ebpfilter policy save file policy_deny_ssh.txt format txt
```
### Apply a Policy
To load a policy from a file, use:
```bash
ebpfilter policy apply file policy.yaml
```
Or, to load the default policy file:
```bash
ebpfilter policy apply
```
### View a Policy
To view a saved policy, use the show parameter. For example:
```bash
ebpfilter policy show file policy_allow_ssh.yaml
```
---
## NAT
Currently, only **source NAT** is supported.
A NAT rule must be defined for a network interface, and the IP address of that interface will be used as the **source IP address** in translated packets.
Current NAT limitations:
- If, after translating the source IP address, the new 5-tuple matches the 5-tuple of another session that is already being NATed, the NAT rule will not be applied.
### Add a NAT Rule
To add a source NAT rule, use the following command:
```bash
ebpfilter nat add src-translation set-ip IP-address|auto [dev IFNAME]
```
- If an explicit `IP-address` is given, it will be used as the new source IP.
- If `auto` is specified, the IP address of the given `IFNAME` interface will be used.
- If only one XDP program is attached to a single interface, the `dev` parameter is optional — the NAT rule will be applied to that interface.
You can also use a shorthand alias to add a source NAT rule:
```bash
ebpfilter snat add set-ip IP-address|auto [dev IFNAME]
```
### Flush NAT Rules
To remove all NAT rules, use:
```bash
ebpfilter nat flush [dev IFNAME]
```
### View NAT Rules
To view currently configured NAT rules and their parameters, run:
```bash
ebpfilter nat show [dev IFNAME]
```
## License
This project is licensed under the GNU General Public License v2 only.