🗺️ Borges

Borges (Better ORGanizations Entities mappingS) maps Autonomous Systems (ASes) to the organizations that operate them. It finds sibling ASes run by the same company, even when WHOIS lists them under different organizations. It combines CAIDA's WHOIS-based AS2Org and PeeringDB with two new signals: LLM extraction of sibling ASNs from PeeringDB's free-text fields, and website inference from redirect chains, domain similarity and favicons. It is the code of the ACM IMC 2025 paper Learning AS-to-Organization Mappings with Borges.

✨ Features

• 🏢 Organization keys: groups ASes by CAIDA AS2Org (WHOIS) organization IDs and PeeringDB organization IDs
• 🤖 LLM sibling extraction: few-shot prompting reads PeeringDB notes and aka fields and keeps only real sibling ASNs, not phone numbers, years or prefix limits
• 🔀 Redirect analysis: networks whose websites resolve to the same final URL are grouped together
• 🖼️ Favicon analysis: shared favicons plus similar domains reveal common branding; a vision LLM rejects framework defaults (WordPress, Bootstrap, …)
• 🧩 Consolidation: merges every signal into network groups, with blocklists for known false bridges
• 💾 Robust pipeline: nine stages with checkpoint/resume, parallel scraping with caching, and Parquet/JSON/CSV exports
• 💸 Free to run: tests and CI need no key. The LLM stages can be skipped or pointed at a local model

🚀 Quick Start

pip install borges                   # or: uv pip install borges
borges init                          # writes config.yaml (prompts, blocklists), .env and data/
borges download                      # latest PeeringDB + AS2Org snapshots into data/input/
borges pipeline run                  # needs an LLM key, or see below to skip it

From a clone (for development):

git clone https://github.com/NU-AquaLab/borges.git
cd borges
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

📖 Usage

Pipeline stages

Commands

borges pipeline list                                   # stages and their dependencies
borges pipeline run                                    # full run
borges pipeline run --stage redirect_scraping --stage as_detection   # selected stages
borges pipeline run --skip favicon_analysis            # skip stages
borges pipeline run --resume                           # continue from checkpoints
borges pipeline run --dry-run                          # show what would run
borges --config my-config.yaml pipeline run            # or: export BORGES_CONFIG=...
borges download --peeringdb-date 2025-07-16 --as2org-date 2025-07-01

borges --help lists the rest (report generate, favicon download, config, version).

💸 Running without a paid API key

Only stages 3 and 6 call an LLM. Pick one option:

With Ollama (ollama pull llama3.2 and ollama pull llama3.2-vision), set this in config.yaml:

api:
  openai:
    api_key: unused                       # local servers ignore it, but it must be set
    base_url: http://localhost:11434/v1
    model: llama3.2
    vision_model: llama3.2-vision

Programmatic use

from borges.config import load_config, set_config
from borges.pipeline import Pipeline

config = load_config("config.yaml")
set_config(config)
pipeline = Pipeline(config)
results = pipeline.run(skip_stages=["as_detection", "favicon_analysis"])

🗃️ Output

export_results writes timestamped files to data/output/:

The main settings in config.yaml:

🔬 Methodology (brief)

The full method is in the paper (PDF). In short:

• Organization keys. Start from organization IDs in CAIDA's AS2Org (WHOIS) and in PeeringDB.
• Information extraction. Few-shot prompting of gpt-4o-mini (temperature 0) recovers sibling ASNs written in PeeringDB's notes and aka fields. Earlier work used regular expressions, which confuse phone numbers, years and prefix limits with ASNs.
• Website inference.
  • Redirects: networks whose PeeringDB websites end at the same final URL are siblings. For example, Limelight (AS22822) and Edgecast (AS15133) both redirect to www.edg.io.
  • Favicons: websites with the same favicon and the same subdomain are grouped. Remaining shared favicons go to a vision-LLM classifier that separates company logos (Claro Chile and Claro Puerto Rico) from framework defaults (Bootstrap, WordPress).
• Consolidation. All signals are merged into organization groups.

Results on the July 2024 PeeringDB and AS2Org snapshots:

⚠️ Known limitations

• No website history. There is no longitudinal archive of the websites listed in PeeringDB, so past runs cannot be reproduced exactly from the code alone. Keep your inputs and outputs.
• PeeringDB coverage is partial. Registration is voluntary, and entries can be incomplete or outdated. For example, some Microsoft ASNs are missing.
• Errors in the input propagate. If a PeeringDB record lists the wrong sibling, Borges faithfully extracts the wrong sibling (e.g. AS10026 listing AS2706).
• Layered ownership is out of scope. Groups spanning separate brands and regions are not linked, such as América Móvil's Claro and A1.
• False merges through weak signals. One favicon or website shared by unrelated networks can chain them into one group. The optional merge guard prevents most of these. It is off by default until its results are reviewed.
• Known false bridges are handled by configuration:
  • AS4004 appears under Orange in PeeringDB but under Sprint in WHOIS. It is listed in peeringdb_asn_exclusions.
  • Shared PeeringDB listings and default favicons can wrongly join small networks to large operators. They are covered by blocklists in config.yaml.
