TapMap

See where your computer connects on a live world map.

TapMap inspects local socket data, enriches IP addresses with geolocation, and visualizes the locations on an interactive map.

It uses:

• psutil (Windows and Linux) or lsof (macOS) to read active network connections
• MaxMind GeoLite2 databases for IP geolocation
• Dash and Plotly to render an interactive world map

Architecture: local socket scan → IP extraction → GeoIP lookup → map rendering.

TapMap runs entirely on your own machine.
It is not a firewall or a full security suite.
It makes network activity visible on a world map and easy to inspect with hover and click.

TapMap can also run in Docker on Linux, with limited process visibility.

---

Documentation

Full documentation, including API reference and platform behavior notes:

https://olalie.github.io/tapmap/

---

Download & run

Download the latest version from the
Releases page

Available builds:

• Windows (zip)
• Linux (zip)
• macOS (zip)

Tested on Windows 11, Ubuntu, and macOS (Apple Silicon).

No installation required. Download, extract, and run.

Start TapMap:

./tapmap

On Windows, double-click tapmap.exe.

On Linux, you may need:

chmod +x tapmap

Platform notes:

• Linux uses xdg-open for the Open data folder action
• macOS uses open

---

Command line

tapmap --help

tapmap --version
tapmap -v

---

Windows SmartScreen

Windows may show a SmartScreen warning the first time you run TapMap.
This is normal for new applications that are not digitally signed.

To start the program:

1. Click More info.
2. Click Run anyway.

---

macOS security warning

macOS may block the app the first time you run TapMap. This is normal for unsigned applications.

To start the program:

1. Try to open the app.
2. Open System Settings → Privacy & Security.
3. Click Open anyway for TapMap.

You may be asked to confirm once more.

Alternatively, you can remove the warning using Terminal:

xattr -d com.apple.quarantine tapmap

---

How it runs

TapMap runs locally and opens in your browser.

The web interface runs on a local server at:

http://127.0.0.1:8050/

If it does not open automatically, enter the address manually in your browser.

The default port is defined by SERVER_PORT in config.py.

The port can be overridden using the environment variable TAPMAP_PORT.

Examples:

Linux / macOS:

TAPMAP_PORT=8060 python tapmap.py

PowerShell:

$env:TAPMAP_PORT="8060"
python tapmap.py

---

GeoIP databases (required for map locations)

TapMap uses local MaxMind GeoLite2 databases for geolocation.
The databases are not included in the download.

TapMap works without these files, but map locations will not be displayed.

Required files:

• GeoLite2-City.mmdb
• GeoLite2-ASN.mmdb

Download is free from MaxMind, but requires an account and acceptance of license terms:

https://dev.maxmind.com/geoip/geolite2-free-geolocation-data

After downloading:

1. Start TapMap.
2. Open the data folder from the app.
3. Copy the .mmdb files into that folder.
4. Click Recheck GeoIP databases.

Update recommendation: download updated databases regularly, for example monthly.
Redistribution is subject to the MaxMind license terms.

---

What TapMap shows

• Services your computer connects to
• Their approximate locations on a world map
• Nearby clusters highlighted visually
• Unmapped public services with missing geolocation
• Established LAN and LOCAL services
• Local open ports (TCP LISTEN and UDP bound)

All data is collected locally on your machine.

---

Why TapMap

Most computers communicate with dozens of remote systems every day.
You usually cannot see them.

TapMap makes these connections visible within seconds.

• See unexpected connections
• Understand where traffic goes
• Get a quick overview of network activity

Unexpected connections may indicate misconfiguration, background services, or unwanted software.

---

Interface

Main view

Actions menu

Unmapped services

Open ports

About

---

Keyboard controls

| Key | Action | |-----|--------| | U | Unmapped public services | | L | Established LAN/LOCAL services | | O | Open ports | | T | Show cache in terminal | | C | Clear cache | | R | Recheck GeoIP databases | | H | Help | | A | About | | ESC | Close window |

---

Privacy

• TapMap runs locally.
• No connection data is sent anywhere.
• Geolocation uses local MaxMind databases.
• If MY_LOCATION = "auto", TapMap makes a small request to detect your public IP.
• To detect offline status, TapMap performs short connection checks to 1.1.1.1 and 8.8.8.8.

---

Configuration

TapMap reads settings from config.py.

Common settings:

• SERVER_PORT
• MY_LOCATION
• POLL_INTERVAL_MS
• COORD_PRECISION
• ZOOM_NEAR_KM

SERVER_PORT defines the default port used by the local Dash server.

The port can be overridden at runtime using the environment variable TAPMAP_PORT.

---

Build from source

Requirements:

• Python 3.10+

Install dependencies:

pip install -r requirements.txt

Run:

python tapmap.py

Run tests:

pytest

---

Docker (Linux)

TapMap can run in Docker on Linux hosts.

Requirements

• Linux host
• Docker installed
• GeoLite2 .mmdb files

Setup

Place the GeoLite2 database files in:

docker-data/

Run

docker compose -f compose.linux.yaml up --build

The server binds to 0.0.0.0 by default in Docker.

Override in compose if needed:

TAPMAP_HOST: "127.0.0.1"

Open in browser on the host:

http://127.0.0.1:8050

If you access the app from another machine, use the host IP address instead.

Notes

• Docker provides full TCP and UDP socket data
• Process information may be unavailable in Docker mode, depending on host security policies
• Requires Linux host (not supported on Docker Desktop for Windows or macOS)

Process visibility in Docker depends on host security policies.

On Ubuntu with the default Docker AppArmor profile (docker-default), SYS_PTRACE alone was not sufficient.

In this setup, process names became available with:

--cap-add=SYS_PTRACE
--security-opt apparmor=unconfined

Behavior may vary across systems.

---

Docker Hub

TapMap can run directly from Docker Hub without cloning the repository.

Setup

Create a local data folder:

mkdir -p ~/tapmap-data

Place the GeoLite2 database files in that folder:

• GeoLite2-City.mmdb
• GeoLite2-ASN.mmdb

Run

docker run --rm \
  --network host \
  --pid host \
  -v ~/tapmap-data:/data \
  -e TAPMAP_IN_DOCKER=1 \
  olalie/tapmap:latest

The server binds to 0.0.0.0 by default in Docker.

To override the bind address:

-e TAPMAP_HOST=127.0.0.1

Open in browser on the host:

http://127.0.0.1:8050

If you access the app from another machine, use the host IP address instead.

Notes

• The mounted folder is used as the container data directory (/data)
• Process information may be unavailable in Docker mode, depending on host security policies
• Requires Linux host (not supported on Docker Desktop for Windows or macOS)

---

Support the project

TapMap is free and open source.

If you find it useful, consider supporting the project:

• Buy Me a Coffee
  https://www.buymeacoffee.com/olalie

• PayPal
  https://www.paypal.com/donate/?hosted_button_id=ELLXBK9BY8EDU

You can also give the project a star on GitHub.

---

License

MIT License

---

Acknowledgements

Thanks to @TechnVision for raising the configurable port use case.

Thanks to @desrod for suggesting a solution for configurable port support.

Thanks to @hugalafutro for suggesting optional SYS_PTRACE support for process visibility on Linux.