tessl/pypi-python-iptables

Python bindings for iptables providing programmatic control over Linux netfilter rules

—

Pending

Overview

Eval results

Files

Rules, Matches, and Targets

Name: tessl/pypi-python-iptables
Author: tessl

Comprehensive rule creation, matching, and targeting system supporting all iptables match and target extensions. This module enables precise packet filtering and manipulation through flexible rule construction with extensible match conditions and actions.

Capabilities

Rule Creation and Management

Rules are the core filtering units in iptables that define packet matching criteria and actions. Each rule can contain multiple matches and must have exactly one target.

class Rule:
    """
    Represents an individual iptables rule with packet matching criteria and target action.
    """
    
    def __init__(self, entry=None, chain=None):
        """
        Initialize a Rule object.
        
        Args:
            entry: Optional low-level rule entry
            chain: Optional parent chain
        """
    
    @property
    def src(self) -> str:
        """Source address/network (e.g., '192.168.1.0/24')"""
    
    @src.setter
    def src(self, value: str) -> None:
        """Set source address/network"""
    
    @property
    def dst(self) -> str:
        """Destination address/network (e.g., '10.0.0.0/8')"""
    
    @dst.setter
    def dst(self, value: str) -> None:
        """Set destination address/network"""
    
    @property
    def protocol(self) -> str:
        """Protocol (tcp, udp, icmp, etc.)"""
    
    @protocol.setter
    def protocol(self, value: str) -> None:
        """Set protocol"""
    
    @property
    def in_interface(self) -> str:
        """Input interface (e.g., 'eth0', 'eth+')"""
    
    @in_interface.setter
    def in_interface(self, value: str) -> None:
        """Set input interface"""
    
    @property
    def out_interface(self) -> str:
        """Output interface (e.g., 'eth0', 'eth+')"""
    
    @out_interface.setter
    def out_interface(self, value: str) -> None:
        """Set output interface"""
    
    @property
    def fragment(self) -> bool:
        """Fragment flag"""
    
    @fragment.setter
    def fragment(self, value: bool) -> None:
        """Set fragment flag"""
    
    @property
    def target(self) -> 'Target':
        """Rule target (action to take)"""
    
    @target.setter
    def target(self, value: 'Target') -> None:
        """Set rule target"""
    
    @property
    def matches(self) -> list:
        """List of Match objects"""
    
    @property
    def counters(self) -> tuple:
        """Packet and byte counters as (packets, bytes)"""
    
    def create_match(self, name: str, revision: int = None) -> 'Match':
        """
        Create and add a match to this rule.
        
        Args:
            name: Match name (tcp, udp, state, etc.)
            revision: Optional match revision
            
        Returns:
            Match object
        """
    
    def create_target(self, name: str, revision: int = None, goto: bool = False) -> 'Target':
        """
        Create a target for this rule.
        
        Args:
            name: Target name (ACCEPT, DROP, MASQUERADE, etc.)
            revision: Optional target revision
            goto: Use goto instead of jump
            
        Returns:
            Target object
        """
    
    def add_match(self, match: 'Match') -> None:
        """
        Add an existing match to this rule.
        
        Args:
            match: Match object to add
        """
    
    def remove_match(self, match: 'Match') -> None:
        """
        Remove a match from this rule.
        
        Args:
            match: Match object to remove
        """
    
    def get_counters(self) -> tuple:
        """
        Get packet and byte counters.
        
        Returns:
            Tuple of (packets, bytes)
        """
    
    def set_counters(self, packets: int, bytes: int) -> None:
        """
        Set packet and byte counters.
        
        Args:
            packets: Packet count
            bytes: Byte count
        """
    
    def final_check(self) -> None:
        """Validate rule completeness and configuration"""

Match Extensions

Matches provide flexible packet filtering conditions. All iptables match extensions are supported through dynamic attribute access.

class Match:
    """
    Represents an iptables match extension for packet filtering conditions.
    """
    
    def __init__(self, rule: Rule, name: str = None, match=None, revision: int = None):
        """
        Initialize a Match object.
        
        Args:
            rule: Parent Rule object
            name: Match name (tcp, udp, state, etc.)
            match: Optional low-level match object
            revision: Optional match revision
        """
    
    @property
    def name(self) -> str:
        """Match name (tcp, udp, state, etc.)"""
    
    @property
    def parameters(self) -> dict:
        """Dictionary of all match parameters"""
    
    @property
    def size(self) -> int:
        """Size of underlying C structure"""
    
    @property
    def rule(self) -> Rule:
        """Parent Rule object"""
    
    def set_parameter(self, parameter: str, value: str = None) -> None:
        """
        Set a match parameter.
        
        Args:
            parameter: Parameter name
            value: Parameter value
        """
    
    def reset(self) -> None:
        """Reset match to default state"""
    
    def final_check(self) -> None:
        """Validate match configuration"""

Target Actions

Targets define what action to take when a packet matches a rule's conditions. Both standard targets and extension targets are supported.

