domcyrus/rustnet

터미널을 위한 프로세스별 네트워크 모니터링: 심층 패킷 분석 (Deep Packet Inspection)을 포함한 실시간 TCP, UDP 및 QUIC 연결을 기본적으로 샌드박스(Sandboxed) 환경에서 제공합니다.

English | 简体中文

사용자의 기기가 생성하는 모든 연결, 해당 연결의 소유자, 그리고 사용 중인 프로토콜에 대한 실시간 가시성을 제공합니다. tcpdump, X11 포워딩(X11 forwarding) 또는 루트 파이핑(root piping)이 필요하지 않습니다.

프로세스별 귀속 (Per-process attribution): Linux에서는 eBPF, macOS에서는 PKTAP, Windows 및 FreeBSD에서는 네이티브 API를 통해 모든 TCP, UDP 및 QUIC 연결을 소유 프로세스에 매핑합니다. Wireshark와 tcpdump는 이를 수행할 수 없으며, netstat 또는 ss는 실시간 상태를 보여줄 수 없습니다.

심층 패킷 분석 (Deep packet inspection): 외부 디섹터(dissectors) 없이도 HTTP, SNI를 포함한 HTTPS/TLS, DNS, SSH, FTP, QUIC, MQTT, BitTorrent, STUN, NTP, mDNS, LLMNR, DHCP, SNMP, SSDP 및 NetBIOS를 식별합니다.

보안 샌드박싱 (Security sandboxing): Landlock (Linux 5.13+), Seatbelt (macOS), 토큰 권한 강하(token privilege drop) + job-object 자식 프로세스 차단 (Windows)을 사용합니다. libpcap이 초기화된 직후 즉시 권한을 강하합니다. SECURITY.md를 참조하십시오.

TCP 네트워크 분석 (TCP network analytics): 연결별 및 전체 합계에 대한 실시간 재전송(retransmissions), 순서가 잘못된 패킷(out-of-order packets) 및 빠른 재전송(fast-retransmit) 감지를 제공합니다.

스마트 연결 생명주기 (Smart connection lifecycle): 프로토콜을 인식하는 타임아웃과 함께 화이트(white) → 옐로우(yellow) → 레드(red) 상태의 노후화(staleness) 표시기를 제공합니다. t를 토글하여 포렌식(forensics)을 위해 과거(종료된) 연결을 계속 표시할 수 있습니다.

Vim/fzf 스타일 필터링: port:, src:, dst:, sni:, process:, state:, proto: 및 /(?i)pattern/을 통한 정규 표현식(regex)을 지원합니다.

GeoIP 강화 (GeoIP enrichment): 로컬 MaxMind GeoLite2를 통한 국가 조회를 수행합니다. 네트워크 호출은 발생하지 않습니다.

크로스 플랫폼 (Cross-platform): Linux, macOS, Windows, FreeBSD를 지원합니다.

RustNet은 단순한 연결 도구(netstat, ss)와 패킷 분석기(Wireshark, tcpdump) 사이의 간극을 메워줍니다:

프로세스 귀속 (Process attribution): 각 연결을 소유한 애플리케이션이 무엇인지 확인합니다. Wireshark는 패킷만 볼 수 있고 소켓 (socket)을 볼 수 없기 때문에 이 기능을 제공할 수 없습니다.

연결 중심 뷰 (Connection-centric view): 연결별 상태, 대역폭 및 프로토콜을 실시간으로 추적합니다.

SSH 친화적 (SSH-friendly): TUI (Text User Interface)가 SSH를 통해 작동하므로, X11 포워딩이나 트래픽 캡처 없이도 원격 서버에서 무엇이 일어나고 있는지 빠르게 확인할 수 있습니다.

RustNet은 패킷 캡처 도구를 보완합니다. 무엇이 연결을 생성하고 있는지 확인하려면 RustNet을 사용하세요. 심층적인 포렌식 분석 (forensic analysis)이 필요한 경우, --pcap-export를 사용하여 프로세스 귀속 정보가 포함된 패킷을 캡처한 다음, scripts/pcap_enrich.py로 데이터를 보강하고, 전체 PID/프로세스 컨텍스트를 포함하여 Wireshark에서 분석하십시오. 자세한 내용은 PCAP Export 및 유사 도구와의 비교 (Comparison with Similar Tools) 섹션을 참조하세요.

