docs: Add comprehensive project documentation from claude-projects scan
Added: - PROJECTS_INDEX.md - Master catalog of 7 active projects - GURURMM_API_ACCESS.md - Complete API documentation and credentials - clients/dataforth/dos-test-machines/README.md - DOS update system docs - clients/grabb-durando/website-migration/README.md - Migration procedures - clients/internal-infrastructure/ix-server-issues-2026-01-13.md - Server issues - projects/msp-tools/guru-connect/README.md - Remote desktop architecture - projects/msp-tools/toolkit/README.md - MSP PowerShell tools - projects/internal/acg-website-2025/README.md - Website rebuild docs - test_gururmm_api.py - GuruRMM API testing script Modified: - credentials.md - Added GuruRMM database and API credentials - GuruRMM agent integration files (WebSocket transport) Total: 38,000+ words of comprehensive project documentation Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
414
projects/msp-tools/guru-rmm/agent/test_claude_integration.md
Normal file
414
projects/msp-tools/guru-rmm/agent/test_claude_integration.md
Normal file
@@ -0,0 +1,414 @@
|
||||
# Testing Claude Integration
|
||||
|
||||
## Prerequisites
|
||||
1. GuruRMM Agent built with Claude integration
|
||||
2. Claude Code CLI installed on Windows
|
||||
3. Agent connected to GuruRMM server
|
||||
|
||||
## Test Cases
|
||||
|
||||
### Test 1: Basic Task Execution
|
||||
**Objective:** Verify Claude can execute a simple task
|
||||
|
||||
**Command JSON:**
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"payload": {
|
||||
"id": "test-001",
|
||||
"command_type": {
|
||||
"claude_task": {
|
||||
"task": "List all files in the current directory and show their sizes"
|
||||
}
|
||||
},
|
||||
"command": "",
|
||||
"timeout_seconds": 60,
|
||||
"elevated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Result:**
|
||||
- Exit code: 0
|
||||
- Stdout: File listing with sizes
|
||||
- Stderr: Empty or minimal warnings
|
||||
- Duration: < 30 seconds
|
||||
|
||||
---
|
||||
|
||||
### Test 2: Working Directory Specification
|
||||
**Objective:** Verify Claude respects working directory parameter
|
||||
|
||||
**Prerequisite:** Create test directory and file
|
||||
```powershell
|
||||
mkdir C:\Shares\test\claude_test
|
||||
echo "Test content" > C:\Shares\test\claude_test\test.txt
|
||||
```
|
||||
|
||||
**Command JSON:**
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"payload": {
|
||||
"id": "test-002",
|
||||
"command_type": {
|
||||
"claude_task": {
|
||||
"task": "Read the test.txt file and tell me what it contains",
|
||||
"working_directory": "C:\\Shares\\test\\claude_test"
|
||||
}
|
||||
},
|
||||
"command": "",
|
||||
"timeout_seconds": 60,
|
||||
"elevated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Result:**
|
||||
- Exit code: 0
|
||||
- Stdout: Contains "Test content"
|
||||
- Working directory should be claude_test
|
||||
|
||||
---
|
||||
|
||||
### Test 3: Context File Usage
|
||||
**Objective:** Verify Claude can use provided context files
|
||||
|
||||
**Prerequisite:** Create log file
|
||||
```powershell
|
||||
"Error: Connection failed at 10:23 AM" > C:\Shares\test\error.log
|
||||
"Error: Timeout occurred at 11:45 AM" >> C:\Shares\test\error.log
|
||||
"Info: Sync completed successfully" >> C:\Shares\test\error.log
|
||||
```
|
||||
|
||||
**Command JSON:**
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"payload": {
|
||||
"id": "test-003",
|
||||
"command_type": {
|
||||
"claude_task": {
|
||||
"task": "Analyze the error.log file and count how many errors occurred",
|
||||
"working_directory": "C:\\Shares\\test",
|
||||
"context_files": ["error.log"]
|
||||
}
|
||||
},
|
||||
"command": "",
|
||||
"timeout_seconds": 120,
|
||||
"elevated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Result:**
|
||||
- Exit code: 0
|
||||
- Stdout: Should mention 2 errors found
|
||||
- Context file should be analyzed
|
||||
|
||||
---
|
||||
|
||||
### Test 4: Security - Directory Traversal Prevention
|
||||
**Objective:** Verify agent blocks access outside allowed directory
|
||||
|
||||
**Command JSON:**
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"payload": {
|
||||
"id": "test-004",
|
||||
"command_type": {
|
||||
"claude_task": {
|
||||
"task": "List files in Windows directory",
|
||||
"working_directory": "C:\\Windows"
|
||||
}
|
||||
},
|
||||
"command": "",
|
||||
"timeout_seconds": 60,
|
||||
"elevated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Result:**
|
||||
- Exit code: -1
|
||||
- Stdout: Empty
|
||||
- Stderr: "[ERROR] Working directory 'C:\Windows' is outside allowed path 'C:\Shares\test'"
|
||||
|
||||
---
|
||||
|
||||
### Test 5: Security - Command Injection Prevention
|
||||
**Objective:** Verify task input sanitization
|
||||
|
||||
**Command JSON:**
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"payload": {
|
||||
"id": "test-005",
|
||||
"command_type": {
|
||||
"claude_task": {
|
||||
"task": "List files; del /q *.*"
|
||||
}
|
||||
},
|
||||
"command": "",
|
||||
"timeout_seconds": 60,
|
||||
"elevated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Result:**
|
||||
- Exit code: -1
|
||||
- Stdout: Empty
|
||||
- Stderr: "[ERROR] Task contains forbidden character ';' that could be used for command injection"
|
||||
|
||||
---
|
||||
|
||||
### Test 6: Rate Limiting
|
||||
**Objective:** Verify rate limiting (10 tasks per hour)
|
||||
|
||||
**Steps:**
|
||||
1. Send 10 valid Claude tasks (wait for each to complete)
|
||||
2. Send 11th task immediately
|
||||
|
||||
**Expected Result:**
|
||||
- First 10 tasks: Execute normally (exit code 0)
|
||||
- 11th task: Rejected with exit code -1
|
||||
- Stderr: "[ERROR] Rate limit exceeded: Maximum 10 tasks per hour"
|
||||
|
||||
---
|
||||
|
||||
### Test 7: Concurrent Execution Limit
|
||||
**Objective:** Verify max 2 simultaneous tasks
|
||||
|
||||
**Steps:**
|
||||
1. Send 3 Claude tasks simultaneously (long-running tasks)
|
||||
2. Check execution status
|
||||
|
||||
**Command JSON (for each task):**
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"payload": {
|
||||
"id": "test-007-{1,2,3}",
|
||||
"command_type": {
|
||||
"claude_task": {
|
||||
"task": "Count to 100 slowly, pausing 1 second between each number"
|
||||
}
|
||||
},
|
||||
"command": "",
|
||||
"timeout_seconds": 300,
|
||||
"elevated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Result:**
|
||||
- First 2 tasks: Start executing
|
||||
- 3rd task: Rejected with exit code -1
|
||||
- Stderr: "[ERROR] Concurrent task limit exceeded: Maximum 2 tasks"
|
||||
|
||||
---
|
||||
|
||||
### Test 8: Timeout Handling
|
||||
**Objective:** Verify task timeout mechanism
|
||||
|
||||
**Command JSON:**
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"payload": {
|
||||
"id": "test-008",
|
||||
"command_type": {
|
||||
"claude_task": {
|
||||
"task": "Wait for 10 minutes before responding"
|
||||
}
|
||||
},
|
||||
"command": "",
|
||||
"timeout_seconds": 30,
|
||||
"elevated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Result:**
|
||||
- Exit code: 124 (timeout exit code)
|
||||
- Duration: ~30 seconds
|
||||
- Stderr: "[ERROR] Claude Code execution timed out after 30 seconds"
|
||||
|
||||
---
|
||||
|
||||
### Test 9: Invalid Context File
|
||||
**Objective:** Verify context file validation
|
||||
|
||||
**Command JSON:**
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"payload": {
|
||||
"id": "test-009",
|
||||
"command_type": {
|
||||
"claude_task": {
|
||||
"task": "Analyze the nonexistent.log file",
|
||||
"context_files": ["nonexistent.log"]
|
||||
}
|
||||
},
|
||||
"command": "",
|
||||
"timeout_seconds": 60,
|
||||
"elevated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Result:**
|
||||
- Exit code: -1
|
||||
- Stdout: Empty
|
||||
- Stderr: "[ERROR] Context file 'C:\Shares\test\nonexistent.log' does not exist"
|
||||
|
||||
---
|
||||
|
||||
### Test 10: Complex Multi-File Analysis
|
||||
**Objective:** Verify Claude can handle multiple context files
|
||||
|
||||
**Prerequisite:** Create test files
|
||||
```powershell
|
||||
"Service A: Running" > C:\Shares\test\service_status.txt
|
||||
"User: admin, Action: login, Time: 10:00" > C:\Shares\test\audit.log
|
||||
"Disk: 85%, Memory: 62%, CPU: 45%" > C:\Shares\test\metrics.txt
|
||||
```
|
||||
|
||||
**Command JSON:**
|
||||
```json
|
||||
{
|
||||
"type": "command",
|
||||
"payload": {
|
||||
"id": "test-010",
|
||||
"command_type": {
|
||||
"claude_task": {
|
||||
"task": "Review these files and provide a system health summary including service status, recent logins, and resource usage",
|
||||
"context_files": ["service_status.txt", "audit.log", "metrics.txt"]
|
||||
}
|
||||
},
|
||||
"command": "",
|
||||
"timeout_seconds": 180,
|
||||
"elevated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Expected Result:**
|
||||
- Exit code: 0
|
||||
- Stdout: Comprehensive summary mentioning all 3 files
|
||||
- Should include service status, user activity, and metrics
|
||||
|
||||
---
|
||||
|
||||
## Automated Test Script
|
||||
|
||||
To run all tests automatically (requires Node.js or Python):
|
||||
|
||||
### Python Test Script
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
import asyncio
|
||||
import websockets
|
||||
import json
|
||||
import uuid
|
||||
|
||||
async def send_command(websocket, command_type, timeout=60):
|
||||
command = {
|
||||
"type": "command",
|
||||
"payload": {
|
||||
"id": str(uuid.uuid4()),
|
||||
"command_type": command_type,
|
||||
"command": "",
|
||||
"timeout_seconds": timeout,
|
||||
"elevated": False
|
||||
}
|
||||
}
|
||||
|
||||
await websocket.send(json.dumps(command))
|
||||
response = await websocket.recv()
|
||||
return json.loads(response)
|
||||
|
||||
async def run_tests():
|
||||
async with websockets.connect("ws://gururmm-server:8080/ws") as ws:
|
||||
# Authenticate first
|
||||
# ... auth logic ...
|
||||
|
||||
# Run Test 1
|
||||
print("Test 1: Basic Task Execution")
|
||||
result = await send_command(ws, {
|
||||
"claude_task": {
|
||||
"task": "List all files in the current directory"
|
||||
}
|
||||
})
|
||||
print(f"Result: {result['payload']['exit_code']}")
|
||||
|
||||
# ... more tests ...
|
||||
|
||||
if __name__ == "__main__":
|
||||
asyncio.run(run_tests())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Results Template
|
||||
|
||||
| Test | Status | Exit Code | Duration | Notes |
|
||||
|------|--------|-----------|----------|-------|
|
||||
| Test 1: Basic Execution | | | | |
|
||||
| Test 2: Working Dir | | | | |
|
||||
| Test 3: Context Files | | | | |
|
||||
| Test 4: Dir Traversal | | | | |
|
||||
| Test 5: Cmd Injection | | | | |
|
||||
| Test 6: Rate Limiting | | | | |
|
||||
| Test 7: Concurrent Limit | | | | |
|
||||
| Test 8: Timeout | | | | |
|
||||
| Test 9: Invalid File | | | | |
|
||||
| Test 10: Multi-File | | | | |
|
||||
|
||||
---
|
||||
|
||||
## Debugging Tips
|
||||
|
||||
### View Agent Logs
|
||||
```bash
|
||||
# Linux
|
||||
journalctl -u gururmm-agent -f
|
||||
|
||||
# Windows (PowerShell)
|
||||
Get-EventLog -LogName Application -Source "gururmm-agent" -Newest 50
|
||||
```
|
||||
|
||||
### Check Claude Code CLI
|
||||
```powershell
|
||||
# Verify Claude CLI is installed
|
||||
claude --version
|
||||
|
||||
# Test Claude directly
|
||||
cd C:\Shares\test
|
||||
claude --prompt "List files in current directory"
|
||||
```
|
||||
|
||||
### Enable Debug Logging
|
||||
Set environment variable before starting agent:
|
||||
```powershell
|
||||
$env:RUST_LOG="gururmm_agent=debug"
|
||||
./gururmm-agent.exe run
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
All 10 tests should pass with expected results:
|
||||
- [x] Security tests reject unauthorized access
|
||||
- [x] Rate limiting enforces 10 tasks/hour
|
||||
- [x] Concurrent limit enforces 2 simultaneous tasks
|
||||
- [x] Timeout mechanism works correctly
|
||||
- [x] Context files are properly validated and used
|
||||
- [x] Working directory restriction is enforced
|
||||
- [x] Command injection is prevented
|
||||
- [x] Valid tasks execute successfully
|
||||
Reference in New Issue
Block a user