korean-isp-detector

한국 인터넷 환경에 특화된 초경량 ISP 식별 및 프록시 / 데이터센터 필터링 Node.js 라이브러리입니다. 외부 유료 API 호출 없이 로컬 MMDB 파일 메모리 매핑을 통해 0ms 지연 시간으로 IP를 분석합니다.

특징

• 로컬 오프라인 0ms 지연: 네트워크 I/O 없이 메모리 인덱스 기반으로 초고속 판별
• 자동 다운로드 & 캐시 엔진: 초기 실행 시 공개 배포 MMDB 자동 캐싱 (~/.cache/korean-isp-detector/), 30일 TTL 백그라운드 갱신 및 다운로드 실패 시 무중단 폴백
• 한국 3대 통신사 & 케이블 ISP 식별: KT, SKT, SK브로드밴드, LGU+, D'LIVE, HCN, CMB, KCTV 제주방송 등 세부 구분
• 프록시 / 데이터센터 차단 지원: AWS, Azure, GCP, NAVER Cloud, Cafe24, Gabia, KINX 등 호스팅/클라우드 대역 감지 시 isSuspicious: true, isLegit: 'no'
• Apple Private Relay 감지: Cloudflare/Fastly Egress 대역 및 Safari Client Hints 감지
• 듀얼 모듈 지원: Node.js v18+ 환경에서 ESM(import) 및 CJS(require) 모두 지원, TypeScript 타입 완벽 제공

설치

npm install korean-isp-detector

사용 방법

1. 기본 사용법 (자동 초기화)

import { createDetector } from 'korean-isp-detector';

// 인스턴스 생성 및 MMDB 자동 로딩
const detector = await createDetector();

// IP 분석 (0ms)
const result = detector.lookup('121.130.0.1');
console.log(result);

2. 출력 결과 예시 (LookupResult)

{
  "ip": "121.130.0.1",
  "isLegit": "yes",
  "isKorean": true,
  "ispType": "residential",
  "ispName": "KT",
  "asn": 4766,
  "isSuspicious": false,
  "clientHints": {
    "isAppleRelaySuspected": false
  }
}

3. 클라우드 / 데이터센터 대역 판별

const result = detector.lookup('13.124.0.1');
// result.isLegit: 'no'
// result.isSuspicious: true
// result.ispType: 'datacenter'
// result.ispName: 'Amazon Web Services'

4. Apple Private Relay 감지 (Client Hints 연동)

const result = detector.lookup('104.28.1.1', {
  userAgent: req.headers['user-agent'],
});

if (result.clientHints?.isAppleRelaySuspected) {
  console.log('Apple Private Relay를 통한 접속입니다.');
}

5. 사용자 정의 설정 (자체 MMDB 파일 지정 등)

import { KoreanIspDetector } from 'korean-isp-detector';

const detector = new KoreanIspDetector({
  asnDbPath: '/path/to/GeoLite2-ASN.mmdb',
  countryDbPath: '/path/to/GeoLite2-Country.mmdb',
  autoDownload: false, // 자체 파일만 사용할 경우
  customAsnRules: {
    // 특정 ASN에 대한 커스텀 룰 오버라이드
    4766: {
      ispName: 'KT 사내 전용망',
      ispType: 'datacenter',
      isSuspicious: true,
      isLegit: 'no',
    }
  }
});

await detector.init();

인터페이스 규격

export interface LookupResult {
  ip: string;
  isLegit: 'yes' | 'no';     // 검증된 국내 정상 일반 ISP 회선인지 여부
  isKorean: boolean;         // 국가 코드가 KR인지 여부
  ispType: 'residential' | 'cable' | 'mobile' | 'datacenter' | 'education' | 'unknown';
  ispName: string;           // KT, SKT, LGU+, D'LIVE, HCN, CMB 등
  asn: number;
  isSuspicious: boolean;     // 데이터센터/호스팅/프록시 의심 여부 (차단 권장)
  clientHints?: {
    isAppleRelaySuspected: boolean; // Cloudflare/Fastly 대역이면서 사파리 접속 의심
  };
}

라이선스

MIT License