Python Stateful Packet-Filtering Firewall

A Python-based stateful packet-filtering firewall for educational purposes. This project demonstrates networking and security concepts including packet inspection, rule-based filtering, and TCP connection state tracking.

Disclaimer

THIS FIREWALL IS FOR EDUCATIONAL PURPOSES ONLY.

It is NOT designed for production use and provides NO SECURITY GUARANTEES. Use at your own risk.

Features

• Rule-based packet filtering based on:
  • Source/destination IP addresses and subnets
  • Source/destination ports
  • Protocols (TCP, UDP, ICMP)
  • Direction (inbound/outbound)
  • TCP flags
• Stateful TCP connection tracking
• Pseudo-stateful tracking for UDP and ICMP
• Multiple operation modes:
  • Live network interface monitoring (using scapy)
  • PCAP file processing for testing
  • Linux NetfilterQueue integration (on supported systems)
• Configurable rules via JSON
• Detailed logging

Requirements

• Python 3.6+
• scapy
• netfilterqueue (Linux only, optional)

Installation

1. Clone this repository or download the files
2. Install dependencies:

pip install -r requirements.txt

Note: On Linux, you may need to install additional dependencies for netfilterqueue:

sudo apt-get install build-essential python3-dev libnetfilter-queue-dev

Usage

Running on a live interface

sudo python firewall.py --interface eth0 --rules rules.json --log firewall.log --verbose

Processing a PCAP file

python firewall.py --pcap input.pcap --rules rules.json --log firewall.log

Using NetfilterQueue (Linux only)

First, set up iptables rules to redirect traffic to the queue:

sudo iptables -A INPUT -j NFQUEUE --queue-num 0
sudo iptables -A OUTPUT -j NFQUEUE --queue-num 0

Then run the firewall:

sudo python firewall.py --nfqueue 0 --rules rules.json --log firewall.log

To reset iptables when done:

sudo iptables -F

Testing

The repository includes a test script that generates a sample PCAP file with various packet types:

python test_firewall.py
python firewall.py --pcap test_packets.pcap --rules rules.json --log firewall_test.log --verbose

Rule Configuration

Rules are defined in a JSON file. Here's an example:

{
    "default_policy": "DROP",
    "rules": [
        {
            "id": "allow-outbound-http",
            "direction": "OUT",
            "protocol": "TCP",
            "src_ip": "0.0.0.0/0",
            "src_port": 0,
            "dst_ip": "0.0.0.0/0",
            "dst_port": 80,
            "action": "ACCEPT"
        },
        {
            "id": "block-malicious-ip",
            "direction": "IN",
            "protocol": "ANY",
            "src_ip": "192.168.1.100/32",
            "dst_ip": "0.0.0.0/0",
            "action": "DROP"
        }
    ]
}

Rule attributes:

• id: A descriptive name for the rule
• direction: "IN" for inbound, "OUT" for outbound
• protocol: "TCP", "UDP", "ICMP", or "ANY"
• src_ip: Source IP address/subnet (0.0.0.0/0 for any)
• src_port: Source port (0 for any)
• dst_ip: Destination IP address/subnet
• dst_port: Destination port (0 for any)
• tcp_flags: Optional string of flag characters (S=SYN, A=ACK, F=FIN, R=RST)
• action: "ACCEPT", "DROP", or "REJECT"

Architecture

The firewall consists of three main components:

1. Packet Processing: Captures and dissects network packets using scapy
2. Rule Engine: Applies user-defined rules to packets
3. State Table: Tracks TCP connection states and maintains pseudo-state for UDP/ICMP

Limitations

This educational firewall has several limitations:

• Performance is not optimized for high-volume traffic
• No IPv6 support
• Limited protocol support (only TCP, UDP, ICMP)
• Basic TCP state tracking compared to production firewalls
• No application layer inspection
• Simplistic direction detection

License

This project is available under the MIT License - see the LICENSE file for details.

Extending the Project

Potential enhancements for learning:

1. Add IPv6 support
2. Implement application layer (L7) filtering
3. Create a GUI for rule management
4. Add statistics and real-time monitoring
5. Implement packet modification capabilities