---

English

Snitch는 실시간 네트워크 트래픽 시각화 도구입니다. 컴퓨터가 만드는 모든 연결을 확인하세요 — 누구와 통신하는지, 어디에 있는지, 어떤 앱이 책임이 있는지.

전체 인터페이스는 영어와 프랑스어로 제공됩니다: 오른쪽 상단 툴바의 EN / FR 토글을 사용하세요.

왜 Snitch인가?

• vs Little Snitch / Lulu — 이들은 연결을 차단하는 macOS 방화벽입니다; Snitch는 트래픽을 시각화하고 설명하며, 크로스 플랫폼이고 무료 오픈소스입니다.
• vs GlassWire — Snitch는 무료 오픈소스(AGPL)이며, 계정이 필요 없고 외부 호출이 전혀 없습니다; 지오로케이션조차 오프라인입니다.
• vs Wireshark — Snitch는 원시 패킷 분석 대신 누구나 읽을 수 있는 실시간 고수준 개요를 제공합니다.
• vs 클라우드 기반 모니터 — 모든 것이 토큰 뒤의 127.0.0.1에서 실행됩니다; 트래픽 데이터는 절대 머신을 떠나지 않습니다.

기능

기능	설명
Force Graph	실시간 노드 그래프 — 중앙에 머신, 모든 연결이 노드로 표시
World Map	대화형 지구본 위에 애니메이션 아크로 표시되는 지오로케이션 IP
15/30/60분 타임라인	SQLite에 로컬 저장되는 슬라이딩 히스토리 (24시간 보존)
이상 탐지	포트 스캔, 비커닝, 잠재적 유출 플래그
프로세스 귀속	어떤 앱이 어떤 트래픽을 생성하는지 파악 (연결당 상위 5개)
LAN 스캐너	시스템 ARP 테이블을 통한 수동 검색 (브로드캐스트 스캔 없음)
프라이버시 점수	발신 트래픽 노출의 실시간 점수
앱별 보기	프로세스별 목적지, 볼륨 및 60분 히스토리
알림 억제	UI에서 관리 가능한 영구 "호스트/유형 무시" 규칙
설정 패널	언어, 보존, 필터, 동의 기반 GeoIP 다운로드, 진단
트래커 탐지	편집 가능한 데이터 파일로 제공되는 접미사 매칭 도메인 목록 (backend/classifier/lists/)
대역폭 모니터	실시간 MB/s 스파크라인
EN / FR UI	완전한 이중 언어 인터페이스, 클릭 한 번으로 전환

다운로드

플랫폼	패키지
macOS (Apple Silicon)	brew install --cask aixisstudio/tap/snitch — 또는 Snitch-1.0.4-macos-arm64.zip
Linux	sudo docker compose up --build — Docker (Linux) 참조
Windows	소스에서 빌드 — Build the installer 참조

또는 최신 릴리스를 받으세요: github.com/aixisstudio/Snitch/releases

macOS 첫 실행 / Premier lancement macOS — Snitch는 ad-hoc 서명되어 있으며 공증되지 않았습니다(유료 Apple Developer ID 없음). 위의 brew install --cask가 격리 플래그를 대신 제거해 줍니다. 수동 zip의 경우: 우클릭 → 열기, 또는 xattr -dr com.apple.quarantine /Applications/Snitch.app를 실행하세요. 첫 실행 시 Snitch는 관리자 비밀번호를 한 번 요청합니다 — 패킷 캡처에 필요하며, tcpdump/Wireshark와 동일합니다. UI 자체는 비권한 상태로 유지됩니다.

FR — Snitch는 ad-hoc 서명되어 있으며 공증되지 않았습니다(유료 Developer ID 없음). 위의 brew install --cask가 격리 플래그를 대신 제거해 줍니다. 수동 zip의 경우: 우클릭 → 열기, 또는 xattr -dr com.apple.quarantine /Applications/Snitch.app를 실행하세요. 첫 실행 시 Snitch는 관리자 비밀번호를 한 번 요청합니다 — 패킷 캡처에 필요하며, tcpdump/Wireshark와 동일합니다. UI는 비권한 상태로 유지됩니다.

스택

계층	기술
패킷 캡처	ctypes → libpcap — Npcap (Windows) / libpcap (Linux/macOS) — 자체 파서 (IPv4/IPv6/TCP/UDP/DNS/TLS-SNI)
백엔드 API	FastAPI — WebSockets — SQLite
프론트엔드	React 18 — Vite — D3.js v7 — TopoJSON
데스크톱 래퍼	Electron 44
지리적 위치	오프라인 전용 — DB-IP Lite (CC BY 4.0)가 backend/data/geo/에 gzip으로 번들되어 첫 실행 시 압축 해제됨; MaxMind GeoLite2 .mmdb도 지원

보안 및 개인정보 보호

