Merge tag 'v0.8.0' into develop

v0.8.0 Breaking Changes: - The PNL view has been removed. Improvements: - Add `pyproject.toml` and `setup.cfg` - Remove argparse from dependencies (@fabaff) - Use f-strings instead of `str.format()` - Add support for Python 3.8, 3.9 and 3.10 - Drop support for Python 3.4, 3.5 and 3.6 - Make some dependencies optional - Refactor code around Scapy's PipeTools - Add metavars to argument parser - Turn `interface` option into argument - Cache the compiled regex in `Config` once computed - Cache the frame filter in `Config` once computed - Cache the MAC address' OUI in `ProbeRequest` - Use the logging package - Add extra dependency group `tests` - Add unit tests for the argument parser - Add `__version__` attribute to package - Use an entry point to generate the CLI tool - Use tox for unit testing Fixes: - Fix interface checking - Close open files before exiting - Use a fake `Config` object in unit tests - Fix linting issues Infrastructure: - Upgrade RTD configuration file to version 2 - Monitor GH Actions dependencies with Dependabot - Use `main` as branch for production releases - Upgrade to GitHub-native Dependabot - Add macOS to build matrix - Switch from Travis CI to GitHub Actions
SkypLabs · Mar 22, 2022 · 0a1d81b · 0a1d81b
2 parents eafaad6 + 1c0bc2a
commit 0a1d81b
Show file tree

Hide file tree

Showing 26 changed files with 227 additions and 66 deletions.
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - complete
+        - docs
+
+sphinx:
+  configuration: docs/conf.py
diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,8 +1,54 @@
+# Changelog
+
+## v0.8.0 - Mar 22, 2022
+
+### Breaking Changes
+
+* The PNL view has been removed.
+
+### Improvements
+
+* Add `pyproject.toml` and `setup.cfg`
+* Remove argparse from dependencies (@fabaff)
+* Use f-strings instead of `str.format()`
+* Add support for Python 3.8, 3.9 and 3.10
+* Drop support for Python 3.4, 3.5 and 3.6
+* Make some dependencies optional
+* Refactor code around Scapy's PipeTools
+* Add metavars to argument parser
+* Turn `interface` option into argument
+* Cache the compiled regex in `Config` once computed
+* Cache the frame filter in `Config` once computed
+* Cache the MAC address' OUI in `ProbeRequest`
+* Use the logging package
+* Add extra dependency group `tests`
+* Add unit tests for the argument parser
+* Add `__version__` attribute to package
+* Use an entry point to generate the CLI tool
+* Use tox for unit testing
+
+### Fixes
+
+* Fix interface checking
+* Close open files before exiting
+* Use a fake `Config` object in unit tests
+* Fix linting issues
+
+### Infrastructure
+
+* Upgrade RTD configuration file to version 2
+* Monitor GH Actions dependencies with Dependabot
+* Use `main` as branch for production releases
+* Upgrade to GitHub-native Dependabot
+* Add macOS to build matrix
+* Switch from Travis CI to GitHub Actions
+
 ## v0.7.2 - Aug 26, 2019
 
 ### Improvements
 
