nox-openclaw-hunter 1.0.0

package/docs/intune.md

@@ -0,0 +1,390 @@
+# Microsoft Intune Integration Guide
+
+Deploy Nox OpenClaw detection and enforcement scripts across your Windows and macOS fleet using Microsoft Intune.
+
+## Overview
+
+This guide explains how to:
+
+1. Deploy PowerShell scripts for Windows detection and enforcement
+2. Deploy shell scripts for macOS detection and enforcement
+3. Set up Proactive Remediation for automated detection and enforcement
+4. Create compliance policies
+5. Monitor results via Intune reporting and Log Analytics
+
+## Prerequisites
+
+- Microsoft Intune subscription (standalone or part of Microsoft 365)
+- Azure AD joined or hybrid joined devices
+- Windows 10/11 or macOS 10.15+ managed devices
+- Intune admin access
+- (Optional) Azure Log Analytics workspace for advanced reporting
+
+## Quick Start
+
+1. Generate scripts:
+   ```bash
+   nox export --platform intune --mode detect --output ./intune-scripts
+   nox export --platform intune --mode enforce --output ./intune-scripts
+   ```
+
+2. Upload scripts to Intune
+3. Configure Proactive Remediation (recommended)
+4. Monitor via Endpoint Analytics
+
+## Script Setup
+
+### Step 1: Generate Scripts
+
+Generate Intune-optimized scripts using the CLI:
+
+```bash
+# Detection scripts
+nox export --platform intune --mode detect --output ./intune-scripts
+
+# Enforcement scripts  
+nox export --platform intune --mode enforce --output ./intune-scripts
+
+# With webhook integration
+nox export --platform intune --mode detect \
+  --webhook https://siem.example.com/webhook \
+  --webhook-token YOUR_TOKEN \
+  --output ./intune-scripts
+```
+
+This generates:
+- `Detect-OpenClaw.ps1` - Windows detection script
+- `Remediate-OpenClaw.ps1` - Windows enforcement script
+- `detect-openclaw.sh` - macOS detection script (if applicable)
+- `remediate-openclaw.sh` - macOS enforcement script (if applicable)
+
+### Step 2: Upload Windows Scripts
+
+#### Platform Scripts Method
+
+1. Navigate to **Devices > Windows > Scripts**
+2. Click **+ Add**
+3. Configure **Basics**:
+   - **Name:** Nox OpenClaw Detection
+   - **Description:** Detects OpenClaw AI agent installations
+4. Configure **Script settings**:
+   - **Script location:** Upload `Detect-OpenClaw.ps1`
+   - **Run this script using the logged on credentials:** No
+   - **Enforce script signature check:** No
+   - **Run script in 64-bit PowerShell:** Yes
+5. Configure **Assignments**:
+   - Add target groups
+6. Click **Create**
+
+Repeat for the enforcement script.
+
+### Step 3: Upload macOS Scripts
+
+1. Navigate to **Devices > macOS > Shell scripts**
+2. Click **+ Add**
+3. Configure **Basics**:
+   - **Name:** Nox OpenClaw Detection (macOS)
+4. Configure **Script settings**:
+   - Upload `detect-openclaw.sh`
+   - **Run script as signed-in user:** No
+   - **Hide script notifications on devices:** Yes
+   - **Script frequency:** Every 1 day
+   - **Max number of times to retry if script fails:** 3
+5. Configure **Assignments**:
+   - Add target groups
+6. Click **Create**
+
+## Proactive Remediation (Recommended)
+
+Proactive Remediation automatically detects and fixes issues. This is the recommended deployment method for Windows.
+
+### Create Remediation Package
+
+1. Navigate to **Devices > Remediations**
+2. Click **+ Create script package**
+3. Configure **Basics**:
+   - **Name:** Nox OpenClaw Detection and Remediation
+   - **Description:** Automatically detects and removes OpenClaw AI agent
+   - **Publisher:** Nox Security
+4. Configure **Settings**:
+   - **Detection script file:** Upload `Detect-OpenClaw.ps1`
+   - **Remediation script file:** Upload `Remediate-OpenClaw.ps1`
+   - **Run this script using the logged on credentials:** No
+   - **Enforce script signature check:** No
+   - **Run script in 64-bit PowerShell:** Yes
+5. Configure **Scope tags** (optional)
+6. Configure **Assignments**:
+   - Select target groups
+   - **Schedule:**
+     - **Run frequency:** Daily (recommended)
+     - Or: Every 6 hours (for high-security environments)
+7. Click **Create**
+
+### How Proactive Remediation Works
+
+1. **Detection phase:** Runs `Detect-OpenClaw.ps1`
+   - Exit code 0 = Compliant (no OpenClaw found)
+   - Exit code 1 = Non-compliant (OpenClaw detected)
+
+2. **Remediation phase:** If detection returns exit code 1
+   - Runs `Remediate-OpenClaw.ps1`
+   - Removes OpenClaw components
+   - Reports success/failure
+
+3. **Reporting:** Results visible in Endpoint Analytics
+
+## Compliance Policy
+
+Create a compliance policy to mark devices with OpenClaw as non-compliant.
+
+### Windows Compliance Policy
+
+1. Navigate to **Devices > Compliance policies**
+2. Click **+ Create Policy**
+3. Select **Windows 10 and later**
+4. Configure **Basics**:
+   - **Name:** OpenClaw Detection Compliance
+5. Configure **Compliance settings**:
+   - Use custom compliance script or rely on Proactive Remediation results
+6. Configure **Actions for noncompliance**:
+
+| Action | Schedule |
+|--------|----------|
+| Mark device noncompliant | Immediately |
+| Send email to end user | After 1 day |
+| Retire the noncompliant device | After 14 days (optional) |
+
+7. Configure **Assignments**
+8. Click **Create**
+
+### Conditional Access Integration
+
+Block non-compliant devices from corporate resources:
+
+1. Navigate to **Azure AD > Security > Conditional Access**
+2. Create or edit policy
+3. Configure **Conditions**:
+   - Device compliance: Require device to be marked as compliant
+4. Configure **Access controls**:
+   - Block access for non-compliant devices
+
+## Monitoring and Reporting
+
+### Script Status Dashboard
+
+1. Navigate to **Devices > Monitor > Device script status**
+2. Select your script
+3. View execution results per device
+
+### Proactive Remediation Reports
+
+1. Navigate to **Reports > Endpoint analytics > Proactive remediations**
+2. Click on your remediation package
+3. View:
+   - **Overview:** Detection and remediation rates
+   - **Device status:** Per-device results
+   - **Issue breakdown:** Common failure reasons
+
+### Log Analytics Integration
+
+Export data to Azure Log Analytics for custom dashboards.
+
+#### Configure Diagnostic Settings
+
+1. Navigate to **Tenant administration > Diagnostics settings**
+2. Click **+ Add diagnostic setting**
+3. Configure:
+   - **Name:** Intune to Log Analytics
+   - **Log categories:** Scripts, Device compliance, etc.
+   - **Destination:** Send to Log Analytics workspace
+4. Click **Save**
+
+#### Example Queries
+
+Devices with OpenClaw detected:
+
+```kusto
+IntuneDevices
+| where TimeGenerated > ago(7d)
+| where DeviceId in (
+    IntuneDeviceComplianceOrg
+    | where ComplianceState == "Noncompliant"
+    | where PolicyName contains "OpenClaw"
+    | project DeviceId
+)
+| project DeviceName, UserPrincipalName, OS, OSVersion, LastContact
+| sort by LastContact desc
+```
+
+Proactive Remediation summary:
+
+```kusto
+IntuneProactiveRemediations
+| where TimeGenerated > ago(30d)
+| where PolicyName == "Nox OpenClaw Detection and Remediation"
+| summarize 
+    Detected = countif(DetectionStatus == "NonCompliant"),
+    Remediated = countif(RemediationStatus == "Success"),
+    Failed = countif(RemediationStatus == "Failed")
+    by bin(TimeGenerated, 1d)
+| render timechart
+```
+
+## Exit Codes
+
+### Detection Script
+
+| Code | Meaning | Intune Status |
+|------|---------|---------------|
+| 0 | OpenClaw not detected | Compliant |
+| 1 | OpenClaw detected | Non-compliant (triggers remediation) |
+| 2 | Script error | Error |
+
+### Remediation Script
+
+| Code | Meaning | Intune Status |
+|------|---------|---------------|
+| 0 | Remediation successful | Success |
+| 1 | Partial failure | With issues |
+| 2 | Script error | Failed |
+| 3 | Nothing to remediate | Success |
+
+## Webhook Integration
+
+### Configure Webhooks in Scripts
+
+Edit scripts before uploading to include webhook configuration:
+
+```powershell
+# At the top of the script
+$WebhookUrl = "https://siem.example.com/api/v1/events"
+$WebhookToken = "YOUR_API_TOKEN"
+```
+
+Or generate scripts with webhooks built-in:
+
+```bash
+nox export --platform intune --mode detect \
+  --webhook https://siem.example.com/webhook \
+  --webhook-token YOUR_TOKEN
+```
+
+### Webhook Payload
+
+```json
+{
+  "event": "openclaw.detection",
+  "version": "1.0",
+  "timestamp": "2026-02-03T10:30:00Z",
+  "status": "detected",
+  "severity": "high",
+  "host": {
+    "hostname": "DESKTOP-ABC123",
+    "os": "Windows",
+    "osVersion": "Microsoft Windows NT 10.0.19045.0",
+    "arch": "AMD64",
+    "user": "jsmith",
+    "domain": "CONTOSO"
+  },
+  "details": "CLI found at C:\\Users\\jsmith\\AppData\\Local\\Programs\\openclaw",
+  "source": {
+    "tool": "nox-openclaw-detector",
+    "version": "1.0.0",
+    "vendor": "Nox Security"
+  }
+}
+```
+
+### Microsoft Sentinel Integration
+
+Create a Logic App to ingest webhooks into Sentinel:
+
+1. Create Logic App with HTTP trigger
+2. Parse JSON payload
+3. Send to Log Analytics Custom Log
+4. Create Sentinel Analytics Rule for detection events
+
+## Advanced Configurations
+
+### Staged Deployment
+
+1. Create Azure AD groups for pilot users
+2. Assign Proactive Remediation to pilot group
+3. Monitor for 2 weeks
+4. Expand to all users
+
+### High-Security Mode
+
+For environments requiring immediate detection:
+
+1. Set Proactive Remediation schedule to every 6 hours
+2. Enable Conditional Access to block non-compliant devices
+3. Configure email alerts for immediate notification
+4. Set remediation to auto-run without user interaction
+
+### Multi-OS Deployment
+
+Deploy to both Windows and macOS fleets:
+
+1. Create device groups:
+   - "All Windows Devices"
+   - "All macOS Devices"
+2. Create separate scripts for each platform
+3. Assign Windows scripts to Windows group
+4. Assign macOS scripts to macOS group
+
+## Troubleshooting
+
+### Script Not Running
+
+1. Verify device is enrolled and checking in
+2. Check device group assignment
+3. Verify Intune Management Extension is installed:
+   - Path: `C:\Program Files (x86)\Microsoft Intune Management Extension`
+4. Review IME logs:
+   - Path: `%ProgramData%\Microsoft\IntuneManagementExtension\Logs`
+
+### Access Denied Errors
+
+1. Verify script runs as SYSTEM (not user)
+2. Check for UAC restrictions
+3. Ensure device is properly enrolled
+4. Verify MDM authority is Intune
+
+### Remediation Not Triggering
+
+1. Verify detection script returns exit code 1 for detection
+2. Check remediation script is assigned to package
+3. Review Proactive Remediation schedule
+4. Check device is within scope of assignments
+
+### PowerShell Execution Policy
+
+If scripts fail due to execution policy:
+
+1. Scripts run via Intune bypass local execution policy
+2. If issues persist, check group policy for overrides
+3. Ensure 64-bit PowerShell option is selected
+
+### macOS Script Issues
+
+1. Check script has correct line endings (LF, not CRLF)
+2. Verify bash syntax is compatible
+3. Check for permission issues with System Integrity Protection
+
+## Best Practices
+
+1. **Use Proactive Remediation**: Automates detection and enforcement
+2. **Start with Detection Only**: Understand scope before enabling remediation
+3. **Test in Pilot Group**: Validate before fleet-wide deployment
+4. **Enable Log Analytics**: Essential for long-term reporting and trend analysis
+5. **Set Appropriate Schedules**: Daily is sufficient for most environments
+6. **Monitor Remediation Success**: Investigate any failures promptly
+7. **Document Exceptions**: Track approved OpenClaw installations in Azure AD notes
+8. **Regular Updates**: Update scripts when new versions are available
+
+## Support
+
+- Email: support@nox.security
+- Documentation: https://docs.nox.security/intune
+- Microsoft Endpoint Manager Admin Center: https://endpoint.microsoft.com