{"id":13775010,"url":"https://github.com/mk-fg/scapy-nflog-capture","last_synced_at":"2025-05-11T07:31:39.165Z","repository":{"id":7935166,"uuid":"9325466","full_name":"mk-fg/scapy-nflog-capture","owner":"mk-fg","description":"Driver for scapy to allow capturing packets via Linux NFLOG interface","archived":true,"fork":false,"pushed_at":"2022-11-01T05:15:04.000Z","size":19,"stargazers_count":8,"open_issues_count":0,"forks_count":6,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-13T13:11:45.531Z","etag":null,"topics":["cffi","linux","module","netfilter","networking","nflog","python","scapy","security","sniffer"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"wtfpl","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mk-fg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-09T16:08:29.000Z","updated_at":"2024-04-21T15:18:39.000Z","dependencies_parsed_at":"2022-09-26T22:10:15.487Z","dependency_job_id":null,"html_url":"https://github.com/mk-fg/scapy-nflog-capture","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fscapy-nflog-capture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fscapy-nflog-capture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fscapy-nflog-capture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mk-fg%2Fscapy-nflog-capture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mk-fg","download_url":"https://codeload.github.com/mk-fg/scapy-nflog-capture/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225027326,"owners_count":17409409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cffi","linux","module","netfilter","networking","nflog","python","scapy","security","sniffer"],"created_at":"2024-08-03T17:01:32.743Z","updated_at":"2024-11-17T10:30:22.768Z","avatar_url":"https://github.com/mk-fg.png","language":"Python","funding_links":[],"categories":["\u003ca id=\"01f99d208e245eb44f15f720043b50d4\"\u003e\u003c/a\u003eScapy"],"sub_categories":[],"readme":"scapy-nflog-capture\n--------------------\n\n**Deprecation Warning:**\nI haven't used or looked at this module for a while,\nand it's obviously long-obsolete python2 code, so unless it's for similar legacy/obsolete uses,\nI'd recommend to avoid using this module, or look at one of its more up-to-date forks, if any.\n\nDriver for [scapy network manipulation tool](http://www.secdev.org/projects/scapy/)\nto allow capturing packets via\n[Linux NFLOG interface](http://wiki.wireshark.org/CaptureSetup/NFLOG).\n\n\n\nInstallation\n--------------------\n\nIt's a regular package for Python 2.7 (not 3.X).\n\nUsing [pip](http://pip-installer.org/) is the best way:\n\n\t% pip install scapy-nflog-capture\n\nIf you don't have it, use:\n\n\t% easy_install pip\n\t% pip install scapy-nflog-capture\n\nAlternatively ([see\nalso](http://www.pip-installer.org/en/latest/installing.html)):\n\n\t% curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python\n\t% pip install scapy-nflog-capture\n\nOr, if you absolutely must:\n\n\t% easy_install scapy-nflog-capture\n\nBut, you really shouldn't do that.\n\nCurrent-git version can be installed like this:\n\n\t% pip install 'git+https://github.com/mk-fg/scapy-nflog-capture.git#egg=scapy-nflog-capture'\n\n\n### Requirements\n\n* Python 2.7 with ctypes support\n* [scapy](http://www.secdev.org/projects/scapy/)\n* [CFFI](http://cffi.readthedocs.org) (for libnetfilter_log bindings)\n* [libnetfilter_log](http://netfilter.org/projects/libnetfilter_log)\n\nCFFI uses C compiler to generate bindings, so gcc (or other compiler) should be\navailable if module is being built from source or used from checkout tree.\n\n\n\nUsage\n--------------------\n\nTwo python modules are installed: scapy_nflog and nflog_ctypes.\n\nscapy_nflog has NFLOGListenSocket class (implementing SuperSocket), which can be\ninstalled as default L2 listener like this:\n\n\t\u003e\u003e\u003e import scapy_nflog\n\t\u003e\u003e\u003e scapy_nflog.install_nflog_listener()\n\ninstall_nflog_listener above is a one-line function, doing `conf.L2listen =\nNFLOGListenSocket`, so if you're building custom module on scapy,\nNFLOGListenSocket class can just be passed directly to scapy internals a\nlistening socket without setting it to be default one.\n\nIDs of NFLOG queues to grab packets from can be controlled via passing optional\n\"queues\" keyword on instance init (int or a list of ints) or by overriding\ndefault \"queues\" class attribute in a subclass and setting that one as listener\nclass instead.\n\nNote that NFLOG actually returns L3 packets, so despite the listener being\ninstalled as L2 above, it will always return instances of IP class, not Ether or\nsuch.\n\n\n### Linux NFLOG\n\nNFLOG is a Linux [netfilter](http://www.netfilter.org/) subsystem target,\nsomewhat like old and simple LOG target, which dumped info for each packet to\nkmsg, but using special netlink queues to export netfilter-matched (think\n[iptables](http://www.netfilter.org/projects/iptables/index.html) rules) packets\nto userspace.\n\nTo export all sent/received packets via nflog:\n\n\tiptables -t raw -I PREROUTING -j NFLOG\n\tiptables -t raw -I OUTPUT -j NFLOG\n\nOf course, any arbitrary filters can be added there, to dump only packets\nmatching specific protocol, port or whatever arbitrary netfilter matcher - see\n[iptables manpage](http://ipset.netfilter.org/iptables.man.html) (or\niptables-extensions(8)) for the list/info on the ones shipped with mainline\nlinux.\n\nNote that it's safe to add the above catch-all rules, as with no listeners\n(nothing queries nflog for these packets), they'll just be discarded regardless\nof these rules and won't be wasting much ram, cpu or anything like that.\n\nUserspace readers (like this module) can subscribe to receive these packets,\nsetting how many bytes of these will be buffered in-kernel for later recv()\ncalls (optional \"nlbufsiz\" keyword to nflog_generator), the rest will be just\ndropped (producing python logging warning by default, unless\n`handle_overflows=False` is passed) until userspace catches up.\n\nNFLOG itself is configurable with parameters like --nflog-group and\n--nflog-range (see iptables-extensions(8)), allowing to have multiple nflog\nqueues for different apps and not passing lots of useless L7 data around.\n\nPerformance - especially coupled with in-kernel noise filtering and packet\ntruncation - seem to be more efficient than simpler approaches like using\nAF_PACKET/SOCK_RAW sockets, but it's highly unlikely to be any kind of a\nbottleneck with scapy sitting on top of it anyway.\n\nOne interesting advantage over libpcap is the ability to capture tunneled\npackets after decryption (traffic coming from ipsec, pptp, openvpn, ssh, etc) or\ntransformation (stripping of ipip wrapping, netlink re-injection and such) here.\n\n\n### nflog_cffi\n\nscapy_nflog is based on nflog_cffi module, which can be used from any python\ncode (scapy shell included):\n\n```python\nfrom nflog_cffi import NFLOG\n\n# without extra_attrs just packet payload (possibly truncated) is returned\nnflog = NFLOG().generator(0, extra_attrs=['len', 'ts'], nlbufsiz=2*2**20)\nfd = next(nflog) # netlink fd to do select/poll on, if necessary\n\n# pkt_len is the *real* length, before nflog-truncation (if any)\n# pkt_ts is the packet timestamp, as reported by kernel/lib\npkt, pkt_len, pkt_ts = next(nflog)\nprint('Got packet, len: {}, ts: {}'.format(pkt_len, pkt_ts))\n\nfor pkt, pkt_len, pkt_ts in nflog: # do stuff with each captured packet\n```\n\nModule uses libnetfilter_log via CFFI.\n\nNFLOG generator has the keywords to control parameters of netlink socket that\nare passed to libnetfilter_log, see [libnetfilter_log\ndocumentation](http://www.netfilter.org/projects/libnetfilter_log/doxygen/group__Log.html)\nfor more verbose description of these.\n\nNot all [libnetfilter_log-exposed\nattributes](http://www.netfilter.org/projects/libnetfilter_log/doxygen/group__Parsing.html)\nare exposed through bindings.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Fscapy-nflog-capture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmk-fg%2Fscapy-nflog-capture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmk-fg%2Fscapy-nflog-capture/lists"}