ASPathLens

A relationship-aware AS path analyzer & lightweight knowledge graph for BGP policy research.

Live Demo: Frontend · API Docs · Dataset Status

---

⚠️ ASPathLens does not confirm BGP hijacks or route leaks. It only explains AS path policy suspiciousness using commercial relationships and organization mappings.

Why ASPathLens?

😫 The Problem BGP AS paths are opaque number sequences Understanding commercial relationships requires cross-referencing multiple CAIDA datasets Valley-free violations and route leak patterns are hard to spot manually No lightweight tool to explore ASN neighborhoods interactively

💡 The Solution One-paste analysis — paste an AS path, get full policy breakdown in seconds CAIDA-powered — auto-labels every hop with p2c/c2p/p2p relationships Valley-free + route leak detection with risk scoring Interactive knowledge graph — explore ASN neighborhoods with force-directed layout

---

✨ Features

	Feature	Description
🔍	Path Analyzer	Per-hop relationship labels, org mapping, valley-free check, risk score
⚖️	Path Diff	Before/after comparison: ASN delta, risk delta, relationship changes
🌐	ASN Explorer	Per-ASN profile: org info, provider/peer/customer counts, ASRank data
📦	Batch Analyzer	Upload CSV/TXT/JSON → top violation patterns, top suspicious ASNs, export
🕸️	Knowledge Graph	Force-directed graph: ASN neighborhood, path subgraph, org graph, pattern graph
🎯	Pattern Search	Search paths by relationship pattern (e.g. p2p → c2p, p2c → c2p)
📊	Dataset Status	Live CAIDA data versions, coverage stats, relationship distribution
📚	Example Gallery	Pre-built examples: route leak, valley violation, multi-hop, same-org
🔌	REST API	9+ endpoints with OpenAPI/Swagger documentation
🖥️	CLI Tool	aspathlens analyze / diff / batch / dataset commands

---

📸 Interface Preview

🔍 Path Analyzer — Full AS path policy breakdown

Paste an AS path → org names, per-hop relationships, valley-free check, route leak detection, risk score

⚖️ Path Diff — Compare two AS paths side by side

Detect ASN replacements, relationship changes, and risk score deltas between two paths

🌐 ASN Explorer — Deep-dive into a single ASN

Org info, provider/peer/customer topology, same-org ASNs, ASRank enhancement

📦 Batch Analyzer — Bulk analysis with aggregate statistics

Upload CSV/TXT/JSON → top violation patterns, suspicious ASNs, per-row results, export

🕸️ Knowledge Graph — Interactive ASN neighborhood exploration

Force-directed graph with 4 layouts: Force · Radial · Hierarchy · Grid. Click to expand neighbors.

🎯 Pattern Search — Search by relationship pattern

Find paths matching specific relationship transitions: p2p→c2p, p2c→c2p, p2c→p2p, etc.

🔌 REST API — Swagger / OpenAPI documentation

Full REST API with interactive Swagger UI at /docs

---

🏗️ Architecture

ASPathLens/
├── backend/                    # FastAPI + Python
│   ├── app/
│   │   ├── api/                # REST endpoints (analysis, batch, KG, ASN, dataset)
│   │   ├── services/           # Core logic (analyzer, valley-free, leak detection, pattern search)
│   │   ├── db/                 # SQLite schema & queries
│   │   ├── models.py           # Pydantic models
│   │   └── main.py             # FastAPI app with lifespan startup
│   ├── data/raw/               # CAIDA raw files (.bz2)
│   ├── scripts/                # Data download & parse scripts
│   └── requirements.txt
├── frontend/                   # React + Vite + Tailwind CSS
│   └── src/
│       ├── pages/              # 11 pages (Analyzer, Diff, Explorer, Batch, KG, Pattern, etc.)
│       ├── components/         # Reusable UI components
│       ├── api/                # Axios API client
│       └── i18n/               # Bilingual (EN/ZH) context
└── docs/screenshots/           # Demo GIFs

Data Pipeline

📥 Data Sources	⚙️ Processing	📊 Analysis	🖥️ Presentation
CAIDA AS Relationship CAIDA AS2Org CAIDA ASRank API	Parse → SQLite Load into memory AS path normalization	Per-hop relationship labeling Valley-free checking Route leak pattern detection Risk scoring	Web UI (11 pages) REST API (9+ endpoints) CLI tool Python library

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+
• CAIDA datasets (downloaded automatically)

Installation

# 1. Clone
git clone https://github.com/liuweihua123/ASPathLens.git
cd ASPathLens

# 2. Backend
cd backend
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 3. Download CAIDA data (~35 MB, one-time)
python scripts/update_all.py

# 4. Start backend
uvicorn app.main:app --reload --port 8000

# 5. Start frontend (new terminal)
cd frontend && npm install && npm run dev

Open http://localhost:5173 — API docs at http://localhost:8000/docs

🐳 Docker (coming soon)

docker compose up --build

---

🔌 API Reference

Method	Endpoint	Description
POST	/api/path/analyze	Full single-path analysis
POST	/api/path/diff	Compare two AS paths
POST	/api/batch/analyze/json	Batch analysis (JSON input)
POST	/api/batch/analyze/csv	Batch analysis (CSV upload)
POST	/api/pattern/search	Search paths by relationship pattern
POST	/api/report/export	Export results (JSON / CSV / Markdown)
GET	/api/asn/{asn}	ASN explorer: org info, neighbors, ASRank
GET	/api/kg/asn/{asn}	Knowledge graph for ASN neighborhood
GET	/api/dataset/status	CAIDA dataset versions & coverage
GET	/api/dataset/diff	Compare dataset versions

