Skip to main content

Finds and tracks wifi devices through raw 802.11 monitoring

Project description

trackerjacker
=============

Finds and tracks wifi devices through raw 802.11 monitoring.

Example use-cases
~~~~~~~~~~~~~~~~~

- Map out all the nearby wifi devices (and which devices are asspciated
with which Access Points)
- Track when a particular MAC is seen
- Track when a particular MAC sends some threshold of data in some time
period
- Track when traffic is happening on a particular Access Point
- Find/track all connections on a particular Access Point

How to use
----------

``trackerjacker`` is configured via a few command-line switches and/or a
config file (the path to which can be specified with the ``-c``
command-line switch).

Command-line options
~~~~~~~~~~~~~~~~~~~~

::

-h, --help show this help message and exit
--map Map mode - output map to wifi_map.yaml
--track Track mode
--monitor-mode-on Enables monitor mode on the specified interface and
exit
--monitor-mode-off Disables monitor mode on the specified interface and
exit
--set-channel CHANNEL
Set the specified wireless interface to the specified
channel and exit
--mac-lookup MAC_LOOKUP
Lookup the vendor of the specified MAC address and
exit
--print-default-config
Print boilerplate config file and exit
-i IFACE, --interface IFACE
Network interface to use
-m DEVICES_TO_WATCH, --macs DEVICES_TO_WATCH
MAC(s) to track; comma separated for multiple
-a APS_TO_WATCH, --access-points APS_TO_WATCH
Access point(s) to track - specified by BSSID; comma
separated for multiple
--channels-to-monitor CHANNELS_TO_MONITOR
Channels to monitor; comma separated for multiple
-t THRESHOLD_BYTES, --threshold THRESHOLD_BYTES
Threshold of packets in time window which causes alert
-w THRESHOLD_WINDOW, --time-window THRESHOLD_WINDOW
Time window (in seconds) which alert threshold is
applied to
--alert-command ALERT_COMMAND
Command to execute upon alert
--display-all-packets
If true, displays all packets matching filters
--log-path LOG_PATH Log path; default is stdout
--log-level LOG_LEVEL
Log level; Options: DEBUG, INFO, WARNING, ERROR,
CRITICAL
-c CONFIG, --config CONFIG
Path to config json file; For example config file, use
--print-default-config

Major commands
^^^^^^^^^^^^^^

Note that there are 7 "commands"/"modes" in trackerjacker. The 2 main
modes are ``--map`` and ``--track``, and there 5 other "do something and
quit" commands:

- ``--map``
- ``--track``
- ``--monitor-mode-on``
- ``--monitor-mode-off``
- ``--set-channel``
- ``--mac-lookup``
- ``--print-default-config``

Example: configuring with command-line args
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

python3 trackerjacker.py -m 8a:23:ab:75:8e:2b --alert-command "date >> /tmp/test.txt"

Notes:

- This monitors for the MAC address: ``8a:23:ab:75:8e:2b``
- When detected, the current time is appended to ``/tmp/test.txt``

Example: configuring with config file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

python3 trackerjacker.py -c my_config.json

And here's the example config file called ``my_config.json``:

::

{
"iface": "wlan0mon",
"devices_to_watch": [
{"mac": "5f:cb:53:1c:8a:2c", "name": "Bob's iPhone"},
{"mac": "32:44:1b:d7:a1:5b", "name": "Alice's iPhone"},
{"mac": "f2:43:2b:e5:c3:6d", "name": "Security camera", "threshold": 20000},
"44:61:32:C6:34:8F"],
"aps_to_watch": [{"bssid": "c6:23:ef:33:cc:a2"}],
"threshold_bytes": 1,
"threshold_window": 10,
"channels_to_monitor": [1, 6, 11, 52],
"channel_switch_scheme": "round_robin"
}

A few notes about this:

- ``threshold_bytes`` is the default threshold of bytes which, if seen,
a causes the alert function to be called
- ``threshold_window`` is the time window in which the
``threshold_bytes`` is analyzed.
- ``devices_to_watch`` is a list which can contain either strings
(representing MACs) or dicts (which allow the specification of a
``name`` and ``threshold``)

- ``name`` is simply what a label you want to be printed when this
device is seen.
- ``threshold`` in the "Security camera" is how many bytes must be
seen

- ``channels_to_monitor`` - list of 802.11 wifi channels to monitor.
The list of channels your wifi card supports is printed when
trackerjacker starts up. By default, all supported channels are
monitored.
- ``channel_switch_scheme`` - either ``default``, ``round_robin``, or
``traffic_based``. ``traffic_based`` determines the channels of most
traffic, and probabilistically monitors them more.

Example: Enable/Disable monitor mode on interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Enable monitor mode:

::

python3 trackerjacker.py --monitor-mode-on -i wlan0

Disable monitor mode:

::

python3 trackerjacker.py --monitor-mode-off -i wlan0mon

Note that trackerjacker will automatically enable/disable monitor mode
if necessary. This functionality is just useful if you want to enable
monitor mode on an interface for use with other applications.

Example: Set adapter channel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

::

python3 trackerjacker.py --set-channel 11 -i wlan0

Note that trackerjacker will automatically switch channels as necessary
during normal map/track actions. This option is just useful if you want
to set the channel on an interface for use with other applications.

Project details


Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for trackerjacker, version 0.6.6
Filename, size File type Python version Upload date Hashes
Filename, size trackerjacker-0.6.6.tar.gz (276.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page