claudetools/projects/msp-tools/toolkit/README.md

# MSP Toolkit - PowerShell Scripts for MSP Technicians

**Project Type:** Internal Tool / MSP Platform
**Status:** Production
**Technology:** PowerShell
**Deployment:** Web-hosted via azcomputerguru.com
**Access Method:** One-liner execution via `iex (irm ...)`

## Overview

Collection of PowerShell scripts for MSP technicians, accessible via web for easy remote execution. Designed for quick deployment on client machines without file downloads or installation.

**Primary Use Cases:**
- Initial system assessment
- Client onboarding
- Troubleshooting and diagnostics
- Automated configuration tasks

---

## Quick Access

### Interactive Menu
```powershell
iex (irm azcomputerguru.com/tools/msp-toolkit.ps1)
```

### Direct Script Execution
```powershell
# System Information
iex (irm azcomputerguru.com/tools/Get-SystemInfo.ps1)

# Health Check
iex (irm azcomputerguru.com/tools/Invoke-HealthCheck.ps1)

# Create Local Admin
iex (irm azcomputerguru.com/tools/Create-LocalAdmin.ps1)

# Configure Static IP
iex (irm azcomputerguru.com/tools/Set-StaticIP.ps1)

# Join Domain
iex (irm azcomputerguru.com/tools/Join-Domain.ps1)

# Install RMM Agent
iex (irm azcomputerguru.com/tools/Install-RMMAgent.ps1)
```

### Parameterized Execution
```powershell
# Run specific script from main menu
iex (irm azcomputerguru.com/tools/msp-toolkit.ps1) -Script systeminfo
iex (irm azcomputerguru.com/tools/msp-toolkit.ps1) -Script healthcheck
iex (irm azcomputerguru.com/tools/msp-toolkit.ps1) -Script localadmin
```

---

## Available Scripts

### Information & Diagnostics

#### Get-SystemInfo.ps1
Comprehensive system information report including:
- OS version and build
- Hardware specifications (CPU, RAM, disk)
- Network configuration
- Installed software
- Windows updates status
- Security settings

**Usage:**
```powershell
iex (irm azcomputerguru.com/tools/Get-SystemInfo.ps1)
```

**Output:** Formatted console report with key system details

---

#### Invoke-HealthCheck.ps1
System health check and diagnostics including:
- Disk space warnings
- Service status verification
- Event log errors (last 24 hours)
- Network connectivity tests
- Antivirus status
- Windows Defender status

**Usage:**
```powershell
iex (irm azcomputerguru.com/tools/Invoke-HealthCheck.ps1)
```

**Output:** Pass/fail status for each check with recommendations

---

### System Configuration

#### Create-LocalAdmin.ps1
Create local administrator account with secure random password.

**Features:**
- Generates cryptographically secure 16-character password
- Creates account with Administrator group membership
- Password never expires setting
- Returns credentials for documentation

**Usage:**
```powershell
iex (irm azcomputerguru.com/tools/Create-LocalAdmin.ps1)

# With custom username
iex (irm azcomputerguru.com/tools/Create-LocalAdmin.ps1) -Username "ACGAdmin"
```

**Output:** Username and generated password (save immediately!)

---

#### Set-StaticIP.ps1
Configure network adapter with static IP address.

**Features:**
- Lists available network adapters
- Sets IP address, subnet mask, gateway
- Configures DNS servers
- Validates configuration

**Usage:**
```powershell
iex (irm azcomputerguru.com/tools/Set-StaticIP.ps1)
```

**Interactive Prompts:**
- Network adapter selection
- IP address
- Subnet mask
- Default gateway
- DNS servers (primary and secondary)

---

#### Join-Domain.ps1
Join computer to Active Directory domain.

**Features:**
- Validates domain reachability
- Prompts for domain admin credentials
- Joins domain
- Optional OU specification
- Restart prompt

**Usage:**
```powershell
iex (irm azcomputerguru.com/tools/Join-Domain.ps1)
```

**Interactive Prompts:**
- Domain name (e.g., contoso.local)
- Domain admin username
- Domain admin password
- OU path (optional)

---

### MSP Tools

#### Install-RMMAgent.ps1
Install GuruRMM monitoring agent.

**Features:**
- Downloads latest agent installer
- Installs with organization-specific API key
- Registers machine in GuruRMM
- Verifies service running

**Usage:**
```powershell
iex (irm azcomputerguru.com/tools/Install-RMMAgent.ps1)
```

**Configuration:**
- Server URL: wss://rmm-api.azcomputerguru.com/ws
- API Key: Embedded in script (rotated periodically)

---

## Project Structure

