# gill-singh-a/stun-ip-tracker architecture

> Architecture diagram of the GitHub repository gill-singh-a/stun-ip-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gill-singh-a/stun-ip-tracker
- Repository: https://github.com/gill-singh-a/stun-ip-tracker

## Overview

STUN IP Tracker is a command-line packet analyzer for identifying IP addresses in STUN traffic, filtering them by ASN, and optionally geolocating and mapping results. Its principal workflow starts with live interface capture or a packet-capture file, then analyzes packets and performs ASN lookup before optionally producing location output. The README documents mapping and geolocation capabilities; the available source excerpt shows where those functions are called, but not their implementation inside the IP-Location submodule.

Main entry points: [`main.py`](https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py) (CLI workflow), [`ignore_asn_names.txt`](https://github.com/gill-singh-a/stun-ip-tracker/blob/master/ignore_asn_names.txt) (Ignored ASN list), [`IP-Location`](https://github.com/gill-singh-a/stun-ip-tracker/tree/master/IP-Location) (IP geolocation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Packet input"]
  node_cli["CLI workflow<br/>[main.py]"]
  node_packet_capture["Packet capture<br/>[main.py]"]
end

subgraph group_analysis["STUN analysis"]
  node_packet_callback["Packet callback<br/>[main.py]"]
  node_stun_analysis["STUN analysis<br/>[main.py]"]
  node_asn_lookup["ASN lookup<br/>[main.py]"]
  node_asn_filter["ASN filtering<br/>[main.py]"]
  node_asn_list["Ignored ASN list"]
end

subgraph group_location["Location output"]
  node_geolocation["IP geolocation"]
  node_map_output["Map output"]
end

node_user(("Operator"))
node_live_packets(("Live packets"))
node_capture_file["Capture file"]
node_whois_service(("WHOIS service"))

node_user -->|"runs"| node_cli
node_cli -->|"starts capture"| node_packet_capture
node_live_packets -->|"supplies packets"| node_packet_capture
node_capture_file -->|"read by"| node_cli
node_packet_capture -->|"dispatches packets"| node_packet_callback
node_cli -->|"iterates packets"| node_packet_callback
node_packet_callback -->|"processes packet"| node_stun_analysis
node_stun_analysis -->|"looks up IP"| node_asn_lookup
node_asn_lookup -->|"queries"| node_whois_service
node_stun_analysis -->|"checks ASN"| node_asn_filter
node_asn_filter -->|"reads"| node_asn_list
node_packet_callback -->|"geolocates IP"| node_geolocation
node_cli -->|"maps locations"| node_map_output

click node_cli "https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py"
click node_packet_capture "https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py"
click node_packet_callback "https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py"
click node_stun_analysis "https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py"
click node_asn_lookup "https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py"
click node_asn_filter "https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py"
click node_asn_list "https://github.com/gill-singh-a/stun-ip-tracker/blob/master/ignore_asn_names.txt"
click node_geolocation "https://github.com/gill-singh-a/stun-ip-tracker/tree/master/IP-Location"
click node_map_output "https://github.com/gill-singh-a/stun-ip-tracker/tree/master/IP-Location"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_packet_capture toneBlue
class node_packet_callback,node_stun_analysis,node_asn_lookup,node_asn_filter,node_asn_list toneAmber
class node_geolocation,node_map_output toneMint
class node_user,node_live_packets,node_capture_file,node_whois_service toneIndigo
```

## Components

### Packet input

- [CLI workflow](https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py): `main.py`
- [Packet capture](https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py): `main.py`

### STUN analysis

- [Packet callback](https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py): `main.py`
- [STUN analysis](https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py): `main.py`
- [ASN lookup](https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py): `main.py`
- [ASN filtering](https://github.com/gill-singh-a/stun-ip-tracker/blob/master/main.py): `main.py`
- [Ignored ASN list](https://github.com/gill-singh-a/stun-ip-tracker/blob/master/ignore_asn_names.txt): `ignore_asn_names.txt`

### Location output

- [IP geolocation](https://github.com/gill-singh-a/stun-ip-tracker/tree/master/IP-Location): `IP-Location`
- [Map output](https://github.com/gill-singh-a/stun-ip-tracker/tree/master/IP-Location): `IP-Location`

### Other components

- **Operator**
- **Live packets**
- **Capture file**
- **WHOIS service**

## Connections

- Operator → CLI workflow: runs
- CLI workflow → Packet capture: starts capture
- Live packets → Packet capture: supplies packets
- Capture file → CLI workflow: read by
- Packet capture → Packet callback: dispatches packets
- CLI workflow → Packet callback: iterates packets
- Packet callback → STUN analysis: processes packet
- STUN analysis → ASN lookup: looks up IP
- ASN lookup → WHOIS service: queries
- STUN analysis → ASN filtering: checks ASN
- ASN filtering → Ignored ASN list: reads
- Packet callback → IP geolocation: geolocates IP
- CLI workflow → Map output: maps locations