Example

curl -X POST http://127.0.0.1:8000/api/path/analyze \
  -H "Content-Type: application/json" \
  -d '{"as_path": "3356 4134 4837 9808"}'

Response (collapsed)

{
  "normalized_path": ["3356", "4134", "4837", "9808"],
  "relationship_sequence": ["p2c", "p2c", "p2c"],
  "valley_free": {
    "is_valid": true,
    "explanation_en": "Path follows valley-free routing policy."
  },
  "risk_score": {
    "score": 0,
    "level": "safe"
  }
}

---

🖥️ CLI Usage

# Single path analysis
aspathlens analyze "3356 4134 4837 9808" --format json

# Compare two paths
aspathlens diff "3356 4134" "3356 1299"

# Batch analysis
aspathlens batch paths.csv --output result.csv

# Dataset status
aspathlens dataset status

---

📊 Data Sources

Dataset	Source	Usage
AS Relationship (serial-2)	CAIDA	Per-hop relationship labels: p2c, c2p, p2p
AS Organizations	CAIDA	ASN → organization mapping, same-org reasoning
ASRank API	CAIDA ASRank	Rank, degree, customer cone (enhancement)

No RouteViews, RIPE RIS, BGPStream, RPKI, IRR, or PeeringDB.

---

🗺️ Roadmap

• ✅ Path Analyzer with valley-free & route leak detection
• ✅ Path Diff comparison
• ✅ ASN Explorer with ASRank integration
• ✅ Batch analysis with CSV/JSON export
• ✅ Interactive Knowledge Graph (4 layouts)
• ✅ Pattern Search by relationship sequence
• ✅ Bilingual UI (English / 中文)
• ✅ REST API with OpenAPI docs
• 🔜 Docker deployment
• 🔜 Historical BGP data integration (RouteViews / RIPE RIS)
• 🔜 RPKI validation support

---

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

---

📄 License

MIT License — see LICENSE for details.

---

Acknowledgments

• CAIDA — AS Relationship, AS2Org, and ASRank datasets
• FastAPI — Backend framework
• React · Vite · Tailwind CSS · ECharts — Frontend stack

---

---

ASPathLens 中文

面向 BGP 路由策略研究的 AS 路径分析器 和 轻量级知识图谱 工具。

输入一条 AS Path 或 ASN，ASPathLens 自动解析 AS 组织归属、逐跳商业关系、valley-free 策略、潜在 route leak 模式和 AS 邻域拓扑。

支持 Web UI · REST API · 命令行 · Python 库 四种使用方式。

⚠️ ASPathLens 不能确认 BGP 劫持或路由泄露。 仅基于 AS 商业关系和组织归属判断路径策略可疑性。

---

📸 功能预览

🔍 路径分析器 粘贴 AS Path → 组织路径、逐跳关系、valley-free、route leak、风险评分	⚖️ 路径对比 Before/After 路径对比：ASN 变化、关系变化、风险差异
🌐 ASN 探索 单个 ASN 深度画像：组织信息、provider/peer/customer、ASRank	📦 批量分析 CSV/TXT/JSON 批量分析 → Top 违规模式、可疑 ASN、导出
🕸️ 知识图谱 力导向图谱探索 ASN 邻域，支持 Force / Radial / Hierarchy / Grid 四种布局	🎯 模式搜索 按关系模式搜索路径：p2p→c2p、p2c→c2p、p2c→p2p

---

🚀 快速开始

环境要求

• Python 3.11+
• Node.js 18+

安装与启动

# 1. 克隆项目
git clone https://github.com/liuweihua123/ASPathLens.git
cd ASPathLens

# 2. 后端
cd backend
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -r requirements.txt

# 3. 下载 CAIDA 数据（约 35 MB，仅需一次）
python scripts/update_all.py

# 4. 启动后端
uvicorn app.main:app --reload --port 8000

# 5. 启动前端（新终端）
cd frontend && npm install && npm run dev

打开 http://localhost:5173 — API 文档：http://localhost:8000/docs

---

🔌 API 接口

方法	接口	说明
POST	/api/path/analyze	单路径完整分析
POST	/api/path/diff	两条路径对比
POST	/api/batch/analyze/json	批量分析（JSON）
POST	/api/batch/analyze/csv	批量分析（CSV）
POST	/api/pattern/search	按关系模式搜索
POST	/api/report/export	导出报告（JSON / CSV / Markdown）
GET	/api/asn/{asn}	ASN 探索：组织、邻居、ASRank
GET	/api/kg/asn/{asn}	ASN 知识图谱
GET	/api/dataset/status	数据集状态
GET	/api/dataset/diff	数据集版本对比

---

📊 数据来源

数据集	来源	用途
AS Relationship (serial-2)	CAIDA	逐跳商业关系标注：p2c、c2p、p2p
AS Organizations	CAIDA	ASN → 组织映射、同组织推理
ASRank API	CAIDA ASRank	Rank、degree、customer cone（增强数据）

---

📄 许可证

MIT License — 详见 LICENSE。

---

致谢

• CAIDA — AS Relationship、AS2Org、ASRank 数据集
• FastAPI · React · Vite · Tailwind CSS · ECharts