yougotmapped 1.0.1__py3-none-any.whl → 1.1.0__py3-none-any.whl

yougotmapped/utils/output.py

@@ -1,67 +1,80 @@
-# utils/output.py
 import json
 import csv
+from pathlib import Path
 from io import StringIO
 
 
-def format_as_normal(data):
-    output = []
-    for d in data:
+def _flatten_dict(data: dict, parent_key: str = "", sep: str = "_") -> dict:
+    items = {}
+
+    for key, value in data.items():
+        new_key = f"{parent_key}{sep}{key}" if parent_key else key
+
+        if isinstance(value, dict):
+            items.update(_flatten_dict(value, new_key, sep=sep))
+        else:
+            items[new_key] = value
+
+    return items
+
+
+def format_normal(results: list[dict]) -> str:
+    blocks = []
+
+    for entry in results:
         lines = []
-        for key, value in d.items():
+        for key, value in entry.items():
             if isinstance(value, dict):
-                lines.append(f"{key.title()}:")
+                lines.append(f"{key}:")
                 for sub_key, sub_val in value.items():
-                    lines.append(f"  {sub_key.title()}: {sub_val}")
+                    lines.append(f"  {sub_key}: {sub_val}")
             else:
-                lines.append(f"{key.title()}: {value}")
-        output.append("\n".join(lines))
-        output.append("\n" + "-" * 40 + "\n")
-    return "\n".join(output)
-
-
-def flatten_for_csv(entry):
-    """
-    Flatten nested dictionaries for CSV.
-    For example: {"anonymity": {"vpn": False}} -> {"anonymity_vpn": False}
-    """
-    flat = {}
-    for key, value in entry.items():
-        if isinstance(value, dict):
-            for sub_key, sub_val in value.items():
-                flat[f"{key}_{sub_key}"] = sub_val
-        else:
-            flat[key] = value
-    return flat
+                lines.append(f"{key}: {value}")
+
+        blocks.append("\n".join(lines))
+        blocks.append("-" * 40)
+
+    return "\n".join(blocks)
+
+
+def format_json(results: list[dict]) -> str:
+    return json.dumps(results, indent=4)
 
 
-def format_as_csv(data):
-    if not data:
+def format_csv(results: list[dict]) -> str:
+    if not results:
         return ""
-    flat_data = [flatten_for_csv(d) for d in data]
-    # Collect all possible fields across entries
-    fieldnames = sorted({key for d in flat_data for key in d.keys()})
-    output = StringIO()
-    writer = csv.DictWriter(output, fieldnames=fieldnames)
+
+    flattened = [_flatten_dict(r) for r in results]
+
+    fieldnames = sorted(
+        {key for entry in flattened for key in entry.keys()}
+    )
+
+    buffer = StringIO()
+    writer = csv.DictWriter(buffer, fieldnames=fieldnames)
     writer.writeheader()
-    for d in flat_data:
-        writer.writerow(d)
-    return output.getvalue()
 
+    for entry in flattened:
+        writer.writerow(entry)
+
+    return buffer.getvalue()
 
-def format_as_json(data):
-    return json.dumps(data, indent=4)
 
+def write_output(
+    results: list[dict],
+    path: str | Path,
+    fmt: str = "normal",
+) -> Path:
+    fmt = fmt.lower()
+    path = Path(path).resolve()
 
-def write_formatted_output(data, file_path, fmt_type="normal"):
-    fmt_type = fmt_type.lower()
-    if fmt_type == "csv":
-        formatted = format_as_csv(data)
-    elif fmt_type == "json":
-        formatted = format_as_json(data)
+    if fmt == "json":
+        content = format_json(results)
+    elif fmt == "csv":
+        content = format_csv(results)
     else:
-        formatted = format_as_normal(data)
+        content = format_normal(results)
 
-    with open(file_path, "w", encoding="utf-8") as f:
-        f.write(formatted)
-    print(f"Output saved to {file_path} in {fmt_type.upper()} format.")
+    path.write_text(content, encoding="utf-8")
+    return path

yougotmapped/utils/ping.py

@@ -1,56 +1,107 @@
-# utils/pings.py
 from ping3 import ping
 import statistics
 
