openclaw-sentinel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,318 @@
+# 🛡️ OpenClaw Sentinel
+
+OpenClaw agents run with elevated privileges on your machine — shell access, file operations, network connections. Sentinel continuously monitors for unauthorized access, suspicious processes, privilege escalation, and system anomalies, alerting you in real-time through any OpenClaw channel.
+
+A security monitoring plugin for [OpenClaw](https://github.com/openclaw/openclaw), powered by [osquery](https://osquery.io).
+
+## What it does
+
+Sentinel watches your machine for suspicious activity and alerts you in real-time:
+
+- **🔍 Process monitoring** — unsigned binaries, privilege escalation, suspicious commands
+- **🔐 SSH monitoring** — logins from unknown hosts, brute force attempts
+- **🌐 Network monitoring** — new listening ports, unexpected services
+- **📁 File integrity** — changes to critical system files, new persistence mechanisms (LaunchDaemons, cron)
+- **🚨 Smart alerting** — learns your baseline (known hosts, ports) and only alerts on anomalies
+
+## Architecture
+
+```
+osqueryd (root daemon)
+    ↓ writes JSON results
+~/.openclaw/sentinel/logs/osquery/osqueryd.results.log
+    ↓ tailed by
+Sentinel watcher (fs.watch + poll fallback)
+    ↓ parsed results
+Analyzer (detection rules)
+    ↓ high/critical events
+OpenClaw → Signal/Slack/Telegram alert
+```
+
+Sentinel **does not** run osqueryd itself (it requires root). You start osqueryd separately via `sudo` or `launchd`, and Sentinel tails its result logs.
+
+## Prerequisites
+
+- **macOS** (Apple Silicon or Intel) or **Linux** (systemd-based)
+- [osquery](https://osquery.io) installed
+- [OpenClaw](https://github.com/openclaw/openclaw) running
+
+### Install osquery
+
+**macOS (Homebrew):**
+```bash
+brew install --cask osquery
+```
+
+**macOS (manual):**
+```bash
+# Download the official .pkg from https://osquery.io/downloads
+```
+
+> **Note:** osquery needs **Full Disk Access** on macOS for the Endpoint Security framework. Grant it to `/opt/osquery/lib/osquery.app/Contents/MacOS/osqueryd` in System Settings → Privacy & Security → Full Disk Access.
+
+**Linux (Debian/Ubuntu):**
+```bash
+wget -qO - https://pkg.osquery.io/deb/pubkey.gpg | sudo gpg --dearmor -o /usr/share/keyrings/osquery-archive-keyring.gpg
+echo "deb [signed-by=/usr/share/keyrings/osquery-archive-keyring.gpg] https://pkg.osquery.io/deb deb main" | sudo tee /etc/apt/sources.list.d/osquery.list
+sudo apt-get update && sudo apt-get install osquery
+```
+
+**Linux (RHEL/CentOS):**
+```bash
+curl -L https://pkg.osquery.io/rpm/GPG | sudo tee /etc/pki/rpm-gpg/RPM-GPG-KEY-osquery
+sudo yum-config-manager --add-repo https://pkg.osquery.io/rpm/osquery-s3-rpm.repo
+sudo yum install osquery
+```
+
+## Installation
+
+```bash
+openclaw plugins install /path/to/openclaw-sentinel
+openclaw gateway restart
+```
+
+## Configuration
+
+Add to your `~/.openclaw/openclaw.json` under `plugins.entries`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "sentinel": {
+        "enabled": true,
+        "config": {
+          "osqueryPath": "/opt/osquery/lib/osquery.app/Contents/MacOS/osqueryi",
+          "logPath": "~/.openclaw/sentinel",
+          "alertChannel": "signal",
+          "alertTo": "+1234567890",
+          "alertSeverity": "high"
+        }
+      }
+    }
+  }
+}
+```
+
+### Config options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `osqueryPath` | string | auto-detect | Path to `osqueryi` binary |
+| `logPath` | string | `~/.openclaw/sentinel` | Directory for sentinel data and osquery logs |
+| `alertChannel` | string | — | Channel for alerts (`signal`, `slack`, `telegram`, etc.) |
+| `alertTo` | string | — | Alert target (phone number, channel ID, etc.) |
+| `alertSeverity` | string | `high` | Minimum severity to alert: `critical`, `high`, `medium`, `low`, `info` |
+| `trustedSigningIds` | string[] | `[]` | Code signing IDs to skip (e.g. `com.apple`) |
+| `trustedPaths` | string[] | `[]` | Binary paths to skip (e.g. `/usr/bin`, `/opt/homebrew/bin`) |
+| `watchPaths` | string[] | `[]` | File paths to monitor for integrity changes |
+| `enableProcessMonitor` | boolean | `true` | Monitor process execution events |
+| `enableFileIntegrity` | boolean | `true` | Monitor file integrity events |
+| `enableNetworkMonitor` | boolean | `true` | Monitor network connections |
+| `pollIntervalMs` | number | `30000` | Fallback poll interval (ms) if fs.watch misses events |
+
+## Starting osqueryd
+
+Sentinel watches osqueryd's output — you need to start osqueryd separately. The included setup script handles everything.
+
+### Automated setup (recommended)
+
+```bash
+sudo ./scripts/setup-daemon.sh
+```
+
+The script auto-detects your OS and will:
+1. Find your osqueryd binary
+2. Create the sentinel directory structure (`~/.openclaw/sentinel/`)
+3. Generate a default osquery config if none exists
+4. Install a system daemon:
+   - **macOS**: LaunchDaemon (`/Library/LaunchDaemons/com.openclaw.osqueryd.plist`)
+   - **Linux**: systemd unit (`/etc/systemd/system/openclaw-osqueryd.service`)
+5. Start osqueryd — auto-starts on boot and restarts on crash
+
+```bash
+# macOS
+sudo launchctl list com.openclaw.osqueryd
+
+# Linux
+sudo systemctl status openclaw-osqueryd
+
+# Uninstall (both)
+sudo ./scripts/setup-daemon.sh --uninstall
+```
+
+### Manual start (for testing)
+
+```bash
+SENTINEL_DIR=~/.openclaw/sentinel
+
+sudo osqueryd \
+  --config_path=$SENTINEL_DIR/config/osquery.conf \
+  --database_path=$SENTINEL_DIR/db \
+  --logger_path=$SENTINEL_DIR/logs/osquery \
+  --pidfile=$SENTINEL_DIR/osqueryd.pid \
+  --logger_plugin=filesystem \
+  --disable_events=false \
+  --events_expiry=3600 \
+  --daemonize \
+  --force
+```
+
+### Full Disk Access
+
+For Endpoint Security framework support (process events, file events), grant Full Disk Access:
+
+**System Settings → Privacy & Security → Full Disk Access → Add osqueryd**
+
+The path is typically `/opt/osquery/lib/osquery.app/Contents/MacOS/osqueryd`.
+
+## Agent tools
+
+Sentinel registers three tools your OpenClaw agent can use:
+
+### `sentinel_status`
+
+Get monitoring status — daemon state, event counts, known baseline.
+
+### `sentinel_query`
+
+Run ad-hoc osquery SQL for security investigation:
+
+```
+"Show me all listening ports"
+→ sentinel_query: SELECT * FROM listening_ports WHERE port > 0;
+
+"What processes are running as root?"
+→ sentinel_query: SELECT name, path, cmdline FROM processes WHERE uid = 0;
+
+"Any SSH keys on this machine?"
+→ sentinel_query: SELECT * FROM user_ssh_keys;
+```
+
+### `sentinel_events`
+
+Get recent security events, filterable by severity or category:
+
+```
+"Show me critical events"
+→ sentinel_events: { severity: "critical" }
+
+"Any SSH-related events?"
+→ sentinel_events: { category: "ssh_login" }
+```
+
+## Usage examples
+
+Just ask your agent in natural language through any OpenClaw channel (Signal, Slack, Discord, etc.):
+
+**System overview:**
+> "How's my machine looking security-wise?"
+> "Any security alerts today?"
+> "What's the sentinel status?"
+
+**Network investigation:**
+> "What ports are open on this machine?"
+> "Show me all outbound connections"
+> "Is anything phoning home to an IP I don't recognize?"
+> "What's listening on port 5432?"
+
+**Process investigation:**
+> "What's running as root right now?"
+> "Any unsigned binaries running?"
+> "Show me recently started processes"
+> "What launched in the last hour?"
+
+**SSH & access:**
+> "Who's logged into this machine?"
+> "Any failed SSH attempts?"
+> "Has anyone tried to brute force SSH?"
+> "Show me all SSH keys on the system"
+
+**Persistence & malware hunting:**
+> "Are there any new LaunchDaemons I should know about?"
+> "Show me all cron jobs"
+> "Any changes to /etc/hosts or sudoers?"
+> "What browser extensions are installed?"
+
+**Forensics:**
+> "What happened on this machine between 2am and 5am?"
+> "Show me all shell history with sudo commands"
+> "Which processes have the most open file descriptors?"
+> "What DNS queries were made in the last hour?"
+
+The agent translates these into osquery SQL, runs them through `sentinel_query`, and explains the results in plain English.
+
+## Detection rules
+
+| Category | Severity | Trigger |
+|----------|----------|---------|
+| Unsigned binary | high | Process executed without valid code signature |
+| Privilege escalation | critical | `sudo`, `su`, `doas` with unexpected targets |
+| Suspicious command | high | `curl \| sh`, `base64 -d`, `nc -l`, reverse shells |
+| Unknown SSH login | high | SSH from IP not in baseline |
+| SSH brute force | critical | 5+ failed auth attempts in short window |
+| New listening port | medium | Port not seen during baseline scan |
+| File integrity | high | Changes to watched paths |
+| Persistence | high | New LaunchDaemon, LaunchAgent, or cron entry |
+
+## How baseline works
+
+On startup, Sentinel snapshots:
+- All currently logged-in remote hosts → **known hosts**
+- All currently listening ports → **known ports**
+
+Future events are compared against this baseline. Only anomalies trigger alerts. The baseline refreshes each time the gateway restarts.
+
+## Example alerts
+
+```
+🚨 SECURITY ALERT
+Severity: HIGH
+Category: ssh_login
+Time: 2026-02-21 10:15:00
+
+Unknown SSH login from 203.0.113.42
+User: root | TTY: ttys003
+
+This host is not in the known baseline.
+```
+
+```
+🔴 SECURITY ALERT
+Severity: CRITICAL
+Category: privilege_escalation
+Time: 2026-02-21 14:30:00
+
+Privilege escalation detected
+User: www → root | PID: 54321
+Command: sudo /bin/bash
+```
+
+## Development
+
+```bash
+git clone https://github.com/sunil-sadasivan/openclaw-sentinel.git
+cd openclaw-sentinel
+npm install
+npm run build          # Compile TypeScript
+npm run dev            # Watch mode
+
+# Install locally for testing
+openclaw plugins install .
+openclaw gateway restart
+```
+
+## Project structure
+
+```
+src/
+├── index.ts       # Plugin entry point — tool registration, watcher startup
+├── config.ts      # SentinelConfig interface, defaults, SecurityEvent types
+├── osquery.ts     # osquery binary discovery, SQL execution, config generation
+├── analyzer.ts    # Detection rules — processes, SSH, ports, files, persistence
+└── watcher.ts     # Event-driven log tailer (fs.watch + poll fallback)
+```
+
+## License
+
+MIT

package/dist/__tests__/alerts.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/alerts.test.js

@@ -0,0 +1,86 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { shouldAlert, meetsThreshold, createAlertState } from "../alerts.js";
+function makeEvent(title, severity = "high") {
+    return {
+        id: "test",
+        timestamp: Date.now(),
+        severity,
+        category: "process",
+        title,
+        description: "test",
+        details: {},
+        hostname: "test",
+    };
+}
+describe("shouldAlert", () => {
+    it("allows first alert", () => {
+        const state = createAlertState();
+        assert.equal(shouldAlert(makeEvent("Test"), state), true);
+    });
+    it("deduplicates same title within 5 minutes", () => {
+        const state = createAlertState();
+        const now = Date.now();
+        assert.equal(shouldAlert(makeEvent("Same Event"), state, now), true);
+        assert.equal(shouldAlert(makeEvent("Same Event"), state, now + 1000), false);
+        assert.equal(shouldAlert(makeEvent("Same Event"), state, now + 60_000), false);
+        assert.equal(shouldAlert(makeEvent("Same Event"), state, now + 299_000), false);
+    });
+    it("allows same title after 5 minute window (entries expire from rate limit window)", () => {
+        const state = createAlertState();
+        const now = Date.now();
+        shouldAlert(makeEvent("Recurring"), state, now);
+        // After 5+ minutes AND after the 1-min rate limit window cleans up
+        assert.equal(shouldAlert(makeEvent("Recurring"), state, now + 301_000), true);
+    });
+    it("allows different titles", () => {
+        const state = createAlertState();
+        const now = Date.now();
+        assert.equal(shouldAlert(makeEvent("Event A"), state, now), true);
+        assert.equal(shouldAlert(makeEvent("Event B"), state, now), true);
+        assert.equal(shouldAlert(makeEvent("Event C"), state, now), true);
+    });
+    it("rate limits at 10 per minute", () => {
+        const state = createAlertState();
+        const now = Date.now();
+        for (let i = 0; i < 10; i++) {
+            assert.equal(shouldAlert(makeEvent(`Event ${i}`), state, now), true);
+        }
+        // 11th should be blocked
+        assert.equal(shouldAlert(makeEvent("Event 10"), state, now), false);
+    });
+    it("allows alerts again after rate limit window expires", () => {
+        const state = createAlertState();
+        const now = Date.now();
+        for (let i = 0; i < 10; i++) {
+            shouldAlert(makeEvent(`Event ${i}`), state, now);
+        }
+        // After 1 minute, rate limit resets
+        assert.equal(shouldAlert(makeEvent("New Event"), state, now + 61_000), true);
+    });
+});
+describe("meetsThreshold", () => {
+    it("critical meets all thresholds", () => {
+        assert.equal(meetsThreshold("critical", "info"), true);
+        assert.equal(meetsThreshold("critical", "low"), true);
+        assert.equal(meetsThreshold("critical", "medium"), true);
+        assert.equal(meetsThreshold("critical", "high"), true);
+        assert.equal(meetsThreshold("critical", "critical"), true);
+    });
+    it("info only meets info threshold", () => {
+        assert.equal(meetsThreshold("info", "info"), true);
+        assert.equal(meetsThreshold("info", "low"), false);
+        assert.equal(meetsThreshold("info", "medium"), false);
+        assert.equal(meetsThreshold("info", "high"), false);
+    });
+    it("high meets high and below", () => {
+        assert.equal(meetsThreshold("high", "high"), true);
+        assert.equal(meetsThreshold("high", "medium"), true);
+        assert.equal(meetsThreshold("high", "critical"), false);
+    });
+    it("defaults to high when invalid severity given", () => {
+        assert.equal(meetsThreshold("critical", "invalid"), true);
+        assert.equal(meetsThreshold("high", "invalid"), true);
+        assert.equal(meetsThreshold("medium", "invalid"), false);
+    });
+});

package/dist/__tests__/analyzer.test.d.ts

@@ -0,0 +1 @@
+export {};