Metadata-Version: 2.4
Name: signature-extraction
Version: 0.9.0
Summary: Extract signatures from IoT event network traffic
Author-email: François De Keersmaeker <francois.dekeersmaeker@uclouvain.be>
Maintainer-email: François De Keersmaeker <francois.dekeersmaeker@uclouvain.be>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://forge.uclouvain.be/smart-home-network-security/signature-extraction
Project-URL: Source, https://forge.uclouvain.be/smart-home-network-security/signature-extraction
Keywords: network,traffic,fingerprinting,firewall
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography==43.0.1
Requires-Dist: scapy==2.6.0
Requires-Dist: pandas==2.2.3
Requires-Dist: dns-unbound-cache-reader
Requires-Dist: profile-translator-blocklist
Dynamic: license-file

# Extraction of network signatures of IoT events

![GitHub License](https://img.shields.io/github/license/smart-home-network-security/signature-extraction)
![GitHub language count](https://img.shields.io/github/languages/count/smart-home-network-security/signature-extraction)


`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.
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) flow**: time-ordered sequence of network packets having the same network 5-tuple.
- **(Packet/Flow) fingerprint**: set of relevant packet features which identify a packet / flow. 
- **Network pattern**: sequence of network flows 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 packet fingerprints.
- [`flow_grouping`](signature_extraction/flow_grouping.py): group packets per flow and extract flow fingerprints.
- [`event_signature_extraction`](signature_extraction/event_signature_extraction.py): extract event signatures from sets 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.
