Nokia / Airtel GPON 홈 라우터 API 및 웹 대시보드

Nokia G-2425G-A GPON Home Gateway(일반적으로 Airtel Xstream Fiber 및 기타 ISP에서 배포)를 웹 대시보드, MCP(Model Context Protocol), REST API, CLI를 통해 제어, 자동화, 관리하세요 — 영구적인 기기 별명(SQLite) 및 브라우저 자동화 제로!

💡 왜 이 프로젝트인가?

문제

대부분의 홈 광섬유 라우터(Airtel의 Nokia GPON ONT 등)는 스마트 홈 생태계를 위한 공식 API나 통합 기능을 제공하지 않습니다. 다음과 같은 작업을 원할 때마다:

• 현재 Wi-Fi에 연결된 기기를 확인하거나,

• 친숙한 별명을 지정하거나(예: "Akanksha Phone", "Guestroom TV"),

• 특정 기기의 인터넷 액세스를 차단하거나(예: 자녀의 화면 시간 관리),

• 시간 또는 스마트 홈 상태에 따라 네트워크 규칙을 자동화하려는 경우...

...브라우저를 수동으로 열고, 느린 웹 포털을 탐색하고, 자격 증명을 입력하고, 여러 중첩된 설정 메뉴를 클릭해야 합니다.

설상가상으로, 라우터의 웹 포털은 복잡한 클라이언트 측 하이브리드 암호화 방식(사용자 정의 SJCL JavaScript를 통한 RSA-1024 + AES-128-CBC)을 사용하므로 간단한 curl 스크립트나 표준 HTTP 요청은 실패합니다. 대부분의 개발자는 무겁고 취약한 브라우저 자동화(Selenium이나 Puppeteer 등)에 의존하게 됩니다.

해결책

이 프로젝트는 순수 Python으로 라우터의 RSA + AES 암호화 핸드셰이크를 완전히 리버스 엔지니어링합니다.

라우터의 내부 엔드포인트와 직접 통신하여 1초 미만의 응답 시간과 브라우저 오버헤드 제로를 제공합니다. 로컬 SQLite 데이터베이스를 결합하여 영구적인 기기 메타데이터(별명, 사용자 지정 메모, 최초/마지막 확인)를 저장하고, 이 핵심 엔진을 네 가지 즉시 사용 가능한 인터페이스로 감쌉니다:

1. 🌐 웹 대시보드 — 라이브 검색, 별명 편집, 원클릭 차단/해제 토글을 갖춘 세련된 다크 글래스모피즘 웹 앱.

2. 🤖 MCP 서버 — AI 에이전트(Antigravity, Claude, Cursor 등)가 Wi-Fi를 제어하고 친숙한 별명으로 차단/해제할 수 있게 합니다.

3. ⚡ REST API(FastAPI) — Home Assistant, 웹훅, 사용자 지정 자동화에 적합합니다.

4. 🖥️ CLI — 즉각적인 터미널 명령 및 bash 스크립팅.

Related MCP server: OpenWRT SSH MCP Server

🎯 실제 사용 사례

1. 🤖 AI 에이전트 음성 및 채팅 제어(MCP를 통한)

이 프로젝트를 MCP 호환 AI 어시스턴트(예: Claude Desktop, Antigravity IDE, Cursor)에 연결하세요. 다음과 같이 말하기만 하면 됩니다:

"기기 f6:cf:28:1c:bd:e5에 'Akanksha Phone' 별명을 설정해 줘."
"Guestroom TV의 인터넷 액세스를 차단해 줘."
"Living Room TV가 지금 Wi-Fi에 연결되어 있니?"
"Akanksha Phone을 차단 해제해 줘."

AI 에이전트는 연결된 기기를 확인하고, 별명/호스트명/IP/MAC으로 대상을 식별한 다음, 라우터에서 자동으로 작업을 실행합니다.

2. 🌐 시각적 웹 대시보드

http://localhost:8000/을 열면 반응형 웹 UI에서 모든 연결된 기기를 모니터링할 수 있습니다:

