aimili-vpngate 딥다이브
— 공개 VPN 서버 목록을 VPS의 HTTP·SOCKS5 프록시로 바꾸는 파이썬 게이트웨이

1프로젝트 한줄 요약

AimiliVPN은 리눅스 VPS 한 대 위에서 VPN Gate 노드 목록을 가져와 OpenVPN으로 연결하고, 그 연결을 HTTP·HTTPS(CONNECT)·SOCKS5 프록시와 웹 관리 화면으로 제공하는 도구입니다. 저장소 이름의 “vpngate”는 일본 쓰쿠바대학이 운영하는 학술 프로젝트 VPN Gate를 가리키며, 이 저장소는 그 서비스의 공개 API를 소비하는 쪽입니다.

검토한 커밋은 2cd7dc58이며 VERSION 파일은 2.1.5, 라이선스는 GPL-3.0입니다. 추적 파일은 25개이고 핵심은 파이썬 5개와 설치 스크립트 1개입니다. 도커 이미지와 일반 리눅스 소스 설치를 모두 지원합니다.

1-1. 이 저장소가 하는 일 한눈에

1-2. 용도와 경계

README의 사용 범위 조항은 합법적인 네트워크 연구, 교육, 개발 테스트, 프라이버시 보호만 허용하고 규제 우회·무단 접근·공격·스팸·사기를 금지한다고 적습니다. 소스 안에도 공격 도구나 탐지 회피 기능은 보이지 않았습니다(7장 끝과 11장 참고). 이 문서는 도구의 구조를 설명하는 학습 자료이며 특정 지역의 이용 가능 여부를 판단해 주지 않습니다.

이 저장소에서 가져갈 핵심은 “남이 만든 접속 설정 파일을 실행하기 전에 무엇을 허용하고 무엇을 거부할지 코드로 정해 두는 방법”입니다.

2왜 주목받는가

TrendShift 목록에서 이 저장소는 23위로 잡혔습니다. 이 순위는 모멘텀 점수이며 설치 수나 품질을 뜻하지 않습니다. 릴리스는 v2.1.3, v2.1.4, v2.1.5가 확인되고, 최신 커밋 시각은 2026-10-14, 전체 커밋은 91개입니다.

2-1. 코드에서 설명되는 매력

• 설치가 한 줄: install.sh가 패키지 설치(apt/apk/dnf/yum), /opt/aimilivpn 배포, systemd 또는 OpenRC(init.d) 서비스 등록, 관리 명령 ml 생성까지 처리합니다.
• 노드 소스가 끊겨도 동작: 공식 API가 막힌 환경을 가정해 GitHub Pages 미러, VPS에 저장된 마지막 스냅샷, 저장소에 동봉된 mirror/vpngate.csv(약 99행)까지 내려갑니다.
• VPS 자체 접속은 건드리지 않음: 기본 경로를 VPN으로 바꾸지 않고, 프록시 소켓만 tun0에 묶습니다. SSH 같은 기존 연결이 끊기지 않게 하는 설계입니다(4장).
• 회귀 테스트가 두껍다: tests/test_manager_logic.py 1,131줄에 테스트 함수 53개가 있고 릴리스 워크플로가 파이썬 3.9·3.11·3.13과 도커 4개 아키텍처를 검사합니다.

2-2. 비슷한 도구와의 위치

3기술 스택 전체 지도

저장소에 requirements.txt나 pyproject.toml이 없습니다. 파이썬 쪽은 http.server, socket, subprocess, urllib, csv, base64, threading 같은 표준 라이브러리로 구성됩니다. 실제 터널링은 외부 프로그램인 OpenVPN이 맡고, 경로 설정은 ip(iproute2)와 sysctl을 호출합니다.

3-1. 계층별 구성

3-2. 코드 규모 (검토 커밋 기준)

4아키텍처 심화 분석

4-1. 전체 시스템 구조도

4-2. 노드 소스 폴백 체인

api_network_sources()는 네 개의 주소를 순서대로 돌려줍니다: official_https, official_http, github_pages_https, github_pages_http_redirect_https. 환경 변수 VPNGATE_API_HTTPS_URL 등으로 바꿀 수 있습니다. 성공한 HTTPS 응답만 로컬 캐시에 저장하고, 평문 HTTP로 받은 데이터는 신뢰 캐시를 덮어쓰지 않습니다(test_http_source_does_not_replace_trusted_cache). 마지막 단계로 번들 스냅샷이 캐시를 시드합니다.

4-3. 접속 설정 파일 허용 목록 (가장 중요한 설계)

VPN Gate의 각 행에는 base64로 인코딩된 .ovpn 파일이 들어 있습니다. OpenVPN 설정은 up, script-security, plugin 같은 지시어로 로컬 프로그램을 실행할 수 있어서 제3자 파일을 그대로 쓰면 위험합니다. snapshot_utils.py는 이를 허용 목록으로 막습니다.

