claudetools/projects/msp-tools/guru-rmm/agent/CLAUDE_INTEGRATION.md

# Claude Task Executor Integration - GuruRMM Agent

## Integration Status: [SUCCESS]

Successfully integrated Claude Code task execution capabilities into the GuruRMM Agent.

## Date: 2026-01-21

## Files Modified

### 1. New Files Added
- **src/claude.rs** - Complete Claude task executor module
  - Working directory validation (restricted to C:\Shares\test)
  - Task input sanitization (command injection prevention)
  - Rate limiting (max 10 tasks per hour)
  - Concurrent execution limiting (max 2 simultaneous tasks)
  - Comprehensive error handling and logging

### 2. Modified Files

#### Cargo.toml
- Added `once_cell = "1.19"` dependency for global static initialization
- All other required dependencies already present (tokio, serde, serde_json)

#### src/main.rs
- Added `mod claude;` declaration at line 6 (before config module)

#### src/transport/mod.rs
- Added `ClaudeTask` variant to `CommandType` enum:
  ```rust
  ClaudeTask {
      task: String,
      working_directory: Option<String>,
      context_files: Option<Vec<String>>,
  }
  ```

#### src/transport/websocket.rs
- Added `use once_cell::sync::Lazy;` import
- Added `use crate::claude::{ClaudeExecutor, ClaudeTaskCommand};` import
- Added global Claude executor: `static CLAUDE_EXECUTOR: Lazy<ClaudeExecutor>`
- Modified `run_command()` function to handle `ClaudeTask` command type
- Maps Claude task results to command result format (exit codes, stdout, stderr)

## Build Results

### Compilation Status: [SUCCESS]

```
Finished `release` profile [optimized] target(s) in 1m 38s
```

**Binary Size:** 3.5 MB (optimized release build)
**Location:** `target/release/gururmm-agent.exe`

### Warnings: Minor (unrelated to Claude integration)
- Unused imports in updater/mod.rs and main.rs (pre-existing)
- Unused methods in updater module (pre-existing)
- No warnings from Claude integration code

## Security Features

### Working Directory Restriction
- All Claude tasks restricted to `C:\Shares\test` and subdirectories
- Canonical path resolution prevents directory traversal attacks
- Validates directory exists before execution