• 라이브 통계 바: 총 기기 수, 온라인 활성 수, 차단 수, 사용자 지정 별명 수.

• 즉시 검색 및 필터: 전체, 온라인, 차단됨, 사용자 지정 별명으로 필터링.

• 인라인 별명 편집기: 모든 기기에 친숙한 별명과 위치 메모를 지정.

• 원클릭 차단/해제: 즉각적인 로딩 스피너와 토스트 알림으로 액세스 토글.

3. 🏠 Home Assistant 통합

REST API를 사용하여 라우터를 Home Assistant에 통합하세요:

• 취침 시간 자동화: 학교가 있는 날 밤 10시에 자녀의 태블릿과 게임 콘솔을 자동으로 차단합니다.

• 재실 감지: 특정 전화기가 네트워크에 연결되거나 떠날 때 자동화를 트리거합니다.

• 대시보드 토글: Home Assistant Lovelace 대시보드에 전용 "인터넷 차단/해제" 스위치 버튼을 만듭니다.

✨ 기능

• 🏷️ 영구 기기 별명 — SQLite(data/router.db)에 저장되므로 "Guestroom TV" 같은 사람이 읽기 쉬운 이름으로 기기를 참조할 수 있습니다.

• 🎯 스마트 다중 대상 해석 — 별명, 호스트명, IP 주소, 또는 MAC 주소로 차단/해제/조회(부분 일치 및 대소문자 무시 지원).

• 🔍 연결된 기기 목록 — 호스트명, IP 주소, MAC 주소, 온라인 활성 상태, 연결 인터페이스(Ethernet, 2.4GHz 802.11, 5GHz 802.11ac).

• 🚫 기기 차단 — 자녀 보호 규칙을 통해 모든 기기의 인터넷 액세스를 24/7 차단합니다.

• ✅ 기기 차단 해제 — 차단 규칙을 즉시 제거합니다.

• 📋 차단 정책 목록 — 모든 활성 액세스 제한 정책 및 일정을 봅니다.

• 🔄 자동 동기화 및 자가 치유 세션 — 라우터 세션이 만료되면 자동으로 재로그인하고 세션을 복구합니다.

• 🔐 브라우저 오버헤드 제로 — pycryptodome 및 requests를 통한 순수 암호화 인증.

🏗️ 아키텍처: 네 가지 상호 작용 방법

📦 설치

# Clone the repository
git clone https://github.com/surajnai567/airtel-router-api.git
cd airtel-router-api

# Install dependencies
pip install -r requirements.txt

의존성: requests, pycryptodome, python-dotenv, fastapi, uvicorn, mcp

⚙️ 구성

루트 디렉터리에 .env 파일을 만드세요(또는 .env.example에서 복사):

ROUTER_IP=192.168.1.1
ROUTER_USERNAME=admin
ROUTER_PASSWORD=your_router_password

# Optional: REST API & Dashboard settings
API_HOST=0.0.0.0
API_PORT=8000

