# Extraction of network signatures of IoT events
`signature-extraction` is a Python package which extracts network pattern signatures,
i.e. a sequence of network flows, from network traffic related to IoT (smart home) events.
## Glossary
- **(User) event**: interaction with an IoT device that triggers a change in its state, and the associated network traffic.
- **(Network) packet**: unit of data transmitted over a network.
- **(Network) 5-tuple**: set of five values that uniquely identify a network flow: source IP address, source port, destination IP address, destination port, and layer 4 protocol.
- **(Network) flow**: time-ordered sequence of network packets having the same network 5-tuple.
- **Flow Fingerprint**: set of relevant packet features which identify a packet / flow. Includes part of, or all, the packet's 5-tuple, as well as other protocol-dependent features, e.g.:
- HTTP: method, URI
- DNS: query name, query type
- DHCP: message type
- CoAP: message type, method, URI
- **Network pattern**: sequence of flows / flow fingerprints that repeatedly occurs together, potentially indicating a specific user event.
- **(Event) signature**: network pattern that uniquely identifies a user event.
## Features
This package is split into three main modules,
each responsible for part of the pipeline:
- [`pkt_extraction`](signature_extraction/pkt_extraction.py): read PCAP files and extract packets.
- [`flow_grouping`](signature_extraction/flow_grouping.py): group packets per flow and generate the flow fingerprint.
- [`event_signature_extraction`](signature_extraction/event_signature_extraction.py): extract an event signature from a set of flow fingerprints.
### Translation to firewall
Additionally, flow fingerprints can be converted to configuration scripts for [@fdekeers](https://github.com/fdekeers)'s [smart-home-firewall](https://github.com/smart-home-network-security/smart-home-firewall), or to a YAML profile exhaustively describing such configuration.
## Installation
### From PyPI
```bash
pip install signature-extraction
```
[PyPI project page](https://pypi.org/project/signature-extraction)
### From local source
Clone the repository and install the dependencies using `pip`.
```bash
git clone https://github.com/smart-home-network-security/signature-extraction.git
cd signature-extraction
pip install -r requirements.txt
pip install .
```
## License
This project is licensed under the GPL-3.0 License -- see the [LICENSE](LICENSE) file for details.
## Acknowledgements
This work is part of the [Smart Home Network Security](https://github.com/smart-home-network-security) research project made by [@fdekeers](https://github.com/fdekeers) and UCLouvain.
It was partially authored by [@remivanboxem](https://github.com/remivanboxem) during his internship at UCLouvain.
Raw data
{
"_id": null,
"home_page": null,
"name": "signature-extraction",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Fran\u00e7ois De Keersmaeker <francois.dekeersmaeker+github@proton.me>",
"keywords": "network, traffic, fingerprinting, firewall",
"author": null,
"author_email": "Fran\u00e7ois De Keersmaeker <francois.dekeersmaeker+github@proton.me>",
"download_url": "https://files.pythonhosted.org/packages/da/61/05947617a23b6f06dfc9beba2d13842966bf328ba72d20357e114617dbb4/signature_extraction-1.0.9.tar.gz",
"platform": null,
"description": "# Extraction of network signatures of IoT events\n\n\n\n\n\n`signature-extraction` is a Python package which extracts network pattern signatures,\ni.e. a sequence of network flows, from network traffic related to IoT (smart home) events.\n\n\n## Glossary\n\n- **(User) event**: interaction with an IoT device that triggers a change in its state, and the associated network traffic.\n- **(Network) packet**: unit of data transmitted over a network.\n- **(Network) 5-tuple**: set of five values that uniquely identify a network flow: source IP address, source port, destination IP address, destination port, and layer 4 protocol.\n- **(Network) flow**: time-ordered sequence of network packets having the same network 5-tuple.\n- **Flow Fingerprint**: set of relevant packet features which identify a packet / flow. Includes part of, or all, the packet's 5-tuple, as well as other protocol-dependent features, e.g.:\n - HTTP: method, URI\n - DNS: query name, query type\n - DHCP: message type\n - CoAP: message type, method, URI \n- **Network pattern**: sequence of flows / flow fingerprints that repeatedly occurs together, potentially indicating a specific user event.\n- **(Event) signature**: network pattern that uniquely identifies a user event.\n\n\n## Features\n\n\nThis package is split into three main modules,\neach responsible for part of the pipeline:\n- [`pkt_extraction`](signature_extraction/pkt_extraction.py): read PCAP files and extract packets.\n- [`flow_grouping`](signature_extraction/flow_grouping.py): group packets per flow and generate the flow fingerprint.\n- [`event_signature_extraction`](signature_extraction/event_signature_extraction.py): extract an event signature from a set of flow fingerprints.\n\n### Translation to firewall\n\nAdditionally, flow fingerprints can be converted to configuration scripts for [@fdekeers](https://github.com/fdekeers)'s [smart-home-firewall](https://github.com/smart-home-network-security/smart-home-firewall), or to a YAML profile exhaustively describing such configuration.\n\n\n## Installation\n\n### From PyPI\n\n```bash\npip install signature-extraction\n```\n\n[PyPI project page](https://pypi.org/project/signature-extraction)\n\n### From local source\n\nClone the repository and install the dependencies using `pip`.\n\n```bash\ngit clone https://github.com/smart-home-network-security/signature-extraction.git\ncd signature-extraction\npip install -r requirements.txt\npip install .\n```\n\n## License\n\nThis project is licensed under the GPL-3.0 License -- see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgements\n\nThis work is part of the [Smart Home Network Security](https://github.com/smart-home-network-security) research project made by [@fdekeers](https://github.com/fdekeers) and UCLouvain.\n\nIt was partially authored by [@remivanboxem](https://github.com/remivanboxem) during his internship at UCLouvain.\n",
"bugtrack_url": null,
"license": null,
"summary": "Extract signatures from IoT event network traffic",
"version": "1.0.9",
"project_urls": {
"Homepage": "https://github.com/smart-home-network-security/signature-extraction",
"Source": "https://github.com/smart-home-network-security/signature-extraction"
},
"split_keywords": [
"network",
" traffic",
" fingerprinting",
" firewall"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c18b4ded4dd43836c9af6da348f3aa43f1b9a0ddcdd7593ebf937b1a7606f031",
"md5": "32e40d09684a9b7e4a5b1c4e2f801fe6",
"sha256": "2b1b8756ec027e3766900732cb97d93d641cb9b81afb68c9aa870b49c6cbc64a"
},
"downloads": -1,
"filename": "signature_extraction-1.0.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "32e40d09684a9b7e4a5b1c4e2f801fe6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 45400,
"upload_time": "2025-10-10T14:28:37",
"upload_time_iso_8601": "2025-10-10T14:28:37.770635Z",
"url": "https://files.pythonhosted.org/packages/c1/8b/4ded4dd43836c9af6da348f3aa43f1b9a0ddcdd7593ebf937b1a7606f031/signature_extraction-1.0.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "da6105947617a23b6f06dfc9beba2d13842966bf328ba72d20357e114617dbb4",
"md5": "2728de86092b1dd2015dee199b4311e7",
"sha256": "3924c196421faa1d847375fcc1f219cee6481d404d0883e594641dba402861a1"
},
"downloads": -1,
"filename": "signature_extraction-1.0.9.tar.gz",
"has_sig": false,
"md5_digest": "2728de86092b1dd2015dee199b4311e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 39368,
"upload_time": "2025-10-10T14:28:39",
"upload_time_iso_8601": "2025-10-10T14:28:39.235381Z",
"url": "https://files.pythonhosted.org/packages/da/61/05947617a23b6f06dfc9beba2d13842966bf328ba72d20357e114617dbb4/signature_extraction-1.0.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-10 14:28:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "smart-home-network-security",
"github_project": "signature-extraction",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "cryptography",
"specs": [
[
"==",
"45.0.6"
]
]
},
{
"name": "scapy",
"specs": [
[
"==",
"2.6.1"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.3.2"
]
]
},
{
"name": "Levenshtein",
"specs": [
[
"==",
"0.27.1"
]
]
},
{
"name": "dns-unbound-cache-reader",
"specs": []
},
{
"name": "profile-translator-blocklist",
"specs": []
}
],
"lcname": "signature-extraction"
}
JSON
