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

---

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