• LLM output varies by model. The published numbers are for gpt-4o-mini. Local or newer models need their own validation.

🏗️ Architecture

src/borges/
├── cli.py                  # Click CLI: init | pipeline | report | favicon | config | version
├── config.py               # Pydantic config, ${ENV} interpolation, global get_config()/set_config()
├── pipeline/
│   ├── runner.py           # Pipeline: stage ordering, dependencies, checkpoints
│   └── stages.py           # the nine stages
├── analyzers/              # LLM sibling extraction, redirects, WHOIS, number validation, consolidation
├── scrapers/               # redirect, HTML and favicon scrapers
├── data/                   # loaders, processors, exporters
├── models/                 # AS network model and Pydantic schemas
└── utils/                  # LLM client (OpenAI-compatible), HTTP client, logging
scripts/                    # download_data.py (= borges download), evaluate_merge_guard.py, check_wheel.py
config.yaml                 # default configuration, prompts and blocklists (shipped in the wheel)
data/reference/             # negative favicon samples (framework defaults)
tests/                      # unit tests; no network, no API key

🧪 Development

uv pip install -e ".[dev]"
ruff check src tests scripts --select E9,F63,F7,F82   # syntax errors and undefined names
black --check src tests                               # formatting (black 26)
mypy src/borges                                       # informational for now
pytest                                                # no network, no API key
git config blame.ignoreRevsFile .git-blame-ignore-revs   # hide the bulk reformat from blame

See CONTRIBUTING.md for the full workflow.

📊 Example Output

$ borges pipeline run --skip as_detection --skip favicon_analysis --dry-run
Pipeline dry run - stages that would be executed:
  ✓ load_data: Load initial data from PeeringDB and WHOIS.
  ✓ redirect_scraping: Scrape redirect information from websites (no HTML content).
  ✓ redirect_analysis: Analyze URL redirects.
  ✓ favicon_download: Scrape favicons from websites.
  ✓ whois_processing: Process WHOIS data.
  ✓ network_consolidation: Consolidate network groups from different analysis sources.
  ✓ export_results: Export final results.

🤝 Contributing

Bug fixes, documentation, tests and new signals are welcome. Please open an issue before large changes. See CONTRIBUTING.md, the Code of Conduct, and SECURITY.md to report a vulnerability privately.

1. Fork the repository
2. Create a feature branch (git checkout -b fix/my-fix)
3. Commit your changes (git commit -m 'Fix …')
4. Push to the branch (git push origin fix/my-fix)
5. Open a Pull Request

📄 License

MIT.

📝 Citation

If you use Borges, please cite the paper. It is also in CITATION.cff, which feeds GitHub's Cite this repository button:

@inproceedings{borges:imc,
  author    = {Selmo, Carlos and Carisimo, Esteban and Bustamante, Fabi{\'a}n E. and Alvarez-Hamelin, J. Ignacio},
  title     = {Learning AS-to-Organization Mappings with Borges},
  booktitle = {Proceedings of the 2025 ACM Internet Measurement Conference},
  series    = {IMC '25},
  year      = {2025},
  month     = {10},
  location  = {Madison, WI, USA},
  publisher = {Association for Computing Machinery},
  doi       = {10.1145/3730567.3732918},
  url       = {https://doi.org/10.1145/3730567.3732918}
}

🔗 Related Resources

• Paper: ACM Digital Library · PDF
• Website and artifacts: nu-aqualab.github.io/borges-website (September 2025 mappings)
• Press: Mapping Who Really Runs the Internet: Introducing Borges (Internet Society Pulse)
• CAIDA AS2Org: AS Organizations dataset and the PeeringDB archive
• as2org+: Arturi, Carisimo and Bustamante, as2org+: Enriching AS-to-Organization Mappings with PeeringDB, PAM 2023
• State-Owned ASes: estcarisimo/state-owned-ases, a hand-built dataset where Borges-style automation could help

🙏 Acknowledgements

• Paper: Learning AS-to-Organization Mappings with Borges
• Authors: Carlos Selmo, Esteban Carisimo, Fabián E. Bustamante, J. Ignacio Alvarez-Hamelin
• Conference: ACM Internet Measurement Conference (IMC) 2025, Madison, WI, USA
• Funding: NSF grant CNS-2107392 and UBACyT 20020220100053BA

Thanks to CAIDA for archiving PeeringDB snapshots and publishing AS2Org, to PeeringDB, and to @zhiyichenGT for the consolidator and WHOIS fixes.