```
msp-toolkit/
├── msp-toolkit.ps1          # Main launcher with interactive menu
├── scripts/                 # Individual PowerShell scripts
│   ├── Get-SystemInfo.ps1
│   ├── Invoke-HealthCheck.ps1
│   ├── Create-LocalAdmin.ps1
│   ├── Set-StaticIP.ps1
│   ├── Join-Domain.ps1
│   └── Install-RMMAgent.ps1
├── config/                  # Configuration files (JSON)
│   ├── applications.json
│   ├── presets.json
│   ├── scripts.json
│   ├── themes.json
│   └── tweaks.json
├── functions/               # Shared functions
│   ├── public/
│   └── private/
├── deploy.bat              # Deployment script
└── README.md
```

---

## Development

### Local Development

```bash
# Clone repository (if tracked in Git)
cd ~/claude-projects/msp-toolkit

# Edit scripts
code scripts/Get-SystemInfo.ps1

# Test locally
powershell -ExecutionPolicy Bypass -File scripts/Get-SystemInfo.ps1
```

### Testing

```powershell
# Test script syntax
powershell -File Test-Script.ps1

# Analyze with PSScriptAnalyzer
Install-Module -Name PSScriptAnalyzer -Force
Invoke-ScriptAnalyzer -Path scripts/Get-SystemInfo.ps1
```

### Deployment

#### Automatic Deployment
```batch
# Run deployment script (Windows)
deploy.bat
```

#### Manual Deployment
```bash
# Deploy main launcher
scp msp-toolkit.ps1 claude@ix.azcomputerguru.com:/home/azcomputerguru/public_html/tools/

# Deploy all scripts
scp scripts/*.ps1 claude@ix.azcomputerguru.com:/home/azcomputerguru/public_html/tools/

# Set permissions
ssh claude@ix.azcomputerguru.com "chmod 644 /home/azcomputerguru/public_html/tools/*.ps1"

# Verify deployment
curl -I https://www.azcomputerguru.com/tools/msp-toolkit.ps1
```

---

## Web Server Configuration

### Location
**Server:** ix.azcomputerguru.com
**Path:** `/home/azcomputerguru/public_html/tools/`
**URL:** https://www.azcomputerguru.com/tools/

### File Structure on Server
```
/home/azcomputerguru/public_html/tools/
├── msp-toolkit.ps1
├── Get-SystemInfo.ps1
├── Invoke-HealthCheck.ps1
├── Create-LocalAdmin.ps1
├── Set-StaticIP.ps1
├── Join-Domain.ps1
├── Install-RMMAgent.ps1
└── [other scripts]
```

### Permissions
```bash
# Files: 644 (rw-r--r--)
chmod 644 /home/azcomputerguru/public_html/tools/*.ps1

# Directory: 755 (rwxr-xr-x)
chmod 755 /home/azcomputerguru/public_html/tools/
```

### MIME Type
Apache serves .ps1 files as text/plain by default (correct for PowerShell scripts).

---

## Security Considerations

### Transport Security
- **HTTPS Required:** All scripts served over TLS
- **Certificate:** Let's Encrypt (auto-renewed via cPanel)
- **Integrity:** Scripts signed with code signing certificate (future enhancement)

### Script Safety
- **Execution Policy:** Scripts use `-ExecutionPolicy Bypass` flag
- **No Automatic Execution:** User must explicitly run `iex (irm ...)`
- **Review Before Use:** Technicians should review scripts before deployment
- **Sensitive Parameters:** Passwords, API keys handled carefully

### Best Practices
1. Always review scripts before executing in production
2. Test in sandbox environment first
3. Validate script integrity (hash checking - future)
4. Rotate API keys periodically (RMMAgent.ps1)
5. Log script executions for audit trail

---

## Usage Examples

### Typical Workflow: New Client Onboarding

```powershell
# 1. Gather system information
iex (irm azcomputerguru.com/tools/Get-SystemInfo.ps1)

# 2. Run health check
iex (irm azcomputerguru.com/tools/Invoke-HealthCheck.ps1)

# 3. Create local admin account
iex (irm azcomputerguru.com/tools/Create-LocalAdmin.ps1) -Username "ACGAdmin"
# SAVE PASSWORD IMMEDIATELY!

# 4. Install RMM agent
iex (irm azcomputerguru.com/tools/Install-RMMAgent.ps1)

# 5. Configure static IP (if needed)
iex (irm azcomputerguru.com/tools/Set-StaticIP.ps1)

# 6. Join domain (if applicable)
iex (irm azcomputerguru.com/tools/Join-Domain.ps1)
```

### Troubleshooting Client Issue