-def classify_rtt_latency(latency):
-    if latency < 1:
-        return "LAN or loopback — same machine or local router"
-    elif latency < 5:
-        return "Local network — same building or direct fiber"
-    elif latency < 20:
-        return "Nearby region — very low-latency ISP link"
-    elif latency < 50:
-        return "Fast WAN — CDN, local data center, or strong routing"
-    elif latency < 100:
-        return "Typical internet — stable ISP-to-ISP connection"
-    elif latency < 200:
-        return "Remote server — possible transcontinental routing"
-    elif latency < 400:
-        return "High latency — distant, congested, or routed via relay"
-    else:
-        return "Unstable or suspicious — VPN, proxy, or degraded network"
-
-def ping_target(host, count=4):
-    """
-    Pings the given host and returns avg latency, loss %, estimated distance, and a basic label.
-    """
+
+FIBER_SPEED_KM_PER_MS = 200 # physical upper bound
+REAL_WORLD_FACTOR = 0.5 # routing + overhead penalty
+EFFECTIVE_SPEED = FIBER_SPEED_KM_PER_MS * REAL_WORLD_FACTOR
+
+
+def estimate_distance_km(rtt_ms: float) -> tuple[int, int, int]:
+    one_way_ms = rtt_ms / 2
+
+    estimated = one_way_ms * EFFECTIVE_SPEED
+
+    min_km = int(estimated * 0.7)
+    max_km = int(estimated * 1.3)
+
+    return int(min_km), int(estimated), int(max_km)
+
+
+def classify_latency(rtt_ms: float) -> str:
+    if rtt_ms < 1:
+        return "Loopback or same-host"
+    if rtt_ms < 5:
+        return "Local network / same building"
+    if rtt_ms < 20:
+        return "Metro or nearby region"
+    if rtt_ms < 50:
+        return "Regional / same country"
+    if rtt_ms < 100:
+        return "Inter-country"
+    if rtt_ms < 200:
+        return "Intercontinental"
+    return "Very distant or routed via relay/VPN"
+
+
+def ping_target(host: str, count: int = 5, timeout: float = 1.0) -> dict:
     latencies = []
 
     for _ in range(count):
         try:
-            delay = ping(host, timeout=1)
-            if delay:
-                latencies.append(delay)
+            delay = ping(host, timeout=timeout)
+            if delay is not None:
+                latencies.append(delay * 1000)  # ms
         except Exception:
             continue
 
+    sent = count
     received = len(latencies)
-    lost = count - received
+    lost = sent - received
 
     if received == 0:
-        return f"Ping to {host}: unreachable ({count} packets lost)"
+        return {
+            "reachable": False,
+            "sent": sent,
+            "received": 0,
+            "packet_loss_percent": 100.0,
+        }
+
+    min_rtt = round(min(latencies), 2)
+    avg_rtt = round(statistics.mean(latencies), 2)
+    med_rtt = round(statistics.median(latencies), 2)
+    max_rtt = round(max(latencies), 2)
+
+    min_km, est_km, max_km = estimate_distance_km(med_rtt)
+
+    return {
+        "reachable": True,
+        "sent": sent,
+        "received": received,
+        "packet_loss_percent": round((lost / sent) * 100, 1),
+        "rtt_ms": {
+            "min": min_rtt,
+            "avg": avg_rtt,
+            "median": med_rtt,
+            "max": max_rtt,
+        },
+        "distance_km": {
+            "estimated": est_km,
+            "min": min_km,
+            "max": max_km,
+        },
+        "classification": classify_latency(med_rtt),
+    }
 
-    avg_latency_ms = round(statistics.mean(latencies) * 1000, 2)
-    packet_loss = round((lost / count) * 100, 1)
 
-    # Go back to fast, rough RTT-based estimate: 200 km/ms
-    estimated_distance_km = round((avg_latency_ms / 2) * 200)
-    label = classify_rtt_latency(avg_latency_ms)
+def format_ping_result(result: dict) -> None:
+    if not result.get("reachable"):
+        print("Host unreachable (100% packet loss)")
+        return
 