# snapshot_utils.py (요지)
MAX_CONFIG_BYTES = 128 * 1024
SAFE_DIRECTIVES = {"auth","cipher","client","dev","proto","remote",
    "remote-cert-tls","tls-client","verb", ...}   # 총 40개
SAFE_INLINE_BLOCKS = {"ca","cert","key","tls-auth","tls-crypt"}

for raw_line in config_text.splitlines():
    directive = parts[0].lstrip("-").lower()
    if directive not in SAFE_DIRECTIVES:
        raise ValueError(f"Unsafe OpenVPN directive: {directive}")
    # dev 는 tun* 만, remote 는 포트 1~65535, ca/cert/key 블록 필수

목록에 없는 지시어가 한 줄이라도 있으면 그 행은 버려지고(parse_and_validate_snapshot()의 except ... continue), 인라인 블록은 다섯 종류만 허용됩니다. test_snapshot_rejects_executable_openvpn_directive가 실행형 지시어 거부를 검사합니다. 허용 목록 방식이라 OpenVPN에 새 지시어가 생겨도 기본이 “거부”라는 점이 블랙리스트보다 안전합니다.

4-4. 경로 분리: 기본 경로는 그대로, 프록시만 VPN으로

setup_policy_routing()은 ip route add default dev tun0 table 100과 ip rule add oif tun0 table 100을 실행하고 rp_filter를 loose(2)로 낮춥니다. 그리고 proxy_server.create_connection()은 외부로 나가는 소켓마다 SO_BINDTODEVICE로 tun0를 지정합니다. 효과는 이렇습니다.

• 프록시를 거친 트래픽만 VPN 노드를 통과합니다.
• VPS의 SSH, 웹 관리 화면, 패키지 업데이트는 원래 경로로 갑니다.
• DNS 조회도 resolve_dns_over_tun0()가 터널 안에서 8.8.8.8로 직접 보내 로컬 DNS 누수를 줄입니다.

SOCKS5와 HTTP는 같은 포트를 씁니다. proxy_client()가 첫 1바이트를 읽어 0x05이면 SOCKS5, 아니면 HTTP로 처리하는 단순한 프로토콜 판별입니다. 동시 연결은 BoundedSemaphore로 기본 256개까지이고, 환경 변수 LOCAL_PROXY_USER·LOCAL_PROXY_PASS를 주면 기본 인증이 켜집니다(secrets.compare_digest 비교).

4-5. 연결 모드와 상태 머신

후보 우선순위는 probe_priority_key()가 (핑 오름차순, 점수 내림차순, 속도 내림차순, 접속 세션 수 오름차순) 튜플로 정합니다. 자동 전환은 연속 3번 실패하면 중단하고 백그라운드 보충 스레드를 하나만 띄웁니다(auto_switch_node()). 상태는 “터널 준비”와 “프록시 출구 준비”로 나뉘어, 둘 다 통과해야 화면에 “연결됨”이 뜹니다.

4-6. IP 유형 분류

같은 VPN Gate 노드라도 가정용 회선이냐 데이터센터냐에 따라 쓸모가 다릅니다. classify_ip_type()은 ip-api.com의 mobile·hosting·proxy 플래그와 ISP/조직명 패턴으로 주거/모바일/데이터센터/미확인을 나누고, 근거가 약하면 ipapi.is로 2차 확인합니다. 소스 주석처럼 “proxy 플래그는 주거 여부를 바꾸지 않고 품질 정보로만 남깁니다”.

5디렉토리 구조 해부

5-1. 처음 읽을 순서

1. snapshot_utils.py (173줄): 허용 목록 검증. 가장 짧고 가장 배울 것이 많습니다.
2. proxy_server.py (474줄): 소켓 프로그래밍 교재처럼 읽힙니다.
3. vpngate_manager.py의 openvpn_command → run_openvpn_until_ready → connect_node 순서.
4. tests/test_manager_logic.py: 의도한 동작을 문장처럼 적은 테스트 이름들.

5-2. 미러 파이프라인

update-vpngate-mirror.yml은 매시 7·22·37·52분에 실행되어 build_vpngate_mirror.py로 공식 API를 받고, snapshot_utils로 같은 검증을 거친 결과를 GitHub Pages에 올립니다. 클라이언트와 미러가 같은 검증 모듈을 공유하므로 미러가 이상한 설정을 올려도 클라이언트가 한 번 더 걸러냅니다. vpngate.meta.json에는 행 수(검토 시점 99), 바이트 수, sha256이 들어 있지만, 앱은 이 메타를 신선도 표시에 쓰며(read_mirror_freshness()) 해시 검증에 쓰는 코드는 찾지 못했습니다.

6학습 포인트 (기술별)