• API 토큰 — 모든 REST 엔드포인트와 WebSocket에는 토큰이 필요합니다. Electron은 실행할 때마다 토큰을 생성하며, Docker/브라우저에서는 백엔드 로그에 한 번 출력되고 data/api_token.txt에 저장됩니다. http://localhost:8000/?token=<TOKEN>으로 UI를 열거나, 프롬프트가 표시되면 토큰을 입력하세요.
• 기본적으로 루프백 전용 — API는 모든 모드에서 127.0.0.1에 바인딩됩니다. LAN 접근을 명시적으로 원하는 경우에만 SNITCH_BIND=0.0.0.0을 설정하세요(토큰 인증은 여전히 적용됩니다).
• CORS/WebSocket 오리진 허용 목록 — localhost:5173, 백엔드 자체 오리진, Electron file:// 페이지만 연결할 수 있습니다.
• 지리 위치는 오프라인 전용 — 온라인 조회는 없습니다. DB-IP Lite(CC BY 4.0)는 backend/data/geo/에 gzip으로 압축된 상태로 포함되어 있으며 첫 실행 시 <data_dir>/geo/로 자동 압축 해제됩니다. 지리 기능은 별도 설정 없이 작동하며 네트워크 호출이 전혀 없습니다. 최신 GeoLite2-City.mmdb/GeoLite2-ASN.mmdb(MaxMind)를 <data_dir>/geo/에 넣거나, 설정 패널에서 새 DB-IP Lite를 다운로드할 수도 있습니다(명시적 동의 필요, 유일하게 가능한 아웃바운드 호출).
• 모든 데이터는 로컬에 유지 — snitch.db(24시간 슬라이딩 윈도우, retention_hours 설정으로 구성 가능)와 data/logs/snitch.log는 절대 머신을 떠나지 않습니다. 텔레메트리는 없습니다. 유일하게 가능한 아웃바운드 호출은 옵트인 방식의 DB-IP Lite 다운로드(설정 → "Download DB-IP Lite")이며, 명시적 클릭이 필요합니다.
• 설정 유지 — 포트 필터, 제외 프로세스, IP 허용 목록, 언어, 보존 기간은 SQLite에 저장되고 재시작 시 복원됩니다.
• 알림 억제 — 각 알림에는 "이 유형/호스트 무시" 동작이 있습니다. 억제 규칙은 영구 저장되며(alert_suppressions 테이블), 알림이 발생하거나 로깅되기 전에 적용되고, POST /alerts/ignore / DELETE /alerts/ignore / GET /alerts/ignore를 통해 재시작 후에도 유지됩니다.
• 기록 — 호스트별 및 프로세스별 분당 바이트/패킷 집계가 보존 기간 동안 SQLite(host_history, process_history)에 저장되어 애플리케이션별 보기와 GET /history/host/{ip} / GET /history/process/{name}을 지원합니다.
• 진단 — GET /diagnostics는 비밀 정보 없이 런타임(캡처 상태, 지리 DB 상태, 인터페이스, 버전, 경로)의 JSON 스냅샷을 반환합니다. 설정 패널에서 이를 내보내거나 로그 디렉터리를 열 수 있습니다(Electron).
• LAN 장치는 시스템 ARP 테이블에서 수동적으로 검색됩니다 — 활성 브로드캐스트 스캔은 없습니다. 장치 이름은 장치가 스스로 브로드캐스트하는 정보에서 학습됩니다: mDNS *.local(Apple/Linux), LLMNR 및 NetBIOS 이름(Windows), DHCP 호스트 이름 옵션, 그리고 전체 오프라인 IEEE OUI 벤더 테이블이 사용되며, 게이트웨이는 라우터로 자동 감지됩니다.
• 전체 위협 모델은 docs/threat-model.md를 참조하세요.

Docker (Linux)

Docker 배포는 Docker 외에는 아무것도 설치하지 않고 Snitch를 실행하려는 Linux 사용자를 위한 것입니다. 패킷 캡처는 network_mode: host를 통해 작동합니다 — 컨테이너가 실제 호스트 트래픽을 볼 수 있습니다.

참고: Mac/Windows의 Docker Desktop은 VM 내부에서 실행되므로 호스트의 트래픽을 캡처할 수 없습니다. 해당 플랫폼에서는 Electron 앱을 사용하세요.

# Clone and enter the repo / Cloner puis entrer dans le dépôt
git clone <your-repo-url> snitch
cd snitch

# Optional: place your MaxMind GeoLite2-City.mmdb in data/ for offline geolocation
# Optionnel : placez votre GeoLite2-City.mmdb dans data/ pour la géolocalisation hors ligne
mkdir -p data

# Build and run (requires Docker + root/sudo for raw socket capture)
# Construire et lancer (Docker + root/sudo requis pour la capture)
sudo docker compose up --build

API 토큰을 가져온 뒤(시작 시 한 번 출력되거나 cat data/api_token.txt), 브라우저에서 **http://localhost:8000/?token=TOKEN**을 엽니다.

백그라운드에서 실행하려면: sudo docker compose up -d --build

Docker 제한 사항:

• 프로세스 귀속은 컨테이너 프로세스로 제한됩니다(호스트 PID는 기본적으로 공유되지 않음)
• 일부 네트워크 구성에서는 LAN 스캐너를 사용할 수 없을 수 있습니다

개발

요구 사항:

• Python 3.11+
• Node.js 18+
• Npcap 설치(Windows 전용)
• 백엔드용 관리자/root 터미널(원시 패킷 캡처)

Demo mode / Mode démo — SNITCH_DEMO=1로 백엔드를 실행하면 합성 트래픽을 실제 파이프라인을 통해 공급합니다: root도, libpcap도, 실제 패킷도 건드리지 않습니다. 스크린샷, 테스트 및 미리보기에 이상적입니다. Lancez le backend avec SNITCH_DEMO=1 pour injecter un trafic synthétique dans le pipeline réel — ni root ni libpcap ni paquets réels.

# Backend (admin terminal) — API at http://127.0.0.1:8000
cd backend
pip install -r requirements.txt
python run_backend.py   # prints the API token once

# Frontend (separate terminal) — UI at http://localhost:5173/?token=TOKEN
cd frontend
npm install
npm run dev