UniFi 네트워크 관리 및 모니터링을 위한 포괄적인 도구 모음입니다.
<img alt="UI Toolkit dashboard" src="https://raw.githubusercontent.com/Crosstalk-Solutions/unifi-toolkit/HEAD/docs/images/dashboard.jpg" />
기능 (Features)
대시보드 (Dashboard)
실시간 시스템 상태를 포함합니다:
- 게이트웨이 정보 (Gateway Info) - 모델, 펌웨어, 가동 시간(uptime)
- 자원 사용량 (Resource Usage) - CPU 및 RAM 활용률
- 네트워크 상태 (Network Health) - WAN, LAN, WLAN, VPN 상태 및 진단 사유
- 연결 클라이언트 (Connected Clients) - 유선 및 무선 장치 수
- WAN 상태 (WAN Status) - IP, ISP, 지연 시간(latency), 가동 시간 (3개 이상의 WAN 동적 지원)
- 디버그 정보 (Debug Info) - 문제 보고를 위한 시스템 정보 원클릭 복사 기능
Wi-Fi Stalker
UniFi 인프라를 통해 특정 클라이언트 장치를 추적합니다.
- MAC 주소 기반 장치 추적 (무선 및 유선)
- 액세스 포인트 간 로밍 감지
- 타임스탬프가 포함된 연결 기록 및 CSV 내보내기
- 신호 강도, 라디오 대역(2.4/5/6 GHz), SSID 추적
- 장치 분석: 체류 시간(dwell time), 선호 AP, 존재 패턴 히트맵
- UI에서 장치 차단/해제
- 웹훅 알림 (Slack, Discord, n8n): 연결, 연결 해제, 로밍, 차단 및 해제 이벤트용
<img width="1355" height="702" alt="image" src="https://github.com/user-attachments/assets/383d3c84-1b24-480a-bbaf-e72c47953b85" />
위협 감시 (Threat Watch)
UniFi 게이트웨이의 IDS/IPS 보안 이벤트를 모니터링합니다.
- 실시간 이벤트 모니터링 (UniFi OS 필요)
- 위협 분류 및 분석
- 주요 공격자 및 대상
- 무시 규칙: IP 주소 및 심각도 레벨로 노이즈 필터링
- 정렬 가능한 이벤트 열 및 고급 필터링
- 웹훅 알림 (Slack, Discord, n8n)
<img width="1359" height="468" alt="image" src="https://github.com/user-attachments/assets/7bfec7f7-bdf6-4ae2-af0e-143dcd982d4a" />
가택 감금(House Arrest)
UniFi의 구역 기반 방화벽을 사용하여 장치 또는 전체 네트워크를 잠글 수 있습니다. 한 번의 클릭으로 되돌릴 수 있으며, 무엇이 차단되고 무엇이 아닌지 정확하게 알려줍니다.
- 네트워크(Networks) - VLAN에 대한 편집 가능한 감사 매트릭스: 방화벽 구역, 네트워크 격리, 인터넷 액세스, mDNS 및 DHCP DNS를 한눈에 볼 수 있으며, SSID별 Wi-Fi 클라이언트 격리가 가능합니다.
- DNS 잠금(DNS Lockdown) - 선택한 네트워크를 승인된 DNS 리졸버로 강제하고, 다른 모든 DNS 응답을 차단합니다 (선택적으로 DNS-over-TLS도 지원).
- 장치(Devices) - MAC 주소별 장치 잠금 사전 설정: 전체 잠금, 인터넷 전용, 또는 LAN 전용으로 설정할 수 있으며, 여러 장치를 선택할 수 있습니다.
- 차단된 트래픽 보기(Blocked traffic view) - 각 잠금이 실제로 무엇을 차단했는지 확인하며, ID별 자체 규칙에 귀속됩니다.
- 모든 변경 사항은 적용 전에 미리 보기가 제공되며, 모든 규칙에는 마커가 있어 해제 시 해당 규칙만 삭제할 수 있습니다. 또한, 강제 적용이 중단된 경우(MAC 주소 변경, UniFi에서 규칙 비활성화) 녹색으로 표시되는 대신 플래그가 지정됩니다.
- 구역 기반 방화벽이 필요합니다 (UniFi OS 콘솔의 UniFi Network 9.0 이상)
전체 가이드와 측정된 제한 사항을 포함하려면 docs/HOUSE-ARREST.md를 참조하세요.
<img alt="House Arrest Networks tab" src="https://raw.githubusercontent.com/Crosstalk-Solutions/unifi-toolkit/HEAD/docs/images/house-arrest.png" />
네트워크 펄스(Network Pulse)
실시간 네트워크 모니터링 대시보드입니다.
- 게이트웨이 상태 (모델, 펌웨어, 가동 시간, WAN)
- 장치 수 (총 클라이언트, 유선, 무선, AP, 스위치)
- Chart.js 시각화 (밴드별 클라이언트, SSID별 클라이언트, 최고 대역폭)
- 상세한 클라이언트 보기와 함께 클릭 가능한 AP 카드
- WebSocket 기반 실시간 업데이트
<img width="1895" height="957" alt="image" src="https://github.com/user-attachments/assets/ca6f0df5-8657-4c2a-ad16-8807aa21bcac" />
빠른 시작(Quick Start)
요구 사항(Requirements)
- Docker (권장) 또는 Python 3.9 이상
- Ubuntu 22.04/24.04 (또는 다른 Linux)
- UniFi OS 컨트롤러 (UDM, UCG, Cloud Key Gen2+). v1.11.0부터 독립형/셀프 호스팅 컨트롤러는 지원되지 않습니다.
로컬 배포(Local Deployment) (LAN 전용)
인증 필요 없음, http://localhost:8000으로 접속 가능
필수 조건: Docker를 먼저 설치하세요 - docs/INSTALLATION.md 참고
git clone https://github.com/Crosstalk-Solutions/unifi-toolkit.git
cd unifi-toolkit
...
http://localhost:8000 에서 접속하세요
프로덕션 배포 (인터넷 노출)
인증 기능 활성화, Caddy를 통한 Let's Encrypt HTTPS 적용
필수 조건: Docker를 먼저 설치하세요 - docs/INSTALLATION.md 참고
git clone https://github.com/Crosstalk-Solutions/unifi-toolkit.git
cd unifi-toolkit
...
https://your-domain.com 에서 접속하세요
문서 (Documentation)
일반 명령어 (Common Commands)
| 작업 | 명령어 |
|---|
| 시작 (로컬) | docker compose up -d |
| ... | |
Images는 GHCR (ghcr.io/crosstalk-solutions/unifi-toolkit)와 Docker Hub (crosstalksolutions/unifi-toolkit) 모두에 게시되며, 두 이미지는 동일합니다. :latest는 릴리스 채널이며 태그가 지정된 릴리스에서만 이동합니다. :edge는 베타 채널이며 매번 병합(merge)될 때 재빌드됩니다. 베타 채널 실행하기를 참조하세요. | |
설정 (Configuration)
설정 마법사 (Setup Wizard) (권장)
대화형 설정 마법사를 실행하세요:
이 마법사는 다음을 수행합니다:
- 암호화 키 생성
- 배포 모드 구성 (로컬/프로덕션)
- 인증 기능 설정 (프로덕션에서만 해당)
.env 파일 생성
수동 설정 (Manual Configuration)
예제 설정을 복사하고 편집하세요:
필수 설정 (Required Settings)
| 변수 | 설명 |
|---|
ENCRYPTION_KEY | 저장된 자격 증명 암호화 (설정 마법사에 의해 자동 생성) |
배포 설정 (Deployment Settings) (프로덕션에서만 해당)
| 변수 | 설명 |
|---|
DEPLOYMENT_TYPE | local 또는 production |
| ... | |
UniFi Controller 설정
UniFi 컨트롤러 자격 증명은 첫 실행 후 웹 UI를 통해 구성합니다 (대시보드의 톱니바퀴 아이콘). 이 정보는 환경 변수에서 읽어오는 것이 아니라 데이터베이스에 암호화되어 저장됩니다.
| 설정 (웹 UI) | 설명 |
|---|
| Controller URL | 로컬 컨트롤러 IP/호스트 이름 (예: https://192.168.1.1) |
| ... | |
참고: 컨트롤러의 로컬 IP 주소(예: https://192.168.1.1)를 사용하세요. unifi.ui.com을 통한 클라우드 액세스는 지원되지 않습니다.
기타 설정
| 변수 | 설명 |
|---|
STALKER_REFRESH_INTERVAL | 장치 새로고침 간격 (초 단위) (기본값: 60) |
| ... | |
비밀을 포함하는 모든 변수는 Docker Swarm/Kubernetes 시크릿이 파일로 마운트되는 경우에 대비하여 _FILE 변형(예. ENCRYPTION_KEY_FILE=/run/secrets/key)도 허용합니다. | |
보안
인증
- Local 모드: 인증 없음 (신뢰할 수 있는 LAN 전용)
- Production 모드: bcrypt 비밀번호 해싱을 사용한 세션 기반 인증
- 속도 제한(Rate limiting): 로그인 실패 5회 = 5분 동안 계정 잠금
HTTPS
프로덕션 배포에서는 자동 HTTPS를 위해 Caddy를 사용합니다:
- Let's Encrypt 인증서 (자동 갱신)
- HTTP에서 HTTPS로 리디렉션
- 보안 헤더 (HSTS, X-Frame-Options 등)
멀티 사이트 네트워킹
여러 UniFi 사이트를 관리할 때는 항상 사이트 간 VPN(site-to-site VPN)을 사용해야 합니다:
✅ 권장: VPN 연결
┌──────────────────┐ ┌──────────────────┐
│ UI Toolkit │◄──VPN──►│ 원격 UniFi │
...
VPN 옵션: UniFi Site-to-Site, WireGuard, Tailscale, IPSec
문제 해결 (Troubleshooting)
UniFi 컨트롤러에 연결할 수 없음
- UniFi OS 필요. 독립형(Standalone)/셀프 호스팅 컨트롤러는 지원되지 않습니다 (v1.11.0 이상). Java 기반 컨트롤러 소프트웨어를 실행하는 경우, v1.10.3이 마지막 호환 버전입니다.
- 안정화(GA) 펌웨어만 사용 가능. 얼리 액세스(Early Access) 펌웨어는 사전 통지 없이 API를 변경하므로 지원되지 않습니다. 도구가 갑자기 오류가 발생하거나 데이터가 비어 있다면, 먼저 펌웨어 채널을 확인하세요 (펌웨어 버전은 Debug Info에 있습니다).
- 자체 서명 인증서의 경우
UNIFI_VERIFY_SSL=false로 설정합니다.
- API 키 인증이 권장됩니다. UniFi OS Settings → Admins에서 생성하세요.
- 컨트롤러에 대한 네트워크 연결을 확인하세요.
장치가 온라인으로 표시되지 않음
- 다음 새로 고침 주기를 위해 60초를 기다리세요.
- MAC 주소 형식이 올바른지 확인하세요.
- UniFi 대시보드에서 장치가 연결되었는지 확인하세요.
Let's Encrypt 인증서 실패
- DNS A 레코드가 서버를 가리키는지 확인하세요.
- 포트 80과 443이 열려 있는지 확인하세요.
- Caddy 로그를 확인하세요:
docker compose logs caddy
로그인 시 속도 제한(Rate limited)
- 잠금 해제가 만료될 때까지 5분을 기다리세요.
- 비밀번호를 잊은 경우
./reset_password.sh를 사용하세요.
호스트 이름 사용 시 요청 거부
- 이 툴킷은 IP 주소,
localhost, .local-스타일 이름 또는 구성된 DOMAIN으로 지정된 요청에만 응답합니다 (anti-DNS-rebinding 보호). Tailscale MagicDNS 이름이나 리버스 프록시 별칭과 같은 다른 이름을 .env 파일의 ALLOWED_HOSTS에 추가하세요.
Docker 문제
.env 파일이 존재하며 ENCRYPTION_KEY를 포함하는지 확인하세요.- 로그를 확인하세요:
docker compose logs -f
- 최신 이미지 풀링 및 실행:
docker compose pull && docker compose up -d
Python으로 실행하기 (Docker 대안)
git clone https://github.com/Crosstalk-Solutions/unifi-toolkit.git
cd unifi-toolkit
...
프로젝트 구조
unifi-toolkit/
├── app/ # 메인 애플리케이션
│ ├── main.py # FastAPI 진입점
...
개발
테스트 실행
프로젝트에는 인증(authentication), 캐싱(caching), 설정(configuration), 암호화(encryption)를 포괄하는 테스트 스위트가 포함되어 있습니다.
pip install -r requirements-dev.txt
...
테스트 모듈:
tests/test_auth.py - 인증, 세션 관리, 속도 제한(rate limiting) (23개 테스트)tests/test_cache.py - TTL 만료를 포함한 인메모리 캐싱 (19개 테스트)tests/test_config.py - Pydantic 설정 및 환경 변수 (13개 테스트)tests/test_crypto.py - 자격 증명에 대한 Fernet 암호화 (14개 테스트)tests/test_house_arrest_policies.py - 가택 감금 정책 빌더, 구역 해상도(zone resolution), 안전 점검 (199개 테스트)
지원
커피 사주기 (Buy Me a Coffee)
UI Toolkit이 유용하다고 생각되시면, 개발 지원을 고려해 주세요:
ko-fi
크레딧
Crosstalk Solutions에서 개발
라이선스
MIT License
