Repository for the IPvSeeYou talk at Black Hat 2021

Overview

IPvSeeYou Geolocation Lookup Tool

Overview

IPvSeeYou.py is a tool to assist with geolocating EUI-64 IPv6 hosts. It

  1. takes as input an EUI-64-derived MAC address,
  2. uses a previously-generated WAN MAC address to BSSID offset table to predict the BSSID for the EUI-64-derived MAC address,
  3. queries a geolocation API for the predicted BSSID, and
  4. prints the results (and optionally outputs to KML.)

Requirements

IPvSeeYou.py is written in and has been tested only using Python3. Installing the packages from the requirements.txt file using:

pip3 install -r requirements.txt

will ensure you have the required dependencies.

Usage

IPvSeeYou.py is written in Python3 and uses argparse, so you can always get help by passing the -h flag:

user@host % ./IPvSeeYou.py -h
usage: IPvSeeYou.py [-h] (-M MAC_FILE | -m MAC | -e EUI | -E EUI_FILE) (-a | -w) [-o OFFSET_FILE]
                    [-k KML] [-U API_USER] [-P API_PASS]

optional arguments:
  -h, --help            show this help message and exit
  -M MAC_FILE, --mac-file MAC_FILE
                        File of MAC addresses from EUI-64 IPv6 addresses to bulk lookup
  -m MAC, --mac MAC     Single MAC address from EUI-64 IPv6 address to attempt to geolocate
  -e EUI, --eui EUI     Single EUI-64 IPv6 address to extract MAC from and attempt to geolocate
  -E EUI_FILE, --eui-file EUI_FILE
                        File of EUI-64 IPv6 addresses to extract MAC from and attempt to geolocate
  -a, --apple           Use Apple's location services API to geolocate BSSID
  -w, --wigle           Use WiGLE's API to geolocate BSSID (requires -U API_USER and -P API_PASS)
  -o OFFSET_FILE, --offset-file OFFSET_FILE
                        File containing inferred OUI offsets (default ./offsets.txt)
  -k KML, --kml KML     Output KML filename
  -U API_USER, --api-user API_USER
                        WiGLE API username (required for -w)
  -P API_PASS, --api-pass API_PASS
                        WiGLE API password (required for -w)

The first set of mutually exclusive arguments indicates how the program should expect EUI-64-derived MAC addresses.

  1. -e EUI indicates that the user is specifying a single EUI-64 IPv6 address to attempt to geolocate, as in -e 2001::0211:22ff:fe33:4455
  2. -E EUI_FILE indicates that the user is specifying a file that contains one or more EUI-64 IPv6 addresses, each separated by a newline, as in -E euis.txt
  3. -m MAC indicates that the user is specifying a single MAC address (that presumably they derived from an EUI-64 IPv6 address), as in -m 00:11:22:33:44:55
  4. -M MAC_FILE indicates that they user is specifying a file containing one or more MAC addresses, each separated by a newline, as in -M macs.txt

The second set of mutually exclusive arguments indicates how the program should look up the predicted BSSID (if one is found) for the EUI-64 derived MAC addresses.

  1. -a/--apple will use Apple's location services API. IPvSeeYou.py uses logic derived from hubert3's iSniff-GPS
  2. -w/--wigle will use WiGLE's API to query for the predicted BSSID. This requires a WiGLE API username and password to be specified using -U/--api-user and -P/--api-pass.

-o/--offset-file OFFSET_FILE is an optional argument to specify OUI and their WAN MAC to BSSID offsets, each on a new line. For example:

00:11:22 -3
00:77:88 2

indicates that the OUI 00:11:22 has a WAN MAC to BSSID offset of -3. By default, a file called ./offsets.txt is used and need not be specified if it exists.

-k/--kml KML is an optional argument that will generate a KML output file with a point for each geolocated EUI-64-derived MAC address.

Examples

MAC addresses, username/password and geolocations in this section are for example purposes only, and will not provide an actual geolocation or authentication to WiGLE.

To specify a single EUI-64 IPv6 address to geolocate using Apple's location services API and output to a KML file called output.kml, we:

./IPvSeeYou.py -e 2001:0:1:2:0200:11ff:fe22:3344 -k output.kml -a

#EUI-64-Derived MAC	BSSID	lat,lon
00:00:11:22:33:44	00:00:11:22:33:46	12.34,56.78 

To specify a file containing EUI-64-derived MAC addresses to geolocate using the WiGLE API, with WiGLE API username and password, we:

./IPvSeeYou.py -M fileOfMacs.txt -w -U abcdefabcdefabcdefabcdef -P 1234567890abcdef
#EUI-64-Derived MAC	BSSID	lat,lon
00:00:11:22:33:44	00:00:11:22:33:46	12.34,56.78 
f8:00:11:22:33:44	f8:00:11:22:33:40	23.45,-12.34