```powershell
# Quick diagnostic check
iex (irm azcomputerguru.com/tools/Invoke-HealthCheck.ps1)

# Detailed system information
iex (irm azcomputerguru.com/tools/Get-SystemInfo.ps1) | Out-File C:\system-info.txt
```

---

## Future Enhancements

### Planned Features

- [ ] Web-based UI for script selection and parameter input
- [ ] Script versioning and rollback capability
- [ ] Logging and execution history in GuruRMM
- [ ] Additional scripts for common MSP tasks
- [ ] API endpoints for RMM integration
- [ ] Multi-tenancy support (client-specific scripts)

### Ideas

- **Windows Updates:** Script to check and install updates
- **Software Deployment:** Install common applications (Chrome, Adobe Reader, etc.)
- **Security Audit:** Comprehensive security posture assessment
- **Network Diagnostics:** Advanced network troubleshooting
- **Backup Verification:** Check backup status (Veeam, Windows Backup, etc.)
- **Certificate Management:** Check SSL/TLS certificate expiration
- **Group Policy Status:** Verify GPO application
- **Event Log Analysis:** Parse event logs for specific errors

---

## Troubleshooting

### Script Won't Download

**Issue:** `iex (irm azcomputerguru.com/tools/script.ps1)` fails

**Check:**
1. Internet connectivity: `Test-NetConnection azcomputerguru.com -Port 443`
2. DNS resolution: `nslookup azcomputerguru.com`
3. Firewall blocking HTTPS?
4. Proxy configuration needed?

**Solution:**
```powershell
# Test basic connectivity
Invoke-WebRequest -Uri https://www.azcomputerguru.com/tools/msp-toolkit.ps1 -UseBasicParsing

# Try with explicit proxy
$proxy = [System.Net.WebRequest]::GetSystemWebProxy()
Invoke-WebRequest -Uri https://www.azcomputerguru.com/tools/msp-toolkit.ps1 -Proxy $proxy.GetProxy("https://www.azcomputerguru.com")
```

### Execution Policy Restriction

**Issue:** Script execution blocked by execution policy

**Solution:**
```powershell
# Check current policy
Get-ExecutionPolicy

# Bypass for single session
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
iex (irm azcomputerguru.com/tools/script.ps1)

# OR use -ExecutionPolicy flag
powershell -ExecutionPolicy Bypass -Command "iex (irm azcomputerguru.com/tools/script.ps1)"
```

### Script Error

**Issue:** Script fails with unexpected error

**Debug:**
```powershell
# Enable verbose output
$VerbosePreference = "Continue"
iex (irm azcomputerguru.com/tools/script.ps1)

# Capture error details
try {
    iex (irm azcomputerguru.com/tools/script.ps1)
} catch {
    $_.Exception.Message
    $_.ScriptStackTrace
}
```

---

## Monitoring and Logs

### Server Logs

**Apache Access Log:** `/var/log/apache2/access_log` or `/usr/local/apache/logs/domlogs/azcomputerguru.com`

**Track Usage:**
```bash
# Count script downloads
grep "GET /tools/" /var/log/apache2/access_log | wc -l

# Most popular scripts
grep "GET /tools/" /var/log/apache2/access_log | awk '{print $7}' | sort | uniq -c | sort -nr
```

### Client Execution Logs

**Future:** Integrate with GuruRMM to log script executions
- Machine ID
- Script name
- Execution timestamp
- Result (success/failure)
- Output summary

---

## Related Projects

**GuruRMM:** MSP monitoring platform (Install-RMMAgent.ps1 integration)
**ClaudeTools:** Project tracking and documentation system
**MSP Operations:** Internal tools and workflows

---

## Source Repository

**Location:** `C:\Users\MikeSwanson\claude-projects\msp-toolkit`

**Git Status:** Not currently tracked in Git (consider adding)

---

## Maintenance

### Regular Tasks

**Monthly:**
- [ ] Review script usage statistics
- [ ] Check for PowerShell best practices violations
- [ ] Update documentation for new scripts
- [ ] Test scripts on Windows 10/11 and Server 2016/2019/2022

**Quarterly:**
- [ ] Security audit of scripts
- [ ] Rotate RMM agent API keys
- [ ] Review and implement feature requests
- [ ] Performance optimization

**Annually:**
- [ ] Comprehensive security review
- [ ] Major version updates
- [ ] Archive old/unused scripts

---

## Support

**Technical Contact:** Mike Swanson
**Email:** mike@azcomputerguru.com
**Phone:** 520.304.8300

**Internal Documentation:** `~/claude-projects/msp-toolkit/`
**Deployment Server:** ix.azcomputerguru.com

---

**Project Status:** Production - Active Use
**Version:** 1.x (no formal versioning yet)
**Last Updated:** 2026-01-22