6-1. 비판적으로 읽을 점

• 세션 토큰이 고정 방식입니다. get_session_token()은 sha256(username:password + 고정 솔트)를 돌려줍니다. 로그인할 때마다 새 무작위 값을 만드는 구조가 아닙니다. 한편 active_sessions 딕셔너리로 만료(30일)를 관리하는 부분은 별도로 있습니다.
• 로그인 시도 제한을 찾지 못했습니다. 비밀 경로와 무작위 계정·비밀번호에 의존하는 구조로 보입니다. 확인한 범위의 관찰이며 없다고 단정하지는 않습니다.
• 관리 화면은 HTTP입니다. TLS 종단이 없으므로 SSH 터널(README 권고)이나 리버스 프록시가 사실상 필요합니다.
• 대형 단일 파일. 7천 줄 파일에 UI와 로직이 섞여 있어 변경 영향 범위를 파악하기 어렵습니다.

7하드웨어 / 시스템 요구사항

법적 측면: README는 VPS 제공자 약관과 해당 지역 법률이 VPN/TUN 사용을 허용하는지 먼저 확인하라고 요구합니다. VPN Gate 노드 운영자가 접속 기록을 남길 수 있으므로 계정·금융 정보를 이 경로로 보내지 말라는 경고도 README에 있습니다. 코드 검토에서 원격 코드 실행, 실행 파일 내려받기, 데이터 외부 전송 같은 악성 동작은 발견하지 못했습니다(검토한 파일: 파이썬 5개, 설치 스크립트, Dockerfile, 워크플로 2개).

8직접 해볼 수 있는 실습 과제

과제 1 — 동봉 스냅샷 직접 검증해 보기 입문

저장소를 받아 읽기 전용으로 스냅샷 파일의 구조를 확인합니다. 아래 스크립트는 네트워크에 접속하지 않고 validate_openvpn_config만 호출합니다. 신뢰할 수 없는 폴더에서 바로 실행하지 말고 별도 작업 폴더에 복사한 코드만 사용하세요.

git clone https://github.com/OpenMili/aimili-vpngate
cd aimili-vpngate
python3 - <<'PY'
import snapshot_utils as s
text = open("mirror/vpngate.csv", encoding="utf-8").read()
rows = s.parse_and_validate_snapshot(text)
print("통과한 노드:", len(rows))
print("국가 분포:", sorted({r["CountryShort"] for r in rows}))
PY

과제 2 — 위험한 지시어가 거부되는지 눈으로 확인 입문

최소 설정 문자열에 script-security 2 한 줄을 넣고 validate_openvpn_config()를 호출해 Unsafe OpenVPN directive 예외가 나는지 확인합니다. 그 다음 tests/test_manager_logic.py의 test_snapshot_rejects_executable_openvpn_directive와 비교해 보세요.

과제 3 — 우선순위 함수 바꿔 보기 초급

probe_priority_key()의 정렬 키 순서를 바꿔 (속도 우선)으로 만들고, 예시 노드 딕셔너리 5개로 어떤 순서가 되는지 비교합니다. 실제 파일을 고치지 말고 복사본에서 해보세요.

과제 4 — 프록시 서버만 격리 실행 중급

테스트용 VPS 또는 VM에서만 진행합니다. proxy_server.py는 tun0에 묶여 있으므로 일반 환경에서는 외부 연결이 실패하는 것이 정상입니다. 이 실패 메시지(ERR_ROUTE_DEV_NOT_FOUND)가 코드의 어느 분기에서 오는지 추적해 보는 것이 학습 목표입니다.

과제 5 — 도커로 설치하고 7928 포트 확인 중급

TUN을 지원하는 일회용 VPS에서만 합니다. 공개 노드는 신뢰할 수 없다는 전제로, 로그인 정보가 필요한 서비스에는 쓰지 않습니다.

docker compose pull && docker compose up -d
docker exec aimilivpn cat /data/ui_auth.json     # 계정과 비밀 경로
ssh -N -L 8787:127.0.0.1:8787 -L 7928:127.0.0.1:7928 root@VPS_IP
curl --proxy socks5h://127.0.0.1:7928 https://api.ipify.org

확인할 것: 출력된 IP가 VPS의 원래 IP와 다른가, 웹 관리 화면에서 노드를 “테스트”했을 때 핑 값이 갱신되는가, VPS의 SSH가 끊기지 않는가. 공개 포트를 열지 말고 SSH 터널로만 접속하세요.

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• github.com/OpenMili/aimili-vpngate — 분석 대상 저장소
• github.com/baoweise-bot/aimili-vpngate — 소스 안에서 저장소 주소로 쓰이는 이름
• vpngate.net — VPN Gate 공식 사이트
• OpenVPN 2.6 레퍼런스 매뉴얼
• RFC 1928 — SOCKS Protocol Version 5