ratatui, libpcap, eBPF (libbpf-rs), DashMap, crossbeam, ring, MaxMind GeoLite2, 그리고 Landlock을 기반으로 구축되었습니다. 전체 의존성 상세 내역은 ARCHITECTURE.md를 참조하세요.

eBPF 강화 프로세스 식별 (Linux 기본값)

RustNet은 Linux에서 향상된 성능과 낮은 오버헤드의 프로세스 식별을 위해 기본적으로 커널 eBPF 프로그램을 사용합니다. 하지만 여기에는 중요한 제한 사항이 있습니다:

프로세스 이름 제한 사항:

• eBPF는 커널의 comm 필드를 사용하며, 이는 16자로 제한됩니다. 이는 전체 실행 파일 경로가 아닌 태스크/스레드 명령 이름을 보여줍니다.
• 멀티스레드 (Multi-threaded) 애플리케이션은 메인 프로세스 이름 대신 스레드 이름을 표시하는 경우가 많습니다.

실제 사례:

• Firefox: "Socket Thread", "Web Content", "Isolated Web Co" 또는 "MainThread"로 나타날 수 있습니다.
• Chrome: "ThreadPoolForeg", "Chrome_IOThread", "BrokerProcess" 또는 "SandboxHelper"로 나타날 수 있습니다.
• Electron 앱: 종종 "electron", "node" 또는 내부 스레드 이름으로 나타납니다.
• 시스템 프로세스: "systemd-resolve" → "systemd-resolve"와 같이 잘린 이름으로 표시됩니다.

폴백 동작 (Fallback Behavior):

• eBPF 로드에 실패하거나 충분한 권한이 없는 경우, RustNet은 자동으로 표준 procfs 기반 프로세스 식별 방식으로 폴백(Fallback)합니다.
• 표준 모드(Standard mode)는 전체 프로세스 이름을 제공하지만 CPU 오버헤드가 더 높습니다.
• eBPF는 기본적으로 활성화되어 있으며, 별도의 빌드 플래그가 필요하지 않습니다.

eBPF를 비활성화하고 procfs 전용 모드를 사용하려면 다음 명령으로 빌드하십시오:

cargo build --release --no-default-features

기술적인 정보는 ARCHITECTURE.md를 참조하십시오.

인터페이스 통계 모니터링 (Interface Statistics Monitoring)

RustNet은 지원되는 모든 플랫폼에서 실시간 네트워크 인터페이스 통계를 제공합니다:

Overview 탭: 현재 속도, 오류 및 드롭(drops)이 포함된 활성 인터페이스를 표시합니다.
Interfaces 탭(i 키를 누름): 모든 인터페이스에 대한 포괄적인 지표를 포함한 상세 테이블을 표시합니다.
크로스 플랫폼 (Cross-Platform): Linux (sysfs), macOS/FreeBSD (getifaddrs), Windows (GetIfTable2 API)
스마트 필터링 (Smart Filtering): Windows는 가상/필터 어댑터를 자동으로 제외합니다.

인터페이스 통계 해석 및 플랫폼별 동작에 대한 자세한 문서는 USAGE.md를 참조하십시오.

사용 가능한 지표 (Metrics Available):

• 총 바이트 및 패킷 (RX/TX)
• 오류 카운터 (수신 및 송신)
• 패킷 드롭 (큐 오버플로)
• 충돌 (Collision, 레거시 방식이며 현대적인 네트워크에서는 거의 사용되지 않음)

통계는 최소한의 성능 영향만 주면서 백그라운드 스레드에서 2초마다 수집됩니다.

Homebrew (macOS / Linux):

brew tap domcyrus/rustnet
brew install rustnet

Ubuntu (25.10+):

