A high-performance, configurable network packet filter implemented as a Linux kernel module with userspace control interface. This driver provides real-time packet filtering capabilities with rule-based matching, multiple operating modes, and comprehensive monitoring.
- Multi-mode Filtering: Blacklist, Whitelist, Count-only, and Disabled modes
- Rule-based Filtering: Match packets by protocol, IP addresses, and ports
- Real-time Statistics: Comprehensive packet counting and byte tracking
- Packet Logging: Circular buffer for packet metadata with timestamping
- Userspace Control: Full control via IOCTL interface
- Virtual Network Device: Creates
pfXinterface for packet interception - Concurrent Safe: RCU-based rule matching, fine-grained locking
- Performance Optimized: Zero-copy where possible, batch processing
- Sysfs/Debugfs Integration: Runtime monitoring and configuration
- Comprehensive Testing: Unit, integration, and performance tests
- Command-line Control:
filter_ctlutility for all operations - Real-time Monitoring:
filter_statswith ncurses interface - Automated Testing: Complete test suite and performance benchmarks
- Production Scripts: Driver loading, configuration, and monitoring scripts
┌─────────────────────────────────────────┐
│ Userspace Applications │
│ • filter_ctl (Control Utility) │
│ • filter_stats (Real-time Monitor) │
│ • filter_test (Test Suite) │
│ • benchmark (Performance Tool) │
└───────────────────┬─────────────────────┘
│ (IOCTL via /dev/packet_filter)
┌───────────────────┴─────────────────────┐
│ Kernel Space │
│ ┌─────────────────────────────────┐ │
│ │ Character Device │ │
│ │ • IOCTL Interface │ │
│ │ • Userspace Communication │ │
│ └───────────────┬─────────────────┘ │
│ │ │
│ ┌───────────────┴─────────────────┐ │
│ │ Packet Filter Engine │ │
│ │ • Rule Database │ │
│ │ • Packet Matching │ │
│ │ • Statistics Collection │ │
│ │ • Logging System │ │
│ └───────────────┬─────────────────┘ │
│ │ │
│ ┌───────────────┴─────────────────┐ │
│ │ Virtual Network Device │ │
│ │ • pf0 Interface Creation │ │
│ │ • Packet Hook/Interception │ │
│ └─────────────────────────────────┘ │
└───────────────────┬─────────────────────┘
│ (Network Stack Integration)
┌───────────────────┴─────────────────────┐
│ Linux Network Stack │
└─────────────────────────────────────────┘
packet_filter/
├── README.md # This file
├── Makefile # Top-level build system
├── packet_filter.c # Main kernel driver
├── packet_filter.h # Driver header file
├── ioctl_defs.h # IOCTL definitions
├── userspace/ # Userspace tools
│ ├── Makefile # Userspace build
│ ├── libfilter.h # Library header
│ ├── libfilter.c # Library implementation
│ ├── filter_ctl.c # Control utility
│ ├── filter_stats.c # Real-time monitor
│ └── filter_test.c # Test program
├── scripts/ # Management scripts
│ ├── load_driver.sh # Driver loading script
│ ├── test_suite.sh # Automated test suite
│ └── perf_test.sh # Performance testing
├── docs/ # Documentation
│ ├── design.md # Design document
│ ├── api.md # API documentation
│ └── testing.md # Testing guide
└── tests/ # Test files
├── unit_test.c # Kernel unit tests
├── packet_generator.c # Test packet generator
└── benchmark.c # Performance benchmark
- CPU: x86_64 or ARM64 processor (multi-core recommended)
- RAM: Minimum 512MB, 1GB+ recommended for testing
- Storage: 100MB free space for build artifacts
- Network: At least one network interface for testing
- Linux Kernel: 4.4 or newer (5.x recommended)
- GCC: 7.0 or newer
- GNU Make: 4.0 or newer
- Linux Headers: Matching running kernel version
- Root Access: For module loading and testing
- ncurses: For real-time monitoring interface
- pcap library: For packet generator
- iperf3/netperf: For performance testing
- valgrind: For memory debugging
- git: For version control
# Required kernel options
CONFIG_MODULES=y # Loadable module support
CONFIG_NET=y # Networking support
CONFIG_NETDEVICES=y # Network device support
CONFIG_PACKET=y # Packet socket
CONFIG_NETFILTER=y # Netfilter support
# Recommended for debugging
CONFIG_DEBUG_FS=y # Debug filesystem
CONFIG_DYNAMIC_DEBUG=y # Dynamic debug support
CONFIG_KALLSYMS=y # Kernel symbol table# Clone the repository (if applicable)
git clone https://github.com/yourusername/packet-filter-driver.git
cd packet-filter-driver
# Build everything
make all
# Or build components separately
make kernel # Build kernel module only
make userspace # Build userspace tools only# Load with the provided script
sudo ./scripts/load_driver.sh --load --test
# Or manually
sudo insmod packet_filter.ko
sudo ./userspace/filter_ctl --get-stats# Set target network interface
sudo ./userspace/filter_ctl --set-device eth0
# Set filtering mode (1=blacklist, 2=whitelist, 3=count-only)
sudo ./userspace/filter_ctl --set-mode 1
# Enable filtering
sudo ./userspace/filter_ctl --enable-filter 1# Block SSH traffic (port 22)
sudo ./userspace/filter_ctl --add-rule "tcp:any:any:any:22:1"
# Log all DNS traffic to Google
sudo ./userspace/filter_ctl --add-rule "udp:any:8.8.8.8:any:53:2"
# Drop ICMP from specific IP
sudo ./userspace/filter_ctl --add-rule "icmp:192.168.1.100:any:any:any:1"# View real-time statistics
sudo ./userspace/filter_stats
# View packet logs
sudo ./userspace/filter_ctl --get-log 50
# Run comprehensive tests
sudo ./scripts/test_suite.sh1. Module loaded via insmod
2. Virtual network device (pf0) created
3. Character device (/dev/packet_filter) registered
4. Sysfs/debugfs entries created
5. Filtering engine initialized (disabled by default)
6. Ready for userspace configuration
Packet Arrival
↓
Check if filtering enabled
↓
Extract packet headers (IP, TCP/UDP/ICMP)
↓
Traverse rule database
↓
Match against rules (protocol, IP, ports)
↓
Execute action (PASS/DROP/LOG)
↓
Update statistics
↓
Forward/Drop packet
for each rule in rule_list:
if rule.protocol != 0 AND rule.protocol != packet.protocol:
continue
if rule.src_ip != 0 AND rule.src_ip != packet.src_ip:
continue
if rule.dst_ip != 0 AND rule.dst_ip != packet.dst_ip:
continue
if rule.src_port != 0 AND rule.src_port != packet.src_port:
continue
if rule.dst_port != 0 AND rule.dst_port != packet.dst_port:
continue
return rule.action // Match found
return default_action // Based on current modeUserspace Application
↓
Open /dev/packet_filter
↓
Issue IOCTL command
↓
Kernel validates request
↓
Execute operation (add rule, get stats, etc.)
↓
Return result/status
↓
Close device file
# Load with custom parameters
sudo insmod packet_filter.ko \
max_rules=2000 \ # Maximum rules (default: 1024)
log_size=2048 \ # Log entries (default: 1024)
default_mode=1 \ # Startup mode (default: 0)
debug=1 # Debug output (default: 0)| Mode | Value | Description |
|---|---|---|
| Disabled | 0 | All packets pass, no filtering |
| Blacklist | 1 | Default PASS, rules specify DROP/LOG |
| Whitelist | 2 | Default DROP, rules specify PASS/LOG |
| Count-only | 3 | Count packets, no filtering |
protocol:src_ip:src_port:dst_ip:dst_port:action
Example:
tcp:any:any:any:22:1 # Drop all SSH
udp:8.8.8.8:any:any:53:2 # Log DNS to Google
icmp:192.168.1.100:any:any:any:1 # Drop ICMP from specific IP
# View driver messages
sudo dmesg | grep packet_filter
# Follow in real-time
sudo dmesg -w | grep packet_filter# Command-line statistics
sudo ./userspace/filter_ctl --get-stats
# Real-time monitoring (ncurses)
sudo ./userspace/filter_stats
# Text mode monitoring
sudo ./userspace/filter_stats --simple# View sysfs entries
ls -la /sys/class/pf/pf0/
# Read statistics
cat /sys/class/pf/pf0/stats
# Check mode
cat /sys/class/pf/pf0/mode# Access debug information
ls -la /sys/kernel/debug/packet_filter/
# Run unit tests
echo run > /sys/kernel/debug/packet_filter/test
# Dump rules
cat /sys/kernel/debug/packet_filter/rules# Run complete test suite
sudo ./scripts/test_suite.sh
# Run specific test categories
sudo ./scripts/test_suite.sh --unit
sudo ./scripts/test_suite.sh --integration
sudo ./scripts/test_suite.sh --performance# Comprehensive performance test
sudo ./scripts/perf_test.sh
# Specific benchmarks
sudo ./userspace/benchmark --throughput
sudo ./userspace/benchmark --latency
sudo ./userspace/benchmark --memory# 5-minute stress test
sudo ./scripts/perf_test.sh --duration 300
# High-concurrency test
sudo ./scripts/stress_test.sh --concurrent 10
# Memory stress test
sudo ./scripts/stress_test.sh --memory# Build with coverage
make coverage
# Run tests
./scripts/run_all_tests.sh
# Generate coverage report
make coverage-report# Check kernel compatibility
uname -r
# Check for missing symbols
sudo dmesg | tail -20
# Verify kernel headers are installed
ls -la /lib/modules/$(uname -r)/build# Check module loaded
lsmod | grep packet_filter
# Check device major number
grep packet_filter /proc/devices
# Create manually (if needed)
sudo mknod /dev/packet_filter c 250 0
sudo chmod 666 /dev/packet_filter# Verify filtering is enabled
sudo ./userspace/filter_ctl --get-mode
# Check rule was added
sudo ./userspace/filter_ctl --list-rules
# Test with simple rule
sudo ./userspace/filter_ctl --add-rule "tcp:any:any:any:9999:1"# Check system load
top -p $(pgrep filter_ctl)
# Monitor interrupts
cat /proc/interrupts | grep -i eth
# Reduce logging if enabled
sudo ./userspace/filter_ctl --flush-log# Enable verbose kernel logging
echo 8 > /proc/sys/kernel/printk
# Trace function calls
echo packet_filter_* > /sys/kernel/debug/tracing/set_ftrace_filter
echo function > /sys/kernel/debug/tracing/current_tracer
# Monitor packet flow
sudo tcpdump -i pf0 -n| Metric | Baseline | With 100 Rules | With 1000 Rules |
|---|---|---|---|
| Throughput | 950+ kpps | 900 kpps | 800 kpps |
| Latency | < 10 μs | < 15 μs | < 25 μs |
| Rule Addition | 8500/sec | 8000/sec | 7500/sec |
| Memory Usage | 256 KB | 512 KB | 2 MB |
- Rule Ordering: Place frequently matched rules first
- Specificity: Use specific rules before general ones
- Log Management: Limit log size based on needs
- Batch Operations: Add/remove multiple rules together
- Monitor Resources: Watch memory and CPU usage
# Set appropriate permissions
sudo chmod 600 /dev/packet_filter
sudo chown root:root /dev/packet_filter
# Use capability-based access
sudo setcap cap_net_admin+ep ./userspace/filter_ctl# Limit maximum rules
echo 5000 > /sys/module/packet_filter/parameters/max_rules
# Limit log size
echo 1024 > /sys/module/packet_filter/parameters/log_size
# Enable rate limiting (future feature)- All userspace inputs are validated in kernel
- Buffer overflow protection implemented
- Sanity checks on rule parameters
- Rate limiting for control operations
| Command | Code | Description |
|---|---|---|
| PF_ADD_RULE | 1 | Add filtering rule |
| PF_DEL_RULE | 2 | Delete rule by ID |
| PF_GET_STATS | 3 | Get statistics |
| PF_CLEAR_STATS | 4 | Clear statistics |
| PF_SET_MODE | 5 | Set filtering mode |
| PF_GET_MODE | 6 | Get current mode |
| PF_ENABLE_FILTER | 7 | Enable/disable filtering |
| PF_GET_LOG | 8 | Get packet log |
| PF_FLUSH_LOG | 9 | Flush log buffer |
| PF_SET_DEVICE | 10 | Set target device |
// Connection management
pf_handle_t* pf_open(const char *device_path);
void pf_close(pf_handle_t *handle);
// Rule management
int pf_add_rule(pf_handle_t *handle, const struct pf_rule *rule);
int pf_delete_rule(pf_handle_t *handle, unsigned int rule_id);
// Statistics
int pf_get_stats(pf_handle_t *handle, struct pf_stats *stats);
void pf_print_stats(const struct pf_stats *stats, FILE *stream);
// Configuration
int pf_set_mode(pf_handle_t *handle, unsigned char mode);
int pf_set_device(pf_handle_t *handle, const char *device_name);For complete API documentation, see docs/api.md.
# 1. Build production version
make production
# 2. Install module and tools
sudo make install
# 3. Create udev rule for permissions
sudo ./scripts/load_driver.sh --udev
# 4. Configure startup (Systemd)
sudo cp scripts/packet-filter.service /etc/systemd/system/
sudo systemctl enable packet-filter
# 5. Load on boot
echo "packet_filter" | sudo tee -a /etc/modules-load.d/packet-filter.conf# 1. Build with debug symbols
make debug
# 2. Enable debug logging
echo 1 > /sys/module/packet_filter/parameters/debug
# 3. Use debugfs for inspection
cat /sys/kernel/debug/packet_filter/rules
# 4. Run unit tests
echo run > /sys/kernel/debug/packet_filter/testFROM ubuntu:20.04
# Install dependencies
RUN apt-get update && apt-get install -y \
build-essential \
linux-headers-$(uname -r) \
kmod
# Copy source
COPY packet_filter /app
# Build and install
RUN cd /app && make all && make install
# Run driver
CMD ["modprobe", "packet_filter"]- Linux Device Drivers, 3rd Edition - Chapter 17: Network Drivers
- Understanding Linux Network Internals - Christian Benvenuti
- Linux Kernel Networking - Rami Rosen
- Kernel Documentation:
/Documentation/networking/
- TCP/IP Illustrated - Richard Stevens
- Linux Socket Programming - Sean Walton
- Network Programming with Go - Adam Woodbeck
# 1. Fork and clone
git clone https://github.com/yourusername/packet-filter-driver.git
# 2. Create feature branch
git checkout -b feature/new-rule-type
# 3. Make changes and test
make clean && make all
sudo ./scripts/test_suite.sh
# 4. Commit changes
git commit -m "Add new rule matching feature"
# 5. Push and create pull request
git push origin feature/new-rule-type- Follow Linux kernel coding style (
scripts/checkpatch.pl) - Document all public APIs
- Include unit tests for new features
- Update documentation with changes
- Maintain backward compatibility
- All new code must include unit tests
- Integration tests must pass
- Performance impact must be measured
- Memory usage must be monitored
This project is licensed under the GNU General Public License v2.0.
Packet Filter Driver
Copyright (C) 2024 Network Driver Project
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
- Linux kernel community for driver development resources
- Network stack maintainers for API documentation
- Open source testing tools and frameworks
- Contributors and testers of this project
- Email: js.ramesh1990@gmail.com
- Check this README and documentation
- Run the test suite to identify issues
- Check kernel logs for error messages
- Verify system requirements are met
- Try the troubleshooting guide above