claudetools/projects/msp-tools/guru-connect/REQUIREMENTS.md

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