sudo add-apt-repository ppa:domcyrus/rustnet
sudo apt update && sudo apt install rustnet

Fedora (42+):

sudo dnf copr enable domcyrus/rustnet
sudo dnf install rustnet

Arch Linux:

sudo pacpac -S rustnet

From crates.io:

cargo install rustnet-monitor

Windows (Chocolatey):

# 관리자 권한의 PowerShell에서 실행
# "WinPcap API-compatible Mode"가 활성화된 상태로 설치된 Npcap (https://npcap.com)이 필요합니다
choco install rustnet

기타 플랫폼:

FreeBSD: rustnet-bsd releases에서 다운로드하세요
Docker, 소스 빌드, 기타 Linux 배포판: 자세한 지침은 INSTALL.md를 참조하세요

패킷 캡처 (Packet capture)를 위해서는 높은 권한이 필요합니다:

# 빠른 시작 (모든 플랫폼)
sudo rustnet
# Linux: sudo 없이 실행할 수 있도록 권한 (capabilities) 부여 (권장)
...

일반 옵션 (Common options):

rustnet -i eth0 # 네트워크 인터페이스 (network interface) 지정
rustnet --show-localhost # localhost 연결 표시
rustnet --no-resolve-dns # 역방향 DNS 조회 (reverse DNS lookups) 비활성화 (기본적으로 활성화됨)
...

자세한 권한 설정은 INSTALL.md를, 전체 옵션은 USAGE.md를 참조하세요.

권한 (capabilities)을 설정했음에도 TUI에서 여전히

eBPF unavailable

이 표시된다면, 문제 해결 (troubleshooting) 섹션의 "Capabilities를 설정했음에도 eBPF를 사용할 수 없는 경우"를 참조하세요.

키	동작
q	종료 (확인을 위해 두 번 누름)
Ctrl+C	즉시 종료
x	모든 연결 삭제 (확인을 위해 두 번 누름)
Tab	탭 간 전환
i	인터페이스 통계 (interface statistics) 보기 전환
↑/k ↓/j	위/아래로 이동
g G	첫 번째/마지막 연결로 점프
Enter	연결 상세 정보 보기
Esc	뒤로 가기 또는 필터 해제
c	원격 주소 (remote address) 복사
p	서비스 이름/포트 전환
d	호스트 이름/IP 전환
s S	정렬 가능한 열 순환 / 정렬 방향 전환
a	프로세스 그룹화 (process grouping) 전환
Space	프로세스 그룹 확장/축소
←/→ 또는 h/l	그룹 축소/확장
PageUp/PageDown 또는 Ctrl+B/F	페이지 탐색
t	과거 (종료된) 연결 표시 전환
r	보기 초기화 (그룹화, 정렬, 필터)
/	필터 모드 진입
h	도움말 전환

자세한 키보드 컨트롤 및 탐색 팁은 USAGE.md를 참조하세요.

빠른 필터링 예시:

/google # 어디에서든 "google" 검색
/port:443 # 포트(port)별 필터링
/process:firefox # 프로세스(process)별 필터링
...

정렬 (Sorting):

• s를 눌러 정렬 가능한 열(Protocol, Address, State, Service, Bandwidth, Process)을 순환합니다. - S (Shift+s)를 눌러 정렬 방향을 전환합니다. - 대역폭 점유가 높은 항목 찾기: s를 누르세요.

“Down/Up ↓”가 나타날 때까지 (업로드+다운로드 결합 속도 기준 정렬)

전체 필터링 구문 및 정렬 가이드는 USAGE.md를 참조하세요.

고급 필터링 예시

키워드 필터 (Keyword filters):

port:44

• "44"를 포함하는 포트 (443, 8080, 4433)

sport:80

• "80"을 포함하는 출발지 포트 (Source ports)

dport:443

• "443"을 포함하는 목적지 포트 (Destination ports)

src:192.168

• "192.168"을 포함하는 출발지 IP (Source IPs)

dst:github.com

• "github.com"을 포함하는 목적지 (Destinations)

process:ssh

• "ssh"를 포함하는 프로세스 이름 (Process names)