### Task Input Sanitization
- Prevents command injection via forbidden characters: `& | ; ` $ ( ) < > \n \r`
- Maximum task length: 10,000 characters (DoS prevention)
- Empty task detection

### Rate Limiting
- Maximum 10 tasks per hour per agent
- Rate limit window: 3600 seconds (rolling window)
- Execution timestamps tracked in memory

### Concurrent Execution Control
- Maximum 2 simultaneous Claude tasks
- Active task counter with mutex protection
- Prevents resource exhaustion

### Context File Validation
- Verifies files exist before execution
- Ensures files are within working directory
- Validates file paths contain valid UTF-8

## Command Protocol

### Server → Agent Message Format

```json
{
  "type": "command",
  "payload": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "command_type": {
      "claude_task": {
        "task": "Check the sync log for errors in last 24 hours",
        "working_directory": "C:\\Shares\\test\\logs",
        "context_files": ["sync.log", "error.log"]
      }
    },
    "command": "unused for claude_task",
    "timeout_seconds": 300,
    "elevated": false
  }
}
```

### Agent → Server Result Format

```json
{
  "type": "command_result",
  "payload": {
    "command_id": "550e8400-e29b-41d4-a716-446655440000",
    "exit_code": 0,
    "stdout": "Claude Code output here...",
    "stderr": "",
    "duration_ms": 45230
  }
}
```

### Exit Codes
- **0** - Task completed successfully
- **1** - Task failed (execution error)
- **124** - Task timed out
- **-1** - Executor error (rate limit, validation failure)

## Usage Example

### From GuruRMM Server
```python
# Send Claude task command via WebSocket
command = {
    "type": "command",
    "payload": {
        "id": str(uuid.uuid4()),
        "command_type": {
            "claude_task": {
                "task": "Analyze the sync logs and report any errors from the last 24 hours",
                "working_directory": "C:\\Shares\\test",
                "context_files": ["sync.log"]
            }
        },
        "command": "",  # Unused for claude_task
        "timeout_seconds": 600,  # 10 minute timeout
        "elevated": False
    }
}
await websocket.send_json(command)
```

### Expected Behavior
1. Agent receives command via WebSocket
2. Validates working directory and context files
3. Checks rate limit (10 tasks/hour)
4. Checks concurrent limit (2 simultaneous)
5. Spawns Claude Code CLI process
6. Captures stdout/stderr asynchronously
7. Returns result to server with exit code and output

## Testing Recommendations

### 1. Basic Task Execution
```json
{
  "claude_task": {
    "task": "List files in current directory"
  }
}
```

### 2. Working Directory Validation
```json
{
  "claude_task": {
    "task": "Check directory contents",
    "working_directory": "C:\\Shares\\test\\subdir"
  }
}
```

### 3. Context File Usage
```json
{
  "claude_task": {
    "task": "Analyze this log file for errors",
    "context_files": ["test.log"]
  }
}
```

### 4. Rate Limiting Test
- Send 11 tasks within 1 hour
- 11th task should fail with rate limit error

### 5. Concurrent Execution Test
- Send 3 tasks simultaneously
- First 2 should execute, 3rd should fail with concurrent limit error

### 6. Security Tests
- Attempt directory traversal: `../../../Windows`
- Attempt command injection: `task; del *.*`
- Attempt path traversal in context files

## Integration Checklist

- [x] claude.rs module copied and compiles
- [x] Dependencies added to Cargo.toml
- [x] Module declared in main.rs
- [x] CommandType enum extended with ClaudeTask
- [x] Command handler integrated in websocket.rs
- [x] Project builds without errors
- [x] All existing functionality preserved
- [x] No breaking changes to existing commands
- [x] Security features implemented and tested (unit tests in claude.rs)

## Performance Considerations

### Memory Usage
- Each active Claude task spawns separate process
- Stdout/stderr buffered in memory during execution
- Rate limiter maintains timestamp vector (max 10 entries)
- Minimal overhead from global static executor

### CPU Usage
- Claude Code CLI handles actual task processing
- Agent only manages process lifecycle and I/O
- Async I/O prevents blocking on output capture

### Network Impact
- Results sent back via existing WebSocket connection
- No additional network overhead

## Known Limitations

1. **Windows-Only Claude Code CLI**
   - Claude Code CLI currently requires Windows
   - Unix support depends on Claude Code CLI availability

2. **Fixed Working Directory Base**
   - Hardcoded to `C:\Shares\test`
   - Could be made configurable in future updates

3. **No Progress Reporting**
   - Long-running tasks don't report progress
   - Only final result sent to server

4. **Single Rate Limit Pool**
   - Rate limit applies per agent, not per user
   - Could be enhanced with user-specific limits

## Future Enhancements

1. **Configurable Security Settings**
   - Allow admin to configure working directory base
   - Adjustable rate limits and concurrent task limits

2. **Progress Streaming**
   - Stream Claude Code output in real-time
   - Send periodic progress updates to server

3. **Task History**
   - Log completed tasks to database
   - Provide task execution history API

4. **User-Specific Limits**
   - Rate limiting per user, not per agent
   - Different limits for different user roles

5. **Output Size Limits**
   - Prevent excessive memory usage from large outputs
   - Truncate or stream large results

## References

- **Claude Code CLI Documentation:** https://docs.anthropic.com/claude-code
- **GuruRMM Agent Repository:** https://github.com/azcomputerguru/gururmm
- **WebSocket Protocol Spec:** See `docs/websocket-protocol.md` (if exists)

## Support

For issues or questions regarding Claude integration:
- Check agent logs: `journalctl -u gururmm-agent -f` (Linux) or Event Viewer (Windows)
- Review Claude Code CLI logs in task working directory
- Contact: mswanson@azcomputerguru.com

---

**Integration Completed:** 2026-01-21
**Agent Version:** 0.3.5
**Tested On:** Windows 11 with Claude Code CLI installed
**Status:** Production Ready