nox-openclaw-hunter 1.0.0

package/docs/jumpcloud.md

@@ -0,0 +1,510 @@
+# JumpCloud Integration Guide
+
+Deploy Nox OpenClaw detection and enforcement scripts across your Windows, macOS, and Linux fleet using JumpCloud.
+
+## Overview
+
+This guide explains how to:
+
+1. Create detection and enforcement commands in JumpCloud
+2. Configure triggers and schedules for automation
+3. Set up System Insights for inventory reporting
+4. Use the JumpCloud API for automation
+5. Configure webhook integration for SIEM alerting
+
+## Prerequisites
+
+- JumpCloud account with Device Management
+- JumpCloud agent installed on managed devices
+- Admin access to JumpCloud console
+- Devices enrolled in JumpCloud
+- (Optional) JumpCloud API key for automation
+
+## Quick Start
+
+1. Generate scripts:
+   ```bash
+   nox export --platform jumpcloud --mode detect --output ./jumpcloud-scripts
+   nox export --platform jumpcloud --mode enforce --output ./jumpcloud-scripts
+   ```
+
+2. Create commands in JumpCloud console
+3. Assign to device groups
+4. Configure triggers or schedules
+
+## Script Setup
+
+### Step 1: Generate Scripts
+
+Generate JumpCloud-optimized scripts using the CLI:
+
+```bash
+# Detection scripts
+nox export --platform jumpcloud --mode detect --output ./jumpcloud-scripts
+
+# Enforcement scripts
+nox export --platform jumpcloud --mode enforce --output ./jumpcloud-scripts
+
+# With webhook integration
+nox export --platform jumpcloud --mode detect \
+  --webhook https://siem.example.com/webhook \
+  --webhook-token YOUR_TOKEN \
+  --output ./jumpcloud-scripts
+```
+
+This generates scripts for all supported platforms:
+- `detect-openclaw.sh` - macOS/Linux detection
+- `detect-openclaw.ps1` - Windows detection
+- `enforce-openclaw.sh` - macOS/Linux enforcement
+- `enforce-openclaw.ps1` - Windows enforcement
+
+### Step 2: Create macOS Detection Command
+
+1. Navigate to **Device Management > Commands**
+2. Click **+** (Add Command)
+3. Configure:
+   - **Name:** Nox OpenClaw Detection (macOS)
+   - **Command:** Paste contents of `detect-openclaw.sh`
+   - **Command Type:** Mac
+   - **Run As:** Root
+   - **Timeout:** 120 seconds
+4. Under **Launch Options:**
+   - **Launch Type:** Trigger
+   - **Trigger Name:** `nox-openclaw-detect`
+5. Under **Schedule** (optional):
+   - **Repeat Type:** Day
+   - **Repeat Interval:** 1
+6. Click **Save**
+
+### Step 3: Create Linux Detection Command
+
+1. Click **+** (Add Command)
+2. Configure:
+   - **Name:** Nox OpenClaw Detection (Linux)
+   - **Command:** Paste contents of `detect-openclaw.sh`
+   - **Command Type:** Linux
+   - **Run As:** Root
+   - **Timeout:** 120 seconds
+3. Configure trigger and schedule as above
+4. Click **Save**
+
+### Step 4: Create Windows Detection Command
+
+1. Click **+** (Add Command)
+2. Configure:
+   - **Name:** Nox OpenClaw Detection (Windows)
+   - **Command:** Paste contents of `detect-openclaw.ps1`
+   - **Command Type:** Windows
+   - **Shell:** PowerShell
+   - **Run As:** Administrator (root)
+   - **Timeout:** 120 seconds
+3. Configure trigger and schedule
+4. Click **Save**
+
+### Step 5: Create Enforcement Commands
+
+Repeat the above steps for enforcement scripts:
+
+- **Timeout:** 300 seconds (longer for enforcement)
+- **Launch Type:** Manual (for on-demand remediation)
+- Or configure trigger: `nox-openclaw-enforce`
+
+## Command Configuration Details
+
+### Command Types
+
+| OS | Command Type | Shell | Script Extension |
+|----|-------------|-------|------------------|
+| macOS | Mac | /bin/bash | .sh |
+| Linux | Linux | /bin/bash | .sh |
+| Windows | Windows | PowerShell | .ps1 |
+
+### Run As Options
+
+| Setting | Description | Use Case |
+|---------|-------------|----------|
+| Root/Administrator | Full system access | Required for enforcement |
+| Current User | User-level access | Detection only (limited) |
+
+### Launch Types
+
+| Type | Description |
+|------|-------------|
+| Manual | Run on-demand from console or API |
+| Trigger | Run via API trigger name |
+| Schedule | Run on recurring schedule |
+
+## Device Group Assignment
+
+### Assign Command to Groups
+
+1. Open the command
+2. Click **Device Groups** tab
+3. Select target groups:
+   - All Devices
+   - macOS Devices
+   - Linux Servers
+   - Windows Workstations
+4. Click **Save**
+
+### Assign to Individual Systems
+
+1. Click **Systems** tab
+2. Select target systems
+3. Click **Save**
+
+## System Insights Integration
+
+Use System Insights to track OpenClaw status in device inventory.
+
+### Create Custom Fact Script
+
+1. Navigate to **Device Management > Commands**
+2. Create command:
+   - **Name:** Nox OpenClaw Status Fact
+   - **Command:**
+
+```bash
+#!/bin/bash
+# Nox OpenClaw Status Fact for JumpCloud System Insights
+
+STATUS="not_installed"
+
+# Check CLI binary
+if command -v openclaw &>/dev/null; then
+    STATUS="installed"
+fi
+
+# Check common paths
+for path in /usr/local/bin/openclaw /opt/homebrew/bin/openclaw /usr/bin/openclaw; do
+    if [[ -f "$path" ]]; then
+        STATUS="installed"
+        break
+    fi
+done
+
+# Check app bundle (macOS)
+if [[ -d "/Applications/OpenClaw.app" ]]; then
+    STATUS="installed"
+fi
+
+# Check config directory
+if [[ -d "$HOME/.openclaw" ]] || ls -d /Users/*/.openclaw &>/dev/null 2>&1 || ls -d /home/*/.openclaw &>/dev/null 2>&1; then
+    STATUS="installed"
+fi
+
+# Check if running
+if pgrep -f "openclaw" > /dev/null 2>&1; then
+    STATUS="running"
+fi
+
+# Check gateway port
+if command -v nc &>/dev/null && nc -z localhost 18789 2>/dev/null; then
+    STATUS="running"
+fi
+
+echo "$STATUS"
+```
+
+3. Configure:
+   - **Command Type:** Mac (create separate for Linux)
+   - **Run As:** Root
+   - **Schedule:** Repeat Daily
+4. Assign to all devices
+
+### Query System Insights
+
+View aggregated results in JumpCloud console:
+
+1. Navigate to **Insights > Systems**
+2. Create custom query or filter
+3. Export data for reporting
+
+## Automated Workflows
+
+### Scheduled Detection
+
+Run detection daily across your fleet:
+
+1. Set command Launch Type to **Trigger + Schedule**
+2. Configure Schedule:
+   - **Repeat Type:** Day
+   - **Repeat Interval:** 1
+   - **Time:** 02:00 (off-hours recommended)
+
+### On-Demand Enforcement via API
+
+Trigger enforcement when detection finds OpenClaw:
+
+```bash
+# Trigger enforcement via API
+curl -X POST "https://console.jumpcloud.com/api/command/trigger/nox-openclaw-enforce" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"systemIds": ["system_id_here"]}'
+```
+
+### Webhook-Based Automation
+
+1. Configure detection script with webhook
+2. Webhook notifies your automation system
+3. Automation triggers enforcement via JumpCloud API
+
+## Monitoring Results
+
+### Command Results Dashboard
+
+1. Navigate to **Device Management > Commands**
+2. Click on a command
+3. Select **Results** tab
+4. Filter by:
+   - Exit Code
+   - Date Range
+   - System Name
+
+### Exit Codes
+
+| Code | Detection Meaning | Enforcement Meaning |
+|------|-------------------|---------------------|
+| 0 | OpenClaw not detected | Enforcement successful |
+| 1 | OpenClaw detected | Partial failure |
+| 2 | Script error | Script error |
+| 3 | N/A | Nothing to enforce |
+
+### Create Alerts
+
+Set up webhooks for command failures:
+
+1. Navigate to **Settings > Webhooks**
+2. Add webhook URL
+3. Select events: Command Results
+4. Configure filters for specific exit codes
+
+## API Integration
+
+### Get API Key
+
+1. Navigate to your avatar > **API Settings**
+2. Create API key with appropriate permissions
+
+### Create Command via API
+
+```bash
+curl -X POST "https://console.jumpcloud.com/api/commands" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Nox OpenClaw Detection (macOS)",
+    "command": "#!/bin/bash\n# Script content...",
+    "commandType": "mac",
+    "shell": "/bin/bash",
+    "user": "root",
+    "sudo": true,
+    "timeout": "120",
+    "launchType": "trigger",
+    "trigger": "nox-openclaw-detect"
+  }'
+```
+
+### Run Command on Demand
+
+```bash
+# Run on specific systems
+curl -X POST "https://console.jumpcloud.com/api/commands/{command_id}/run" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"systems": ["system_id_1", "system_id_2"]}'
+```
+
+### Get Command Results
+
+```bash
+curl -X GET "https://console.jumpcloud.com/api/commands/{command_id}/results" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "Content-Type: application/json"
+```
+
+### Trigger Command by Name
+
+```bash
+curl -X POST "https://console.jumpcloud.com/api/command/trigger/nox-openclaw-detect" \
+  -H "x-api-key: YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"systemIds": ["system_id"]}'
+```
+
+## Webhook Integration
+
+### Configure in Scripts
+
+Edit scripts before uploading:
+
+```bash
+# At the top of shell scripts
+WEBHOOK_URL="https://siem.example.com/api/v1/events"
+WEBHOOK_TOKEN="YOUR_API_TOKEN"
+```
+
+```powershell
+# At the top of PowerShell scripts
+$WebhookUrl = "https://siem.example.com/api/v1/events"
+$WebhookToken = "YOUR_API_TOKEN"
+```
+
+### Webhook Payload
+
+```json
+{
+  "event": "openclaw.detection",
+  "version": "1.0",
+  "timestamp": "2026-02-03T10:30:00Z",
+  "status": "detected",
+  "severity": "high",
+  "host": {
+    "hostname": "server-01.example.com",
+    "os": "Linux",
+    "arch": "x86_64",
+    "user": "admin"
+  },
+  "details": "CLI found at /usr/local/bin/openclaw; Config directory found",
+  "source": {
+    "tool": "nox-openclaw-detector",
+    "version": "1.0.0",
+    "vendor": "Nox Security"
+  }
+}
+```
+
+## Device Groups for Targeting
+
+### Recommended Groups
+
+Create device groups for organized targeting:
+
+| Group Name | Criteria | Use Case |
+|------------|----------|----------|
+| All Managed Devices | All enrolled systems | Detection scanning |
+| macOS Workstations | OS = macOS | Mac-specific commands |
+| Linux Servers | OS = Linux | Linux-specific commands |
+| Windows Workstations | OS = Windows | Windows-specific commands |
+| High Security | Tag = high-security | More frequent scanning |
+
+### Dynamic Groups
+
+Create groups based on command results:
+
+1. Run detection command
+2. Parse results via API
+3. Update group membership programmatically
+4. Target enforcement to detected group
+
+## Advanced Configurations
+
+### Multi-Stage Deployment
+
+1. **Stage 1: Detection Only**
+   - Deploy detection to all devices
+   - Review results for 1-2 weeks
+   - Identify scope of OpenClaw presence
+
+2. **Stage 2: Targeted Enforcement**
+   - Create group of detected devices
+   - Deploy enforcement to detected group
+   - Monitor remediation success
+
+3. **Stage 3: Continuous Monitoring**
+   - Schedule daily detection
+   - Automate enforcement triggers
+   - Alert on new detections
+
+### High-Security Mode
+
+For critical systems:
+
+1. Schedule detection every 6 hours
+2. Configure immediate webhook alerts
+3. Set up auto-enforcement triggers
+4. Enable detailed logging
+
+### Cross-Platform Consistency
+
+Ensure consistent detection across all platforms:
+
+1. Create identical command names with OS suffix
+2. Use same trigger names
+3. Configure same schedules
+4. Aggregate results by trigger name
+
+## Troubleshooting
+
+### Command Not Running
+
+1. Verify JumpCloud agent is running:
+   ```bash
+   # macOS/Linux
+   sudo systemctl status jcagent
+   # or
+   sudo launchctl list | grep jumpcloud
+   ```
+
+2. Check agent logs:
+   - macOS/Linux: `/var/log/jcagent.log`
+   - Windows: `C:\Windows\Temp\jcagent.log`
+
+3. Verify device is online in JumpCloud console
+
+4. Check device group assignment
+
+### Permission Errors
+
+1. Verify command runs as root/Administrator
+2. Check sudo is enabled for command
+3. Verify script has correct permissions
+4. Check for SELinux/AppArmor restrictions (Linux)
+
+### Timeout Issues
+
+1. Increase timeout value:
+   - Detection: 120-180 seconds
+   - Enforcement: 300-600 seconds
+
+2. Check for hung processes during enforcement
+
+3. Simplify script if consistently timing out
+
+### Webhook Failures
+
+1. Verify URL is accessible from devices
+2. Check corporate firewall allows outbound HTTPS
+3. Validate authentication token
+4. Check script has curl/Invoke-RestMethod available
+
+### Windows-Specific Issues
+
+1. Verify PowerShell version (5.1+ required)
+2. Check execution policy isn't blocking
+3. Ensure Windows Firewall allows JumpCloud agent
+
+### macOS-Specific Issues
+
+1. Check System Integrity Protection status
+2. Verify Full Disk Access for JumpCloud agent
+3. Check for MDM profile restrictions
+
+## Best Practices
+
+1. **Organize by OS**: Create separate commands for each operating system
+2. **Use Device Groups**: Avoid assigning to individual systems
+3. **Schedule Off-Hours**: Minimize user impact during enforcement
+4. **Monitor Results**: Regularly review command results and failures
+5. **Test First**: Deploy to pilot group before fleet-wide rollout
+6. **Enable Webhooks**: Integrate with SIEM for centralized alerting
+7. **Document Triggers**: Maintain list of trigger names and purposes
+8. **API Automation**: Use API for advanced workflows and integrations
+
+## Support
+
+- Email: support@nox.security
+- Documentation: https://docs.nox.security/jumpcloud
+- JumpCloud Support: https://support.jumpcloud.com
+- JumpCloud API Docs: https://docs.jumpcloud.com/api

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "nox-openclaw-hunter",
+  "version": "1.0.0",
+  "description": "OpenClaw Detection & Removal CLI by Nox Security",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "nox": "./bin/nox.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node bin/nox.js",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "compile": "bun build ./src/index.ts --compile --outfile nox",
+    "compile:macos-arm": "bun build ./src/index.ts --compile --target=bun-darwin-arm64 --outfile nox-macos-arm64",
+    "compile:macos-x64": "bun build ./src/index.ts --compile --target=bun-darwin-x64 --outfile nox-macos-x64",
+    "compile:linux": "bun build ./src/index.ts --compile --target=bun-linux-x64 --outfile nox-linux",
+    "compile:windows": "bun build ./src/index.ts --compile --target=bun-windows-x64 --outfile nox-win.exe"
+  },
+  "keywords": [
+    "security",
+    "openclaw",
+    "detection",
+    "purge",
+    "cli",
+    "endpoint-security",
+    "mdm",
+    "siem"
+  ],
+  "author": "Nox Security <support@nox.security>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Arampc/Nox-OpenClaw-Hunter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Arampc/Nox-OpenClaw-Hunter/issues"
+  },
+  "homepage": "https://nox.security",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "cli-table3": "^0.6.3",
+    "commander": "^12.0.0",
+    "inquirer": "^9.2.12",
+    "ora": "^8.0.1",
+    "yaml": "^2.3.4"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.9",
+    "@types/node": "^20.11.0",
+    "esbuild": "^0.20.0",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}