# GuruConnect Requirements ## Design Principles 1. **End-user simplicity** - One-click or code-based session joining 2. **Standalone capable** - Works independently, integrates with GuruRMM optionally 3. **Technician-centric** - Built for MSP workflows --- ## End-User Portal (connect.azcomputerguru.com) ### Unauthenticated View When a user visits the portal without being logged in: ``` ┌─────────────────────────────────────────────────────┐ │ │ │ [Company Logo] │ │ │ │ Enter your support code: │ │ ┌─────────────────────────┐ │ │ │ 8 4 7 2 9 1 │ │ │ └─────────────────────────┘ │ │ │ │ [ Connect ] │ │ │ │ ───────────────────────────────────────────────── │ │ │ │ Instructions will appear here after clicking │ │ Connect, based on your browser. │ │ │ └─────────────────────────────────────────────────────┘ ``` ### Connection Flow 1. **User enters code** → Click "Connect" 2. **Server validates code** → Returns session info or error 3. **Attempt app launch** via custom protocol: - `guruconnect://session/{code}` - If app is installed, it launches and connects 4. **If app doesn't launch** (timeout ~3 seconds): - Auto-download small EXE (`GuruConnect-{code}.exe`) - Show browser-specific instructions ### Browser-Specific Instructions Detect browser via User-Agent and show appropriate guidance: **Chrome:** > "Click the download in the bottom-left corner of your screen, then click 'Open'" > [Screenshot of Chrome download bar] **Firefox:** > "Click 'Save File', then open your Downloads folder and double-click the file" > [Screenshot of Firefox download dialog] **Edge:** > "Click 'Open file' in the download notification at the top of your screen" > [Screenshot of Edge download prompt] **Safari:** > "Click the download icon in the toolbar, then double-click the file" > [Screenshot of Safari downloads] **Generic/Unknown:** > "Your download should start automatically. Look for the file in your Downloads folder and double-click to run it." ### Custom Protocol Handler **Protocol:** `guruconnect://` **Format:** `guruconnect://session/{code}` **Registration:** - Permanent agent registers protocol handler on install - One-time agent does NOT register (to avoid clutter) **Behavior:** - If registered: OS launches installed agent with session code - If not registered: Browser shows "nothing happened" → triggers download fallback ### One-Time Session Agent (Temp/Support) **Key Requirements:** - Runs in **user space** - NO admin elevation required - Downloads as `GuruConnect-{code}.exe` (code baked in) - ~3-5MB executable - Self-contained (no installer, no dependencies) - Connects directly to session on launch - Self-deletes after session ends (or on next reboot) **Elevation Note:** - Basic screen sharing works without admin - Some features (input to elevated windows, UAC dialogs) need admin - Show optional "Run as Administrator" button for full access --- ## Technician Dashboard (Logged-In View) ### Visual Style Follow GuruRMM dashboard design: - HSL CSS variables for theming (dark/light mode support) - Sidebar navigation with lucide-react icons - Card-based content areas - Responsive layout (mobile hamburger menu) - Consistent component library (Button, Card, Input) ### Navigation Structure ``` ┌──────────────────────────────────────────────────────────────┐ │ ┌──────────┐ │ │ │GuruConnect│ │ │ └──────────┘ │ │ │ │ [LIST] Support ← Active temp sessions │ │ [COMPUTER] Access ← Unattended/permanent sessions │ │ [CONFIG] Build ← Installer builder │ │ [GEAR] Settings ← Preferences, groupings, appearance │ │ │ │ ───────────── │ │ 👤 Mike S. │ │ Admin │ │ [Sign out] │ └──────────────────────────────────────────────────────────────┘ ``` ### Support Tab (Active Temporary Sessions) **Layout:** ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Support Sessions [ + Generate Code ] │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ ▼ My Sessions (3) │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 847291 │ John's PC │ Connected │ 00:15:32 │ [Join] [End] │ │ │ │ 293847 │ Waiting │ Pending │ - │ [Cancel] │ │ │ │ 182736 │ Sarah-PC │ Connected │ 00:45:10 │ [Join] [End] │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ▼ Team Sessions (2) [Howard's sessions] │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ 928374 │ DESKTOP-A │ Connected │ 00:05:22 │ [View] [Join] │ │ │ │ 746382 │ Laptop-01 │ Connected │ 01:20:15 │ [View] │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ▶ Support Requests (1) [End-user initiated] │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` **Features:** - Sessions grouped by technician (own first, then team) - Real-time status updates (WebSocket) - Duration timer for active sessions - Quick actions: Join, View (spectate), End, Cancel - Support request queue from end-user tray icon requests ### Access Tab (Unattended/Permanent Sessions) **Layout:** ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Access [SEARCH] [Search...] [ + Build ] │ ├──────────────┬──────────────────────────────────────────────────────┤ │ │ │ │ ▼ By Company │ All Machines by Company 1083 machines │ │ (empty) 120│ ─────────────────────────────────────────────────── │ │ 4 Paws 1│ ┌──────────────────────────────────────────────┐ │ │ ACG 10│ │ ● PC-FRONT01 │ Glaztech │ Win 11 │ Online │ │ │ Glaztech 224 │ ● SERVER-DC01 │ Glaztech │ Svr 22 │ Online │ │ │ AirPros 2│ │ ○ LAPTOP-SALES │ Glaztech │ Win 10 │ 2h ago │ │ │ ... │ │ ● WORKSTATION-3 │ ACG │ Win 11 │ Online │ │ │ │ │ ... │ │ │ ▶ By Site │ └──────────────────────────────────────────────┘ │ │ ▶ By OS │ │ │ ▶ By Tag │ ──────────────── Machine Detail ───────────────── │ │ │ Name: PC-FRONT01 │ │ ──────────── │ Company: Glaztech Industries │ │ Smart Groups │ Site: Phoenix Office │ │ ──────────── │ OS: Windows 11 Pro (23H2) │ │ Attention 1│ User: jsmith │ │ Online 847 IP: 192.168.1.45 / 72.194.62.4 │ │ Offline 30d 241 Serial: 8XKJF93 │ │ Offline 1yr 238 Last Seen: Now │ │ Outdated 516│ │ │ Recent 5│ [ Connect ] [ Wake ] [ Tools ▼ ] │ │ │ │ │ ▶ My Filters │ │ │ + New Filter│ │ └──────────────┴──────────────────────────────────────────────────────┘ ``` **Left Sidebar - Groupings:** - By Company (with counts, expandable) - By Site - By OS - By Tag - By Device Type - Smart Groups (auto-generated) - Custom Filters (user-created) **Main Panel:** - Machine list with status indicators (● online, ○ offline) - Quick info columns (configurable) - Click to select → shows detail panel **Right Panel - Machine Detail:** - Full machine info (Session, Device, Network sections) - Action buttons: Connect, Wake (if offline), Tools dropdown ### Build Tab (Installer Builder) **Layout:** ``` ┌─────────────────────────────────────────────────────────────────────┐ │ Build Installer │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ Name: [ Use Machine Name ▼ ] │ │ Company: [ __________________________ ] (autocomplete) │ │ Site: [ __________________________ ] (autocomplete) │ │ Department: [ __________________________ ] │ │ Device Type: [ Workstation ▼ ] │ │ Tag: [ __________________________ ] │ │ │ │ Platform: ○ Windows 64-bit (recommended) │ │ ○ Windows 32-bit │ │ ○ Linux (coming soon) │ │ │ │ ───────────────────────────────────────────────────────────────── │ │ │ │ [ Download EXE ] [ Download MSI ] [ Copy URL ] [ Send Link ] │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### Settings Tab **Sections:** **Appearance:** - Theme: Light / Dark / System - Sidebar: Expanded / Collapsed by default - Default landing tab: Support / Access **Groupings:** - Default grouping for Access tab - Show/hide specific smart groups - Configure custom filter defaults **Notifications:** - Browser notifications: On/Off - Sound alerts: On/Off - Email alerts for support requests: On/Off **Session Defaults:** - Default session visibility: Private / Team / Company - Auto-accept from specific companies **Account:** - Change password - Two-factor authentication - API keys (for integrations) --- ## Session Types ### 1. Support Sessions (Attended/One-Time) **End-User Experience:** - User visits portal (e.g., `support.azcomputerguru.com`) - Portal generates a 5-6 digit numeric code (e.g., `847291`) - User enters code OR clicks generated link - Small executable downloads and runs (no install required) - Session connects to assigned technician **Technician Experience:** - Generate session codes from dashboard - Codes can be pre-assigned to specific tech or first-come - Session appears on assigned tech's dashboard **Code Management:** - Codes remain active until used (no automatic expiration) - Anti-collision: Active codes tracked in database, never reissued while active - Once session completes, code is released back to pool - Manual code cancellation available - Optional: Tech can set manual expiration if desired - 6 digits = 1M codes, plenty of headroom for concurrent active codes ### 2. Unattended Sessions (Permanent/MSP) **Installer Builder:** Build custom installers with pre-defined metadata fields: | Field | Description | Example | |-------|-------------|---------| | Name | Machine identifier | "Use Machine Name" (auto) or custom | | Company | Client/organization | "Glaztech Industries" | | Site | Physical location | "Phoenix Office" | | Department | Business unit | "Accounting" | | Device Type | Machine category | "Workstation", "Server", "Laptop" | | Tag | Custom label | "VIP", "Critical", "Testing" | **Installer Output Options:** - Download EXE directly - Download MSI (for GPO deployment) - Copy installer URL (for deployment scripts) - Send link via email **Server-Built Installers:** - Server generates installers on-demand - All metadata (Company, Site, etc.) baked into binary - Unique installer per configuration - No manual config file editing required - Server URL and auth token embedded **MSI Support:** - MSI wrapper for Group Policy deployment - Silent install support: `msiexec /i guruconnect.msi /qn` - Uninstall via Add/Remove Programs or GPO - Transform files (.mst) for custom configurations (optional) **End-User Reconfiguration:** - Re-run installer with flags to modify settings - `--reconfigure` flag enters config mode instead of reinstall - User can change: Name, Site, Tag, Department - Changes sync to server on next check-in - Useful for when machine moves to different site/department Example: ``` guruconnect-agent.exe --reconfigure --site "New York Office" --tag "Laptop" ``` **Deployment:** - Installed as Windows service - Persists across reboots - Auto-reconnects on network changes - Can be bundled with GuruRMM agent OR standalone - Metadata fields baked into agent at build time **Management:** - Assigned to client/site hierarchy - Always available for remote access (when machine is on) - Background service, no user interaction required --- ## Technician Dashboard ### Session Visibility & Permissions | Role | Own Sessions | Team Sessions | All Sessions | |------|--------------|---------------|--------------| | Technician | Full access | View if permitted | No | | Senior Tech | Full access | View + join | View | | Admin | Full access | Full access | Full access | **Permission Model:** - Sessions created by a tech default to their dashboard - Configurable visibility: Private, Team, Company-wide - "Snoop" capability for supervisors (view session list, optionally join) - Session handoff between technicians ### Auto-Generated Groups (Sidebar) The dashboard automatically generates navigable groups based on metadata and status: **By Metadata Field:** - All Machines by Company (with counts per company) - All Machines by Site - All Machines by OS - All Machines by Tag - All Machines by Device Type **Smart Status Groups:** | Group | Definition | |-------|------------| | Attention | Machines flagged for follow-up | | Host Connected | Tech currently connected | | Guest Connected | End-user currently at machine | | Recently Accessed | Connected within last 24 hours | | Offline 30 Days | No check-in for 30+ days | | Offline 1 Year | Stale agents, cleanup candidates | | Outdated Clients | Agent version behind current | | Powered on last 10 min | Just came online | **Custom Session Groups:** - Create saved filter combinations - Name and organize custom groups - Share groups with team (optional) ### Machine Detail Panel When a machine is selected, show comprehensive info in side panel: **Session Info:** - Name, Company, Site, Department - Device Type, Tag - Hosts Connected (tech count) - Guests Connected (user present) - Guest Last Connected - Logged On User - Idle Time - Pending Activity - Custom Attributes **Device Info:** - Machine name - Operating System + Version - OS Install Date - Processor - Available Memory - Manufacturer & Model - Serial Number / Service Tag - Machine Description **Network Info:** - Public IP Address - Private IP Address(es) - MAC Address(es) **Other:** - Agent Version - Last Check-in - First Seen - Screenshot thumbnail (optional) ### Unattended Session Search **Searchable Fields:** - Hostname / Computer name - Internal IP address - External/Public IP address - Currently logged-in user - OS type (Windows 10, 11, Server 2019, etc.) - OS version/build number - Serial number - Service tag (Dell, HP, Lenovo tags) - Client/Site assignment - Custom tags/labels - Last check-in time - Agent version **Filter Capabilities:** - Last check-in: < 1 hour, < 24 hours, < 7 days, > 30 days (stale) - OS type grouping - Client/Site hierarchy - Online/Offline status - Custom saved filters (user-defined queries) **Saved Searches:** - Create and name custom filter combinations - Share saved searches with team - Pin frequently used searches --- ## Remote Control Features ### Screen Control - Real-time screen viewing - Mouse control (click, drag, scroll) - Keyboard input - Multi-monitor support (switch displays, view all) ### Clipboard Integration **Priority Feature - Full Bidirectional Clipboard:** | Direction | Content Types | |-----------|---------------| | Local → Remote | Text, Files, Images, Rich text | | Remote → Local | Text, Files, Images, Rich text | **Special Capabilities:** - **Keystroke injection from clipboard** - Paste local clipboard as keystrokes (for login screens, BIOS, pre-OS environments) - Drag-and-drop file transfer - Large file support (chunked transfer with progress) ### File Transfer - Browse remote filesystem - Upload files to remote - Download files from remote - Drag-and-drop support - Transfer queue with progress ### Backstage Tools (No Screen Required) - Remote command prompt / PowerShell - Task manager view - Services manager - Registry editor (future) - Event log viewer (future) - System info panel ### Chat / Messaging **Bidirectional Chat:** - Tech can message end user during session - End user can message tech - Chat persists across session reconnects - Chat history viewable in session log **End-User Initiated Contact:** - System tray icon for permanent agents - "Request Support" option in tray menu - User can type message/description of issue - Creates support request visible to assigned technicians **Technician Notifications:** - Dashboard shows pending support requests - Optional: Desktop/browser notifications for new requests - Optional: Email/webhook alerts for after-hours requests - Request queue with timestamps and user messages ### Credential Management (Future) **Credential Injection:** - Integration with ITGlue for credential lookup - Integration with GuruRMM credential vault - Tech selects credential from dropdown, never sees actual password - Credential injected directly as keystrokes to remote session - Audit log of which credential was used, by whom, when **Local Credential Capture (Future):** - Optional feature to capture credentials entered during session - Stored encrypted, accessible only to admins - For scenarios where client provides password verbally --- ## Security Requirements ### Authentication - Technician login with username/password - MFA/2FA support (TOTP) - SSO integration (future - Azure AD, Google) - API key auth for programmatic access ### Session Security - All traffic over TLS/WSS - End-to-end encryption for screen data - Session consent prompt (attended sessions) - Configurable session timeout ### Audit & Compliance - Full audit log: who, when, what machine, duration - Optional session recording - Action logging (file transfers, commands run) - Exportable audit reports --- ## Integration ### GuruRMM Integration - Launch remote session from RMM agent list - Share agent data (hostname, IP, user, etc.) - Single authentication - Unified dashboard option ### Standalone Mode - Fully functional without GuruRMM - Own user management - Own agent deployment - Can be licensed/sold separately --- ## Agent Requirements ### Support Session Agent (One-Time) - Single executable, no installation - Downloads and runs from portal - Self-deletes after session ends - Minimal footprint (<5MB) - No admin rights required for basic screen share - Admin rights optional for elevated access ### Unattended Agent (Permanent) - Windows service installation - Auto-start on boot - Runs as SYSTEM for full access - Configurable check-in interval - Resilient reconnection **Auto-Update:** - Agent checks for updates on configurable interval - Silent background update (no user interaction) - Rollback capability if update fails - Version reported to server for "Outdated Clients" filtering **Lightweight Performance:** - Minimal CPU/RAM footprint when idle - No performance impact during normal operation - Screen capture only active during remote session - Target: <10MB RAM idle, <1% CPU idle **Survival & Recovery:** - Survives reboots (Windows service auto-start) - Works in Safe Mode with Networking - Registers as safe-mode-capable service - Remote-initiated Safe Mode reboot (with networking) - Auto-reconnects after safe mode boot **Safe Mode Reboot Feature:** - Tech can trigger safe mode reboot from dashboard - Options: Safe Mode, Safe Mode with Networking, Safe Mode with Command Prompt - Agent persists through safe mode boot - Useful for malware removal, driver issues, repairs **Emergency Reboot:** - Force immediate reboot without waiting for processes - Bypasses "program not responding" dialogs - Equivalent to holding power button, but cleaner - Use case: Frozen system, hung updates, unresponsive machine - Confirmation required to prevent accidental use **Wake-on-LAN:** - Store MAC address for each agent - Send WoL magic packet to wake offline machines - Works within same broadcast domain (LAN) - For remote WoL: requires WoL relay/proxy on local network - Dashboard shows "Wake" button for offline machines with known MAC - Optional: Integration with GuruRMM agent as WoL relay ### Reported Metrics (Unattended) - Hostname - Internal IP(s) - External IP - Current user - OS type and version - Serial number - Service tag - CPU, RAM, Disk (basic) - Last boot time - Agent version - Custom properties (extensible) --- ## Platform Support ### Build Targets | Target | Architecture | Priority | Notes | |--------|--------------|----------|-------| | `x86_64-pc-windows-msvc` | 64-bit | Primary | Default build, Win7+ | | `i686-pc-windows-msvc` | 32-bit | Secondary | Legacy outliers | ### Phase 1 (MVP) - Windows 10/11 agents (64-bit) - Windows Server 2016+ agents (64-bit) - Web dashboard (any browser) ### Phase 2 - 32-bit agent builds for legacy systems - Windows 7/8.1 support ### Future Phases - macOS agent - Linux agent - Mobile viewer (iOS/Android) --- ## Non-Functional Requirements ### Performance - Screen updates: 30+ FPS on LAN, 15+ FPS on WAN - Input latency: <100ms on LAN, <200ms on WAN - Support 50+ concurrent unattended agents per server (scalable) ### Reliability - Agent auto-reconnect on network change - Server clustering for HA (future) - Graceful degradation on poor networks ### Deployment - Single binary server (Docker or native) - Single binary agent (MSI installer + standalone EXE) - Cloud-hostable or on-premises --- ## Team Feedback (2025-12-28) ### Howard's Requirements #### Core Remote Support & Access Capabilities 1. **Screen Sharing & Remote Control** - View and interact with the end-user's desktop in real time - Technicians can control mouse and keyboard, just like sitting at the remote machine 2. **Attended & Unattended Access** - Attended support: on-demand support sessions where the user connects via a session code or link - Unattended access: persistent remote connections that allow access anytime without user presence 3. **Session Management** - Initiate, pause, transfer, and end remote sessions - Session transfer: pass control of a session to another technician - Session pause and idle timeout controls 4. **File & Clipboard Sharing** - Drag-and-drop file transfer between local and remote systems - Clipboard sharing for copy/paste between devices 5. **Multi-Session Handling** - Technicians can manage multiple concurrent remote sessions 6. **Multi-Monitor Support** - Seamlessly switch between multiple monitors on the remote system #### Advanced Support & Administrative Functions 7. **Backstage / Silent Support Mode** - Execute tasks, run scripts, and troubleshoot without disrupting the user's screen (background session) 8. **Shared & Personal Toolboxes** - Save commonly used tools, scripts, or executables - Share them with team members for reuse in sessions 9. **Custom Scripts & Automation** - Automate repetitive tasks during remote sessions 10. **Diagnostic & Command Tools** - Run PowerShell, Command Prompt, view system event logs, uninstall apps, start/stop services, kill processes, etc. - Better PowerShell/CMD running abilities with configurable timeouts (checkboxes/text boxes instead of typing every time) #### Security & Access Control Features 11. **Encryption** - All traffic is secured with AES-256 encryption 12. **Role-Based Permissions** - Create granular technician roles and permissions to control who can do what 13. **Two-Factor & Login Security** - Support for multi-factor authentication (MFA) and other secure login methodologies 14. **Session Consent & Alerts** - Require end-user consent before connecting (configurable) - Alerts notify users of maintenance or work in progress 15. **Audit Logs & Session Recording** - Automatically record sessions - Maintain detailed logs of connections and actions for compliance #### Communication & Collaboration Tools 16. **Real-Time Chat** - Text chat between technician and end user during sessions 17. **Screen Annotations** - Draw and highlight areas on the user's screen for clearer instructions #### Cross-Platform & Mobile Support 18. **Cross-Platform Support** - Remote control across Windows, macOS, Linux, iOS, and Android 19. **Mobile Technician Support** - Technicians can support clients from mobile devices (view screens, send Ctrl-Alt-Delete, reboot) 20. **Guest Mobile Support** - Remote assistance for user Android and iOS devices #### Integration & Customization 21. **PSA & Ticketing Integrations** - Launch support sessions from RMM/PSA and other ticketing systems 22. **Custom Branding & Interface** - White-labeling, logos, colors, and custom client titles 23. **Machine Organization & Search** - Dynamic grouping of devices and custom property filtering to locate machines quickly #### Reporting & Monitoring 24. **Session & System Reports** - Audit logs, session histories, technician performance data, etc. 25. **Diagnostic Reporting** - Collect performance and diagnostic information during or after sessions ### Additional Notes from Howard - **64-bit client requirement** - ScreenConnect doesn't have a 64-bit client, which limits deployment options - **PowerShell timeout controls** - Should have UI controls (checkboxes/text boxes) for timeouts rather than typing commands every time