openclaw-sentinel 0.1.0 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 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).
+A security monitoring plugin for [OpenClaw](https://github.com/openclaw/openclaw), powered by [osquery](https://github.com/osquery/osquery).
 
 ## What it does
 
@@ -33,7 +33,7 @@ Sentinel **does not** run osqueryd itself (it requires root). You start osqueryd
 ## Prerequisites
 
 - **macOS** (Apple Silicon or Intel) or **Linux** (systemd-based)
-- [osquery](https://osquery.io) installed
+- [osquery](https://github.com/osquery/osquery) installed
 - [OpenClaw](https://github.com/openclaw/openclaw) running
 
 ### Install osquery
@@ -66,8 +66,45 @@ sudo yum install osquery
 
 ## Installation
 
+### From npm (recommended)
+
+```bash
+npm install -g openclaw-sentinel
+```
+
+Then add the plugin to your `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "sentinel": {
+        "enabled": true,
+        "module": "openclaw-sentinel",
+        "config": {
+          "alertChannel": "signal",
+          "alertTo": "+1234567890",
+          "alertSeverity": "high"
+        }
+      }
+    }
+  }
+}
+```
+
+Restart your gateway:
+
 ```bash
-openclaw plugins install /path/to/openclaw-sentinel
+openclaw gateway restart
+```
+
+### From source (development)
+
+```bash
+git clone https://github.com/sunil-sadasivan/openclaw-sentinel.git
+cd openclaw-sentinel
+npm install && npm run build
+openclaw plugins install .
 openclaw gateway restart
 ```
 
@@ -296,10 +333,7 @@ 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
+npm test               # Run tests (60 tests)
 ```
 
 ## Project structure

package/dist/__tests__/alerts.test.js

@@ -18,20 +18,19 @@ describe("shouldAlert", () => {
         const state = createAlertState();
         assert.equal(shouldAlert(makeEvent("Test"), state), true);
     });
-    it("deduplicates same title within 5 minutes", () => {
+    it("deduplicates same title within 1 minute", () => {
         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);
+        assert.equal(shouldAlert(makeEvent("Same Event"), state, now + 30_000), false);
+        assert.equal(shouldAlert(makeEvent("Same Event"), state, now + 59_000), false);
     });
-    it("allows same title after 5 minute window (entries expire from rate limit window)", () => {
+    it("allows same title after 1 minute 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);
+        assert.equal(shouldAlert(makeEvent("Recurring"), state, now + 61_000), true);
     });
     it("allows different titles", () => {
         const state = createAlertState();

package/dist/__tests__/analyzer.test.js

@@ -120,30 +120,34 @@ describe("analyzeProcessEvents", () => {
 });
 describe("analyzeLoginEvents", () => {
     const knownHosts = new Set(["192.168.1.100", "100.64.0.1"]);
-    it("detects unknown remote host", () => {
+    it("detects unknown remote host as high severity", () => {
         const rows = [
             { user: "root", host: "203.0.113.42", type: "user" },
         ];
         const events = analyzeLoginEvents(rows, knownHosts);
         assert.equal(events.length, 1);
         assert.equal(events[0].severity, "high");
-        assert.equal(events[0].category, "auth");
+        assert.equal(events[0].category, "ssh_login");
     });
-    it("skips known hosts", () => {
+    it("emits info event for known hosts", () => {
         const rows = [
             { user: "sunil", host: "192.168.1.100", type: "user" },
         ];
         const events = analyzeLoginEvents(rows, knownHosts);
-        assert.equal(events.length, 0);
+        assert.equal(events.length, 1);
+        assert.equal(events[0].severity, "info");
+        assert.equal(events[0].category, "ssh_login");
     });
-    it("skips Tailscale CGNAT range (100.64-127.x.x)", () => {
+    it("emits info event for Tailscale CGNAT range (100.64-127.x.x)", () => {
         const rows = [
             { user: "sunil", host: "100.79.207.74", type: "user" },
             { user: "sunil", host: "100.94.48.17", type: "user" },
             { user: "sunil", host: "100.127.255.255", type: "user" },
         ];
         const events = analyzeLoginEvents(rows, new Set());
-        assert.equal(events.length, 0);
+        assert.equal(events.length, 3);
+        assert.equal(events[0].severity, "info");
+        assert.ok(events[0].description.includes("Tailscale"));
     });
     it("does NOT skip non-Tailscale 100.x IPs", () => {
         const rows = [

package/dist/__tests__/log-stream.test.d.ts

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

package/dist/__tests__/log-stream.test.js

@@ -0,0 +1,165 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+// We can't easily test the spawned process, but we can test the parsing logic
+// by importing and testing the module's parse functions.
+// Since parse functions are not exported, we test via the public class behavior.
+// Instead, test the SSH event patterns that the parser handles:
+describe("SSH log line patterns", () => {
+    // These patterns match what sshd outputs and our parser expects
+    it("matches 'Accepted publickey' pattern", () => {
+        const line = '2026-02-22 16:30:00.123456-0500  0x1234  Default  0x0  0  sshd: Accepted publickey for sunil from 100.79.207.74 port 52341 ssh2';
+        const match = line.match(/sshd.*?:\s+Accepted\s+(\S+)\s+for\s+(\S+)\s+from\s+(\S+)\s+port\s+(\d+)/);
+        assert.ok(match);
+        assert.equal(match[1], "publickey");
+        assert.equal(match[2], "sunil");
+        assert.equal(match[3], "100.79.207.74");
+        assert.equal(match[4], "52341");
+    });
+    it("matches 'Accepted password' pattern", () => {
+        const line = '2026-02-22 16:30:00.123456-0500  0x1234  Default  0x0  0  sshd: Accepted password for root from 203.0.113.42 port 22 ssh2';
+        const match = line.match(/sshd.*?:\s+Accepted\s+(\S+)\s+for\s+(\S+)\s+from\s+(\S+)\s+port\s+(\d+)/);
+        assert.ok(match);
+        assert.equal(match[1], "password");
+        assert.equal(match[2], "root");
+        assert.equal(match[3], "203.0.113.42");
+    });
+    it("matches 'Failed password' pattern", () => {
+        const line = '2026-02-22 16:30:00.123456-0500  0x1234  Default  0x0  0  sshd: Failed password for sunil from 203.0.113.42 port 22 ssh2';
+        const match = line.match(/sshd.*?:\s+Failed\s+password\s+for\s+(?:invalid\s+user\s+)?(\S+)\s+from\s+(\S+)\s+port\s+(\d+)/);
+        assert.ok(match);
+        assert.equal(match[1], "sunil");
+        assert.equal(match[2], "203.0.113.42");
+    });
+    it("matches 'Failed password for invalid user' pattern", () => {
+        const line = '2026-02-22 16:30:00.123456-0500  0x1234  Default  0x0  0  sshd: Failed password for invalid user admin from 203.0.113.42 port 22 ssh2';
+        const match = line.match(/sshd.*?:\s+Failed\s+password\s+for\s+(?:invalid\s+user\s+)?(\S+)\s+from\s+(\S+)\s+port\s+(\d+)/);
+        assert.ok(match);
+        assert.equal(match[1], "admin");
+        assert.equal(match[2], "203.0.113.42");
+    });
+    it("matches 'Invalid user' pattern", () => {
+        const line = '2026-02-22 16:30:00.123456-0500  0x1234  Default  0x0  0  sshd: Invalid user admin from 203.0.113.42 port 22';
+        const match = line.match(/sshd.*?:\s+Invalid\s+user\s+(\S+)\s+from\s+(\S+)\s+port\s+(\d+)/);
+        assert.ok(match);
+        assert.equal(match[1], "admin");
+        assert.equal(match[2], "203.0.113.42");
+    });
+    it("matches macOS sshd-session USER_PROCESS pattern", () => {
+        const line = "Feb 22 16:39:32 sunils-mac-mini sshd-session: sunil [priv][58912]: USER_PROCESS: 58916 ttys001";
+        const match = line.match(/sshd-session:\s+(\S+)\s+\[priv\]\[(\d+)\]:\s+USER_PROCESS:\s+(\d+)\s+(\S+)/);
+        assert.ok(match);
+        assert.equal(match[1], "sunil");
+        assert.equal(match[2], "58912");
+        assert.equal(match[3], "58916");
+        assert.equal(match[4], "ttys001");
+    });
+    it("does not match sshd-session DEAD_PROCESS", () => {
+        const line = "Feb 22 16:38:12 sunils-mac-mini sshd-session: sunil [priv][53930]: DEAD_PROCESS: 53934 ttys012";
+        const match = line.match(/sshd-session:\s+(\S+)\s+\[priv\]\[(\d+)\]:\s+USER_PROCESS:\s+(\d+)\s+(\S+)/);
+        assert.equal(match, null);
+    });
+    it("does not match unrelated sshd lines", () => {
+        const line = '2026-02-22 16:30:00.123456-0500  0x1234  Default  0x0  0  sshd: Connection closed by 100.79.207.74 port 52341';
+        const accepted = line.match(/sshd.*?:\s+Accepted/);
+        const failed = line.match(/sshd.*?:\s+Failed\s+password/);
+        const invalid = line.match(/sshd.*?:\s+Invalid\s+user/);
+        assert.equal(accepted, null);
+        assert.equal(failed, null);
+        assert.equal(invalid, null);
+    });
+});
+describe("Tailscale IP detection", () => {
+    function isTailscaleIP(host) {
+        const octets = host.split(".").map(Number);
+        return octets[0] === 100 && octets[1] >= 64 && octets[1] <= 127;
+    }
+    it("identifies Tailscale IPs", () => {
+        assert.equal(isTailscaleIP("100.79.207.74"), true);
+        assert.equal(isTailscaleIP("100.94.48.17"), true);
+        assert.equal(isTailscaleIP("100.64.0.1"), true);
+        assert.equal(isTailscaleIP("100.127.255.255"), true);
+    });
+    it("rejects non-Tailscale IPs", () => {
+        assert.equal(isTailscaleIP("100.63.255.255"), false);
+        assert.equal(isTailscaleIP("100.128.0.1"), false);
+        assert.equal(isTailscaleIP("192.168.1.1"), false);
+        assert.equal(isTailscaleIP("203.0.113.42"), false);
+    });
+});
+describe("Linux sudo log patterns", () => {
+    it("matches sudo command execution", () => {
+        const line = "Feb 22 16:30:00 myhost sudo[1234]:   sunil : TTY=pts/0 ; PWD=/home/sunil ; USER=root ; COMMAND=/usr/bin/apt update";
+        const match = line.match(/sudo\[\d+\]:\s+(\S+)\s*:\s*(?:.*?;\s*)?TTY=(\S+)\s*;\s*PWD=(\S+)\s*;\s*USER=(\S+)\s*;\s*COMMAND=(.*)/);
+        assert.ok(match);
+        assert.equal(match[1], "sunil");
+        assert.equal(match[2], "pts/0");
+        assert.equal(match[4], "root");
+        assert.equal(match[5].trim(), "/usr/bin/apt update");
+    });
+    it("matches sudo with incorrect password attempts", () => {
+        const line = "Feb 22 16:30:00 myhost sudo[1234]:   sunil : 3 incorrect password attempts ; TTY=pts/0 ; PWD=/home/sunil ; USER=root ; COMMAND=/usr/bin/rm -rf /";
+        const match = line.match(/sudo\[\d+\]:\s+(\S+)\s*:\s*(?:.*?;\s*)?TTY=(\S+)\s*;\s*PWD=(\S+)\s*;\s*USER=(\S+)\s*;\s*COMMAND=(.*)/);
+        assert.ok(match);
+        assert.equal(match[1], "sunil");
+        assert.ok(line.includes("incorrect password"));
+    });
+    it("matches sudo PAM session opened", () => {
+        const line = "Feb 22 16:30:00 myhost sudo[1234]: pam_unix(sudo:session): session opened for user root(uid=0) by sunil(uid=1000)";
+        const match = line.match(/sudo\[\d+\]:\s+pam_unix\(sudo:session\):\s+session\s+opened\s+for\s+user\s+(\S+).*?by\s+(\S+)/);
+        assert.ok(match);
+        assert.equal(match[1], "root(uid=0)");
+        assert.equal(match[2], "sunil(uid=1000)");
+    });
+});
+describe("Linux user account log patterns", () => {
+    it("matches useradd new user (strips trailing comma)", () => {
+        const line = "Feb 22 16:30:00 myhost useradd[1234]: new user: name=backdoor, UID=1001, GID=1001, home=/home/backdoor, shell=/bin/bash";
+        const match = line.match(/useradd\[\d+\]:\s+new\s+user:\s+name=([^,\s]+)/);
+        assert.ok(match);
+        assert.equal(match[1], "backdoor");
+    });
+    it("matches userdel delete user", () => {
+        const line = "Feb 22 16:30:00 myhost userdel[1234]: delete user 'olduser'";
+        const match = line.match(/userdel\[\d+\]:\s+delete\s+user\s+'(\S+)'/);
+        assert.ok(match);
+        assert.equal(match[1], "olduser");
+    });
+    it("matches passwd password changed", () => {
+        const line = "Feb 22 16:30:00 myhost passwd[1234]: pam_unix(passwd:chauthtok): password changed for sunil";
+        const match = line.match(/passwd\[\d+\]:\s+pam_unix\(passwd:chauthtok\):\s+password\s+changed\s+for\s+(\S+)/);
+        assert.ok(match);
+        assert.equal(match[1], "sunil");
+    });
+    it("matches usermod change user", () => {
+        const line = "Feb 22 16:30:00 myhost usermod[1234]: change user 'sunil' shell";
+        const match = line.match(/usermod\[\d+\]:\s+change\s+user\s+'(\S+)'/);
+        assert.ok(match);
+        assert.equal(match[1], "sunil");
+    });
+    it("matches groupadd new group (strips trailing comma)", () => {
+        const line = "Feb 22 16:30:00 myhost groupadd[1234]: new group: name=newgroup, GID=1002";
+        const match = line.match(/groupadd\[\d+\]:\s+new\s+group:\s+name=([^,\s]+)/);
+        assert.ok(match);
+        assert.equal(match[1], "newgroup");
+    });
+});
+describe("Linux remote desktop log patterns", () => {
+    it("matches xrdp client connection", () => {
+        const line = "Feb 22 16:30:00 myhost xrdp[1234]: connected client: 203.0.113.42";
+        const match = line.match(/xrdp\[\d+\]:\s+.*?(?:connected|connection).*?(\d+\.\d+\.\d+\.\d+)/i);
+        assert.ok(match);
+        assert.equal(match[1], "203.0.113.42");
+    });
+    it("matches xrdp session started", () => {
+        const line = "Feb 22 16:30:00 myhost xrdp-sesman[1234]: session started for user sunil";
+        const match = line.match(/xrdp-sesman\[\d+\]:\s+.*?session\s+started.*?user\s+(\S+)/i);
+        assert.ok(match);
+        assert.equal(match[1], "sunil");
+    });
+    it("matches VNC connection", () => {
+        const line = "Feb 22 16:30:00 myhost x11vnc[1234]: Got connection from client 203.0.113.42";
+        const match = line.match(/(?:x11vnc|vnc|Xvnc)\[\d+\]:\s+.*?(?:connection|connect).*?(\d+\.\d+\.\d+\.\d+)/i);
+        assert.ok(match);
+        assert.equal(match[1], "203.0.113.42");
+    });
+});

package/dist/__tests__/query-safety.test.d.ts

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

package/dist/__tests__/query-safety.test.js

@@ -0,0 +1,86 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+/**
+ * Test the query safety checks that protect sentinel_query from
+ * osqueryi meta-command injection and dangerous table access.
+ */
+const BLOCKED_TABLES = ["carves", "curl", "curl_certificate"];
+const BLOCKED_PATTERNS = [
+    /^\s*\./, // Any dot-command
+    /;\s*\./, // Dot-command after semicolon
+    /ATTACH\s/i, // ATTACH database
+    /LOAD\s/i, // Load extension
+];
+function isBlocked(sql) {
+    const patternMatch = BLOCKED_PATTERNS.find((p) => p.test(sql));
+    if (patternMatch)
+        return "meta-command";
+    const sqlLower = sql.toLowerCase();
+    const tableMatch = BLOCKED_TABLES.find((t) => sqlLower.includes(t));
+    if (tableMatch)
+        return tableMatch;
+    return null;
+}
+describe("sentinel_query safety checks", () => {
+    describe("blocks osqueryi meta-commands", () => {
+        it("blocks .shell command", () => {
+            assert.ok(isBlocked(".shell ls -la /"));
+        });
+        it("blocks .shell with leading whitespace", () => {
+            assert.ok(isBlocked("  .shell cat /etc/passwd"));
+        });
+        it("blocks .output (file exfiltration)", () => {
+            assert.ok(isBlocked(".output /tmp/exfil.txt"));
+        });
+        it("blocks .read (file read)", () => {
+            assert.ok(isBlocked(".read /etc/shadow"));
+        });
+        it("blocks .mode", () => {
+            assert.ok(isBlocked(".mode csv"));
+        });
+        it("blocks .headers", () => {
+            assert.ok(isBlocked(".headers on"));
+        });
+        it("blocks dot-command after semicolon", () => {
+            assert.ok(isBlocked("SELECT 1; .shell whoami"));
+        });
+        it("blocks ATTACH database", () => {
+            assert.ok(isBlocked("ATTACH '/tmp/evil.db' AS evil"));
+        });
+        it("blocks LOAD extension", () => {
+            assert.ok(isBlocked("LOAD /tmp/evil.so"));
+        });
+    });
+    describe("blocks dangerous tables", () => {
+        it("blocks carves table", () => {
+            assert.equal(isBlocked("SELECT * FROM carves"), "carves");
+        });
+        it("blocks curl table", () => {
+            assert.equal(isBlocked("SELECT * FROM curl WHERE url='http://evil.com'"), "curl");
+        });
+        it("blocks curl_certificate table", () => {
+            // "curl" substring matches first — both are blocked, exact match doesn't matter
+            assert.ok(isBlocked("SELECT * FROM curl_certificate"));
+        });
+        it("blocks case-insensitive table names", () => {
+            assert.equal(isBlocked("SELECT * FROM CURL"), "curl");
+        });
+    });
+    describe("allows legitimate queries", () => {
+        it("allows process listing", () => {
+            assert.equal(isBlocked("SELECT * FROM processes"), null);
+        });
+        it("allows listening ports", () => {
+            assert.equal(isBlocked("SELECT * FROM listening_ports WHERE port > 0"), null);
+        });
+        it("allows shell_history (contains 'shell' but not a meta-command)", () => {
+            assert.equal(isBlocked("SELECT * FROM shell_history"), null);
+        });
+        it("allows logged_in_users", () => {
+            assert.equal(isBlocked("SELECT * FROM logged_in_users"), null);
+        });
+        it("allows complex JOINs", () => {
+            assert.equal(isBlocked("SELECT p.name, lp.port FROM listening_ports lp JOIN processes p ON lp.pid = p.pid"), null);
+        });
+    });
+});

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

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

package/dist/__tests__/suppressions.test.js

@@ -0,0 +1,196 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { SuppressionStore } from "../suppressions.js";
+function makeEvent(overrides = {}) {
+    return {
+        id: "test-1",
+        timestamp: Date.now(),
+        severity: "high",
+        category: "ssh_login",
+        title: "SSH login from unknown host",
+        description: 'User "root" logged in from unknown host: 203.0.113.42',
+        details: { user: "root", host: "203.0.113.42", type: "publickey" },
+        hostname: "test-host",
+        ...overrides,
+    };
+}
+describe("SuppressionStore", () => {
+    let tmpDir;
+    let store;
+    beforeEach(() => {
+        tmpDir = mkdtempSync(join(tmpdir(), "sentinel-test-"));
+        store = new SuppressionStore(tmpDir);
+    });
+    afterEach(() => {
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it("starts with no rules", async () => {
+        const rules = await store.list();
+        assert.equal(rules.length, 0);
+    });
+    it("adds and lists rules", async () => {
+        await store.add({
+            scope: "title",
+            title: "SSH login detected",
+            reason: "Known Tailscale logins",
+            expiresAt: null,
+        });
+        const rules = await store.list();
+        assert.equal(rules.length, 1);
+        assert.equal(rules[0].scope, "title");
+        assert.equal(rules[0].title, "SSH login detected");
+        assert.equal(rules[0].reason, "Known Tailscale logins");
+        assert.equal(rules[0].suppressCount, 0);
+    });
+    it("suppresses by title", async () => {
+        await store.add({
+            scope: "title",
+            title: "SSH login from unknown host",
+            reason: "Expected",
+            expiresAt: null,
+        });
+        const evt = makeEvent();
+        const match = store.isSuppressed(evt);
+        assert.ok(match);
+        assert.equal(match.reason, "Expected");
+        assert.equal(match.suppressCount, 1);
+    });
+    it("does not suppress non-matching title", async () => {
+        await store.add({
+            scope: "title",
+            title: "sudo command executed",
+            reason: "Normal",
+            expiresAt: null,
+        });
+        const evt = makeEvent({ title: "SSH login from unknown host" });
+        assert.equal(store.isSuppressed(evt), null);
+    });
+    it("suppresses by category", async () => {
+        await store.add({
+            scope: "category",
+            category: "ssh_login",
+            reason: "All SSH is fine",
+            expiresAt: null,
+        });
+        const evt = makeEvent();
+        const match = store.isSuppressed(evt);
+        assert.ok(match);
+    });
+    it("suppresses by field match", async () => {
+        await store.add({
+            scope: "field",
+            field: "user",
+            fieldValue: "sunil",
+            reason: "Sunil's own sudo",
+            expiresAt: null,
+        });
+        const evt = makeEvent({
+            title: "sudo command executed",
+            category: "privilege",
+            details: { user: "sunil", command: "/usr/bin/ls" },
+        });
+        assert.ok(store.isSuppressed(evt));
+        // Different user should not be suppressed
+        const evt2 = makeEvent({
+            title: "sudo command executed",
+            category: "privilege",
+            details: { user: "attacker", command: "/bin/bash" },
+        });
+        assert.equal(store.isSuppressed(evt2), null);
+    });
+    it("suppresses by exact match", async () => {
+        await store.add({
+            scope: "exact",
+            title: "SSH login from unknown host",
+            description: 'User "root" logged in from unknown host: 203.0.113.42',
+            reason: "Known scanner",
+            expiresAt: null,
+        });
+        const evt = makeEvent();
+        assert.ok(store.isSuppressed(evt));
+        // Same title, different description should not match
+        const evt2 = makeEvent({ description: "Different host" });
+        assert.equal(store.isSuppressed(evt2), null);
+    });
+    it("respects expiry", async () => {
+        await store.add({
+            scope: "title",
+            title: "SSH login from unknown host",
+            reason: "Temporary",
+            expiresAt: Date.now() - 1000, // Already expired
+        });
+        const evt = makeEvent();
+        assert.equal(store.isSuppressed(evt), null);
+    });
+    it("removes rules", async () => {
+        const rule = await store.add({
+            scope: "title",
+            title: "test",
+            reason: "test",
+            expiresAt: null,
+        });
+        assert.equal((await store.list()).length, 1);
+        const removed = await store.remove(rule.id);
+        assert.equal(removed, true);
+        assert.equal((await store.list()).length, 0);
+    });
+    it("removes returns false for unknown id", async () => {
+        const removed = await store.remove("nonexistent");
+        assert.equal(removed, false);
+    });
+    it("cleans up expired rules", async () => {
+        await store.add({
+            scope: "title",
+            title: "old",
+            reason: "expired",
+            expiresAt: Date.now() - 1000,
+        });
+        await store.add({
+            scope: "title",
+            title: "current",
+            reason: "active",
+            expiresAt: null,
+        });
+        const cleaned = await store.cleanup();
+        assert.equal(cleaned, 1);
+        const remaining = await store.list();
+        assert.equal(remaining.length, 1);
+        assert.equal(remaining[0].title, "current");
+    });
+    it("persists across instances", async () => {
+        await store.add({
+            scope: "title",
+            title: "persisted",
+            reason: "test persistence",
+            expiresAt: null,
+        });
+        // New store instance pointing at same dir
+        const store2 = new SuppressionStore(tmpDir);
+        const rules = await store2.list();
+        assert.equal(rules.length, 1);
+        assert.equal(rules[0].title, "persisted");
+    });
+    it("describes rules in plain English", () => {
+        assert.equal(SuppressionStore.describe({ scope: "title", title: "sudo command executed" }), 'All alerts titled "sudo command executed"');
+        assert.equal(SuppressionStore.describe({ scope: "category", category: "ssh_login" }), 'All alerts in category "ssh_login"');
+        assert.equal(SuppressionStore.describe({ scope: "field", field: "user", fieldValue: "sunil" }), 'Alerts where user = "sunil"');
+        assert.equal(SuppressionStore.describe({ scope: "exact", title: "test" }), 'Exact match: "test" with specific description');
+    });
+    it("increments suppress count on repeated matches", async () => {
+        await store.add({
+            scope: "title",
+            title: "SSH login from unknown host",
+            reason: "Expected",
+            expiresAt: null,
+        });
+        const evt = makeEvent();
+        store.isSuppressed(evt);
+        store.isSuppressed(evt);
+        store.isSuppressed(evt);
+        const rules = await store.list();
+        assert.equal(rules[0].suppressCount, 3);
+    });
+});

package/dist/alerts.js

@@ -3,7 +3,7 @@
  */
 import { SEVERITY_ORDER } from "./config.js";
 const MAX_ALERTS_PER_MINUTE = 10;
-const ALERT_DEDUP_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
+const ALERT_DEDUP_WINDOW_MS = 60 * 1000; // 1 minute
 export function createAlertState() {
     return { recentAlerts: [] };
 }
@@ -11,17 +11,22 @@ export function createAlertState() {
  * Check if an alert should be sent (rate limit + dedup).
  */
 export function shouldAlert(evt, alertState, now = Date.now()) {
-    // Clean entries older than the dedup window (5 min)
+    // Clean entries older than the dedup window (1 min)
     alertState.recentAlerts = alertState.recentAlerts.filter((a) => now - a.time < ALERT_DEDUP_WINDOW_MS);
     // Rate limit: max alerts per minute (count only last 60s)
     const recentCount = alertState.recentAlerts.filter((a) => now - a.time < 60_000).length;
     if (recentCount >= MAX_ALERTS_PER_MINUTE) {
         return false;
     }
-    // Dedup: same title within window
-    const isDupe = alertState.recentAlerts.some((a) => a.title === evt.title && now - a.time < ALERT_DEDUP_WINDOW_MS);
-    if (isDupe)
-        return false;
+    // Skip dedup for failed auth — every attempt matters
+    const skipDedup = evt.category === "ssh_login" &&
+        (evt.title.includes("failed") || evt.title.includes("Failed") || evt.title.includes("invalid") || evt.title.includes("Invalid"));
+    if (!skipDedup) {
+        // Dedup: same title within window
+        const isDupe = alertState.recentAlerts.some((a) => a.title === evt.title && now - a.time < ALERT_DEDUP_WINDOW_MS);
+        if (isDupe)
+            return false;
+    }
     alertState.recentAlerts.push({ time: now, title: evt.title });
     return true;
 }

package/dist/analyzer.js

@@ -78,13 +78,16 @@ export function analyzeLoginEvents(rows, knownHosts) {
         // Skip local logins
         if (!host || host === "localhost" || host === "::1" || host === "127.0.0.1")
             continue;
-        // Skip Tailscale CGNAT range (100.64.0.0/10)
+        // Check if Tailscale CGNAT range (100.64.0.0/10)
         const octets = host.split(".").map(Number);
-        if (octets[0] === 100 && octets[1] >= 64 && octets[1] <= 127)
-            continue;
-        // New remote login from unknown host
-        if (!knownHosts.has(host)) {
-            events.push(event("high", "auth", "SSH login from unknown host", `User "${user}" logged in from unknown host: ${host}\nLogin type: ${type}`, { user, host, type }));
+        const isTailscale = octets[0] === 100 && octets[1] >= 64 && octets[1] <= 127;
+        if (isTailscale || knownHosts.has(host)) {
+            // Known host / Tailscale login — info-level awareness
+            events.push(event("info", "ssh_login", "SSH login detected", `User "${user}" logged in from ${isTailscale ? "Tailscale" : "known"} host: ${host}\nLogin type: ${type}`, { user, host, type, tailscale: isTailscale }));
+        }
+        else {
+            // Unknown host — high severity
+            events.push(event("high", "ssh_login", "SSH login from unknown host", `User "${user}" logged in from unknown host: ${host}\nLogin type: ${type}`, { user, host, type }));
         }
     }
     return events;