Added documentation. Cleanup

Author: jllorente

README.md

@@ -135,6 +135,31 @@ Full documentation with API reference is available
 Examples
 ========
 
+High level abstractions
+-----------------------
+
+``python-iptables`` implements a low-level interface that tries to closely
+match the underlying C libraries. The module ``iptc.easy`` improves the
+usability of the library by providing a rich set of high-level functions
+designed to simplify the interaction with the library, for example::
+
+    >>> import iptc
+    >>> iptc.easy.dump_table('nat', ipv6=False)
+    {'INPUT': [], 'OUTPUT': [], 'POSTROUTING': [], 'PREROUTING': []}
+    >>> iptc.easy.dump_chain('filter', 'OUTPUT', ipv6=False)
+    [{'comment': {'comment': 'DNS traffic to Google'},
+      'dst': '8.8.8.8/32',
+      'protocol': 'udp',
+      'target': 'ACCEPT',
+      'udp': {'dport': '53'}}]
+    >>> iptc.easy.add_chain('filter', 'TestChain')
+    True
+    >>> rule_d = {'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}
+    >>> iptc.easy.insert_rule('filter', 'TestChain', rule_d)
+    >>> iptc.easy.dump_chain('filter', 'TestChain')
+    [{'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}]
+    >>> iptc.easy.delete_chain('filter', 'TestChain', flush=True)
+
 Rules
 -----
 
@@ -546,6 +571,21 @@ or more rules, than commit it:
 The drawback is that Table is a singleton, and if you disable
 autocommit, it will be disabled for all instances of that Table.
 
+Easy rules with dictionaries
+----------------------------
+To simplify operations with ``python-iptables`` rules we have included support to define and convert Rules object into python dictionaries.
+
+    >>> import iptc
+    >>> table = iptc.Table(iptc.Table.FILTER)
+    >>> chain = iptc.Chain(table, "INPUT")
+    >>> # Create an iptc.Rule object from dictionary
+    >>> rule_d = {'comment': {'comment': 'Match tcp.22'}, 'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}
+    >>> rule = iptc.easy.encode_iptc_rule(rule_d)
+    >>> # Obtain a dictionary representation from the iptc.Rule
+    >>> iptc.easy.decode_iptc_rule(rule)
+    {'tcp': {'dport': '22'}, 'protocol': 'tcp', 'comment': {'comment': 'Match tcp.22'}, 'target': 'ACCEPT'}
+
+
 Known Issues
 ============
 

doc/examples.rst

@@ -1,6 +1,31 @@
 Examples
 ========
 
+High level abstractions
+-----------------------
+
+``python-iptables`` implements a low-level interface that tries to closely
+match the underlying C libraries. The module ``iptc.easy`` improves the
+usability of the library by providing a rich set of high-level functions
+designed to simplify the interaction with the library, for example::
+
+    >>> import iptc
+    >>> iptc.easy.dump_table('nat', ipv6=False)
+    {'INPUT': [], 'OUTPUT': [], 'POSTROUTING': [], 'PREROUTING': []}
+    >>> iptc.easy.dump_chain('filter', 'OUTPUT', ipv6=False)
+    [{'comment': {'comment': 'DNS traffic to Google'},
+      'dst': '8.8.8.8/32',
+      'protocol': 'udp',
+      'target': 'ACCEPT',
+      'udp': {'dport': '53'}}]
+    >>> iptc.easy.add_chain('filter', 'TestChain')
+    True
+    >>> rule_d = {'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}
+    >>> iptc.easy.insert_rule('filter', 'TestChain', rule_d)
+    >>> iptc.easy.dump_chain('filter', 'TestChain')
+    [{'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}]
+    >>> iptc.easy.delete_chain('filter', 'TestChain', flush=True)
+
 Rules
 -----
 
@@ -419,9 +444,9 @@ To simplify operations with ``python-iptables`` rules we have included support t
     >>> chain = iptc.Chain(table, "INPUT")
     >>> # Create an iptc.Rule object from dictionary
     >>> rule_d = {'comment': {'comment': 'Match tcp.22'}, 'protocol': 'tcp', 'target': 'ACCEPT', 'tcp': {'dport': '22'}}
-    >>> rule = iptc.Rule.from_dict(rule_d)
+    >>> rule = iptc.easy.encode_iptc_rule(rule_d)
     >>> # Obtain a dictionary representation from the iptc.Rule
-    >>> rule.to_dict()
+    >>> iptc.easy.decode_iptc_rule(rule)
     {'tcp': {'dport': '22'}, 'protocol': 'tcp', 'comment': {'comment': 'Match tcp.22'}, 'target': 'ACCEPT'}
 
 

iptc/easy.py

@@ -288,6 +288,69 @@ def batch_delete_rules(table, batch_rules, ipv6=False, raise_exc=True):
         if raise_exc: raise
 
 
+def encode_iptc_rule(rule_d, ipv6=False):
+    """ Return a Rule(6) object from the input dictionary """
+    # Sanity check
+    assert(isinstance(rule_d, dict))
+    # Basic rule attributes
+    rule_attr = ('src', 'dst', 'protocol', 'in-interface', 'out-interface', 'fragment')
+    iptc_rule = Rule6() if ipv6 else Rule()
+    # Avoid issues with matches that require basic parameters to be configured first
+    for name in rule_attr:
+        if name in rule_d:
+            _iptc_setrule(iptc_rule, name, rule_d[name])
+    for name, value in rule_d.items():
+        try:
+            if name in rule_attr:
+                continue
+            elif name == 'target':
+                _iptc_settarget(iptc_rule, value)
+            else:
+                _iptc_setmatch(iptc_rule, name, value)
+        except Exception as e:
+            #print('Ignoring unsupported field <{}:{}>'.format(name, value))
+            continue
+    return iptc_rule
+
+def decode_iptc_rule(iptc_rule, ipv6=False):
+    """ Return a dictionary representation of the Rule(6) object
+    Note: host IP addresses are appended their corresponding CIDR """
+    d = {}
+    if ipv6==False and iptc_rule.src != '0.0.0.0/0.0.0.0':
+        _ip, _netmask = iptc_rule.src.split('/')
+        _netmask = _netmask_v4_to_cidr(_netmask)
+        d['src'] = '{}/{}'.format(_ip, _netmask)
+    elif ipv6==True and iptc_rule.src != '::/0':
+        d['src'] = iptc_rule.src
+    if ipv6==False and iptc_rule.dst != '0.0.0.0/0.0.0.0':
+        _ip, _netmask = iptc_rule.dst.split('/')
+        _netmask = _netmask_v4_to_cidr(_netmask)
+        d['dst'] = '{}/{}'.format(_ip, _netmask)
+    elif ipv6==True and iptc_rule.dst != '::/0':
+        d['dst'] = iptc_rule.dst
+    if iptc_rule.protocol != 'ip':
+        d['protocol'] = iptc_rule.protocol
+    if iptc_rule.in_interface is not None:
+        d['in-interface'] = iptc_rule.in_interface
+    if iptc_rule.out_interface is not None:
+        d['out-interface'] = iptc_rule.out_interface
+    if ipv6 == False and iptc_rule.fragment:
+        d['fragment'] = iptc_rule.fragment
+    for m in iptc_rule.matches:
+        if m.name not in d:
+            d[m.name] = m.get_all_parameters()
+        elif isinstance(d[m.name], list):
+            d[m.name].append(m.get_all_parameters())
+        else:
+            d[m.name] = [d[m.name], m.get_all_parameters()]
+    if iptc_rule.target and iptc_rule.target.name and len(iptc_rule.target.get_all_parameters()):
+        name = iptc_rule.target.name.replace('-', '_')
+        d['target'] = {name:iptc_rule.target.get_all_parameters()}
+    elif iptc_rule.target and iptc_rule.target.name:
+        d['target'] = iptc_rule.target.name
+    # Return a filtered dictionary
+    return _filter_empty_field(d)
+
 ### INTERNAL FUNCTIONS ###
 def _iptc_table_available(table, ipv6=False):
     """ Return True if the table is available, False otherwise """
@@ -357,69 +420,6 @@ def _iptc_settarget(iptc_rule, value):
     else:
         iptc_target = iptc_rule.create_target(value)
 
-def encode_iptc_rule(rule_d, ipv6=False):
-    # Sanity check
-    assert(isinstance(rule_d, dict))
-    # Basic rule attributes
-    rule_attr = ('src', 'dst', 'protocol', 'in-interface', 'out-interface', 'fragment')
-    iptc_rule = Rule6() if ipv6 else Rule()
-    # Avoid issues with matches that require basic parameters to be configured first
-    for name in rule_attr:
-        if name in rule_d:
-            _iptc_setrule(iptc_rule, name, rule_d[name])
-    for name, value in rule_d.items():
-        try:
-            if name in rule_attr:
-                #_iptc_setrule(iptc_rule, name, value)
-                continue
-            elif name == 'target':
-                _iptc_settarget(iptc_rule, value)
-            else:
-                _iptc_setmatch(iptc_rule, name, value)
-        except Exception as e:
-            #print('Ignoring unsupported field <{}:{}>'.format(name, value))
-            continue
-    return iptc_rule
-
-def decode_iptc_rule(iptc_rule, ipv6=False):
-    """ Return a dictionary representation of an iptc_rule
-    Note: host IP addresses are appended their corresponding CIDR """
-    d = {}
-    if ipv6==False and iptc_rule.src != '0.0.0.0/0.0.0.0':
-        _ip, _netmask = iptc_rule.src.split('/')
-        _netmask = _netmask_v4_to_cidr(_netmask)
-        d['src'] = '{}/{}'.format(_ip, _netmask)
-    elif ipv6==True and iptc_rule.src != '::/0':
-        d['src'] = iptc_rule.src
-    if ipv6==False and iptc_rule.dst != '0.0.0.0/0.0.0.0':
-        _ip, _netmask = iptc_rule.dst.split('/')
-        _netmask = _netmask_v4_to_cidr(_netmask)
-        d['dst'] = '{}/{}'.format(_ip, _netmask)
-    elif ipv6==True and iptc_rule.dst != '::/0':
-        d['dst'] = iptc_rule.dst
-    if iptc_rule.protocol != 'ip':
-        d['protocol'] = iptc_rule.protocol
-    if iptc_rule.in_interface is not None:
-        d['in-interface'] = iptc_rule.in_interface
-    if iptc_rule.out_interface is not None:
-        d['out-interface'] = iptc_rule.out_interface
-    if ipv6 == False and iptc_rule.fragment:
-        d['fragment'] = iptc_rule.fragment
-    for m in iptc_rule.matches:
-        if m.name not in d:
-            d[m.name] = m.get_all_parameters()
-        elif isinstance(d[m.name], list):
-            d[m.name].append(m.get_all_parameters())
-        else:
-            d[m.name] = [d[m.name], m.get_all_parameters()]
-    if iptc_rule.target and iptc_rule.target.name and len(iptc_rule.target.get_all_parameters()):
-        name = iptc_rule.target.name.replace('-', '_')
-        d['target'] = {name:iptc_rule.target.get_all_parameters()}
-    elif iptc_rule.target and iptc_rule.target.name:
-        d['target'] = iptc_rule.target.name
-    # Return a filtered dictionary
-    return _filter_empty_field(d)
-
 def _batch_begin_table(table, ipv6=False):
     """ Disable autocommit on a table """
     iptc_table = _iptc_gettable(table, ipv6)

iptc/ip4tc.py

@@ -10,7 +10,7 @@
 import weakref
 
 from .util import find_library, load_kernel
-from .xtables import (XT_INV_PROTO, NFPROTO_IPV4, NFPROTO_IPV6, XTablesError, xtables,
+from .xtables import (XT_INV_PROTO, NFPROTO_IPV4, XTablesError, xtables,
                       xt_align, xt_counters, xt_entry_target, xt_entry_match)
 
 __all__ = ["Table", "Chain", "Rule", "Match", "Target", "Policy", "IPTCError"]
@@ -1389,123 +1389,6 @@ def _get_mask(self):
     mask = property(_get_mask)
     """This is the raw mask buffer as iptables uses it when removing rules."""
 
-    @classmethod
-    def from_dict(cls, rule_d):
-        """Generate a Rule(6) object from the input dictionary."""
-        # Sanity check
-        assert(isinstance(rule_d, dict))
-        # Basic rule attributes
-        rule_attr = ('src', 'dst', 'protocol', 'in-interface', 'out-interface', 'fragment')
-        iptc_rule = cls()
-        # Avoid issues with matches that require basic parameters to be configured first
-        for name in rule_attr:
-            if name in rule_d:
-                _iptc_setrule(iptc_rule, name, rule_d[name])
-        for name, value in rule_d.items():
-            try:
-                if name in rule_attr:
-                    #_iptc_setrule(iptc_rule, name, value)
-                    continue
-                elif name == 'target':
-                    _iptc_settarget(iptc_rule, value)
-                else:
-                    _iptc_setmatch(iptc_rule, name, value)
-            except Exception as e:
-                #print('Ignoring unsupported field <{}:{}>'.format(name, value))
-                continue
-        return iptc_rule
-
-    def to_dict(self):
-        """Generate a dictionary representation of the Rule(6) object."""
-        d = {}
-        if self.nfproto==NFPROTO_IPV4 and self.src != '0.0.0.0/0.0.0.0':
-            d['src'] = self.src
-        elif self.nfproto==NFPROTO_IPV6 and self.src != '::/0':
-            d['src'] = self.src
-        if self.nfproto==NFPROTO_IPV4 and self.dst != '0.0.0.0/0.0.0.0':
-            d['dst'] = self.dst
-        elif self.nfproto==NFPROTO_IPV6 and self.dst != '::/0':
-            d['dst'] = self.dst
-        if self.protocol != 'ip':
-            d['protocol'] = self.protocol
-        if self.in_interface is not None:
-            d['in-interface'] = self.in_interface
-        if self.out_interface is not None:
-            d['out-interface'] = self.out_interface
-        if self.nfproto==NFPROTO_IPV4 and self.fragment:
-            d['fragment'] = self.fragment
-        for m in self.matches:
-            if m.name not in d:
-                d[m.name] = m.get_all_parameters()
-            elif isinstance(d[m.name], list):
-                d[m.name].append(m.get_all_parameters())
-            else:
-                d[m.name] = [d[m.name], m.get_all_parameters()]
-        if self.target and self.target.name and len(self.target.get_all_parameters()):
-            name = self.target.name.replace('-', '_')
-            d['target'] = {name:self.target.get_all_parameters()}
-        elif self.target and self.target.name:
-            d['target'] = self.target.name
-        # Return a filtered dictionary
-        return _filter_empty_field(d)
-
-# Helper functions for dictionary operations over Rule(6) objects
-def _iptc_setattr(object, name, value):
-    # Translate attribute name
-    name = name.replace('-', '_')
-    setattr(object, name, value)
-
-def _iptc_setattr_d(object, value_d):
-    for name, value in value_d.items():
-        _iptc_setattr(object, name, value)
-
-def _iptc_setrule(iptc_rule, name, value):
-    _iptc_setattr(iptc_rule, name, value)
-
-def _iptc_setmatch(iptc_rule, name, value):
-    # Iterate list/tuple recursively
-    if isinstance(value, list) or isinstance(value, tuple):
-        for inner_value in value:
-            _iptc_setmatch(iptc_rule, name, inner_value)
-    # Assign dictionary value
-    elif isinstance(value, dict):
-        iptc_match = iptc_rule.create_match(name)
-        _iptc_setattr_d(iptc_match, value)
-    # Assign value directly
-    else:
-        iptc_match = iptc_rule.create_match(name)
-        _iptc_setattr(iptc_match, name, value)
-
-def _iptc_settarget(iptc_rule, value):
-    # Target is dictionary - Use only 1 pair key/value
-    if isinstance(value, dict):
-        for k, v in value.items():
-            iptc_target = iptc_rule.create_target(k)
-            _iptc_setattr_d(iptc_target, v)
-            return
-    # Simple target
-    else:
-        iptc_target = iptc_rule.create_target(value)
-
-def _filter_empty_field(data_d):
-    """
-    Remove empty lists from dictionary values
-    Before: {'target': {'CHECKSUM': {'checksum-fill': []}}}
-    After:  {'target': {'CHECKSUM': {'checksum-fill': ''}}}
-    Before: {'tcp': {'dport': ['22']}}}
-    After:  {'tcp': {'dport': '22'}}}
-    """
-    for k, v in data_d.items():
-        if isinstance(v, dict):
-            data_d[k] = _filter_empty_field(v)
-        elif isinstance(v, list) and len(v) != 0:
-            v = [_filter_empty_field(_v) if isinstance(_v, dict) else _v for _v in v ]
-        if isinstance(v, list) and len(v) == 1:
-            data_d[k] = v.pop()
-        elif isinstance(v, list) and len(v) == 0:
-            data_d[k] = ''
-    return data_d
-
 
 class Chain(object):
     """Rules are contained by chains.