🔒 보안 참고: .env 및 data/*.db 파일은 .gitignore에 포함되어 있으므로 라우터 자격 증명과 로컬 데이터베이스가 커밋되지 않습니다.

🌐 1. 웹 대시보드 및 REST API

서버를 시작합니다:

python -m api.server

• 브라우저에서 **http://localhost:8000/**을 열어 웹 대시보드를 확인하세요.

• **http://localhost:8000/docs**를 열어 대화형 Swagger API 문서를 확인하세요.

REST 엔드포인트

🤖 2. MCP 서버 사용법(AI 에이전트용)

Model Context Protocol(MCP)을 사용하여 라우터 도구를 AI 에이전트에 직접 노출합니다.

사용 가능한 MCP 도구

• list_devices() — Nickname, Hostname, IP, MAC, Active, Blocked, Interface가 포함된 형식화된 테이블을 반환합니다.

• set_device_nickname(target, nickname, notes=None) — 기기의 친숙한 별명을 설정하거나 업데이트합니다.

• block_device(target, policy_name=None) — 별명(예: "Guestroom TV"), 호스트명, IP 또는 MAC으로 기기를 차단합니다.

• unblock_device(target) — 별명, 호스트명, IP 또는 MAC으로 기기의 차단을 해제합니다.

• list_blocked_devices() — 활성 차단 기기와 해당 별명 및 정책을 반환합니다.

MCP 구성

이 서버를 MCP 클라이언트 구성(예: claude_desktop_config.json 또는 mcp_config.json)에 추가하세요:

{
  "mcpServers": {
    "home_router": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "d:/project/routerapi"
    }
  }
}

🖥️ 3. CLI 사용법

# List all connected/known devices (with nicknames)
python -m cli.main list

# List all currently blocked devices
python -m cli.main blocked

# Block a device by MAC address or Nickname
python -m cli.main block AA:BB:CC:DD:EE:FF

# Block a device with a custom policy name
python -m cli.main block AA:BB:CC:DD:EE:FF --name "Kid_Tablet_Block"

# Unblock a device by MAC address
python -m cli.main unblock AA:BB:CC:DD:EE:FF

🐍 4. Python 라이브러리 사용법

from core import RouterAPI

# Initialize and authenticate
router = RouterAPI(ip_address="192.168.1.1", username="admin", password="admin_password")
if router.login():
    # 1. Set a friendly nickname
    router.set_nickname("f6:cf:28:1c:bd:e5", "Akanksha Phone")

    # 2. Get all devices (auto-synced with SQLite)
    devices = router.list_devices()
    for d in devices:
        print(f"[{'ONLINE' if d['active'] else 'OFFLINE'}] {d['nickname'] or d['hostname']} ({d['ip']}) - {d['mac']}")

    # 3. Block directly by nickname!
    router.block_device("Akanksha Phone")

    # 4. Unblock by nickname!
    router.unblock_device("Akanksha Phone")

    # Clean up session
    router.logout()

📁 프로젝트 구조

routerapi/
├── core/                      # Core business logic (the engine)
│   ├── __init__.py            # Re-exports RouterAPI, DB helpers, and crypto
│   ├── client.py              # RouterAPI client class with smart target resolution
│   ├── crypto.py              # AES-CBC + RSA encryption implementation
│   └── db.py                  # SQLite database layer for persistent nicknames
│
├── api/                       # REST API & Web Dashboard
│   ├── __init__.py
│   ├── server.py              # FastAPI server with CORS, static routes, & models
│   └── static/                # Web Dashboard assets
│       ├── index.html         # Dashboard HTML template
│       ├── style.css          # Dark glassmorphism stylesheet
│       └── app.js             # Frontend state management & async API calls
│
├── mcp_server/                # Model Context Protocol interface
│   ├── __init__.py
│   └── server.py              # MCP server exposing router tools to AI
│
├── cli/                       # Terminal interface
│   ├── __init__.py
│   └── main.py                # Argparse CLI entry point
│
├── data/                      # Local SQLite storage (git-ignored)
│   └── router.db              # Persistent device metadata & nicknames
│
├── .env                       # Credentials (git-ignored)
├── .env.example               # Template environment configuration
├── .gitignore
├── requirements.txt           # Project dependencies
└── Readme.md                  # Project documentation

⚠️ 참고 사항 및 면책 조항

• 세션 만료 및 자가 치유: 라우터 세션은 비활성 상태 후 자연스럽게 시간 초과됩니다. API 및 MCP 서버는 후속 호출에서 재인증을 자동으로 관리합니다.

• 자녀 보호 호환성: 새로운 펌웨어(NPCProfileList 그룹 기반 액세스 제어)와 이전 펌웨어(pc_config 액세스 정책)를 모두 지원합니다.

• 테스트된 하드웨어: Nokia G-2425G-A GPON Home Gateway(Airtel Xstream Fiber)에서 테스트되었습니다.

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.