Metadata-Version: 1.1
Name: pydivert
Version: 2.0.3
Summary: Python binding to windivert driver
Home-page: https://github.com/ffalcinelli/pydivert
Author: Fabio Falcinelli
Author-email: fabio.falcinelli@gmail.com
License: LGPLv3
Download-URL: https://github.com/ffalcinelli/pydivert/releases/2.0.3
Description: pydivert
        ^^^^^^^^
        
        |appveyor| |codecov| |latest_release| |python_versions|
        
        Python bindings for WinDivert_, a Windows driver that allows user-mode applications to
        capture/modify/drop network packets sent to/from the Windows network stack.
        
        Requirements
        ------------
        
        - Python 2.7 or Python 3.4+ (32 or 64 bit)
        - Windows Vista/7/8/10 or Windows Server 2008 (32 or 64 bit)
        - Administrator Privileges
        
        Installation
        ------------
        
        You can install PyDivert by running
        
        .. code-block:: text
        
            $ pip install pydivert
        
        Starting with PyDivert 1.0.2, WinDivert_ is bundled with
        PyDivert and does not need to be installed separately.
        
        
        **WinDivert Version Compatibility**
        
        =================================  ===============
        PyDivert                           WinDivert
        ---------------------------------  ---------------
        0.0.7                              1.0.x or 1.1.x
        1.0.x (API-compatible with 0.0.7)  1.1.8 (bundled)
        2.0.x                              1.1.8 (bundled)
        =================================  ===============
        
        Getting Started
        ---------------
        
        PyDivert consists of two main classes: ``pydivert.WinDivert`` and ``pydivert.Packet``.
        First, you usually want to create a ``WinDivert`` object to start capturing network traffic and then
        call ``.recv()`` to receive the first ``Packet`` that was captured. By receiving packets, they are taken
        out of the Windows network stack and will not be sent out unless you take action.
        You can re-inject packets by calling ``.send(packet)``.
        The following example opens a WinDivert handle, receives a single packet, prints it, re-injects it,
        and then exits:
        
        .. code-block:: python
        
            import pydivert
        
            # Capture only TCP packets to port 80, i.e. HTTP requests.
            w = pydivert.WinDivert("tcp.DstPort == 80 and tcp.PayloadLength > 0")
        
            w.open()  # packets will be captured from now on
        
            packet = w.recv()  # read a single packet
            print(packet)
            w.send(packet)  # re-inject the packet into the network stack
        
            w.close()  # stop capturing packets
        
        Packets that are not matched by the ``"tcp.DstPort == 80 and tcp.PayloadLength > 0"`` filter will not be handled by WinDivert
        and continue as usual. The syntax for the filter language is described in the `WinDivert documentation <https://reqrypt.org/windivert-doc.html#filter_language>`_.
        
        Python Idioms
        -------------
        
        ``pydivert.WinDivert`` instances can be used as *context managers* for capturing traffic and as (infinite) *iterators* over
        packets. The following code is equivalent to the example above:
        
        .. code-block:: python
        
            import pydivert
        
            with pydivert.WinDivert("tcp.DstPort == 80 and tcp.PayloadLength > 0") as w:
                for packet in w:
                    print(packet)
                    w.send(packet)
                    break
        
        Packet Modification
        -------------------
        
        ``pydivert.Packet`` provides a variety of properties that can be used to access and modify the
        packet's headers or payload. For example, you can browse the web on port 1234 with PyDivert:
        
        .. code-block:: python
        
            import pydivert
        
            with pydivert.WinDivert("tcp.DstPort == 1234 or tcp.SrcPort == 80") as w:
                for packet in w:
                    if packet.dst_port == 1234:
                        print(">") # packet to the server
                        packet.dst_port = 80
                    if packet.src_port == 80:
                        print("<") # reply from the server
                        packet.src_port = 1234
                    w.send(packet)
        
        Try opening http://example.com:1234/ in your browser!
        
        WinDivert supports access and modification of a variety of TCP/UDP/ICMP attributes out of the box.
        
        .. code-block:: python
        
            >>> print(packet)
            Packet({'direction': <Direction.OUTBOUND: 0>,
             'dst_addr': '93.184.216.34',
             'dst_port': 443,
             'icmpv4': None,
             'icmpv6': None,
             'interface': (23, 0),
             'ipv4': {'src_addr': '192.168.86.169',
                      'dst_addr': '93.184.216.34',
                      'packet_len': 81},
             'ipv6': None,
             'is_inbound': False,
             'is_loopback': False,
             'is_outbound': True,
             'payload': '\x17\x03\x03\x00$\x00\x00\x00\x00\x00\x00\x02\x05\x19q\xbd\xcfD\x8a\xe3...',
             'raw': <memory at 0x028924E0>,
             'src_addr': '192.168.86.169',
             'src_port': 52387,
             'tcp': {'src_port': 52387,
                     'dst_port': 443,
                     'syn': False,
                     'ack': True,
                     'fin': False,
                     'rst': False,
                     'psh': True,
                     'urg': False,
                     'header_len': 20,
                     'payload': '\x17\x03\x03\x00$\x00\x00\x00\x00\x00\x00\x02\x05\x19q\xbd\xcfD\x8a\xe3...'},
             'udp': None})
        
        Uninstalling PyDivert
        ---------------------
        
        You can uninstall PyDivert by running
        
        .. code-block:: text
        
            $ pip uninstall pydivert
        
        If the WinDivert driver is still running at that time, it will remove itself on the next reboot.
        
        API Reference Documentation
        ---------------------------
        
        The API Reference Documentation for PyDivert can be found `here <https://ffalcinelli.github.io/pydivert/>`_.
        
        .. |appveyor| image:: https://img.shields.io/appveyor/ci/ffalcinelli/pydivert/master.svg
            :target: https://ci.appveyor.com/project/ffalcinelli/pydivert
            :alt: Appveyor Build Status
        
        .. |codecov| image:: https://img.shields.io/codecov/c/github/ffalcinelli/pydivert/master.svg
            :target: https://codecov.io/gh/ffalcinelli/pydivert
            :alt: Coverage Status
        
        .. |latest_release| image:: https://img.shields.io/pypi/v/pydivert.svg
            :target: https://pypi.python.org/pypi/pydivert
            :alt: Latest Version
        
        .. |python_versions| image:: https://img.shields.io/pypi/pyversions/pydivert.svg
            :target: https://pypi.python.org/pypi/pydivert
            :alt: Supported Python versions
        
        .. _WinDivert: https://reqrypt.org/windivert.html
        
Keywords: windivert,network,tcp/ip
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Win32 (MS Windows)
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Operating System :: Microsoft :: Windows :: Windows Vista
Classifier: Operating System :: Microsoft :: Windows :: Windows Server 2008
Classifier: Operating System :: Microsoft :: Windows :: Windows 7
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking :: Firewalls
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Utilities
