## What is Nflogr?
Nflogr is a Python extension module that allows access to messages and packet
data logged via iptables/netfilter using `NFLOG` on 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 Nflogr
Nflogr is available from
[https://github.com/ryancdotorg/python-nflogr](https://github.com/ryancdotorg/python-nflogr).
## Setup
### Disclaimer
This 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 Start
```
git clone https://github.com/ryancdotorg/python-nflogr
cd python-nflogr
python3 setup.py install
```
### Requirements
* Python 3.6 or later, including header files.
* The Python `distutils` and `setuptools` packages.
* 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}
```
## Usage
### Open an NFLOG group handler
NOTE: Either root or `cap_net_admin` is required to open the handler.
```python
import nflogr
group_id = 123
nflog = nflogr.open(group_id)
"""
your code here
"""
nflog.close()
```
or
```python
import nflogr
group_id = 123
with nflog as nflogr.open(group_id):
"""
your code here
"""
```
### Optional keyword arguments for the `open()` function
The `open()` 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 exception
* nflogr.ENOBUFS_HANDLE - increment the enbufs counter
* nflogr.ENOBUFS_DISABLE - disable ENOBUFS errors entirely
##### copymode (int, default nflogr.COPY_PACKET)
The amount of data to be copied to userspace for each packet.
* nflogr.COPY_NONE - do not copy any data
* nflogr.COPY_META - copy only packet metadata
* nflogr.COPY_PACKET - copy entire packet
### Nflog objects
Nflog objects encapsulate NFLOG group handlers. They have the following
attributes:
| Name | Description |
| --- | --- |
| rcvbuf | Maximum size of the socket receive buffer in bytes. (int) |
| drops | Number of times ENOBUFS has been received on the socket (int, can only be set to zero) |
| queued | Number of messages received from the socket but not yet read by the application (int, read-only) |
### Functions available on the handler
##### `nflog.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'. Returns `None`.
##### `nflog.close()`
Closes the handler.
NOTE: Nflogr buffers packets, so reads continue to succeed.
##### `nflog.getfd()`
Returns the numeric file descriptor (int), or `None` if not applicable.
##### `nflog.getgroup()`
Returns the numeric log group id (int), or `None` if not applicable.
### NflogData objects
Message handling functions provide NflogData objects, which have the following
read-only attributes:
| Name | Description |
| --- | --- |
| proto | Layer 3 protocol (EtherType) of the packet (int) |
| hwtype | Hardware type identifier (int, see `if_arp.h`) |
| nfmark | Netfilter packet mark value (int) |
| timestamp | Timestamp of when the packet was logged (float) |
| timestamp_us | Timestamp of when the packet was logged in microseconds (int) |
| indev | Name of the logical interface the packet was received on (str), or `None` if not known/applicable |
| physindev | Name of the physical interface the packet was received on (str), or `None` if not known/applicable |
| outdev | Name of the logical interface the packet will be sent on (str), or `None` if not known/applicable |
| physoutdev | Name of the physical interface the packet will be sent on (str), or `None` if not known/applicable |
| uid | Numeric user id of the user that generated the packet (int), or `None` if not known/applicable |
| gid | Numeric group id of the user that generated the packet (int), or `None` if not known/applicable |
| hwaddr | Layer 2 source address (bytes) |
| hwhdr | Layer 2 packet header (bytes) |
| payload | Layer 3 packet data (bytes) |
| prefix | String prefix specified in iptables’ NFLOG target (str) |
NflogData is iterable, so `dict(data)` will work as expected.
### Process messages from a handler
```python
for data in nflog:
"""
your code here
"""
```
or
```python
while True:
data = nflog.next()
"""
your code here
"""
```
### Process messages from a handler using a callback function
```python
def nflog_callback(data):
"""
your code here
"""
nflog.loop(nflog_callback)
```
## License ##
This software is MIT licensed. See the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/ryancdotorg/python-nflogr",
"name": "nflogr",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "nflog linux",
"author": "Ryan Castellucci",
"author_email": "pypi-b51f@ryanc.org",
"download_url": "https://files.pythonhosted.org/packages/87/0b/a4045ba92dd199a2900e2afe20c30eb841a1645c07b85750f43d9114f41d/nflogr-0.2.12.tar.gz",
"platform": "linux",
"description": "## What is Nflogr?\n\nNflogr is a Python extension module that allows access to messages and packet\ndata logged via iptables/netfilter using `NFLOG` on Linux. There are other\nexisting libraries that provide similar functionality. Nflogr offers the\nfollowing improvements:\n\n* Works with Python threads.\n* Provides a simple object oriented API.\n\n## Getting Nflogr\n\nNflogr is available from\n[https://github.com/ryancdotorg/python-nflogr](https://github.com/ryancdotorg/python-nflogr).\n\n## Setup\n\n### Disclaimer\n\nThis is my first Python extension module, and I consider it \u2018beta quality\u2019. It\nmay crash, contain exploitable security vulnerabilities, be unpythonic, etc.\nThere aren\u2019t currently any tests, though infrastructure to add them is in\nplace.\n\nCode review and/or patches to fix bugs would be appreciated.\n\n### Quick Start\n\n```\ngit clone https://github.com/ryancdotorg/python-nflogr\ncd python-nflogr\npython3 setup.py install\n```\n\n### Requirements\n\n * Python 3.6 or later, including header files.\n * The Python `distutils` and `setuptools` packages.\n * A C++ compiler. GCC G++ 8.3.0 is known to work.\n * Development versions of libnfnetlink and libnetfilter_log.\n\nOn Debian/Ubuntu, try:\n```\nsudo apt install libnetfilter-log-dev build-essential\nsudo apt install python3-{distutils,setuptools,dev}\n```\n\n## Usage\n\n### Open an NFLOG group handler\n\nNOTE: Either root or `cap_net_admin` is required to open the handler.\n\n```python\nimport nflogr\n\ngroup_id = 123\nnflog = nflogr.open(group_id)\n\"\"\"\nyour code here\n\"\"\"\nnflog.close()\n```\n\nor\n\n```python\nimport nflogr\n\ngroup_id = 123\nwith nflog as nflogr.open(group_id):\n \"\"\"\n your code here\n \"\"\"\n```\n\n### Optional keyword arguments for the `open()` function\n\nThe `open()` function accepts the following optional keyword arguments:\n\n##### timeout (float, default 0)\n\nThe maximum time that nflog waits until it pushes the log buffer to userspace\nif no new logged packets have occurred.\n\nSpecified in seconds with 0.01 granularity.\n\n##### qthresh (int, default 1)\n\nThe maximum number of log entries in the buffer until it is pushed to userspace.\n\n##### rcvbuf (int, default 0)\n\nThe maximum size (in bytes) of the receiving socket buffer. Large values may be\nneeded to avoid dropping packets.\n\nIf set to 0, the system default value will be used.\n\n##### nlbuf (int, default 0)\n\nThe size (in bytes) of the buffer that is used to stack log messages in nflog.\n\nIf set to 0, the kernel default (one memory page) will be used.\n\nNOTE: Changing this from the default is strongly discouraged.\n\n##### enobufs (int, default nflogr.ENOBUFS_RAISE)\n\nControl what happens when recv() fails with ENOBUFS due to dropped packets.\n\n* nflogr.ENOBUFS_RAISE - raise an nflogr.NflogDroppedError exception\n* nflogr.ENOBUFS_HANDLE - increment the enbufs counter\n* nflogr.ENOBUFS_DISABLE - disable ENOBUFS errors entirely\n\n##### copymode (int, default nflogr.COPY_PACKET)\n\nThe amount of data to be copied to userspace for each packet.\n\n* nflogr.COPY_NONE - do not copy any data\n* nflogr.COPY_META - copy only packet metadata\n* nflogr.COPY_PACKET - copy entire packet\n\n### Nflog objects\n\nNflog objects encapsulate NFLOG group handlers. They have the following\nattributes:\n\n| Name | Description |\n| --- | --- |\n| rcvbuf | Maximum size of the socket receive buffer in bytes. (int) |\n| drops | Number of times ENOBUFS has been received on the socket (int, can only be set to zero) |\n| queued | Number of messages received from the socket but not yet read by the application (int, read-only) |\n\n### Functions available on the handler\n\n##### `nflog.queue(wait=True)`\n\nReads messages from the socket, and queues them internally. Returns the number\nof messages queued (which may be zero), or -1 on error. If wait is set to False,\nthe call will be non-blocking.\n\n##### `nflog.next(wait=True)`\n\nReturns the next message (NflogData). If wait is set to False, the call will be\nnon-blocking, and None will be returned if no messages are available.\n\n##### `nflog.loop(fn, count=-1)`\n\nPasses messages (NflogData) to a callback function. The optional second\nargument specifies a maximum number of messages to handle before returning,\nwith -1 meaning 'infinite'. Returns `None`.\n\n##### `nflog.close()`\n\nCloses the handler.\n\nNOTE: Nflogr buffers packets, so reads continue to succeed.\n\n##### `nflog.getfd()`\n\nReturns the numeric file descriptor (int), or `None` if not applicable.\n\n##### `nflog.getgroup()`\n\nReturns the numeric log group id (int), or `None` if not applicable.\n\n### NflogData objects\n\nMessage handling functions provide NflogData objects, which have the following\nread-only attributes:\n\n| Name | Description |\n| --- | --- |\n| proto | Layer 3 protocol (EtherType) of the packet (int) |\n| hwtype | Hardware type identifier (int, see `if_arp.h`) |\n| nfmark | Netfilter packet mark value (int) |\n| timestamp | Timestamp of when the packet was logged (float) |\n| timestamp_us | Timestamp of when the packet was logged in microseconds (int) |\n| indev | Name of the logical interface the packet was received on (str), or `None` if not known/applicable |\n| physindev | Name of the physical interface the packet was received on (str), or `None` if not known/applicable |\n| outdev | Name of the logical interface the packet will be sent on (str), or `None` if not known/applicable |\n| physoutdev | Name of the physical interface the packet will be sent on (str), or `None` if not known/applicable |\n| uid | Numeric user id of the user that generated the packet (int), or `None` if not known/applicable |\n| gid | Numeric group id of the user that generated the packet (int), or `None` if not known/applicable |\n| hwaddr | Layer 2 source address (bytes) |\n| hwhdr | Layer 2 packet header (bytes) |\n| payload | Layer 3 packet data (bytes) |\n| prefix | String prefix specified in iptables\u2019 NFLOG target (str) |\n\nNflogData is iterable, so `dict(data)` will work as expected.\n\n\n### Process messages from a handler\n\n```python\nfor data in nflog:\n \"\"\"\n your code here\n \"\"\"\n```\n\nor\n\n```python\nwhile True:\n data = nflog.next()\n \"\"\"\n your code here\n \"\"\"\n```\n\n### Process messages from a handler using a callback function\n\n```python\ndef nflog_callback(data):\n \"\"\"\n your code here\n \"\"\"\n\nnflog.loop(nflog_callback)\n```\n\n## License ##\n\nThis software is MIT licensed. See the LICENSE file for details.",
"bugtrack_url": null,
"license": "MIT",
"summary": "An object-oriented Python interface to read data via NFLOG",
"version": "0.2.12",
"project_urls": {
"Homepage": "https://github.com/ryancdotorg/python-nflogr"
},
"split_keywords": [
"nflog",
"linux"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "870ba4045ba92dd199a2900e2afe20c30eb841a1645c07b85750f43d9114f41d",
"md5": "a13c48c0b100383a888bb7864949db82",
"sha256": "c0556214c48a4b51cf240bdf04d3fd0da6670a5ed8f558ac8bffb500c807c8a8"
},
"downloads": -1,
"filename": "nflogr-0.2.12.tar.gz",
"has_sig": false,
"md5_digest": "a13c48c0b100383a888bb7864949db82",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 28247,
"upload_time": "2023-10-14T14:18:26",
"upload_time_iso_8601": "2023-10-14T14:18:26.649869Z",
"url": "https://files.pythonhosted.org/packages/87/0b/a4045ba92dd199a2900e2afe20c30eb841a1645c07b85750f43d9114f41d/nflogr-0.2.12.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-14 14:18:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ryancdotorg",
"github_project": "python-nflogr",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "nflogr"
}
JSON