-* Use the new [Scapy built-in asynchronous sniffer](https://scapy.readthedocs.io/en/latest/usage.html#asynchronous-sniffing)
+* Use the new [Scapy built-in asynchronous
+  sniffer](https://scapy.readthedocs.io/en/latest/usage.html#asynchronous-sniffing)
 * Introduce the new `Config` object containing the configuration of ProbeQuest
 
 ### Fixes
@@ -17,8 +63,10 @@
 
 ### Fixes
 
-* Error when trying to decode ESSIDs using invalid UTF-8 characters ([#4](https://github.com/SkypLabs/probequest/issues/4))
-* Arguments not working (-e, -r) ([#17](https://github.com/SkypLabs/probequest/issues/17))
+* Error when trying to decode ESSIDs using invalid UTF-8 characters
+  ([#4](https://github.com/SkypLabs/probequest/issues/4))
+* Arguments not working (-e, -r)
+  ([#17](https://github.com/SkypLabs/probequest/issues/17))
 
 ## v0.7.0 - Oct 8, 2018
 
@@ -34,7 +82,9 @@
 
 ### Fixes
 
-* Test if a packet has a `Dot11ProbeReq` layer before parsing it ([#5](https://github.com/SkypLabs/probequest/issues/5), [#8](https://github.com/SkypLabs/probequest/issues/8))
+* Test if a packet has a `Dot11ProbeReq` layer before parsing it
+  ([#5](https://github.com/SkypLabs/probequest/issues/5),
+  [#8](https://github.com/SkypLabs/probequest/issues/8))
 
 ## v0.6.1 - May 28, 2018
 
@@ -71,7 +121,8 @@ The project has been renamed to ProbeQuest.
 
 ### Fixes
 
-* The sniffer stops after having received the first frame ([#3](https://github.com/SkypLabs/probequest/issues/3))
+* The sniffer stops after having received the first frame
+  ([#3](https://github.com/SkypLabs/probequest/issues/3))
 
 ## v0.5.0 - Feb 7, 2018
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -22,7 +22,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'ProbeQuest'
-copyright = '2020, Paul-Emmanuel Raoul'
+copyright = '2022, Paul-Emmanuel Raoul'
 author = 'Paul-Emmanuel Raoul'
 
 # The full version, including alpha/beta/rc tags

diff --git a/docs/development.rst b/docs/development.rst
@@ -15,19 +15,21 @@ Running the unit tests
 Releasing a new version
 -----------------------
 
-Below are the different steps to do before releasing a new version:
-
-- Run all tests and be sure they all pass
-- Update the `VERSION` variable in `probequest/version.py`
-- Update the requirements in `setup.py` if needed
-- Update the package's metadata (description, classifiers, etc) in `setup.py` if needed
-- Update `README.rst` if needed
-- Update the documentation if needed and make sure it compiles well (`cd ./docs && make html`)
-- Update the copyright year in `docs/conf.py` if needed
-- Add the corresponding release note to `CHANGELOG.md`
+Below are the different steps to follow before releasing a new version:
+
+- Run all tests and be sure they all pass.
+- Update the `version` field in `setup.cfg`.
+- Update the requirements in `setup.cfg` if needed.
+- Update the package's metadata (description, classifiers, etc.) in `setup.cfg`
+  if needed.
+- Update `README.rst` if needed.
+- Update the documentation if needed and make sure it compiles well (`cd ./docs
+  && make html`).
+- Update the copyright year in `docs/conf.py` if needed.
+- Add the corresponding release note to `CHANGELOG.md`.
 
 After having pushed the new release:
 
-- Edit the release note on GitHub
+- Create the corresponding release note on GitHub.
 
 .. _tox: https://tox.readthedocs.io
diff --git a/docs/index.rst b/docs/index.rst
@@ -6,7 +6,8 @@
 Welcome to ProbeQuest's documentation!
 ======================================
 
-ProbeQuest is a toolkit allowing to sniff and display the Wi-Fi probe requests passing nearby your wireless interface.
+ProbeQuest is a toolkit allowing to sniff and display the Wi-Fi probe requests
+passing nearby your wireless interface.
 
 This project has been inspired by `this paper`_.
 

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -2,18 +2,25 @@
 Installation
 ============
 
-Using pip (recommended)
+From PyPI (recommended)
 -----------------------
 
 ::
 
-    sudo pip3 install --upgrade probequest
+    pip3 install --upgrade probequest
 
 From sources
 ------------
 
+ProbeQuest is packaged with `Setuptools`_.
+
+The default Git branch is `develop`. To install the latest stable version, you
+need to clone the `main` branch.
+
 ::
 
-    git clone https://github.com/SkypLabs/probequest.git
+    git clone -b main https://github.com/SkypLabs/probequest.git
     cd probequest
-    sudo pip3 install --upgrade .
+    pip3 install --upgrade .
+
+.. _Setuptools: https://setuptools.pypa.io/
diff --git a/docs/mitigation.rst b/docs/mitigation.rst
@@ -4,17 +4,35 @@ Mitigation
 
 As far as I know, there are two mitigation techniques:
 
-- Don’t use probe requests at all. It is by far the most efficient way not to leak any piece of information. As said earlier, it is not necessary to rely on probe requests to get the list of the nearby access points since they  broadcast their name by themselves.
-- Randomise the source MAC address of each probe request sent. This way, it’s no longer possible for a third party to link probe requests to a specific device based on the Wi-Fi data collected. However, using a Software-Defined Radio to capture RF metadata such as the frequency offset, it would be possible to fingerprint each Wi-Fi packet and so each Wi-Fi device, regardless of their source MAC address (this technique will be implemented in ProbeQuest).
+- Don’t use probe requests at all. It is by far the most efficient way not to
+  leak any piece of information. As said earlier, it is not necessary to rely on
+  probe requests to get the list of the nearby access points since they
+  broadcast their name by themselves.
+- Randomise the source MAC address of each probe request sent. This way, it’s no
+  longer possible for a third party to link probe requests to a specific device
+  based on the Wi-Fi data collected. However, using a Software-Defined Radio to
+  capture RF metadata such as the frequency offset, it would be possible to
+  fingerprint each Wi-Fi packet and so each Wi-Fi device, regardless of their
+  source MAC address (this technique will be implemented in ProbeQuest).
 
-In practice, you can install `Wi-Fi Privacy Police`_ from `F-Droid`_ or the `Play Store`_ to prevent your Android devices from leaking their PNL.
+Android
+-------
+
+Some Android-based operating systems, like `GrapheneOS`_, randomise the source
+MAC address natively. Otherwise, you can install `Wi-Fi Privacy Police`_ from
+`F-Droid`_ or the `Play Store`_ to prevent your Android devices from leaking
+their PNL.
 
 .. image:: _static/img/wifi_privacy_police_main_screen.png
 
 Once installed, the **Privacy protection** option should be switched on.
 
+iOS
+---
+
 On iOS, the source MAC address is randomised since iOS 8.
 
 .. _F-Droid: https://f-droid.org/packages/be.uhasselt.privacypolice/
+.. _GrapheneOS: https://grapheneos.org/
 .. _Play Store: https://play.google.com/store/apps/details?id=be.uhasselt.privacypolice
 .. _Wi-Fi Privacy Police: https://github.com/BramBonne/privacypolice
diff --git a/docs/modules.rst b/docs/modules.rst
@@ -6,4 +6,4 @@ Modules
     :maxdepth: 1
     :glob:
 
-    modules/*
+    modules/**
diff --git a/docs/modules/cli.rst b/docs/modules/cli.rst
@@ -0,0 +1,5 @@
+CLI
+---
+
+.. automodule:: probequest.cli
+    :members:
diff --git a/docs/modules/exceptions.rst b/docs/modules/exceptions.rst
@@ -0,0 +1,5 @@
+Exceptions
+----------
+
+.. automodule:: probequest.exceptions
+    :members:
diff --git a/docs/modules/exporters/csv.rst b/docs/modules/exporters/csv.rst
@@ -0,0 +1,6 @@
+CSV Exporter
+------------
+
+.. automodule:: probequest.exporters.csv
+    :members:
+
diff --git a/docs/modules/fake_packet_sniffer.rst b/docs/modules/fake_packet_sniffer.rst
diff --git a/docs/modules/packet_sniffer.rst b/docs/modules/packet_sniffer.rst
diff --git a/docs/modules/pnl.rst b/docs/modules/pnl.rst
diff --git a/docs/modules/probe_request_filter.rst b/docs/modules/probe_request_filter.rst
@@ -0,0 +1,5 @@
+Probe Request Filter
+--------------------
+
+.. automodule:: probequest.probe_request_filter
+    :members:
diff --git a/docs/modules/probe_request_parser.rst b/docs/modules/probe_request_parser.rst
@@ -0,0 +1,5 @@
+Probe Request Parser
+--------------------
+
+.. automodule:: probequest.probe_request_parser
+    :members:
diff --git a/docs/modules/raw.rst b/docs/modules/raw.rst
diff --git a/docs/modules/sniffers/fake_probe_request_sniffer.rst b/docs/modules/sniffers/fake_probe_request_sniffer.rst
@@ -0,0 +1,5 @@
+Fake Probe Request Sniffer
+--------------------------
+
+.. automodule:: probequest.sniffers.fake_probe_request_sniffer
+    :members:
diff --git a/docs/modules/probe_request_sniffer.rst → ...odules/sniffers/probe_request_sniffer.rst b/docs/modules/probe_request_sniffer.rst → ...odules/sniffers/probe_request_sniffer.rst
@@ -1,5 +1,5 @@
 Probe Request Sniffer
 ---------------------
 
-.. automodule:: probequest.probe_request_sniffer
+.. automodule:: probequest.sniffers.probe_request_sniffer
     :members:
diff --git a/docs/modules/ui/console.rst b/docs/modules/ui/console.rst
@@ -0,0 +1,5 @@
+Console
+-------
+
+.. automodule:: probequest.ui.console
+    :members:
diff --git a/docs/probe_requests.rst b/docs/probe_requests.rst
@@ -2,9 +2,15 @@
 What are Wi-Fi probe requests?
 ==============================
 
-Probe requests are sent by a station to elicit information about access points, in particular to determine if an access point is present or not in the nearby environment. Some devices (mostly smartphones and tablets) use these requests to determine if one of the networks they have previously been connected to is in range, leaking their preferred network list (PNL) and, therefore, your personal information.
+Probe requests are sent by a station to elicit information about access points,
+in particular to determine if an access point is present or not in the nearby
+environment. Some devices (mostly smartphones and tablets) use these requests to
+determine if one of the networks they have previously been connected to is in
+range, leaking their preferred network list (PNL) and, therefore, your personal
+information.
 
-Below is a typical Wi-Fi authentication process between a mobile station (for example, your smartphone) and an access point (AP):
+Below is a typical Wi-Fi authentication process between a mobile station (for
+example, your smartphone) and an access point (AP):
 
 .. seqdiag::
 
@@ -22,8 +28,13 @@ Below is a typical Wi-Fi authentication process between a mobile station (for ex
       "Mobile Station" <-- "Access Point" [label = "Association Response"];
     }
 
-Step 1 is optional (and therefore, step 2) since the access points announce their presence by broadcasting their name (ESSID) using `beacon frames`_. Consequently, it is not necessary to rely on probe requests to get the list of the access points available. It is a design choice that, although it speeds up the discovery process, causes privacy and security issues.
+Step 1 is optional (and therefore, step 2) since the access points announce
+their presence by broadcasting their name (ESSID) using `beacon frames`_.
+Consequently, it is not necessary to rely on probe requests to get the list of
+the access points available. It is a design choice that, although it speeds up
+the discovery process, causes privacy and security issues.
 
-ProbeQuest can be used to leverage this leak of information to conduct diverse social engineering and network attacks.
+ProbeQuest can be used to leverage this leak of information to conduct diverse
+social engineering and network attacks.
 
 .. _beacon frames: https://en.wikipedia.org/wiki/Beacon_frame
diff --git a/docs/security.rst b/docs/security.rst
@@ -5,13 +5,16 @@ Security Policy
 Reporting a Vulnerability
 -------------------------
 
-If you have found a security issue in ProbeQuest, please disclose it responsibly by emailing me at `skyper(at)skyplabs[dot]net`. My PGP public key can be found on my `Keybase profile`_:
+If you have found a security issue in ProbeQuest, please disclose it responsibly
+by emailing me at `skyper(at)skyplabs[dot]net`. My PGP public key can be found
+on my `Keybase profile`_:
 
 .. image:: https://img.shields.io/keybase/pgp/skyplabs.svg
    :target: https://keybase.io/skyplabs/pgp_keys.asc
    :alt: PGP key fingerprint
 
-To facilitate the encryption process, you can use `this online tool`_. You can also use it to verify my signatures.
+To facilitate the encryption process, you can use `this online tool`_. You can
+also use it to verify my signatures.
 
 .. _Keybase profile: https://keybase.io/skyplabs
 .. _this online tool: https://keybase.io/encrypt#skyplabs