Package: nflogr
What is Nflogr?Nflogr is a Python extension module that allows access to messages and packet
data logged via iptables/netfilter usingNFLOGon Linux. There are other
existing libraries that provide similar functionality. Nflogr offers the
following improvements:Works with Python threads.Provides a simple object oriented API.Getting NflogrNflogr is available fromhttps://github.com/ryancdotorg/python-nflogr.SetupDisclaimerThis is my first Python extension module, and I consider it ‘beta quality’. It
may crash, contain exploitable security vulnerabilities, be unpythonic, etc.
There aren’t currently any tests, though infrastructure to add them is in
place.Code review and/or patches to fix bugs would be appreciated.Quick Startgit clone https://github.com/ryancdotorg/python-nflogr
cd python-nflogr
python3 setup.py installRequirementsPython 3.6 or later, including header files.The Pythondistutilsandsetuptoolspackages.A C++ compiler. GCC G++ 8.3.0 is known to work.Development versions of libnfnetlink and libnetfilter_log.On Debian/Ubuntu, try:sudo apt install libnetfilter-log-dev build-essential
sudo apt install python3-{distutils,setuptools,dev}UsageOpen an NFLOG group handlerNOTE: Either root orcap_net_adminis required to open the handler.importnflogrgroup_id=123nflog=nflogr.open(group_id)"""your code here"""nflog.close()orimportnflogrgroup_id=123withnflogasnflogr.open(group_id):"""your code here"""Optional keyword arguments for theopen()functionTheopen()function accepts the following optional keyword arguments:timeout (float, default 0)The maximum time that nflog waits until it pushes the log buffer to userspace
if no new logged packets have occurred.Specified in seconds with 0.01 granularity.qthresh (int, default 1)The maximum number of log entries in the buffer until it is pushed to userspace.rcvbuf (int, default 0)The maximum size (in bytes) of the receiving socket buffer. Large values may be
needed to avoid dropping packets.If set to 0, the system default value will be used.nlbuf (int, default 0)The size (in bytes) of the buffer that is used to stack log messages in nflog.If set to 0, the kernel default (one memory page) will be used.NOTE: Changing this from the default is strongly discouraged.enobufs (int, default nflogr.ENOBUFS_RAISE)Control what happens when recv() fails with ENOBUFS due to dropped packets.nflogr.ENOBUFS_RAISE - raise an nflogr.NflogDroppedError exceptionnflogr.ENOBUFS_HANDLE - increment the enbufs counternflogr.ENOBUFS_DISABLE - disable ENOBUFS errors entirelycopymode (int, default nflogr.COPY_PACKET)The amount of data to be copied to userspace for each packet.nflogr.COPY_NONE - do not copy any datanflogr.COPY_META - copy only packet metadatanflogr.COPY_PACKET - copy entire packetNflog objectsNflog objects encapsulate NFLOG group handlers. They have the following
attributes:NameDescriptionrcvbufMaximum size of the socket receive buffer in bytes. (int)dropsNumber of times ENOBUFS has been received on the socket (int, can only be set to zero)queuedNumber of messages received from the socket but not yet read by the application (int, read-only)Functions available on the handlernflog.queue(wait=True)Reads messages from the socket, and queues them internally. Returns the number
of messages queued (which may be zero), or -1 on error. If wait is set to False,
the call will be non-blocking.nflog.next(wait=True)Returns the next message (NflogData). If wait is set to False, the call will be
non-blocking, and None will be returned if no messages are available.nflog.loop(fn, count=-1)Passes messages (NflogData) to a callback function. The optional second
argument specifies a maximum number of messages to handle before returning,
with -1 meaning 'infinite'. ReturnsNone.nflog.close()Closes the handler.NOTE: Nflogr buffers packets, so reads continue to succeed.nflog.getfd()Returns the numeric file descriptor (int), orNoneif not applicable.nflog.getgroup()Returns the numeric log group id (int), orNoneif not applicable.NflogData objectsMessage handling functions provide NflogData objects, which have the following
read-only attributes:NameDescriptionprotoLayer 3 protocol (EtherType) of the packet (int)hwtypeHardware type identifier (int, seeif_arp.h)nfmarkNetfilter packet mark value (int)timestampTimestamp of when the packet was logged (float)timestamp_usTimestamp of when the packet was logged in microseconds (int)indevName of the logical interface the packet was received on (str), orNoneif not known/applicablephysindevName of the physical interface the packet was received on (str), orNoneif not known/applicableoutdevName of the logical interface the packet will be sent on (str), orNoneif not known/applicablephysoutdevName of the physical interface the packet will be sent on (str), orNoneif not known/applicableuidNumeric user id of the user that generated the packet (int), orNoneif not known/applicablegidNumeric group id of the user that generated the packet (int), orNoneif not known/applicablehwaddrLayer 2 source address (bytes)hwhdrLayer 2 packet header (bytes)payloadLayer 3 packet data (bytes)prefixString prefix specified in iptables’ NFLOG target (str)NflogData is iterable, sodict(data)will work as expected.Process messages from a handlerfordatainnflog:"""your code here"""orwhileTrue:data=nflog.next()"""your code here"""Process messages from a handler using a callback functiondefnflog_callback(data):"""your code here"""nflog.loop(nflog_callback)LicenseThis software is MIT licensed. See the LICENSE file for details.