LandmarkForge: Multi-Agent and Multi-Source Landmark Mining at Internet Scale
An automated IPv4/IPv6 network IP landmark mining and evaluation system based on a multi-agent architecture.
中文文档: README_CN.md
- What is LandmarkForge?
- Key Innovations
- System Architecture
- Setup
- Large File Downloads
- Usage Guide
- Output
- Directory Structure
- FAQ
- Citation
Every device on the Internet has an IP address. An IP Landmark is an IP address whose physical location has been confirmed — for example, if you know that a certain server is located in "Mountain View, California", then its IP is a landmark.
These known-location landmarks act as anchor points on the map. With enough anchors, IP geolocation algorithms can infer the physical locations of unknown IP addresses — at country, city, or even street level. This is critical for map services, content delivery, cybersecurity, and more.
However, IP addresses are dynamic: servers migrate, IPs are reassigned, devices go online and offline. Landmark mining is therefore not a one-time task — it requires long-term, continuous, automated maintenance and updating.
LandmarkForge is an automated system that mines IP landmarks from across the Internet. Its core design philosophy is multi-agent collaboration — using 5 specialized "Agents" that each extract landmarks from different data sources, followed by unified validation.
| # | Agent | Data Source | Description |
|---|---|---|---|
| 1 | LLM-Web | Web content | Search for pages with IP + location info; use LLMs to understand content and extract landmarks |
| 2 | IoT-Fast | IoT device pages | Webcam and router pages follow fixed templates; "template matching" for high-speed extraction |
| 3 | IPv6-Geo | IPv6 address structure | Some IPv6 addresses embed Wi-Fi router MAC addresses; reverse lookup via Wi-Fi geolocation databases |
| 4 | rDNS | Reverse DNS records | Network admins embed city codes in hostnames (e.g., nyc-router.isp.net); parse naming conventions |
| 5 | Cloud | Cloud infrastructure | AWS, Azure etc. publish IP ranges and datacenter locations; correlate and map |
┌─────────────────────────────────────────────────────────┐
│ Data Acquisition Layer │
│ Collect active IPv4/IPv6 addresses → feed all Agents │
└──────────────────────────┬──────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────┐
│ Mining Layer (5 Agents) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Agent 1 │ │ Agent 2 │ │ Agent 3 │ │ Agent 4 │ │
│ │ LLM-Web │ │IoT-Fast │ │IPv6-Geo │ │ rDNS │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ │
│ │ Agent 5 │ │
│ │ Cloud │ │
│ └──────────┘ │
└──────────────────────────┬──────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────┐
│ Validation Layer │
│ DB Cross-Check + Physical Feasibility → High-quality │
└─────────────────────────────────────────────────────────┘
Innovation 1: Self-Training LLM Web Semantic Mining
Integrates Large Language Models into landmark mining with a six-stage closed-loop pipeline (Search → URL Filter → HTML Filter → Parse → Verify → Keyword Feedback), continuously improving filtering efficiency through LoRA self-training. Adapters are only ~40M parameters / ~80MB, requiring zero manual labeling.
Innovation 2: IoT Page Template-Based Fast Channel
Many IoT device pages are generated by a small set of firmware templates. The fast channel uses five-path joint extraction + voting (≥3/5 consensus required), achieving ~70× speedup (9.85 ms vs 705.8 ms per page).
Innovation 3: Cloud Service Landmark Mining
First systematic study of cloud service IP landmark mining. Collects 433K prefixes from 51 cloud providers and 12.8K datacenter records, building country/state/city/datacenter four-level geographic buckets.
Innovation 4: Multi-Agent Unified Scheduling and Continuous Maintenance
A controller agent coordinates periodic execution (monthly/weekly), addressing the paradigm shift from "one-time collection" to "long-term automated maintenance".
| Metric | LandmarkForge | ProbeGeo | GeoCAM | HLOC | LMGeo6 |
|---|---|---|---|---|---|
| Landmark count | 187.5K + 81M Cloud | 89,849 | ~16K | ~50K | 62,697 |
| IPv4/IPv6 support | Dual-stack | IPv4 only | IPv4 only | Dual | IPv6 only |
| Country coverage | 217 | 181 | ~170 | — | 165 |
| City coverage | 15,572 | 7,094 | 6,450 | — | 5,805 |
| AS coverage | 10,160 | 4,495 | 2,880 | — | 4,030 |
Efficiency:
- Web mining vs ProbeGeo: ~7× speedup, page downloads reduced 84.2%
- IoT mining vs ProbeGeo: ~70× speedup (9.85 ms/page)
- LLM inference accounts for only ~5.7% of total time; not the bottleneck
| Source | Landmarks | Coverage |
|---|---|---|
| LLM-Web (Agent 1) | 25,834 | 126 countries, 2,693 cities |
| IoT-Fast (Agent 2) | 97,293 | 185 countries, 13,706 cities |
| IPv6-EUI64 (Agent 3) | 25,530 | 29 countries, 1,380 cities |
| IPv6-Embv4 (Agent 3) | 9,955 | 94 countries, 292 cities |
| rDNS (Agent 4) | 28,917 | 135 countries, 1,049 cities |
| Non-Cloud Total | 187,529 | 194 countries, 15,469 cities |
| Cloud (Agent 5) | 81,148,144 | 197 countries, 5,098 buckets |
- IP Hitlist Fetcher: Collects public IPv4/IPv6 active address sets, RIPE Atlas daily measurement data
- Active Prober: Based on ZMap (IPv4 full-network scan) and 6Scan (IPv6 seed-based probing)
- Cloud Prefix Collector: Periodically collects cloud provider public IP prefixes and region metadata
Agent 1 — LLM-Web: Six-stage closed-loop pipeline (Seed → Search → URL Filter → HTML Filter → Parse → Verify). 4-bit quantized Llama 3.1-8B base model + two independent LoRA adapters (URL/HTML filtering). HTML feature extractor compresses raw pages into a six-dimensional signal summary.
Agent 2 — IoT-Fast: URL fingerprint pre-check → four-level cascaded matching (URL→HTML DOM→CSS→text labels) → five-path extraction + voting (≥3/5). Three successful URLs under the same domain auto-trigger template registration.
Agent 3 — IPv6-Geo: EUI-64 address detection → OUI offset rules infer BSSID → multi-source Wi-Fi DB query (Mylnikov/Apple/WiGLE) + coordinate clustering. Embedded-IPv4 path: prefix matching → extract embedded IPv4 → DB query.
Agent 4 — rDNS: Concurrent PTR queries (aiodns) → geo-hint dictionary matching (GeoNames/IATA/ICAO/CLLI/UN-LOCODE, ~9K entries) → marisa-trie prefix tree index → noise filtering (414-word blacklist).
Agent 5 — Cloud: Standardization + classification (51 providers, ~433K prefixes) → facility geocoding → four-layer geographic bucket aggregation (centroid method) → cloud prefix liveness probing → CDN filtering (rDNS assisted).
- Database Cross-Check: IPinfo / IP2Location / MaxMind GeoIP2 / WHOIS
- MDCE (Mean Database Coordinate Error), threshold 50 km
- Distributed Probe Pool: RIPE Atlas 12,000+ probes + ProbeGeo 6,217 nodes
- CBG Physical Feasibility Constraint: Checks whether measured RTT is less than the theoretical minimum (c_fiber = 2c/3)
- Cumulative Runtime Timer: Tracks total pipeline runtime across sessions with checkpoint-resume; auto-triggers validation after configurable threshold (default: 1 week)
- Evaluation Metrics: Per-source pass rate, MDCE distribution (mean/median/p95/p99/buckets), rejection reason breakdown, confidence level distribution
| Component | Minimum | Recommended |
|---|---|---|
| CPU | 4 cores | 8+ cores |
| RAM | 16 GB | 32 GB+ |
| GPU | NVIDIA RTX 3060 (6 GB VRAM) | RTX 5070 Ti (16 GB VRAM) |
| Disk | 20 GB free | 100 GB+ |
| Network | Stable Internet connection | Low latency |
# Ubuntu / Debian
sudo apt-get install python3 python3-pip python3-venv chromium-browser
# Windows
# Install Python 3.10+: https://www.python.org/downloads/
# Install Google Chrome or Chromium# conda (recommended)
conda create -n landmarkforge python=3.10 -y
conda activate landmarkforge
# or venv
python3 -m venv venv && source venv/bin/activate # Linux
python -m venv venv && venv\Scripts\activate # Windows# One-click install (recommended)
pip install -r requirements.txt
# Or manual install
pip install beautifulsoup4 lxml requests pyyaml
pip install torch transformers peft bitsandbytes accelerate datasets trl # LLM
pip install patchright scikit-learn # Browser + clustering
pip install aiodns marisa-trie dnspython tqdm # DNS + Trie + progress barEdit configs/default.yaml (optional, for improved validation accuracy):
validation:
ipinfo_token: "" # ipinfo.io API token (free: https://ipinfo.io/)
ip2location_key: "" # ip2location.io API key (free: https://ip2location.io/)
ripe_atlas_api_key: "" # RIPE Atlas API key (optional, for active measurement)Basic functionality works without any API keys.
The following files are too large for Git and must be downloaded separately:
mkdir -p landmarkforge/mining/agent_1_llm_web/models/Meta-Llama-3.1-8B-Instruct-GGUF
# HuggingFace download Q4_K_S quantized
pip install huggingface_hub
huggingface-cli download bartowski/Meta-Llama-3.1-8B-Instruct-GGUF \
Meta-Llama-3.1-8B-Instruct-Q4_K_S.gguf \
--local-dir landmarkforge/mining/agent_1_llm_web/models/Meta-Llama-3.1-8B-Instruct-GGUF- Mylnikov (~3 GB): https://api.mylnikov.org/ →
landmarkforge/mining/agent_3_ipv6_geo/data/bssid_mylnikov.db - WiGLE (~2 GB): https://wigle.net/ →
landmarkforge/mining/agent_3_ipv6_geo/data/bssid_wigle.db
Downloaded automatically on first run to data/hitlists/. Or manually trigger:
python -m landmarkforge.data_acquisition.hitlist_fetcherpython run.py --listpython run.py --test --agent1 --llm # Agent 1: ~4 min
python run.py --test --agent2 # Agent 2: seconds
python run.py --test --agent3 # Agent 3: uses cached checkpoints
python run.py --test --agent4 # Agent 4: seconds
python run.py --test --agent5 # Agent 5: ~2 min# Single Agent
python run.py --agent4 --no-hitlist-fetch
# Parallel all Agents (recommended)
python run.py --all --no-hitlist-fetch
# Restart from scratch
python run.py --all --no-hitlist-fetch --restart# DB cross-check only
python -m landmarkforge.validation.run --input results/candidates.csv --db-only
# With active measurement
python -m landmarkforge.validation.run --input results/candidates.csv --active-measurement
# Force validation (bypass cumulative timer threshold)
python run.py --force-validation| Argument | Description |
|---|---|
--test |
Test mode (small scale) |
--agent1 ~ --agent5 |
Run specific Agent |
--module N |
Run by number (1-5) |
--all |
Run all Agents in parallel |
--no-hitlist-fetch |
Skip download, use existing data |
--restart |
Clear all checkpoints |
--llm |
Enable LLM inference |
--llm-base-url URL |
Specify LLM endpoint |
--max-ips N |
Limit IP count (Agent 4) |
--clear |
Clear intermediate/final results |
--dry-run |
Preview cleanup (with --clear) |
--list |
List Agent statuses |
--validate |
Run validation layer |
--validation-input CSV |
Validation input CSV path |
--force-validation |
Force validation (bypass timer) |
| Agent | Checkpoint Location | Description |
|---|---|---|
| Agent 1 | state/ queue files |
Per-batch writes |
| Agent 3 | state/agent3_*.json |
Stage-level |
| Agent 4 | state/agent4_*.jsonl |
Stage-level |
| Cumulative Timer | state/pipeline_runtime.json |
Atomic writes, crash-safe |
Simply re-run after interruption to resume. Use --restart to clear.
| File | Agent | Content |
|---|---|---|
results/agent1_landmarks.csv |
1 | IP, lat/lon, city, country, ASN |
results/agent3_landmarks.csv |
3 | IPv6, coordinates, source method |
results/agent4_rdns_landmarks.csv |
4 | IP, hostname, hint, coordinates, verified |
results/agent5_cloud_landmarks.csv |
5 | IP, centroid, bucket precision, cloud provider |
results/validation_report.json |
Validator | Full validation results + evaluation metrics |
results/validated_landmarks.csv |
Validator | Standardized verified landmark CSV |
results/validation_summary.txt |
Validator | Human-readable summary |
Logs are in logs/. Parallel runs produce per-Agent logs at logs/multi_agent/agent{N}_*.log.
LandmarkForge/
├── run.py # CLI entry
├── requirements.txt # Python dependencies
├── sync_github.py # GitHub sync script
├── README.md # English documentation
├── README_CN.md # Chinese documentation
├── configs/default.yaml # Global config
├── landmarkforge/
│ ├── core/ # Data models + config management
│ │ ├── config.py # Unified configuration
│ │ ├── models.py # Data models
│ │ └── pipeline_timer.py # Cumulative runtime timer
│ ├── data_acquisition/ # Data acquisition layer
│ ├── mining/ # 5 mining Agents
│ │ ├── agent_1_llm_web/ # LLM-Web semantic mining
│ │ ├── agent_2_iot_fast/ # IoT template matching
│ │ ├── agent_3_ipv6_geo/ # IPv6 landmark mining
│ │ ├── agent_4_rdns/ # rDNS landmark mining
│ │ ├── agent_5_cloud/ # Cloud service mining
│ │ └── dual_channel_router.py # Agent 1+2 dual channel router
│ ├── validation/ # Validation layer
│ │ ├── validator.py # Unified validator
│ │ ├── db_cross_checker.py # DB consistency check
│ │ ├── active_measurement.py # CBG physical constraint
│ │ ├── probe_pool.py # Distributed probe pool
│ │ ├── rtt_measurer.py # RTT measurement
│ │ ├── confidence_scorer.py # Confidence scoring
│ │ ├── evaluation_metrics.py # Evaluation metrics
│ │ ├── reporter.py # Report generator
│ │ ├── run.py # CLI entry
│ │ ├── schedule_trigger.py # Scheduled validation trigger
│ │ ├── db_clients/ # Geolocation DB clients
│ │ └── tests/ # Unit tests
│ └── controller/ # Controller Agent (planned)
├── data/hitlists/ # IP address pool (runtime)
├── state/ # Checkpoints (runtime)
├── results/ # Output (runtime)
└── logs/ # Logs (runtime)
Q: Agent 1 reports "LLM service failed to start"?
A: Ensure the GGUF model is downloaded (see §5.1), or use --llm-base-url to specify an external API.
Q: Agent 3 reports "No IPv6 addresses"?
A: data/hitlists/ is empty. Run python -m landmarkforge.data_acquisition.hitlist_fetcher to download.
Q: Agent 4 is very slow on first run?
A: The geo-hint prefix tree is built on first run. Subsequent runs load from dict.json cache in seconds.
Q: Does it work without API keys? A: Yes. API keys only improve validation pass rate; landmarks can be produced without them.
Q: How to clean all results and restart?
A: python run.py --clear (add --dry-run to preview).
Q: How does validation auto-trigger work?
A: The cumulative runtime timer tracks total pipeline runtime across all sessions. When the threshold is reached (default: 168 hours = 1 week), validation is automatically triggered. Use --force-validation to run immediately.
@article{wu2026landmarkforge,
title={LandmarkForge: Multi-Agent and Multi-Source Landmark Mining at Internet Scale},
author={Wu, Sizhuang and Yang, Yifan and Li, Xionglve and Hou, Bingnan and Qiu, Zhenyu and Zhou, Jingwen and Cai, Zhiping},
journal={under review},
year={2026}
}Maintained by WSANsudo · National University of Defense Technology