Link support codes to agent sessions

- Server: Accept support_code param in WebSocket connection
- Server: Link code to session when agent connects, mark as connected
- Server: Mark code as completed when agent disconnects
- Agent: Accept support code from command line argument
- Agent: Send hostname and support_code in WebSocket params
- Portal: Trigger agent download with code in filename
- Portal: Show code reminder in download instructions
- Dashboard: Add machines list fetching (Access tab)
- Add TODO.md for feature tracking

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2025-12-28 14:11:52 -07:00
parent 9af59158b2
commit 1d2ca47771
10 changed files with 447 additions and 21 deletions

230
TODO.md Normal file
View File

@@ -0,0 +1,230 @@
# GuruConnect Feature Tracking
## Status Legend
- [ ] Not started
- [~] In progress
- [x] Complete
---
## Phase 1: Core MVP
### Infrastructure
- [x] WebSocket relay server (Axum)
- [x] Agent WebSocket client
- [x] Protobuf message protocol
- [x] Agent authentication (agent_id, api_key)
- [x] Session management (create, join, leave)
- [x] Systemd service deployment
- [x] NPM proxy (connect.azcomputerguru.com)
### Support Codes
- [x] Generate 6-digit codes
- [x] Code validation API
- [x] Code status tracking (pending, connected, completed, cancelled)
- [~] Link support codes to agent sessions
- [ ] Code expiration (auto-expire after X minutes)
- [ ] Support code in agent download URL
### Dashboard
- [x] Technician login page
- [x] Support tab with code generation
- [x] Access tab with connected agents
- [ ] Session detail panel with tabs
- [ ] Screenshot thumbnails
- [ ] Join/Connect button
### Agent (Windows)
- [x] DXGI screen capture
- [x] GDI fallback capture
- [x] WebSocket connection
- [x] Config persistence (agent_id)
- [ ] Support code parameter
- [ ] Hostname/machine info reporting
- [ ] Screenshot-only mode (for thumbnails)
---
## Phase 2: Remote Control
### Screen Viewing
- [ ] Web-based viewer (canvas)
- [ ] Raw frame decoding
- [ ] Dirty rectangle optimization
- [ ] Frame rate adaptation
### Input Control
- [x] Mouse event handling (agent)
- [x] Keyboard event handling (agent)
- [ ] Input relay through server
- [ ] Multi-monitor support
### Encoding
- [ ] VP9 software encoding
- [ ] H.264 hardware encoding (NVENC/QSV)
- [ ] Adaptive quality based on bandwidth
---
## Phase 3: Backstage Tools (like ScreenConnect)
### Device Information
- [ ] OS version, hostname, domain
- [ ] Logged-in user
- [ ] Public/private IP addresses
- [ ] MAC address
- [ ] CPU, RAM, disk info
- [ ] Uptime
### Toolbox APIs
- [ ] Process list (name, PID, memory)
- [ ] Installed software list
- [ ] Windows services list
- [ ] Event log viewer
- [ ] Registry browser
### Remote Commands
- [ ] Run shell commands
- [ ] PowerShell execution
- [ ] Command output streaming
- [ ] Command history per session
### Chat/Messaging
- [ ] Technician → Client messages
- [ ] Client → Technician messages
- [ ] Message history
### File Transfer
- [ ] Upload files to remote
- [ ] Download files from remote
- [ ] Progress tracking
- [ ] Folder browsing
---
## Phase 4: Session Management
### Timeline/History
- [ ] Connection events
- [ ] Session duration tracking
- [ ] Guest connection history
- [ ] Activity log
### Session Recording
- [ ] Record session video
- [ ] Playback interface
- [ ] Storage management
### Notes
- [ ] Per-session notes
- [ ] Session tagging
---
## Phase 5: Access Mode (Unattended)
### Persistent Agent
- [ ] Windows service installation
- [ ] Auto-start on boot
- [ ] Silent/background mode
- [ ] Automatic reconnection
### Machine Groups
- [ ] Company/client organization
- [ ] Site/location grouping
- [ ] Custom tags
- [ ] Filtering/search
### Installer Builder
- [ ] Customized agent builds
- [ ] Pre-configured company/site
- [ ] Silent install options
- [ ] MSI packaging
---
## Phase 6: Security & Authentication
### Technician Auth
- [ ] User accounts
- [ ] Password hashing
- [ ] JWT tokens
- [ ] Session management
### MFA
- [ ] TOTP (Google Authenticator)
- [ ] Email verification
### Audit Logging
- [ ] Login attempts
- [ ] Session access
- [ ] Command execution
- [ ] File transfers
### Permissions
- [ ] Role-based access
- [ ] Per-client permissions
- [ ] Feature restrictions
---
## Phase 7: Integrations
### PSA Integration
- [ ] HaloPSA
- [ ] Autotask
- [ ] ConnectWise
### GuruRMM Integration
- [ ] Dashboard embedding
- [ ] Single sign-on
- [ ] Asset linking
---
## Phase 8: Polish
### Branding
- [ ] White-label support
- [ ] Custom logos
- [ ] Custom colors
### Mobile Support
- [ ] Responsive viewer
- [ ] Touch input handling
### Annotations
- [ ] Draw on screen
- [ ] Pointer highlighting
- [ ] Screenshot annotations
---
## Current Sprint
### In Progress
1. Link support codes to agent sessions
2. Show connected status in dashboard
### Next Up
1. Support code in agent download/config
2. Device info reporting from agent
3. Screenshot thumbnails
---
## Notes
### ScreenConnect Feature Reference (from screenshots)
- Support session list with idle times and connection bars
- Detail panel with tabbed interface:
- Join/Screen (thumbnail, Join button)
- Info (device details)
- Timeline (connection history)
- Chat (messaging)
- Commands (shell execution)
- Notes
- Toolbox (processes, software, events, services)
- File transfer
- Logs
- Settings

