nox-openclaw-hunter 1.0.0

package/docs/jamf.md

@@ -0,0 +1,400 @@
+# Jamf Pro Integration Guide
+
+Deploy Nox OpenClaw detection and enforcement scripts across your macOS fleet using Jamf Pro.
+
+## Overview
+
+This guide explains how to:
+
+1. Add detection and enforcement scripts to Jamf Pro
+2. Create policies for automated scanning
+3. Set up extension attributes for inventory
+4. Create Smart Groups for targeting
+5. Configure webhook integration for SIEM alerting
+
+## Prerequisites
+
+- Jamf Pro 10.x or later
+- macOS 10.15+ managed devices
+- Admin access to Jamf Pro console
+- (Optional) Webhook endpoint for SIEM integration
+
+## Quick Start
+
+1. Generate scripts:
+   ```bash
+   nox export --platform jamf --mode detect --output ./jamf-scripts
+   nox export --platform jamf --mode enforce --output ./jamf-scripts
+   ```
+
+2. Upload scripts to Jamf Pro
+3. Create detection policy with recurring trigger
+4. (Optional) Create enforcement policy scoped to detected devices
+
+## Script Setup
+
+### Step 1: Generate Scripts
+
+Generate Jamf-optimized scripts using the CLI:
+
+```bash
+# Detection script
+nox export --platform jamf --mode detect --output ./jamf-scripts
+
+# Enforcement script
+nox export --platform jamf --mode enforce --output ./jamf-scripts
+
+# With webhook integration
+nox export --platform jamf --mode detect \
+  --webhook https://siem.example.com/webhook \
+  --webhook-token YOUR_TOKEN \
+  --output ./jamf-scripts
+```
+
+### Step 2: Add Detection Script
+
+1. Navigate to **Settings > Computer Management > Scripts**
+2. Click **+ New**
+3. Configure the **General** tab:
+   - **Display Name:** Nox OpenClaw Detection
+   - **Category:** Security
+   - **Info:** Detects OpenClaw AI agent installations
+   - **Notes:** Generated by nox-openclaw-detector v1.0.0
+4. Configure the **Script** tab:
+   - Paste contents of `detect-openclaw.sh`
+5. Configure the **Options** tab:
+   - **Priority:** Before
+   - **Parameter 4 Label:** Webhook URL
+   - **Parameter 5 Label:** Webhook Token
+   - **Parameter 6 Label:** Verbose Mode (true/false)
+6. Click **Save**
+
+### Step 3: Add Enforcement Script
+
+1. Navigate to **Settings > Computer Management > Scripts**
+2. Click **+ New**
+3. Configure the **General** tab:
+   - **Display Name:** Nox OpenClaw Enforcement
+   - **Category:** Security
+   - **Info:** Removes OpenClaw AI agent installations
+4. Configure the **Script** tab:
+   - Paste contents of `enforce-openclaw.sh`
+5. Configure the **Options** tab:
+   - **Priority:** Before
+   - **Parameter 4 Label:** Webhook URL
+   - **Parameter 5 Label:** Webhook Token
+   - **Parameter 6 Label:** Quarantine Mode (true/false)
+   - **Parameter 7 Label:** Verbose Mode (true/false)
+6. Click **Save**
+
+## Extension Attribute
+
+Create an extension attribute to report OpenClaw status in Jamf inventory.
+
+### Add Extension Attribute
+
+1. Navigate to **Settings > Computer Management > Extension Attributes**
+2. Click **+ New**
+3. Configure:
+   - **Display Name:** OpenClaw Status
+   - **Description:** Reports OpenClaw installation status
+   - **Data Type:** String
+   - **Inventory Display:** General
+   - **Input Type:** Script
+4. Paste the extension attribute script:
+
+```bash
+#!/bin/bash
+# Nox OpenClaw Detection - Jamf Extension Attribute
+
+OPENCLAW_STATUS="Not Installed"
+
+# Check CLI binary
+if command -v openclaw &>/dev/null; then
+    OPENCLAW_STATUS="Installed"
+fi
+
+# Check common paths
+for path in /usr/local/bin/openclaw /opt/homebrew/bin/openclaw; do
+    if [[ -f "$path" ]]; then
+        OPENCLAW_STATUS="Installed"
+        break
+    fi
+done
+
+# Check app bundle
+if [[ -d "/Applications/OpenClaw.app" ]]; then
+    OPENCLAW_STATUS="Installed"
+fi
+
+# Check config directory
+if [[ -d "$HOME/.openclaw" ]] || ls -d /Users/*/.openclaw &>/dev/null 2>&1; then
+    OPENCLAW_STATUS="Installed"
+fi
+
+# Check if running
+if pgrep -f "openclaw" > /dev/null 2>&1; then
+    OPENCLAW_STATUS="Running"
+fi
+
+# Check gateway port
+if nc -z localhost 18789 2>/dev/null; then
+    OPENCLAW_STATUS="Running"
+fi
+
+echo "<result>$OPENCLAW_STATUS</result>"
+```
+
+5. Click **Save**
+
+### Extension Attribute Values
+
+| Value | Meaning |
+|-------|---------|
+| `Not Installed` | No OpenClaw components found |
+| `Installed` | OpenClaw detected but not actively running |
+| `Running` | OpenClaw is actively running |
+
+## Policy Configuration
+
+### Detection Policy
+
+Create a policy to run detection on a schedule.
+
+1. Navigate to **Computers > Policies**
+2. Click **+ New**
+3. Configure **General**:
+   - **Display Name:** Nox OpenClaw Detection
+   - **Enabled:** Yes
+   - **Trigger:** Recurring Check-in
+   - **Execution Frequency:** Once per day
+4. Configure **Scripts**:
+   - Click **Configure**
+   - Add "Nox OpenClaw Detection" script
+   - Set parameter values:
+     - **Parameter 4 (Webhook URL):** Your SIEM webhook URL
+     - **Parameter 5 (Webhook Token):** Your authentication token
+     - **Parameter 6 (Verbose):** false
+5. Configure **Scope**:
+   - **Targets:** All Managed Clients (or specific groups)
+6. Click **Save**
+
+### Enforcement Policy
+
+Create a policy to remediate detected installations.
+
+1. Navigate to **Computers > Policies**
+2. Click **+ New**
+3. Configure **General**:
+   - **Display Name:** Nox OpenClaw Enforcement
+   - **Enabled:** Yes (or No for manual trigger only)
+   - **Trigger:** Custom (see below) or Recurring Check-in
+   - **Execution Frequency:** Ongoing
+4. Configure **Scripts**:
+   - Add "Nox OpenClaw Enforcement" script
+   - Set parameter values as needed
+5. Configure **Scope**:
+   - **Targets:** Smart Group "OpenClaw Detected" (see below)
+6. Click **Save**
+
+### Self Service Policy (Optional)
+
+Allow users or IT to manually run enforcement:
+
+1. Create policy as above
+2. Set **Trigger:** Self Service
+3. Configure **Self Service**:
+   - **Make the policy available in Self Service:** Yes
+   - **Button Name:** Remove OpenClaw
+   - **Description:** Removes unauthorized AI agent software
+
+## Smart Groups
+
+### OpenClaw Detected
+
+Identify devices with OpenClaw installed:
+
+1. Navigate to **Computers > Smart Computer Groups**
+2. Click **+ New**
+3. Configure:
+   - **Display Name:** OpenClaw Detected
+   - **Criteria:**
+
+| And/Or | Criteria | Operator | Value |
+|--------|----------|----------|-------|
+| | Extension Attribute: OpenClaw Status | is | Installed |
+| or | Extension Attribute: OpenClaw Status | is | Running |
+
+4. Click **Save**
+
+### OpenClaw Running
+
+Identify devices actively running OpenClaw (high priority):
+
+1. Navigate to **Computers > Smart Computer Groups**
+2. Click **+ New**
+3. Configure:
+   - **Display Name:** OpenClaw Running
+   - **Criteria:**
+
+| Criteria | Operator | Value |
+|----------|----------|-------|
+| Extension Attribute: OpenClaw Status | is | Running |
+
+4. Click **Save**
+
+### OpenClaw Clean
+
+Identify devices without OpenClaw (for compliance reporting):
+
+1. Create Smart Group with criteria:
+
+| Criteria | Operator | Value |
+|----------|----------|-------|
+| Extension Attribute: OpenClaw Status | is | Not Installed |
+
+## Exit Codes
+
+Scripts report these exit codes to Jamf:
+
+| Code | Detection Meaning | Enforcement Meaning | Jamf Behavior |
+|------|-------------------|---------------------|---------------|
+| 0 | Not detected | Successful removal | Policy marked successful |
+| 1 | Detected | Partial failure | Policy marked failed |
+| 2 | Script error | Script error | Policy marked failed |
+| 3 | N/A | Nothing to remove | Policy marked successful |
+
+## Webhook Integration
+
+### Configure Webhooks in Policy
+
+Set webhook parameters in the policy script configuration:
+
+- **Parameter 4:** `https://siem.example.com/api/v1/events`
+- **Parameter 5:** `Bearer YOUR_API_TOKEN`
+
+### Webhook Payload
+
+Detection events send this payload:
+
+```json
+{
+  "event": "openclaw.detection",
+  "version": "1.0",
+  "timestamp": "2026-02-03T10:30:00Z",
+  "status": "detected",
+  "severity": "high",
+  "host": {
+    "hostname": "MacBook-Pro.local",
+    "os": "Darwin",
+    "arch": "arm64",
+    "user": "jsmith"
+  },
+  "jamf": {
+    "computer_name": "MacBook-Pro.local",
+    "mount_point": "/",
+    "username": "jsmith"
+  },
+  "details": "CLI found at /usr/local/bin/openclaw; Config directory found",
+  "source": {
+    "tool": "nox-openclaw-detector",
+    "version": "1.0.0",
+    "vendor": "Nox Security"
+  }
+}
+```
+
+### SIEM Queries
+
+Example Splunk query:
+
+```splunk
+index=security sourcetype=nox_openclaw event=openclaw.detection status=detected
+| stats count by host.hostname, details
+| sort -count
+```
+
+Example Datadog query:
+
+```
+source:nox_openclaw status:detected | count by host
+```
+
+## Advanced Configurations
+
+### Staged Rollout
+
+1. Create a static group with pilot devices
+2. Scope detection policy to pilot group first
+3. Monitor results for 1-2 weeks
+4. Expand scope to all managed devices
+
+### Automated Remediation Workflow
+
+1. Detection policy runs daily
+2. Smart Group "OpenClaw Detected" updates automatically
+3. Enforcement policy scoped to Smart Group runs immediately
+4. Webhook alerts security team of both events
+
+### Compliance Reporting
+
+Create an Advanced Search:
+
+1. Navigate to **Computers > Search Inventory**
+2. Create criteria: Extension Attribute "OpenClaw Status" is not "Not Installed"
+3. Save as "OpenClaw Compliance Report"
+4. Schedule email delivery to security team
+
+## Troubleshooting
+
+### Script Not Running
+
+1. Verify policy scope includes target computers
+2. Check policy trigger and frequency settings
+3. Ensure computer is checking in to Jamf
+4. Review **Management > Logs** on the computer
+
+### Permission Errors
+
+1. Scripts should run as root (default for policies)
+2. Check for SIP restrictions on certain paths
+3. Verify MDM profile allows script execution
+
+### Extension Attribute Not Updating
+
+1. Force inventory update: `sudo jamf recon`
+2. Check extension attribute is enabled
+3. Verify script syntax is correct
+
+### Webhook Failures
+
+1. Verify URL is accessible from managed devices
+2. Check firewall rules allow outbound HTTPS
+3. Validate bearer token
+4. Add verbose logging to troubleshoot:
+   - Set Parameter 6 to `true`
+   - Check policy logs in Jamf
+
+### False Negatives
+
+If OpenClaw is installed but not detected:
+
+1. Check for non-standard installation paths
+2. Verify detection script has latest signatures
+3. Run with verbose mode enabled
+4. Report to support@nox.security
+
+## Best Practices
+
+1. **Test First**: Deploy to a pilot group before fleet-wide rollout
+2. **Schedule Off-Hours**: Run detection during low-usage periods
+3. **Monitor Results**: Review Jamf logs and Smart Group membership regularly
+4. **Use Webhooks**: Integrate with SIEM for centralized alerting
+5. **Document Exceptions**: Track any approved OpenClaw installations
+6. **Regular Updates**: Update scripts when new versions are available
+
+## Support
+
+- Email: support@nox.security
+- Documentation: https://docs.nox.security/jamf
+- Jamf Marketplace: [Nox OpenClaw Detector](https://marketplace.jamf.com)