sni:api

• "api"를 포함하는 SNI 호스트네임 (SNI hostnames)

app:openssh

• OpenSSH를 사용하는 SSH 연결

state:established

• 프로토콜 상태 (Protocol state)로 필터링

proto:tcp

• 프로토콜 유형 (Protocol type)으로 필터링

상태 필터링 (State filtering):

state:syn_recv

• Half-open 연결 (SYN flood 탐지)

state:established

• Established 연결만 표시

state:quic_connected

• 활성 QUIC 연결

state:dns_query

• DNS 쿼리 연결

결합 예시 (Combined examples):

sport:80 process:nginx

• 80번 포트로부터의 Nginx 연결

dport:443 sni:google.com

• Google로의 HTTPS 연결

process:firefox state:quic_connected

• Firefox QUIC 연결

dport:22 app:openssh state:established

• Established된 OpenSSH 연결

연결 생명주기 및 시각적 지표 (Connection Lifecycle & Visual Indicators)

RustNet은 연결을 제거하기 전에 스마트 타임아웃 (Smart timeouts)과 시각적 경고를 사용합니다.

시각적 노후화 지표 (Visual staleness indicators):

White (흰색): 활성 상태 (타임아웃의 75% 미만)
Yellow (노란색): 노후됨 (타임아웃의 75-90%)
Red (빨간색): 임계치 도달 (타임아웃의 90% 초과)

프로토콜 인식 타임아웃 (Protocol-aware timeouts):

HTTP/HTTPS: 10분 (Keep-alive 지원)
SSH: 30분 (장기 세션)
TCP active (활성): 10분, idle (유휴): 5분
QUIC connected: 3분 (또는 피어의 transport-param idle 타임아웃이 있는 경우 해당 시간 적용); Initial / Handshaking: 60초
DNS: 30초
TCP CLOSED: 5초

예시: HTTP 연결은 7.5분에 노란색으로 변하고, 9분에 빨간색으로 변하며, 10분에 제거됩니다.

전체 타임아웃 상세 정보는 USAGE.md를 참조하세요.

INSTALL.md

• 모든 플랫폼에 대한 상세 설치 지침, 권한 설정 및 문제 해결(troubleshooting)

USAGE.md

• 명령줄 옵션(command-line options), 필터링(filtering), 정렬(sorting) 및 로깅(logging)을 포함한 전체 사용 가이드

SECURITY.md

• Landlock 샌드박싱(sandboxing) 및 권한 관리(privilege management)를 포함한 보안 기능

ARCHITECTURE.md

• 기술 아키텍처(technical architecture), 플랫폼 구현 및 성능 상세 정보

PROFILING.md

• Flamegraph 설정 및 최적화 팁을 포함한 성능 프로파일링(performance profiling) 가이드

ROADMAP.md

• 계획된 기능 및 향후 개선 사항

RELEASE.md

• 유지 관리자(maintainers)를 위한 릴리스 프로세스

기여(Contributions)를 환영합니다! 기여 방법에 대한 가이드라인은 CONTRIBUTING.md를 참조하세요.

이 프로젝트에 기여한 사람들의 목록은 CONTRIBUTORS.md를 참조하세요.

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

• 터미널 UI를 위해 ratatui로 구축됨
• libpcap 기반의 패킷 캡처(Packet capture)
• 다음과 같은 도구에서 영감을 받음:
  tshark, wireshark, tcpdump, sniffnet, netstat, ss, iftop, 그리고 bandwhich
• 일부 코드는 vibe coded (OMG) / LLM 신들이 당신과 함께하기를

더 나은 조직화를 위해 일부 섹션이 전용 파일로 이동되었습니다:

권한 설정 (Permissions Setup): 이제 INSTALL.md - Permissions Setup에 있습니다
설치 지침 (Installation Instructions): 이제 INSTALL.md에 있습니다
상세 사용법 (Detailed Usage): 이제 USAGE.md에 있습니다
아키텍처 상세 정보 (Architecture Details): 이제 ARCHITECTURE.md에 있습니다