class Target:
    """
    Represents an iptables target extension defining packet actions.
    """
    
    STANDARD_TARGETS: list  # List of standard target names
    
    def __init__(self, rule: Rule, name: str = None, target=None, revision: int = None, goto: bool = None):
        """
        Initialize a Target object.
        
        Args:
            rule: Parent Rule object
            name: Target name (ACCEPT, DROP, MASQUERADE, etc.)
            target: Optional low-level target object
            revision: Optional target revision
            goto: Use goto instead of jump
        """
    
    @property
    def name(self) -> str:
        """Target name"""
    
    @property
    def parameters(self) -> dict:
        """Dictionary of all target parameters"""
    
    @property
    def standard_target(self) -> str:
        """Standard target name if applicable"""
    
    @property
    def goto(self) -> bool:
        """Whether target uses goto"""
    
    def set_parameter(self, parameter: str, value: str = None) -> None:
        """
        Set a target parameter.
        
        Args:
            parameter: Parameter name  
            value: Parameter value
        """
    
    def reset(self) -> None:
        """Reset target to default state"""
    
    def final_check(self) -> None:
        """Validate target configuration"""

Usage Examples

Basic Rule Creation

import iptc

# Create table and chain
table = iptc.Table(iptc.Table.FILTER)
chain = iptc.Chain(table, "INPUT")

# Create a rule to accept SSH traffic from specific network
rule = iptc.Rule()
rule.protocol = "tcp"
rule.src = "192.168.1.0/24"
rule.in_interface = "eth0"

# Add TCP match for SSH port
tcp_match = rule.create_match("tcp")
tcp_match.dport = "22"

# Set target to ACCEPT
rule.target = rule.create_target("ACCEPT")

# Insert rule into chain
chain.insert_rule(rule)

Advanced Rule with Multiple Matches

import iptc

table = iptc.Table(iptc.Table.FILTER)
chain = iptc.Chain(table, "INPUT")

# Create rule with multiple conditions
rule = iptc.Rule()
rule.protocol = "tcp"

# Add TCP match
tcp_match = rule.create_match("tcp")
tcp_match.dport = "80"

# Add state match for established connections
state_match = rule.create_match("state")
state_match.state = "ESTABLISHED,RELATED"

# Add comment match for documentation
comment_match = rule.create_match("comment")
comment_match.comment = "Allow established HTTP connections"

# Set target
rule.target = rule.create_target("ACCEPT")

chain.insert_rule(rule)

NAT Rule Example

import iptc

# Access NAT table
nat_table = iptc.Table(iptc.Table.NAT)
postrouting_chain = iptc.Chain(nat_table, "POSTROUTING")

# Create masquerade rule for outgoing traffic
rule = iptc.Rule()
rule.protocol = "tcp"
rule.out_interface = "eth0"

# Create MASQUERADE target
masq_target = rule.create_target("MASQUERADE")
masq_target.to_ports = "1024-65535"

rule.target = masq_target
postrouting_chain.append_rule(rule)

Rule with Negation

import iptc

table = iptc.Table(iptc.Table.FILTER)
chain = iptc.Chain(table, "INPUT")

# Create rule to block specific MAC address
rule = iptc.Rule()

# Add MAC match with negation
mac_match = rule.create_match("mac")
mac_match.mac_source = "!00:11:22:33:44:55"  # ! for negation

rule.target = rule.create_target("DROP")
chain.insert_rule(rule)

Complex Matching with iprange

import iptc

table = iptc.Table(iptc.Table.FILTER)
chain = iptc.Chain(table, "INPUT")

rule = iptc.Rule()
rule.protocol = "tcp"

# Add TCP match
tcp_match = rule.create_match("tcp") 
tcp_match.dport = "22"

# Add IP range match
iprange_match = rule.create_match("iprange")
iprange_match.src_range = "192.168.1.100-192.168.1.200"
iprange_match.dst_range = "172.22.33.106"

rule.target = rule.create_target("DROP")
chain.insert_rule(rule)

# This is equivalent to:
# iptables -A INPUT -p tcp --dport 22 -m iprange --src-range 192.168.1.100-192.168.1.200 --dst-range 172.22.33.106 -j DROP

Working with Counters

import iptc
import time

table = iptc.Table(iptc.Table.FILTER)
chain = iptc.Chain(table, "OUTPUT")

# Get current counters
for rule in chain.rules:
    packets, bytes = rule.get_counters()
    print(f"Rule counters: {packets} packets, {bytes} bytes")

# Wait and refresh to get updated counters
time.sleep(5)
table.refresh()  # Important: refresh to get updated counters

for rule in chain.rules:
    packets, bytes = rule.get_counters() 
    print(f"Updated counters: {packets} packets, {bytes} bytes")

Match and Target Parameters

Different matches and targets have different parameters. Here are some common examples:

import iptc

rule = iptc.Rule()

# TCP match parameters
tcp_match = rule.create_match("tcp")
tcp_match.sport = "80"        # Source port
tcp_match.dport = "443"       # Destination port
tcp_match.tcp_flags = "SYN,ACK SYN"  # TCP flags

# UDP match parameters  
udp_match = rule.create_match("udp")
udp_match.sport = "53"
udp_match.dport = "53"

# State match parameters
state_match = rule.create_match("state")
state_match.state = "NEW,ESTABLISHED,RELATED"

# Limit match parameters
limit_match = rule.create_match("limit")
limit_match.limit = "10/min"
limit_match.limit_burst = "5"

# MARK target parameters
mark_target = rule.create_target("MARK")
mark_target.set_mark = "0x1"

# DNAT target parameters
dnat_target = rule.create_target("DNAT")
dnat_target.to_destination = "192.168.1.100:8080"

# LOG target parameters
log_target = rule.create_target("LOG")
log_target.log_prefix = "DROPPED: "
log_target.log_level = "4"

Install with Tessl CLI