Metadata-Version: 1.1
Name: scapy-nflog-capture
Version: 13.04.8
Summary: Driver for scapy to allow capturing packets via Linux NFLOG interface
Home-page: http://github.com/mk-fg/scapy-nflog-capture
Author: Mike Kazantsev
Author-email: mk.fraggod@gmail.com
License: WTFPL
Description: scapy-nflog-capture
        -------------------
        
        Driver for `scapy network manipulation
        tool <http://www.secdev.org/projects/scapy/>`_ to allow capturing
        packets via `Linux NFLOG
        interface <http://wiki.wireshark.org/CaptureSetup/NFLOG>`_.
        
        Installation
        ------------
        
        It's a regular package for Python 2.7 (not 3.X).
        
        Using `pip <http://pip-installer.org/>`_ is the best way:
        
        ::
        
            % pip install scapy-nflog-capture
        
        If you don't have it, use:
        
        ::
        
            % easy_install pip
            % pip install scapy-nflog-capture
        
        Alternatively (`see
        also <http://www.pip-installer.org/en/latest/installing.html>`_):
        
        ::
        
            % curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python
            % pip install scapy-nflog-capture
        
        Or, if you absolutely must:
        
        ::
        
            % easy_install scapy-nflog-capture
        
        But, you really shouldn't do that.
        
        Current-git version can be installed like this:
        
        ::
        
            % pip install 'git+https://github.com/mk-fg/scapy-nflog-capture.git#egg=scapy-nflog-capture'
        
        Requirements
        ~~~~~~~~~~~~
        
        -  Python 2.7 with ctypes support
        -  `scapy <http://www.secdev.org/projects/scapy/>`_
        -  `libnetfilter\_log.so.1 <http://netfilter.org/projects/libnetfilter_log>`_
        
        Usage
        -----
        
        Two python modules are installed: scapy\_nflog and nflog\_ctypes.
        
        scapy\_nflog has NFLOGListenSocket class (implementing SuperSocket),
        which can be installed as default L2 listener like this:
        
        ::
        
            >>> import scapy_nflog
            >>> scapy_nflog.install_nflog_listener()
        
        install\_nflog\_listener above is a one-line function, doing
        ``conf.L2listen = NFLOGListenSocket``, so if you're building custom
        module on scapy, NFLOGListenSocket class can just be passed directly to
        scapy internals a listening socket without setting it to be default one.
        
        IDs of NFLOG queues to grab packets from can be controlled via passing
        optional "queues" keyword on instance init (int or a list of ints) or by
        overriding default "queues" class attribute in a subclass and setting
        that one as listener class instead.
        
        Note that NFLOG actually returns L3 packets, so despite the listener
        being installed as L2 above, it will always return instances of IP
        class, not Ether or such.
        
        Linux NFLOG
        ~~~~~~~~~~~
        
        NFLOG is a Linux `netfilter <http://www.netfilter.org/>`_ subsystem
        target, somewhat like old and simple LOG target, which dumped info for
        each packet to kmsg, but using special netlink queues to export
        netfilter-matched (think
        `iptables <http://www.netfilter.org/projects/iptables/index.html>`_
        rules) packets to userspace.
        
        To export all packets received via nflog:
        
        ::
        
            iptables -t raw -I PREROUTING -j NFLOG
            iptables -t raw -I OUTPUT -j NFLOG
        
        Of course, any arbitrary filters can be added there, to dump only
        packets matching specific protocol, port or whatever arbitrary netfilter
        matcher - see `iptables
        manpage <http://ipset.netfilter.org/iptables.man.html>`_ (or
        iptables-extensions(8)) for the list/info on the ones shipped with
        mainline linux.
        
        Note that it's safe to add the above catch-all rules, as with no
        listeners (nothing queries nflog for these packets), they'll just be
        discarded regardless of these rules and won't be wasting ram, cpu or
        anything like that.
        
        Userspace readers (like this module) can subscribe to receive these
        packets, setting how many bytes of these will be buffered in-kernel for
        later recv() calls (optional "nlbufsiz" keyword to nflog\_generator),
        the rest will be just dropped (producing python logging warning by
        default, unless ``handle_overflows=False`` is passed) until userspace
        catches up.
        
        NFLOG itself is configurable with parameters like --nflog-group and
        --nflog-range (see iptables-extensions(8)), allowing to have multiple
        nflog queues for different apps and not passing lots of useless L7 data
        around.
        
        NFLOG performance - especially coupled with in-kernel noise filtering
        and packet truncation - seem to be more efficient than simpler
        approaches like using AF\_PACKET/SOCK\_RAW sockets, but it's highly
        unlikely to be any kind of a bottleneck with scapy sitting on top of it
        anyway.
        
        One interesting advantage over libpcap is the ability to capture
        tunneled packets after decryption (traffic coming from ipsec, pptp,
        openvpn, ssh, etc) or transformation (stripping of ipip wrapping,
        netlink re-injection and such) here.
        
        nflog\_ctypes
        ~~~~~~~~~~~~~
        
        scapy\_nflog module is based on nflog\_ctypes module (originally written
        for
        `nflog-zmq-pcap-pipe <https://github.com/mk-fg/nflog-zmq-pcap-pipe>`_
        project), which can be used from any python code (scapy shell included):
        
        ::
        
            from nflog_ctypes import nflog_generator
        
            # without extra_attrs just packet payload (possibly truncated) is returned
            nflog = nflog_generator(0, extra_attrs=['len', 'ts'], nlbufsiz=2*2**20) # queue id
            fd = next(nflog) # netlink fd to do select/poll on, if necessary
        
            # pkt_len is the *real* length, before nflog-truncation (if any)
            # pkt_ts is the packet timestamp, as reported by kernel/lib
            pkt, pkt_len, pkt_ts = next(nflog)
            print('Got packet, len: {}, ts: {}'.format(pkt_len, pkt_ts))
        
            for pkt, pkt_len, pkt_ts in nflog: # do stuff with each captured packet
        
        Module uses
        `libnetfilter\_log <http://www.netfilter.org/projects/libnetfilter_log/index.html>`_
        via cPython ctypes ffi.
        
        nflog\_generator has the keywords to control parameters of netlink
        socket that are passed to libnetfilter\_log, see `libnetfilter\_log
        documentation <http://www.netfilter.org/projects/libnetfilter_log/doxygen/group__Log.html>`_
        for more verbose description of these. Not everything from
        libnetfilter\_log is supported, patches welcome.
        
        I would have used C
        `nflog-bindings <https://www.wzdftpd.net/redmine/projects/nflog-bindings>`_
        module, but it leaks RAM like titanic, uses printf() in the code (and
        for each. captured packet, no less), plus still incomplete and buggy.
        
Keywords: nflog,scapy,plugin,driver,traffic,analysis,analyze,capture,dump,network,linux,security,sniffer,spoof,netfilter,iptables,xtables,filter,filtering,firewall,audit
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Telecommunications Industry
Classifier: License :: OSI Approved
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 2 :: Only
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: System :: Operating System Kernels :: Linux