-    return (
-        f"Ping to {host} ({count} packets):\n"
-        f"  Avg Latency: {avg_latency_ms} ms\n"
-        f"  Packet Loss: {packet_loss}%\n"
-        f"  Est. Distance: ~{estimated_distance_km} km (RTT-based)\n"
-        f"  Inference: {label}"
+    print(f"Packets: sent={result['sent']} received={result['received']}")
+    print(f"Packet loss: {result['packet_loss_percent']}%")
+
+    rtt = result["rtt_ms"]
+    print(
+        f"RTT (ms): min={rtt['min']} avg={rtt['avg']} "
+        f"median={rtt['median']} max={rtt['max']}"
+    )
+
+    dist = result["distance_km"]
+    print(
+        f"Estimated distance: ~{dist['estimated']} km "
+        f"(range {dist['min']}–{dist['max']} km)"
     )
+
+    print(f"Inference: {result['classification']}")

yougotmapped/utils/trace.py

@@ -1,70 +1,95 @@
-# utils/trace.py
 import subprocess
 import platform
-import re
 import ipaddress
-from yougotmapped.utils.network import get_geolocation
+import re
 
-def run_traceroute(host, max_hops=30, timeout=60):
-    system = platform.system()
-    if system == "Windows":
-        cmd = ["tracert", "-h", str(max_hops), host]
-    elif system in ["Linux", "Darwin"]:
-        cmd = ["traceroute", "-m", str(max_hops), "-w", "1", host]
-    else:
-        return f"Traceroute not supported on {system}"
+from yougotmapped.utils.network import get_hop_location
 
-    try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
-        return format_trace_output(result.stdout)
-    except subprocess.TimeoutExpired:
-        return f"Traceroute to {host} timed out after {timeout} seconds."
-    except FileNotFoundError:
-        return f"Traceroute command not found on this system."
-    except Exception as e:
-        return f"Traceroute failed: {e}"
 
+IP_REGEX = re.compile(r"(\d{1,3}(?:\.\d{1,3}){3})")
+RTT_REGEX = re.compile(r"(\d+(?:\.\d+)?)\s*ms")
 
-def is_private_ip(ip):
+
+def _is_private_ip(ip: str) -> bool:
     try:
         return ipaddress.ip_address(ip).is_private
     except ValueError:
         return False
 
 
-def extract_ip_latency(line):
-    ip_match = re.findall(r"(\d+\.\d+\.\d+\.\d+)", line)
-    rtt_match = re.findall(r"(\d+\.\d+) ms", line)
-    return ip_match[0] if ip_match else None, rtt_match[0] if rtt_match else None
+def _build_traceroute_command(host: str, max_hops: int) -> list[str]:
+    if platform.system() == "Windows":
+        return ["tracert", "-h", str(max_hops), host]
+
+    return ["traceroute", "-m", str(max_hops), "-w", "1", host]
 
 
-def format_trace_output(raw_output):
-    lines = raw_output.strip().split("\n")
-    formatted_lines = []
-    last_ip = None
+def run_traceroute(
+    host: str,
+    max_hops: int = 30,
+    timeout: int = 60,
+) -> dict:
+    cmd = _build_traceroute_command(host, max_hops)
 
-    for index, line in enumerate(lines):
-        ip, rtt = extract_ip_latency(line)
-        if not ip:
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        return {"error": "Traceroute timed out"}
+    except FileNotFoundError:
+        return {"error": "Traceroute command not found"}
+    except Exception as exc:
+        return {"error": str(exc)}
+
+    hops = []
+
+    for index, line in enumerate(proc.stdout.splitlines(), start=1):
+        ips = IP_REGEX.findall(line)
+        if not ips:
             continue
 
-        label = "(Private)" if is_private_ip(ip) else extract_label(line)
-        formatted_lines.append(f"[{index+1}] {ip.ljust(18)} {label.ljust(30)} {rtt} ms")
-        last_ip = ip
+        ip = ips[0]
+        private = _is_private_ip(ip)
+
+        rtts = [float(x) for x in RTT_REGEX.findall(line)]
+        rtt_ms = rtts if rtts else None
+
+        hop_geo = None
+        if not private:
+            hop_geo = get_hop_location(ip)
+
+        hops.append({
+            "hop": index,
+            "ip": ip,
+            "private": private,
+            "rtt_ms": rtt_ms,
+            "latitude": hop_geo.get("latitude") if hop_geo else None,
+            "longitude": hop_geo.get("longitude") if hop_geo else None,
+        })
+
+    return {
+        "target": host,
+        "hops": hops,
+    }
+
 
-    # Append final geolocation if last IP is public
-    if last_ip and not is_private_ip(last_ip):
-        data = get_geolocation(last_ip, None)
-        if data:
-            geo_info = f"  --> {data.get('city', 'N/A')}, {data.get('region', '')} ({data.get('org', 'N/A')})"
-            formatted_lines.append(geo_info)
+def format_traceroute(result: dict) -> None:
+    if "error" in result:
+        print(f"Traceroute error: {result['error']}")
+        return
 
-    return "\n".join(formatted_lines)
+    for hop in result.get("hops", []):
+        hop_no = hop["hop"]
+        ip = hop["ip"]
+        label = "PRIVATE" if hop["private"] else "PUBLIC"
 
+        rtt = hop["rtt_ms"]
+        rtt_display = (
+            f"{min(rtt):.1f} ms" if isinstance(rtt, list) else "*"
+        )
 
-def extract_label(line):
-    parts = line.split()
-    for part in parts:
-        if any(ext in part for ext in [".com", ".net", ".org"]):
-            return f"({part})"
-    return "(Public)"
+        print(f"[{hop_no:>2}] {ip:<15} {label:<7} {rtt_display}")

yougotmapped-1.1.0.dist-info/METADATA

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: yougotmapped
+Version: 1.1.0
+Summary: A terminal tool to map IPs and domains with style.
+Author-email: diputs <diputs-sudo@proton.me>
+License: MIT
+Project-URL: Homepage, https://github.com/diputs-sudo/YouGotMapped
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: folium
+Requires-Dist: ping3
+Requires-Dist: scapy
+Dynamic: license-file
+
+# YouGotMapped
+
+![Example traceroute and geographic routing visualization generated by YouGotMapped](docs/example-output.png)
+
+YouGotMapped is a command-line network intelligence and visualization tool that correlates IP addresses and domains with geographic, routing, and performance data.
+
+It integrates geolocation, latency analysis, traceroute inspection, and anonymity detection into a single, structured workflow, producing both human-readable output and machine-consumable logs.
+
+---
+
+## Overview
+
+YouGotMapped is designed to provide visibility into how traffic traverses networks and where endpoints are geographically represented. It is suitable for diagnostic, educational, and research use in environments where the user has appropriate authorization.
+
+The tool emphasizes clarity, traceability, and reproducibility of results.
+
+---
+
+## Key Capabilities
+
+- IP and domain geolocation
+- Interactive geographic visualization via HTML maps
+- ICMP-based reachability and latency measurement
+- Jitter analysis and stability inference
+- TCP MSS discovery
+- Bandwidth estimation using TCP performance models
+- Hop-by-hop traceroute with geographic correlation
+- VPN, proxy, and anonymity signal detection
+- Structured output in JSON, CSV, or plain text formats
+
+---
+
+## Intended Use
+
+YouGotMapped is intended for:
+
+- Network diagnostics and troubleshooting
+- Infrastructure visibility and analysis
+- Educational exploration of routing behavior
+- Authorized reconnaissance in controlled environments
+
+Users are responsible for ensuring they have explicit permission to analyze any systems or networks they do not own.
+
+---
+
+## Prohibited Use
+
+This project must not be used for:
+
+- Unauthorized monitoring or surveillance
+- Targeting individuals or private infrastructure
+- Harassment, exploitation, or data misuse
+- Any activity that violates applicable laws or policies
+
+---
+
+## Requirements
+
+- Python 3.8 or newer
+- Network access permitting ICMP and TCP probes
+- Runtime dependencies:
+  - `requests`
+  - `folium`
+  - `ping3`
+  - `scapy`
+
+Dependencies are validated at startup.
+
+---
+
+## Installation
+
+YouGotMapped can be installed directly from PyPI:
+
+```bash
+pip install yougotmapped
+```
+
+After installation, the `yougotmapped` command is available on the system PATH.
+
+### From Source
+
+Clone the repository:
+
+```bash
+git clone https://github.com/your-username/YouGotMapped.git
+cd YouGotMapped
+```
+
+Install dependencies:
+
+```bash
+pip install -r requirements.txt
+```
+
+Running from Source:
+
+```bash
+python -m yougotmapped.cli
+```
+
+---
+
+## Usage
+
+Analyze a single target using all available modules:
+
+```bash
+yougotmapped -i 8.8.8.8 -a
+```
+
+Export results as JSON:
+
+```bash
+yougotmapped -i 8.8.8.8 -a -o f:json
+```
+
+Disable map generation:
+
+```bash
+yougotmapped -i example.com -t --no-map
+```
+
+---
+
+## Command-Line Options
+
+```text
+-i, --ip [IP ...]        IP addresses or domains
+-f, --file FILE          Input file with targets
+-p, --ping               Latency and reachability test
+-j, --jitter             Jitter and stability analysis
+-m, --mtu                MTU / MSS discovery
+-b, --bandwidth          Bandwidth estimation
+-t, --trace              Traceroute analysis
+-c, --hidecheck          Anonymity detection
+-a, --all                Run all modules
+--no-map                 Disable map output
+-o, --output             Output format (f:json, f:csv, f:normal)
+```
+
+---
+
+## Output
+
+Each execution produces:
+
+* Structured log files with timestamps
+* Optional interactive HTML maps
+* Terminal summaries for immediate inspection
+
+Outputs are designed to be both auditable and reproducible.
+
+---
+
+## Legal Notice
+
+By using this software, you acknowledge that:
+
+* You have authorization to analyze the specified targets
+* You accept full responsibility for its use
+* The author is not liable for misuse or resulting damages
+
+This software is provided for educational and research purposes.
+
+---
+
+## Contributing
+
+Contributions are welcome if they improve accuracy, reliability, or clarity and adhere to ethical and legal standards. Functionality that materially enables misuse will not be accepted.
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the LICENSE file for details.
+

yougotmapped-1.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+yougotmapped/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yougotmapped/cli.py,sha256=wK4y2Oh1iGiBXdJ6stMJ6veajS6-_0ZXh5OxsWnjHHo,7399
+yougotmapped/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+yougotmapped/utils/anonymity.py,sha256=qi2vdNsnppYwounC1OQdaAs21FqmNj4KewtDh3e5H7c,2439
+yougotmapped/utils/bandwidth.py,sha256=6jVUPNn4e0DM_mwN5k5AwVSzNoipY1DmWqZZpbbOtTw,1526
+yougotmapped/utils/dependencies.py,sha256=hF_r2PDBGfXgKeOyDc-iTtOzmdvBlR95iUnJZ0soimo,1494
+yougotmapped/utils/ingress.py,sha256=X9Gp11KnKMBwaox3W4tAaQs52ICiDPSMWJwwLSrIg4w,1692
+yougotmapped/utils/jitter.py,sha256=Kuc66BbywBoFDmbi-FRkMrx21r9YBlqfFhUI9GQuT_g,1940
+yougotmapped/utils/mapping.py,sha256=j-kPVEFocNy8fUvjdxr9H5hDSbvSLVNEek6J9xJ0Vlc,2719
+yougotmapped/utils/mss.py,sha256=KK8gVtnzpYi9c8eM313BC4X_wPx1wOGis4vTZgdNs_Q,3029
+yougotmapped/utils/mtu.py,sha256=ZbjLhNRko0ngYEPBKtZbnOTtXIlxcm-ylYOIz_SReZM,1772
+yougotmapped/utils/network.py,sha256=kq_uFKq2vpzDdZ9s748ke-NzLS3Y_woARSB3htNC8Qg,2173
+yougotmapped/utils/output.py,sha256=1nLRr3X-o_KdsUASWXhvS9TibZOv05X_Inj7_a2ZCWI,1867
+yougotmapped/utils/ping.py,sha256=TbI-lWSR6OaYKRpYqmUNEraW-nhkh5F-9WJd7jl7bto,2866
+yougotmapped/utils/trace.py,sha256=dKDpxcMnrZd-y6jjqTMrl6_ylIwYSreZMOmXXvbwHrw,2383
+yougotmapped-1.1.0.dist-info/licenses/LICENSE,sha256=E9UVVmDEpddJlGAMso045DiZPv_MO-UdjzTXkhiG7ps,1068
+yougotmapped-1.1.0.dist-info/METADATA,sha256=1p8ZuWX9wLV_epP93rhURl1_YjpJmbl5FldS9SVeRvE,4790
+yougotmapped-1.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+yougotmapped-1.1.0.dist-info/entry_points.txt,sha256=zv6jK4RV-3qvJ59qY1dZxML0g3qahKVMztwobKtTP-Q,55
+yougotmapped-1.1.0.dist-info/top_level.txt,sha256=XYHTw9YTF8Rz9Xj06Gh-xEl5IYs467gQR4BYlNrxZmM,13
+yougotmapped-1.1.0.dist-info/RECORD,,

{yougotmapped-1.0.1.dist-info → yougotmapped-1.1.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.7.1)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

{yougotmapped-1.0.1.dist-info → yougotmapped-1.1.0.dist-info}/licenses/LICENSE

@@ -1,9 +1,9 @@
 MIT License
 
-Copyright (c) 2025 diputs
+Copyright (c) 2025 diputs-sudo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the “Software”), to deal
+of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
@@ -12,16 +12,10 @@ furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----
-
-📝 Side note from the author:
-If this script crashes your terminal or geo-locates your toaster... that's on you.  
-But hey — it worked flawlessly on my end. 🫠