🔍 What process is talking? 🌐 To which domain? 🚪 Through which port?
30-second demo: status check → port explanation → process tracing → live TUI dashboard
Real-time dashboard: connections, DNS queries, timeline, and suspicious activity — all in one view
Linux debugging is fragmented. You juggle between ss, netstat, lsof, DNS logs, process trees, and firewall rules — all disconnected, all manual.
PortPulse unifies everything into a single real-time command center:
| Traditional Way | PortPulse Way |
|---|---|
ss -tupn + lsof -i + dig |
portpulse live |
| Manually correlating PIDs to connections | Auto-correlated process → port → domain mapping |
| No risk assessment | Built-in heuristic risk scoring (0.0 → 1.0) |
| Separate tools for each task | One unified TUI with 5 views |
| No DNS visibility | Real-time DNS query capture |
| No container awareness | Docker/Kubernetes container detection |
💡 Think of PortPulse as
htopfor your network — but with risk intelligence and eBPF superpowers.
# Install from source
git clone https://github.com/the-shadow-0/PortPulse.git
cd PortPulse && cargo install --path crates/cli
# Launch the dashboard (use sudo for eBPF probes)
sudo portpulse live
# Or without root (fallback mode)
portpulse live --no-ebpfThat's it. Two commands to full network visibility.
See every active connection with its owning process, user, container, and domain in real-time.
Catch every DNS resolution as it happens — see which process queried what domain, when, and what it resolved to.
Every connection is scored from 0.0 (safe) to 1.0 (critical) using heuristics:
- Suspicious TLDs (
.tk,.ml,.xyz) - Known bad ports (4444, 31337, 6667)
- Domain entropy (DGA detection)
- DNS tunneling patterns
- Unknown/unnamed processes
- Root processes on non-standard ports
A persistent alert bar at the top of the screen highlighting high-risk connections with blinking indicators.
The WOW feature — processes and domains connected by live-updating edges:
- Blue for normal connections
- Pulsing red for suspicious activity
- Port labels at edge midpoints
- Legend with node type icons
Interactive connection graph: processes ↔ domains with live risk coloring
Hierarchical view of processes with tree-drawing characters, showing connection counts per process.
Chronological log of all network events: connections opened/closed, DNS queries, policy violations.
Define custom rules:
- "Never talk to domain X"
- "Alert on port 4444"
- "Block IP range 10.0.0.0/8"
- "Alert when process Y makes connections"
Generate nftables rules to block suspicious domains:
portpulse quarantine --domain evil.tkExport to JSON or CSV for SIEM integration:
portpulse export --format json --what connections -o report.json
Unified dashboard: connections table, DNS log, and timeline in one split view
Animated graph showing process→domain connections with risk-colored edges
Deep-dive into a suspicious connection: risk score breakdown with actionable reasons
portpulse live # Interactive TUI dashboard
portpulse live --threshold 0.3 # Lower suspicious threshold
portpulse live --no-ebpf # Force /proc fallback mode
portpulse trace --pid 1234 # Trace a specific process
portpulse trace --pid 1234 -c # Include child processes
portpulse explain 443 # What's using port 443?
portpulse explain 4444 # Why is port 4444 suspicious?
portpulse quarantine -d evil.tk # Generate blocking rules
portpulse export -f csv -w all # Export everything as CSV
portpulse status # Check eBPF & system status| Key | Action |
|---|---|
1 — 5 |
Switch panels (Dashboard, Connections, DNS, Processes, Graph) |
Tab |
Cycle through panels |
j / ↓ |
Move selection down |
k / ↑ |
Move selection up |
Enter |
Open detail view for selected connection |
/ |
Filter by process name, domain, or port |
s |
Toggle sort direction |
Esc |
Back / close detail view |
q |
Quit PortPulse |
┌─────────────────────────────────────────────────────────────┐
│ User Interface │
│ ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────┐ │
│ │ TUI │ │ CLI │ │ Export │ │ Policy │ │
│ │ ratatui │ │ clap │ │ JSON/CSV │ │ Engine │ │
│ └────┬────┘ └────┬─────┘ └────┬─────┘ └──────┬───────┘ │
│ │ │ │ │ │
│ ┌────▼────────────▼─────────────▼────────────────▼───────┐ │
│ │ Core Engine │ │
│ │ ┌────────────┐ ┌────────────┐ ┌──────────────────┐ │ │
│ │ │ Aggregator │ │ Classifier │ │ Event Bus │ │ │
│ │ │ (correlate)│ │ (risk) │ │ (tokio broadcast)│ │ │
│ │ └────────────┘ └────────────┘ └──────────────────┘ │ │
│ └──────────────────────┬──────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────▼──────────────────────────────────┐ │
│ │ Event Source Layer │ │
│ │ ┌──────────────────┐ ┌────────────────────────────┐ │ │
│ │ │ eBPF Probes │ │ /proc/net Fallback │ │ │
│ │ │ (kprobes, tp) │ │ (tcp, udp, tcp6, udp6) │ │ │
│ │ │ via Aya │ │ + /proc/*/fd inode scan │ │ │
│ │ └──────────────────┘ └────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌───────────────────────────────────────────────────────────┤
│ │ Linux Kernel │
│ │ tcp_v4_connect · inet_csk_accept · udp_sendmsg │
│ │ tcp_set_state · /proc/net/* · socket inodes │
│ └───────────────────────────────────────────────────────────┘
| Component | Technology | Why |
|---|---|---|
| Core | Rust | Zero-cost abstractions, memory safety, blazing performance |
| Kernel Probes | eBPF (via Aya) | Safe kernel-level tracing without kernel modules |
| Terminal UI | Ratatui + Crossterm | Modern TUI framework with rich widgets and canvas |
| Async Runtime | Tokio | High-throughput concurrent event processing |
| CLI | Clap | Ergonomic argument parsing with color output |
| Serialization | Serde | Fast JSON/CSV export |
"Something is phoning home from this server — what process, what domain, when did it start?"
sudo portpulse live --threshold 0.3"Which container is making unexpected network calls?"
PortPulse detects Docker/containerd containers automatically via cgroup analysis.
"Show me all connections to non-standard ports by root processes."
Use the filter (/) and sort (s) in the TUI to drill down instantly.
"Export all network activity for audit review."
portpulse export --format csv --what all -o audit-report.csv"Why is my app connecting to this IP? What DNS resolution led there?"
portpulse trace --pid $(pgrep myapp) --children
portpulse explain 8080git clone https://github.com/the-shadow-0/PortPulse.git
cd PortPulse
cargo install --path crates/clicurl -sSf https://raw.githubusercontent.com/the-shadow-0/PortPulse/main/scripts/install.sh | bash# Homebrew
brew install portpulse
# Arch Linux (AUR)
yay -S portpulse
# Debian/Ubuntu
sudo dpkg -i portpulse_0.1.0_amd64.debWe welcome contributions! See CONTRIBUTING.md for details.
Please read our Code of Conduct before participating.
- Add more port descriptions to the
explaincommand - Add IPv6 support to the connection graph
- Implement sort-by-column in the connections table
- Add configurable color themes
- Write more unit tests for the classifier
- Prometheus metrics exporter
- Elasticsearch/OpenSearch sink
- Slack/Discord alerting
- Custom DNS resolvers
- GeoIP enrichment module
- Local-first: All data stays on your machine. No telemetry, no phone-home.
- Read-only eBPF: Probes are strictly observational — they cannot modify kernel state.
- No payload capture: PortPulse captures metadata (IPs, ports, PIDs) — never packet contents.
- Privilege separation: eBPF requires root; the TUI can run unprivileged with /proc fallback.
- Audit logging: Every policy violation is logged with timestamps and evidence.
For vulnerability reporting, see SECURITY.md.
- 🐛 Report a Bug
- 💡 Request a Feature
- 💬 Join Discussions
- ⭐ Star on GitHub — it helps a lot!
MIT License — see LICENSE for details.
⚡ Built with Rust, eBPF, and ❤️ for the open-source community.
If PortPulse helped you, consider giving it a ⭐ — it means the world to us!
