{"id":36223854,"url":"https://github.com/shblue21/ntomb","last_synced_at":"2026-01-11T05:02:47.598Z","repository":{"id":327565412,"uuid":"1104251105","full_name":"shblue21/ntomb","owner":"shblue21","description":"🎃 A Halloween-themed terminal TUI for visualizing Linux network connections. Monitor \"undead\" connections with coffins, ghosts, and zombies while maintaining clarity for SREs and security engineers. Built with Rust + Ratatui. Kiroween 2025 hackathon submission.","archived":false,"fork":false,"pushed_at":"2025-12-16T15:20:02.000Z","size":2796,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T21:32:58.757Z","etag":null,"topics":["halloween-theme","linux","netstat","network-monitoring","ratatui","rust","security","sre-tools","terminal","tui"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shblue21.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-26T00:49:36.000Z","updated_at":"2025-12-16T15:20:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shblue21/ntomb","commit_stats":null,"previous_names":["shblue21/ntomb"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shblue21/ntomb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shblue21%2Fntomb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shblue21%2Fntomb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shblue21%2Fntomb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shblue21%2Fntomb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shblue21","download_url":"https://codeload.github.com/shblue21/ntomb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shblue21%2Fntomb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28287032,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T04:44:51.577Z","status":"ssl_error","status_checked_at":"2026-01-11T04:44:44.232Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["halloween-theme","linux","netstat","network-monitoring","ratatui","rust","security","sre-tools","terminal","tui"],"created_at":"2026-01-11T05:02:46.978Z","updated_at":"2026-01-11T05:02:47.577Z","avatar_url":"https://github.com/shblue21.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ntomb – undead connections monitor\n\n**A terminal TUI that visualizes network \"undead\" connections using graveyard and coffin metaphors**\n\n\u003e **Kiroween 2025 Submission Version**: [`kiroween-2025-submission`](https://github.com/yourusername/ntomb/releases/tag/kiroween-2025-submission)  \n\u003e This tag marks the official submission version for the Kiroween 2025 hackathon (submitted December 5, 2025).  \n\u003e Development continues on the main branch with bug fixes and new features.\n\n---\n\n## Screenshots\n\n### Main Interface\n![ntomb main interface](./docs/screenshots/main-ui.png)\n*The Graveyard (left) visualizes network topology with radial node layout, while Soul Inspector (top right) shows detailed connection info and Traffic History (middle right) displays real-time activity. Active Connections panel (bottom right) lists all sockets with state-based colors.*\n\n\u003c!-- TODO: add Host mode vs Process mode comparison --\u003e\n\n\u003c!-- TODO: add Kiroween Overdrive mode demo --\u003e\n\n\u003c!-- TODO: add suspicious connections detection demo --\u003e\n\n---\n\n## Introduction\n\nntomb is a terminal-based monitoring tool that visualizes network connections on Linux systems in real-time. Unlike traditional tools like `netstat` and `ss` that display connections as flat lists, ntomb presents the relationship between hosts and endpoints intuitively through a **Halloween-themed graphical interface**.\n\nNetwork endpoints are arranged radially around a central coffin (⚰️), with different icons and colors representing connection states. While leveraging \"undead\" metaphors like zombie processes (💀), active connections (🎃), and fading connections (👻), ntomb maintains the **clarity and readability** needed by SREs and security engineers in production environments.\n\n---\n\n## Features\n\n### 🕸️ The Graveyard (Network Topology)\n- **Central HOST Coffin (⚰️)**: Displays current host or selected process at the center\n- **Radial Node Layout**: Endpoints arranged in 3 rings based on network zones (local/private/public)\n- **Braille Art Rendering**: Smooth curves using Canvas widget with Braille markers\n- **Connection State Visualization**: \n  - 🎃 ESTABLISHED (active connections)\n  - 👻 TIME_WAIT (fading connections)\n  - 💀 CLOSE_WAIT (zombie connections)\n  - 👂 LISTEN (listening sockets)\n- **Legend Display**: Icon meanings shown as `[⚰️ host 🏠 local 🎃 ext 👑 hot]`\n- **Summary Statistics**: Real-time display of Endpoints, Listening, and Total counts\n\n### 🔮 Soul Inspector (Detail Panel)\n- **Target Information**: Detailed info for selected host/process\n  - TARGET: Name and icon\n  - ROLE: Server/client/public connection counts\n  - STATE: Active/listening connection status\n  - CONN: Total connection count and PID\n  - RISK: Suspicious connection detection (high-port, non-standard patterns)\n  - SCAN: Refresh interval display\n- **Blockified Layout**: Information clearly organized by category\n\n### 📊 Traffic History (Last 60s)\n- **Real-time Activity Sparkline**: Visualizes network activity over the last 60 seconds\n- **Statistics Display**: Shows Avg/Peak activity scores\n- **Mode-specific Data**: Different data for Host mode (all connections) vs Process mode (selected process)\n\n### 📜 Open Sockets / 🌐 Active Connections\n- **Connection List**: All active connections in a scrollable list\n- **Process Information**: Owning process shown with `[name(pid)]` tag\n- **State-based Colors**: ESTABLISHED (green), LISTEN (white), TIME_WAIT (orange), CLOSE (red)\n- **Selection Highlight**: Currently selected connection highlighted with Deep Indigo background\n\n### 🎨 Kiroween Overdrive Mode\n- **Enhanced Halloween Theme**: Toggleable enhanced visual effects with 'H' key\n- **Animations**: Dynamic visual effects like pulse and zombie blinking (toggle with 'A' key)\n- **Adaptive Performance**: Automatically reduces animation complexity when connection count is high\n\n### 🔧 Cross-Platform Emoji Rendering\n- **Auto-Detection**: Detects terminal emoji width at startup for accurate positioning\n- **Manual Adjustment**: Fine-tune with `[` / `]` keys if icons appear misaligned\n- **Environment Variables**: `NTOMB_EMOJI_WIDTH_OFFSET`, `NTOMB_ASCII_MODE` for customization\n\n### ⌨️ Keyboard Navigation\n- **Intuitive Shortcuts**: Always displayed in the status bar at the bottom\n- **Mode Switching**: Toggle between Host mode ↔ Process mode with 'P' key\n- **Refresh Rate Control**: Real-time adjustment with '+'/'-' keys\n- **Panel Switching**: Move focus with Tab key\n\n### 🔧 .kiro-based Design\n- **Spec-driven Development**: Requirements, design, and tasks documented in `.kiro/specs/`\n- **Steering Guides**: Visual design, security domain, and coding style guides in `.kiro/steering/`\n- **MCP Integration**: Model Context Protocol server implementation in `ntomb_mcp/` (suspicious detection rules)\n\n---\n\n## Installation\n\n### Requirements\n- **OS**: Linux (macOS has limited support)\n- **Rust**: 1.70 or higher\n- **Dependencies**: \n  - `netstat2` (cross-platform socket information)\n  - `sysinfo` (process information)\n  - `ratatui` + `crossterm` (TUI rendering)\n\n### Build from Source\n\n```bash\n# Clone repository\ngit clone https://github.com/yourusername/ntomb\ncd ntomb\n\n# Build\ncargo build --release\n\n# Run\n./target/release/ntomb\n```\n\n### Install via Cargo\n\n```bash\ncargo install --path .\n```\n\n---\n\n## Usage\n\n### Basic Execution\n\n```bash\n# Run in Host mode (default)\nntomb\n\n# Focus on specific process (switch with 'P' key after launch)\nntomb\n# → Select a connection and press 'P' key\n```\n\n### Common Use Cases\n\n1. **Finding Undead Connections on Local Development Machine**\n   - Run in Host mode to check TIME_WAIT and CLOSE_WAIT connections across the system\n   - Discover zombie processes or resource leak patterns\n\n2. **Monitoring Network Activity of Specific Process**\n   - Select a suspicious connection and press 'P' key to focus on that process\n   - Analyze activity patterns over the last 60 seconds using Traffic History\n\n3. **Detecting Security Anomalies**\n   - Check RISK line for suspicious connections (high-port, non-standard patterns)\n   - Discover unexpected connections to public IPs\n\n4. **Network Debugging**\n   - Real-time monitoring of connection states between services\n   - Identify performance issues using latency-based ring layout\n\n---\n\n## Interaction / Keybindings\n\n| Key | Description |\n|-----|-------------|\n| `↑` / `↓` | Move up/down in connection list |\n| `P` | Toggle process focus (Host ↔ Process mode) |\n| `+` / `=` | Decrease refresh rate (increase interval) |\n| `-` / `_` | Increase refresh rate (decrease interval) |\n| `A` | Toggle animations (pulse, zombie blinking, etc.) |\n| `H` | Toggle Kiroween Overdrive mode (enhanced Halloween theme) |\n| `T` | Toggle endpoint labels (show/hide IP:port) |\n| `[` / `]` | Adjust emoji width offset (for cross-platform rendering) |\n| `\\` | Reset emoji width offset to auto-detected value |\n| `Q` / `Esc` | Quit |\n\n**Status Bar Indicators:**\n- `[A:ON/OFF]` - Animation state\n- `[H:ON/OFF]` - Overdrive mode state\n- `[t:ON/OFF]` - Label display state\n- `[E:±N]` - Emoji width offset (for cross-platform compatibility)\n\n---\n\n## Architecture / Design\n\n### Core Components\n\n- **`src/net/mod.rs`**: Network connection scanning\n  - Cross-platform socket information collection using `netstat2` library\n  - TCP connection state parsing and Connection struct creation\n\n- **`src/procfs/mod.rs`**: Process mapping (Linux-only)\n  - Socket inode extraction by scanning `/proc/\u003cpid\u003e/fd/*`\n  - Process name reading from `/proc/\u003cpid\u003e/comm`\n  - Graceful handling of permission errors\n\n- **`src/app/mod.rs`**: Application state management\n  - `AppState`: Connection data, mode, settings, animation state\n  - `GraveyardMode`: Host / Process mode switching\n  - `RefreshConfig`: Dynamic refresh interval adjustment\n\n### UI Layer\n\n- **`src/ui/banner.rs`**: Header (title, tagline, global statistics)\n- **`src/ui/graveyard.rs`**: Network topology map\n  - Canvas widget + Braille markers\n  - Network zone-based ring layout (local/private/public)\n  - Coffin rendering and exclusion zone\n- **`src/ui/inspector.rs`**: Soul Inspector + Traffic History\n  - Blockified information layout\n  - Activity history display using Sparkline widget\n- **`src/ui/grimoire.rs`**: Connection list (Open Sockets / Active Connections)\n- **`src/ui/status_bar.rs`**: Bottom status bar (key bindings, toggle states)\n\n### Theme System\n\n- **`src/theme/mod.rs`**: Color palette definition\n  - Neon Purple, Pumpkin Orange, Blood Red, Toxic Green, Bone White\n  - Icon mapping for Overdrive mode\n\n### .kiro Spec Structure\n\n```\n.kiro/\n├── specs/\n│   ├── ui-skeleton/          # UI layout and interaction\n│   ├── process-focus/        # Process focus feature\n│   ├── configurable-refresh/ # Refresh rate control\n│   ├── graveyard-adaptive-layout/ # Adaptive layout\n│   ├── ntomb-graveyard-vfx/  # Visual effects and animations\n│   ├── network_map.yaml      # Network map configuration\n│   └── suspicious_detection.yaml # Suspicious connection detection rules\n└── steering/\n    ├── visual-design.md      # Color, layout, widget design guide\n    ├── security-domain.md    # Security principles, read-only, detection heuristics\n    └── ntomb-coding-style.md # Rust coding style, testing strategy\n```\n\n---\n\n## Limitations / Roadmap\n\n### Current Limitations\n\n- **Linux Primary Support**: macOS has limited support (no procfs functionality)\n- **Root Privileges**: sudo required to view process information of other users\n- **Terminal Size**: Minimum 80x24 recommended; smaller sizes may break layout\n- **Actual Byte Transfer**: Currently displays connection activity score only (kB/s not supported)\n- **BPF Integration**: eBPF-based real-time packet capture not yet implemented (shown as \"TBD\" in UI)\n\n### Planned Features\n\n- [ ] **Actual Byte Transfer Display**: `ss -i` parsing or eBPF integration\n- [ ] **Enhanced Suspicious Detection**: Expand `.kiro/specs/suspicious_detection.yaml` rules\n- [ ] **Full MCP Server Integration**: External tool integration via ntomb_mcp\n- [ ] **Filtering and Search**: Filter by specific IP, port, or process name\n- [ ] **Log Export**: Save connection history to JSON/CSV\n- [ ] **Plugin System**: Custom detection rules and visualization extensions\n\n---\n\n## Development\n\n### Development Environment Setup\n\n```bash\n# Install dependencies\ncargo build\n\n# Run tests\ncargo test\n\n# Code formatting\ncargo fmt\n\n# Linting\ncargo clippy\n\n# Release build (optimized + stripped)\ncargo build --release\n```\n\n### Testing Strategy\n\n- **Unit Tests**: Located in `#[cfg(test)]` blocks within each module\n- **Property-Based Tests**: Using `proptest` (some planned for implementation)\n- **Integration Tests**: In `tests/` directory (to be added)\n\n### Code Structure Principles\n\n- **Read-only Principle**: Never modifies system state (security-domain.md)\n- **Graceful Degradation**: Elegantly handles permission errors, platform differences, etc.\n- **Clear Separation**: Distinct layers for data collection (net, procfs) / business logic (app) / UI (ui)\n\n---\n\n## Contributing\n\nntomb is an open-source project and welcomes contributions!\n\n### Contribution Guidelines\n\n1. **Code Style**: Must pass `cargo fmt` and `cargo clippy`\n2. **Testing**: Add tests for new features\n3. **Documentation**: Write doc comments for public APIs\n4. **Issues/PRs**: Use GitHub Issues and Pull Requests\n\nBug reports, feature suggestions, and code contributions are all welcome!\n\n---\n\n## License\n\nMIT License\n\nSee [LICENSE](LICENSE) file for details.\n\n---\n\n## Credits\n\n**Built with:**\n- [Ratatui](https://github.com/ratatui-org/ratatui) - Rust TUI framework\n- [Crossterm](https://github.com/crossterm-rs/crossterm) - Cross-platform terminal control\n- [netstat2](https://github.com/zhongzc/netstat2) - Network socket information library\n- [sysinfo](https://github.com/GuillaumeGomez/sysinfo) - System/process information\n- [Kiro AI](https://kiro.ai) - Spec-driven development assistant\n\n**Inspired by:**\n- `netstat`, `ss`, `lsof`, `iftop` - Classic network tools\n- Halloween 🎃 - Inspiration for the undead metaphor\n\n---\n\n**💀 \"Revealing the unseen connections of the undead.\" 💀**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshblue21%2Fntomb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshblue21%2Fntomb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshblue21%2Fntomb/lists"}