Credits

Much of the code that interacts with Apple's Location Services was borrowed from @hubert3's excellent iSniff-GPS, presented at Black Hat USA 2012.

You might also like...
Yes, it's true :two_hearts: This repository has 316 stars.

Yes, it's true! Inspired by a similar repository from @RealPeha, but implemented using a webhook on AWS Lambda and API Gateway, so it's serverless! If

Yes, it's true :yellow_heart: This repository has 326 stars.

Yes, it's true! Inspired by a similar repository from @RealPeha, but implemented using a webhook on AWS Lambda and API Gateway, so it's serverless! If

Yes, it's true :heartbeat: This repository has 337 stars.

Yes, it's true! Inspired by a similar repository from @RealPeha, but implemented using a webhook on AWS Lambda and API Gateway, so it's serverless! If

Yes, it's true :orange_heart: This repository has 346 stars.

Yes, it's true! Inspired by a similar repository from @RealPeha, but implemented using a webhook on AWS Lambda and API Gateway, so it's serverless! If

Yes, it's true :purple_heart: This repository has 353 stars.

Yes, it's true! Inspired by a similar repository from @RealPeha, but implemented using a webhook on AWS Lambda and API Gateway, so it's serverless! If

This is a repository for the Duke University Cloud Computing course project on Serveless Data Engineering Pipeline. For this project, I recreated the below pipeline.
This is a repository for the Duke University Cloud Computing course project on Serveless Data Engineering Pipeline. For this project, I recreated the below pipeline.

AWS Data Engineering Pipeline This is a repository for the Duke University Cloud Computing course project on Serverless Data Engineering Pipeline. For

This repository contains free labs for setting up an entire workflow and DevOps environment from a real-world perspective in AWS
This repository contains free labs for setting up an entire workflow and DevOps environment from a real-world perspective in AWS

DevOps-The-Hard-Way-AWS This tutorial contains a full, real-world solution for setting up an environment that is using DevOps technologies and practic

A small repository with convenience functions for working with the Notion API.

Welcome! Within this respository are a few convenience functions to assist with the pulling and pushing of data from the Notion API.

a public repository helping ML/DL engineers and DS to beautify the notebook with minimal coding.

ml-helper-functions a public repository helping ML/DL engineers and DS to beautify the notebook with minimal coding.

An information scroller Twitter trends, news, weather for raspberry pi and Pimoroni Unicorn Hat Mini and Scroll Phat HD.

uticker An information scroller Twitter trends, news, weather for raspberry pi and Pimoroni Unicorn Hat Mini and Scroll Phat HD. Features include: Twi

Tansu Şenyurt 1 Nov 28, 2021
An information scroller Twitter trends, news, weather for raspberry pi and Pimoroni Unicorn Hat Mini and Scroll Phat HD.

uticker An information scroller Twitter trends, news, weather for raspberry pi and Pimoroni Unicorn Hat Mini and Scroll Phat HD. Features include: Twi

kottuora 5 Oct 31, 2022
Presentation and code files for the talk at PyCon Indonesia

pycon-indonesia Presentation and code files for the talk at PyCon Indonesia. Files used for the PyCon Indonesia presentation. [Directory Includes:] Be

Neeraj Pandey 2 Dec 4, 2021
Celestial - a Python regex Discord chatbot who can talk with you.

Celestial a Python regex Discord chat bot who can talk with you. Invite url: https://discord.com/api/oauth2/authorize?client_id=927573556961869825&per

Jirayu Kaewsing 3 Jan 1, 2023
Prabashwara's Pm Bot repository. You can deploy and edit this repository.

Tᴇʟᴇɢʀᴀᴍ Pᴍ Bᴏᴛ | Prabashwara's PM Bot Unmaintained. The new repo of @Pm-Bot is private. (It is no longer based on this source code. The completely re

Rivibibu Prabshwara Ⓒ 2 Jul 5, 2022
Tesseract Open Source OCR Engine (main repository)

Tesseract OCR About This package contains an OCR engine - libtesseract and a command line program - tesseract. Tesseract 4 adds a new neural net (LSTM

null 48.3k Jan 5, 2023
Yes, it's true :revolving_hearts: This repository has 301 stars.

Yes, it's true! Inspired by a similar repository from @RealPeha, but implemented using a webhook on AWS Lambda and API Gateway, so it's serv

null 511 Dec 30, 2022
Yes, it's true :revolving_hearts: This repository has 301 stars.

Yes, it's true! Inspired by a similar repository from @RealPeha, but implemented using a webhook on AWS Lambda and API Gateway, so it's serv

null 510 Dec 28, 2022