View File

@@ -48,6 +48,9 @@ chrono = { version = "0.4", features = ["serde"] }
# Hostname
hostname = "0.4"
# URL encoding
urlencoding = "2"
[target.'cfg(windows)'.dependencies]
# Windows APIs for screen capture and input
windows = { version = "0.58", features = [

View File

@@ -21,6 +21,10 @@ pub struct Config {
/// Optional hostname override
pub hostname_override: Option<String>,
/// Support code for one-time support sessions (set via command line)
#[serde(skip)]
pub support_code: Option<String>,
/// Capture settings
#[serde(default)]
pub capture: CaptureConfig,
@@ -119,6 +123,9 @@ impl Config {
let _ = config.save();
}
// support_code is always None when loading from file (set via CLI)
config.support_code = None;
return Ok(config);
}
@@ -137,6 +144,7 @@ impl Config {
api_key,
agent_id,
hostname_override: std::env::var("GURUCONNECT_HOSTNAME").ok(),
support_code: None, // Set via CLI
capture: CaptureConfig::default(),
encoding: EncodingConfig::default(),
};

View File

@@ -1,6 +1,12 @@
//! GuruConnect Agent - Remote Desktop Agent for Windows
//!
//! Provides screen capture, input injection, and remote control capabilities.
//!
//! Usage:
//! guruconnect-agent.exe [support_code]
//!
//! If a support code is provided, the agent will connect using that code
//! for a one-time support session.
mod capture;
mod config;
@@ -28,8 +34,25 @@ async fn main() -> Result<()> {
info!("GuruConnect Agent v{}", env!("CARGO_PKG_VERSION"));
// Parse command line arguments
let args: Vec<String> = std::env::args().collect();
let support_code = if args.len() > 1 {
let code = args[1].trim().to_string();
// Validate it looks like a 6-digit code
if code.len() == 6 && code.chars().all(|c| c.is_ascii_digit()) {
info!("Support code provided: {}", code);
Some(code)
} else {
info!("Invalid support code format, ignoring: {}", code);
None
}
} else {
None
};
// Load configuration
let config = config::Config::load()?;
let mut config = config::Config::load()?;
config.support_code = support_code;
info!("Loaded configuration for server: {}", config.server_url);
// Run the agent

View File

@@ -46,10 +46,13 @@ impl SessionManager {
pub async fn connect(&mut self) -> Result<()> {
self.state = SessionState::Connecting;
let hostname = self.config.hostname();
let transport = WebSocketTransport::connect(
&self.config.server_url,
&self.config.agent_id,
&self.config.api_key,
Some(&hostname),
self.config.support_code.as_deref(),
).await?;
self.transport = Some(transport);

View File

@@ -29,15 +29,35 @@ pub struct WebSocketTransport {
impl WebSocketTransport {
/// Connect to the server
pub async fn connect(url: &str, agent_id: &str, api_key: &str) -> Result<Self> {
// Append agent_id and API key as query parameters
pub async fn connect(
url: &str,
agent_id: &str,
api_key: &str,
hostname: Option<&str>,
support_code: Option<&str>,
) -> Result<Self> {
// Build query parameters
let mut params = format!("agent_id={}&api_key={}", agent_id, api_key);
if let Some(hostname) = hostname {
params.push_str(&format!("&hostname={}", urlencoding::encode(hostname)));
}
if let Some(code) = support_code {
params.push_str(&format!("&support_code={}", code));
}
// Append parameters to URL
let url_with_params = if url.contains('?') {
format!("{}&agent_id={}&api_key={}", url, agent_id, api_key)
format!("{}&{}", url, params)
} else {
format!("{}?agent_id={}&api_key={}", url, agent_id, api_key)
format!("{}?{}", url, params)
};
tracing::info!("Connecting to {} as agent {}", url, agent_id);
if let Some(code) = support_code {
tracing::info!("Using support code: {}", code);
}
let (ws_stream, response) = connect_async(&url_with_params)
.await

View File

@@ -24,6 +24,10 @@ pub struct AgentParams {
agent_id: String,
#[serde(default)]
agent_name: Option<String>,
#[serde(default)]
support_code: Option<String>,
#[serde(default)]
hostname: Option<String>,
}
#[derive(Debug, Deserialize)]
@@ -38,10 +42,12 @@ pub async fn agent_ws_handler(
Query(params): Query<AgentParams>,
) -> impl IntoResponse {
let agent_id = params.agent_id;
let agent_name = params.agent_name.unwrap_or_else(|| agent_id.clone());
let agent_name = params.hostname.or(params.agent_name).unwrap_or_else(|| agent_id.clone());
let support_code = params.support_code;
let sessions = state.sessions.clone();
let support_codes = state.support_codes.clone();
ws.on_upgrade(move |socket| handle_agent_connection(socket, sessions, agent_id, agent_name))
ws.on_upgrade(move |socket| handle_agent_connection(socket, sessions, support_codes, agent_id, agent_name, support_code))
}
/// WebSocket handler for viewer connections
@@ -60,8 +66,10 @@ pub async fn viewer_ws_handler(
async fn handle_agent_connection(
socket: WebSocket,
sessions: SessionManager,
support_codes: crate::support_codes::SupportCodeManager,
agent_id: String,
agent_name: String,
support_code: Option<String>,
) {
info!("Agent connected: {} ({})", agent_name, agent_id);
@@ -70,6 +78,13 @@ async fn handle_agent_connection(
info!("Session created: {}", session_id);
// If a support code was provided, mark it as connected
if let Some(ref code) = support_code {
info!("Linking support code {} to session {}", code, session_id);
support_codes.mark_connected(code, Some(agent_name.clone()), Some(agent_id.clone())).await;
support_codes.link_session(code, session_id).await;
}
let (mut ws_sender, mut ws_receiver) = socket.split();
// Task to forward input events from viewers to agent
@@ -82,6 +97,8 @@ async fn handle_agent_connection(
});
let sessions_cleanup = sessions.clone();
let support_codes_cleanup = support_codes.clone();
let support_code_cleanup = support_code.clone();
// Main loop: receive frames from agent and broadcast to viewers
while let Some(msg) = ws_receiver.next().await {
@@ -119,6 +136,13 @@ async fn handle_agent_connection(
// Cleanup
input_forward.abort();
sessions_cleanup.remove_session(session_id).await;
// Mark support code as completed if one was used
if let Some(ref code) = support_code_cleanup {
support_codes_cleanup.mark_completed(code).await;
info!("Support code {} marked as completed", code);
}
info!("Session {} ended", session_id);
}

View File

@@ -147,6 +147,27 @@ impl SupportCodeManager {
}
}
/// Link a support code to an actual WebSocket session
pub async fn link_session(&self, code: &str, real_session_id: Uuid) {
let mut codes = self.codes.write().await;
if let Some(support_code) = codes.get_mut(code) {
// Update session_to_code mapping with real session ID
let old_session_id = support_code.session_id;
support_code.session_id = real_session_id;
// Update the reverse mapping
let mut session_to_code = self.session_to_code.write().await;
session_to_code.remove(&old_session_id);
session_to_code.insert(real_session_id, code.to_string());
}
}
/// Get code by its code string
pub async fn get_code(&self, code: &str) -> Option<SupportCode> {
let codes = self.codes.read().await;
codes.get(code).cloned()
}
/// Mark a code as completed
pub async fn mark_completed(&self, code: &str) {
let mut codes = self.codes.write().await;

View File

@@ -269,17 +269,17 @@
<div class="sidebar-panel">
<div class="sidebar-section">
<div class="sidebar-section-title">Status</div>
<div class="sidebar-item active">
<div class="sidebar-item active" data-filter="all">
<span>All Machines</span>
<span class="sidebar-count">0</span>
<span class="sidebar-count" id="countAll">0</span>
</div>
<div class="sidebar-item">
<div class="sidebar-item" data-filter="online">
<span>Online</span>
<span class="sidebar-count">0</span>
<span class="sidebar-count" id="countOnline">0</span>
</div>
<div class="sidebar-item">
<div class="sidebar-item" data-filter="offline">
<span>Offline</span>
<span class="sidebar-count">0</span>
<span class="sidebar-count" id="countOffline">0</span>
</div>
</div>
<div class="sidebar-section">
@@ -289,13 +289,13 @@
</div>
</div>
</div>
<div class="main-panel">
<div class="main-panel" id="machinesList">
<div class="empty-state">
<h3>No machines</h3>
<p>Install the agent on a machine to see it here</p>
</div>
</div>
<div class="detail-panel">
<div class="detail-panel" id="machineDetail">
<div class="empty-state">
<h3>Select a machine</h3>
<p>Click a machine to view details</p>
@@ -476,6 +476,90 @@
}
loadSessions();
// Load connected machines (Access tab)
let machines = [];
let selectedMachine = null;
async function loadMachines() {
try {
const response = await fetch("/api/sessions");
machines = await response.json();
// Update counts
document.getElementById("countAll").textContent = machines.length;
document.getElementById("countOnline").textContent = machines.length;
document.getElementById("countOffline").textContent = "0";
renderMachinesList();
} catch (err) {
console.error("Failed to load machines:", err);
}
}
function renderMachinesList() {
const container = document.getElementById("machinesList");
if (machines.length === 0) {
container.innerHTML = '<div class="empty-state"><h3>No machines</h3><p>Install the agent on a machine to see it here</p></div>';
return;
}
container.innerHTML = '<div style="padding: 12px;">' + machines.map(m => {
const started = new Date(m.started_at).toLocaleString();
const isSelected = selectedMachine?.id === m.id;
return '<div class="sidebar-item' + (isSelected ? ' active' : '') + '" onclick="selectMachine(\'' + m.id + '\')" style="margin-bottom: 8px; padding: 12px;">' +
'<div style="display: flex; align-items: center; gap: 12px;">' +
'<div style="width: 10px; height: 10px; border-radius: 50%; background: hsl(142, 76%, 50%);"></div>' +
'<div>' +
'<div style="font-weight: 500;">' + (m.agent_name || m.agent_id.slice(0,8)) + '</div>' +
'<div style="font-size: 12px; color: hsl(var(--muted-foreground));">Connected ' + started + '</div>' +
'</div>' +
'</div>' +
'</div>';
}).join("") + '</div>';
}
function selectMachine(id) {
selectedMachine = machines.find(m => m.id === id);
renderMachinesList();
renderMachineDetail();
}
function renderMachineDetail() {
const container = document.getElementById("machineDetail");
if (!selectedMachine) {
container.innerHTML = '<div class="empty-state"><h3>Select a machine</h3><p>Click a machine to view details</p></div>';
return;
}
const m = selectedMachine;
const started = new Date(m.started_at).toLocaleString();
container.innerHTML =
'<div class="detail-section">' +
'<div class="detail-section-title">Machine Info</div>' +
'<div class="detail-row"><span class="detail-label">Agent ID</span><span class="detail-value">' + m.agent_id.slice(0,8) + '...</span></div>' +
'<div class="detail-row"><span class="detail-label">Session ID</span><span class="detail-value">' + m.id.slice(0,8) + '...</span></div>' +
'<div class="detail-row"><span class="detail-label">Connected</span><span class="detail-value">' + started + '</span></div>' +
'<div class="detail-row"><span class="detail-label">Viewers</span><span class="detail-value">' + m.viewer_count + '</span></div>' +
'</div>' +
'<div class="detail-section">' +
'<div class="detail-section-title">Actions</div>' +
'<button class="btn btn-primary" style="width: 100%; margin-bottom: 8px;" onclick="connectToMachine(\'' + m.id + '\')">Connect</button>' +
'<button class="btn btn-outline" style="width: 100%;" disabled>Transfer Files</button>' +
'</div>';
}
function connectToMachine(sessionId) {
// TODO: Open viewer in new window
alert("Viewer not yet implemented.\\n\\nSession ID: " + sessionId + "\\n\\nWebSocket: wss://connect.azcomputerguru.com/ws/viewer?session_id=" + sessionId);
}
// Refresh machines every 5 seconds
loadMachines();
setInterval(loadMachines, 5000);
</script>
</body>
</html>

View File

@@ -381,16 +381,26 @@
// Show instructions
showInstructions();
// For now, show a message that download will be available soon
// TODO: Implement actual download endpoint
setLoading(false);
connectBtn.querySelector('.btn-text').textContent = 'Download Starting...';
// Placeholder - in production this will download the agent
// Create a temporary link to download the agent
// The agent will be run with the code as argument
const downloadLink = document.createElement('a');
downloadLink.href = '/guruconnect-agent.exe';
downloadLink.download = 'GuruConnect-' + code + '.exe';
document.body.appendChild(downloadLink);
downloadLink.click();
document.body.removeChild(downloadLink);
// Show instructions with the code reminder
setTimeout(() => {
alert('Agent download will be available once the agent is built.\n\nSession ID: ' + sessionId);
connectBtn.querySelector('.btn-text').textContent = 'Connect';
}, 1000);
connectBtn.querySelector('.btn-text').textContent = 'Run the Downloaded File';
// Update instructions to include the code
instructionsList.innerHTML = getBrowserInstructions(detectBrowser()).map(step => '<li>' + step + '</li>').join('') +
'<li><strong>Important:</strong> When prompted, enter code: <strong style="color: hsl(var(--primary)); font-size: 18px;">' + code + '</strong></li>';
}, 500);
}
function showError(message) {