{"id":13826589,"url":"https://github.com/geovation/wifispy","last_synced_at":"2025-04-26T22:32:51.627Z","repository":{"id":46933346,"uuid":"56499601","full_name":"Geovation/wifispy","owner":"Geovation","description":"Sniff Wifi traffic, log device addresses.","archived":false,"fork":false,"pushed_at":"2021-09-21T05:35:14.000Z","size":21,"stargazers_count":111,"open_issues_count":6,"forks_count":31,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-04T18:11:24.769Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Geovation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-04-18T10:42:47.000Z","updated_at":"2025-03-09T11:33:15.000Z","dependencies_parsed_at":"2022-09-05T17:01:42.733Z","dependency_job_id":null,"html_url":"https://github.com/Geovation/wifispy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fwifispy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fwifispy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fwifispy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Geovation%2Fwifispy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Geovation","download_url":"https://codeload.github.com/Geovation/wifispy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251063667,"owners_count":21530837,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T09:01:40.783Z","updated_at":"2025-04-26T22:32:46.613Z","avatar_url":"https://github.com/Geovation.png","language":"Python","funding_links":[],"categories":["\u003ca id=\"7bf0f5839fb2827fdc1b93ae6ac7f53d\"\u003e\u003c/a\u003e工具"],"sub_categories":["\u003ca id=\"32739127f0c38d61b14448c66a797098\"\u003e\u003c/a\u003e嗅探\u0026\u0026Sniff"],"readme":"Wifi Spy\n========\n\nSniff Wifi traffic, log device addresses.\n\nUses [Pcapy](https://github.com/CoreSecurity/pcapy) to capture packets. It's probably the best mantained out of [many](https://pypi.python.org/pypi?%3Aaction=search\u0026term=pcap) libraries wrapping the somewhat definitive packet capture library [libpcap](https://github.com/the-tcpdump-group/libpcap).\n\nUses [Dpkt](https://github.com/kbandla/dpkt) to interrogate and extract data from each packet. It's one of two popular packet manipulation libraries, the other being [Impacket](https://github.com/CoreSecurity/impacket), which I had less luck with.\n\nThe other notable library in this space is [Scapy](https://github.com/secdev/scapy/).\n\n\nRunning\n-------\n\nThere's two different sets of configuration for Mac OS and Linux in `wifispy.py`, you'll have to comment out the appropriate set before running. I've only been able to make it work on Linux so far.\n\n    $ pip install -r requirements.txt\n    $ sudo python wifispy.py\n\nNeeds to be run with `sudo` because we're doing system-level stuff. For the same reason `pcapy` won't work within a virtual environment.\n\n\nApproach\n--------\n\n1. Put card into [monitor mode](https://en.wikipedia.org/wiki/Monitor_mode). This means it will passively sniff all wireless traffic it sees. It differs from the somewhat similar [promiscuous mode](https://en.wikipedia.org/wiki/Promiscuous_mode), which (as I understand it) gives you more information, but requires you to be connected to a network. Not all cards support monitor mode. This is done via a terminal command, as it doesn't seem possible through Python.\n\n2. Rotate channels. There are 13 channels in the 2.4GHz band, which are the most commonly used. There are also a number of others in the 5GHz range, but not all cards support these channels. Since cards can only be tuned to one channel at a time, we need to randomly switch channels in the background to ensure we're picking up devices using any channel. This is also done via a terminal command. Note that the nature of this process means we will miss some (many) packets, but for our purposes that shouldn't be a problem.\n\n3. Sniff packets using Pcapy. Each packet recieved goes into a function for processing.\n\n4. Process sniffed packets using Dpkt. Each first needs to be decoded. Using a [Radiotap](http://www.radiotap.org/defined-fields) decoder means we can access 'pseudo-headers' which are inserted by the card rather than having actually been transmitted. Radiotap is a standard for injecting/interpreting these, though what actual information ends up there is up to the card manufacturer. For example, one card I tested packets did not include any signal strength data.\n\n5. There are three types of wireless (aka. 802.11) packet: management, control, and data. Each differs in what information it contains. Extract the key fields from the Radiotap headers, and write these along with the current timestamp to an in-memory queue.\n\n6. In the background, periodically write everything from the queue to a SQLite database.\n\n\nUnanswered questions\n--------------------\n\n* Very occassionally the error `Key error: 1 10` gets printed to the console. I don't know why.\n* The logs show periodic exceptions (`Key error: 127`) from trying to parse some packets. This seems to happen more often when the card is tuned to channel 6, from what I can see. I suspect the source is some device broadcasting malformed packets on this channel, but I've not been able to confirm this.\n* I've derived a number for signal (in dBm), but it does not take into account how much noise there is, although that's probably relevant too.\n* I've not got this to work on OS X -- BSD-based systems use the `/dev/bpf*` devices, which Pcapy doesn't seem to be able to cope with. It doesn't look like Scapy supports it either, but it does seem to [be being worked on](https://github.com/secdev/scapy/issues/104).\n\n\nRelated projects\n----------------\n\n* [wifi-monitor](https://github.com/dave5623/wifi_monitor)\n* [wifi-rifle](https://github.com/sensepost/WiFi-Rifle)\n\n\nArticles\n--------\n\n* https://www.crc.id.au/tracking-people-via-wifi-even-when-not-connected/\n* http://edwardkeeble.com/2014/02/passive-wifi-tracking/\n\n\nOn the command-line\n-------------------\n\nThis is a list of commands I've found useful whilst working on this project.\n\n### Mac\n\nYou will need to use the `airport` command, so create a symlink:\n\n    $ sudo ln -s /System/Library/PrivateFrameworks/Apple80211.framework/Versions/Current/Resources/airport /usr/local/bin/airport\n\nFind out the names of your network interfaces:\n\n    $ ifconfig\n\nThe default Wifi interface appears to be named `en0`.\n\nSelect the channel you would like to sniff (here, channel 6):\n\n    $ airport en0 channel 6\n\nSee all the existing networks and their channels:\n\n    $ airport en0 scan\n\nPut your card into monitor mode:\n\n    $ sudo tcpdump -i en0 -Ic1 -py IEEE802_11\n\nIf this has worked it will say so in `airport en0 getinfo`.\n\nTo take the card out of monitor mode:\n\n    $ sudo tcpdump -i en0 -Ic1\n\nSniff traffic and store in a `pcap` file:\n\n    $ sudo tcpdump -i en0 -I -pw output.pcap\n\n### Linux\n\nCheck what country the system thinks you're in. This will affect what channels you can use.\n\n    $ iw reg get\n\nIt should say `country GB`, but if not:\n\n    $ iw reg set GB\n\nThis will mean you get all possible UK frequencies when you:\n\n    $ iwlist wlan1 freq\n\nFind out the names of your network interfaces:\n\n    $ ifconfig\n\nThe default Wifi interface appears to be named `wlan1`.\n\nSelect the channel you would like to sniff (here, channel 6):\n\n    $ iw dev wlan1 set channel 6\n\nSee all the existing networks and their channels:\n\n    $ sudo iwlist wlan1 scan\n\nPut your card into monitor mode:\n\n    $ iw dev wlan1 set type monitor\n\nIf this has worked it will say so in `iwconfig`.\n\nTo take the card out of monitor mode:\n\n    $ iw dev wlan1 set type managed\n\nSniff traffic and store in a `pcap` file:\n\n    $ sudo tcpdump -i en0 -I -pw output.pcap\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeovation%2Fwifispy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeovation%2Fwifispy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeovation%2Fwifispy/lists"}