azcomputerguru/guru-connect
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
582387f60ee22fbda441e5a30fc9c79c90abc769
guru-connect/REQUIREMENTS.md
Mike Swanson cbb09ea524 Add portal UX and dashboard specifications 
Portal (unauthenticated):
- Code entry with browser-specific download instructions
- Custom protocol handler (guruconnect://session/{code})
- One-time agent runs in userspace, no admin required

Dashboard (authenticated):
- Support tab: Active sessions by technician, support request queue
- Access tab: Three-panel layout with groupings sidebar
- Build tab: Installer builder form
- Settings tab: Appearance, groupings, notifications, account

Visual style matches GuruRMM dashboard design

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-28 10:37:34 -07:00

693 lines
26 KiB
Markdown
Raw Blame History

# 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│ │
│ └──────────┘ │
│ │
│ 📋 Support ← Active temp sessions │
│ 🖥️ Access ← Unattended/permanent sessions │
│ 🔧 Build ← Installer builder │
│ ⚙️ 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...] [ + 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
Reference in New Issue View Git Blame Copy Permalink