@bolt-cli/cli 0.0.0-stage → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/watch.js ADDED
@@ -0,0 +1,698 @@
1
+ "use strict";
2
+ // Bolt Sentinel watch core: background defensive checks for servers.
3
+ //
4
+ // Design (see docs/bolt/watch): the daemon runs ON the operator's own
5
+ // machine, deterministically and read-only. Every signal below only READS:
6
+ // log tails, listener tables, file hashes, load counters. Nothing here
7
+ // changes the system - responses live in explicit playbooks (default OFF)
8
+ // that only run when the operator pre-authorized them in policy.json.
9
+ //
10
+ // Zero deps, stdlib only. All OS access funnels through injectable readers
11
+ // (`io`) so the whole module is unit-testable without touching a real host.
12
+ // Every finding carries a stable fingerprint so the server can dedupe and
13
+ // the operator can tell a new incident from a repeated observation.
14
+ const crypto = require("crypto");
15
+ const fs = require("fs");
16
+ const os = require("os");
17
+ const path = require("path");
18
+ const { execFileSync } = require("node:child_process");
19
+
20
+ function watchDir(home) {
21
+ return path.join(home || os.homedir(), ".bolt", "watch");
22
+ }
23
+
24
+ function paths(home) {
25
+ const dir = watchDir(home);
26
+ return {
27
+ dir,
28
+ policy: path.join(dir, "policy.json"),
29
+ baseline: path.join(dir, "baseline.json"),
30
+ events: path.join(dir, "events.jsonl"),
31
+ log: path.join(dir, "watch.log"),
32
+ pid: path.join(dir, "watch.pid"),
33
+ };
34
+ }
35
+
36
+ function ensureDir(home) {
37
+ fs.mkdirSync(watchDir(home), { recursive: true, mode: 0o700 });
38
+ }
39
+
40
+ // ---------------------------------------------------------------- policy
41
+
42
+ const POLICY_VERSION = 1;
43
+
44
+ // Conservative defaults: everything that could change the system is OFF,
45
+ // phone-home and AI triage are ON (they only move summaries, and triage is
46
+ // capped per day). Thresholds err toward quiet: a background watcher that
47
+ // cries wolf gets disabled, and a disabled watcher protects no one.
48
+ function defaultPolicy() {
49
+ return {
50
+ version: POLICY_VERSION,
51
+ enabled: true,
52
+ intervalSec: 300,
53
+ signals: { auth: true, ports: true, files: true, resources: true },
54
+ thresholds: { authFails: 10, authWindowMin: 10, loadMult: 3.0, diskPct: 90, memPct: 92 },
55
+ authLogPaths: ["/var/log/auth.log", "/var/log/secure", "/var/log/auth.log.1"],
56
+ authTailBytes: 256 * 1024,
57
+ watchPaths: [
58
+ "/etc/passwd",
59
+ "/etc/group",
60
+ "/etc/sudoers",
61
+ "/etc/ssh/sshd_config",
62
+ "/etc/crontab",
63
+ "/etc/cron.d",
64
+ "/root/.ssh/authorized_keys",
65
+ ],
66
+ phoneHome: true,
67
+ triage: { enabled: true, maxPerDay: 3, severities: ["high", "critical"] },
68
+ playbooks: { blockIp: "off", killPid: "off", restartService: "off" },
69
+ };
70
+ }
71
+
72
+ function loadPolicy(home) {
73
+ const merged = defaultPolicy();
74
+ try {
75
+ const raw = JSON.parse(fs.readFileSync(paths(home).policy, "utf8"));
76
+ if (raw && typeof raw === "object") {
77
+ for (const key of ["enabled", "intervalSec", "authTailBytes", "phoneHome"]) {
78
+ if (raw[key] !== undefined) merged[key] = raw[key];
79
+ }
80
+ for (const group of ["signals", "thresholds", "triage"]) {
81
+ if (raw[group] && typeof raw[group] === "object") Object.assign(merged[group], raw[group]);
82
+ }
83
+ for (const list of ["authLogPaths", "watchPaths"]) {
84
+ if (Array.isArray(raw[list])) merged[list] = raw[list].filter((p) => typeof p === "string").slice(0, 64);
85
+ }
86
+ if (raw.playbooks && typeof raw.playbooks === "object") {
87
+ for (const name of Object.keys(merged.playbooks)) {
88
+ if (raw.playbooks[name] === "allow" || raw.playbooks[name] === "off") merged.playbooks[name] = raw.playbooks[name];
89
+ }
90
+ }
91
+ }
92
+ } catch {
93
+ // Missing or corrupt policy boots safe: defaults, nothing authorized.
94
+ }
95
+ merged.intervalSec = Math.min(3600, Math.max(60, Number(merged.intervalSec) || 300));
96
+ return merged;
97
+ }
98
+
99
+ function savePolicy(home, policy) {
100
+ ensureDir(home);
101
+ fs.writeFileSync(paths(home).policy, JSON.stringify({ ...policy, version: POLICY_VERSION }, null, 2), { mode: 0o600 });
102
+ return policy;
103
+ }
104
+
105
+ // ---------------------------------------------------------------- baseline
106
+
107
+ function loadBaseline(home) {
108
+ try {
109
+ const raw = JSON.parse(fs.readFileSync(paths(home).baseline, "utf8"));
110
+ if (raw && typeof raw === "object") return raw;
111
+ } catch {
112
+ // No baseline yet: first check establishes it (see runChecks).
113
+ }
114
+ return {};
115
+ }
116
+
117
+ function saveBaseline(home, baseline) {
118
+ ensureDir(home);
119
+ fs.writeFileSync(paths(home).baseline, JSON.stringify({ ...baseline, updatedAt: new Date().toISOString() }, null, 2), { mode: 0o600 });
120
+ }
121
+
122
+ // ---------------------------------------------------------------- io
123
+
124
+ // Default OS readers. Each is a tiny function so tests inject fakes:
125
+ // { readFile(p, maxBytes), listPorts(), hashFile(p), load(), mem(), disk() }.
126
+ function defaultIo() {
127
+ return {
128
+ readFile: (p, maxBytes) => readTail(p, maxBytes),
129
+ listPorts,
130
+ hashFile: (p) => hashFile(p),
131
+ load: () => os.loadavg()[0],
132
+ cpus: () => Math.max(1, os.cpus().length),
133
+ mem: () => {
134
+ const total = os.totalmem();
135
+ const free = os.freemem();
136
+ return { pct: total ? Math.round(((total - free) / total) * 100) : 0 };
137
+ },
138
+ disk: () => diskUsage("/"),
139
+ };
140
+ }
141
+
142
+ function readTail(p, maxBytes) {
143
+ try {
144
+ const st = fs.statSync(p);
145
+ if (!st.isFile()) return null;
146
+ const size = st.size;
147
+ const start = Math.max(0, size - (maxBytes || 262144));
148
+ const fd = fs.openSync(p, "r");
149
+ try {
150
+ const buf = Buffer.alloc(size - start);
151
+ fs.readSync(fd, buf, 0, buf.length, start);
152
+ return buf.toString("utf8");
153
+ } finally {
154
+ fs.closeSync(fd);
155
+ }
156
+ } catch {
157
+ return null;
158
+ }
159
+ }
160
+
161
+ function hashFile(p) {
162
+ try {
163
+ const st = fs.statSync(p);
164
+ if (st.isDirectory()) return { kind: "dir", hash: null };
165
+ const h = crypto.createHash("sha256");
166
+ h.update(fs.readFileSync(p));
167
+ return { kind: "file", hash: h.digest("hex"), size: st.size };
168
+ } catch (error) {
169
+ return { kind: "unreadable", hash: null, error: error && error.code ? String(error.code) : "error" };
170
+ }
171
+ }
172
+
173
+ // Listening TCP ports without shelling out where possible: /proc/net/tcp*
174
+ // on Linux, `ss`/`netstat` fallback, nothing on other platforms (the signal
175
+ // reports unavailable instead of guessing).
176
+ function listPorts(execFn) {
177
+ const run = execFn || ((cmd, args) => execFileSync(cmd, args, { encoding: "utf8", timeout: 8000, windowsHide: true }));
178
+ if (process.platform === "linux") {
179
+ try {
180
+ const ports = new Set();
181
+ for (const file of ["/proc/net/tcp", "/proc/net/tcp6"]) {
182
+ let text = "";
183
+ try {
184
+ text = fs.readFileSync(file, "utf8");
185
+ } catch {
186
+ continue;
187
+ }
188
+ for (const line of text.split("\n").slice(1)) {
189
+ const cols = line.trim().split(/\s+/);
190
+ if (cols.length < 4 || cols[3] !== "0A") continue;
191
+ const local = cols[1] || "";
192
+ const portHex = local.split(":")[1] || "";
193
+ const port = parseInt(portHex, 16);
194
+ if (port > 0 && port < 65536) ports.add(port);
195
+ }
196
+ }
197
+ if (ports.size) return { ok: true, ports: [...ports].sort((a, b) => a - b) };
198
+ } catch {
199
+ // fall through to ss/netstat
200
+ }
201
+ }
202
+ for (const [cmd, args] of [["ss", ["-ltn"]], ["netstat", ["-ltn"]]]) {
203
+ try {
204
+ const out = run(cmd, args);
205
+ const ports = new Set();
206
+ const re = /[.:](\d{1,5})\s/g;
207
+ let m;
208
+ while ((m = re.exec(out)) !== null) {
209
+ const port = Number(m[1]);
210
+ if (port > 0 && port < 65536) ports.add(port);
211
+ }
212
+ return { ok: true, ports: [...ports].sort((a, b) => a - b), via: cmd };
213
+ } catch {
214
+ // try the next tool
215
+ }
216
+ }
217
+ return { ok: false, ports: [], reason: "no listener source (no /proc/net/tcp, ss, or netstat)" };
218
+ }
219
+
220
+ function diskUsage(mount) {
221
+ try {
222
+ const out = execFileSync("df", ["-P", mount || "/"], { encoding: "utf8", timeout: 8000, windowsHide: true });
223
+ const line = out.split("\n").find((l) => l.includes("%")) || "";
224
+ const m = line.match(/(\d+)%/);
225
+ return { ok: true, pct: m ? Number(m[1]) : 0 };
226
+ } catch {
227
+ return { ok: false, pct: 0, reason: "df unavailable" };
228
+ }
229
+ }
230
+
231
+ // ---------------------------------------------------------------- signals
232
+
233
+ const AUTH_FAIL_RES = [/Failed password/i, /authentication failure/i, /Failed login/i, /Invalid user .* from/i];
234
+
235
+ const SYSLOG_MONTHS = { Jan: 0, Feb: 1, Mar: 2, Apr: 3, May: 4, Jun: 5, Jul: 6, Aug: 7, Sep: 8, Oct: 9, Nov: 10, Dec: 11 };
236
+
237
+ // Syslog timestamps carry no year ("Oct 12 10:00:00"): assume the current
238
+ // year, rolling back one when that lands in the future (Dec/Jan boundary).
239
+ // Unparseable lines return null — callers count them as timeless rather than
240
+ // dropping evidence they cannot place. Pure, tested via checkAuth.
241
+ function syslogTime(line, now = Date.now()) {
242
+ const m = String(line || "").match(/^([A-Z][a-z]{2})\s+(\d{1,2})\s+(\d{2}):(\d{2}):(\d{2})/);
243
+ if (!m || SYSLOG_MONTHS[m[1]] === undefined) return null;
244
+ const year = new Date(now).getFullYear();
245
+ const t = Date.parse(`${m[1]} ${m[2]} ${year} ${m[3]}:${m[4]}:${m[5]}`);
246
+ if (Number.isNaN(t)) return null;
247
+ // More than a day in the future means last December's log on a January box.
248
+ if (t - now > 86400000) return t - 31536000000;
249
+ return t;
250
+ }
251
+
252
+ function checkAuth(policy, io, now = Date.now()) {
253
+ const windowMs = Math.max(1, Number(policy.thresholds.authWindowMin) || 10) * 60 * 1000;
254
+ const limit = Math.max(1, Number(policy.thresholds.authFails) || 10);
255
+ let text = null;
256
+ let source = "";
257
+ for (const p of policy.authLogPaths) {
258
+ const t = io.readFile(p, policy.authTailBytes);
259
+ if (t !== null) {
260
+ text = t;
261
+ source = p;
262
+ break;
263
+ }
264
+ }
265
+ if (text === null) {
266
+ return { signal: "auth", ok: true, available: false, summary: "no readable auth log (checked " + policy.authLogPaths.length + " paths)", findings: [] };
267
+ }
268
+ const fails = [];
269
+ let timeless = 0;
270
+ for (const line of text.split("\n")) {
271
+ if (!AUTH_FAIL_RES.some((re) => re.test(line))) continue;
272
+ const ts = syslogTime(line, now);
273
+ // Old lines are history, not an incident: only the live window counts.
274
+ // Lines without a parseable clock still count (timeless) — dropping
275
+ // evidence we cannot place would hide bursts in exotic formats.
276
+ if (ts !== null && now - ts > windowMs) continue;
277
+ if (ts === null) timeless += 1;
278
+ const ip = (line.match(/from\s+(\d{1,3}(?:\.\d{1,3}){3})/) || [])[1] || "unknown";
279
+ const user = (line.match(/for\s+(?:invalid user\s+)?([A-Za-z0-9_.-]+)\s+from/i) || [])[1] || "unknown";
280
+ fails.push({ ip, user, line: line.slice(-220) });
281
+ }
282
+ const windowLabel = `~${policy.thresholds.authWindowMin}min window${timeless ? ` (${timeless} timeless)` : ""}`;
283
+ const summary = `${fails.length} failed logins in ${windowLabel} (tail of ${source})`;
284
+ if (fails.length < limit) {
285
+ return { signal: "auth", ok: true, available: true, summary, findings: [] };
286
+ }
287
+ const byIp = new Map();
288
+ for (const f of fails) byIp.set(f.ip, (byIp.get(f.ip) || 0) + 1);
289
+ const top = [...byIp.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([ip, n]) => `${ip} (${n})`).join(", ");
290
+ const day = new Date(now).toISOString().slice(0, 10);
291
+ return {
292
+ signal: "auth",
293
+ ok: false,
294
+ available: true,
295
+ summary,
296
+ findings: [{
297
+ severity: "high",
298
+ title: `Auth burst: ${fails.length} failed logins in ~${policy.thresholds.authWindowMin}min window`,
299
+ detail: `Top sources: ${top}. Source: ${source}. A burst followed by a success from the same address is the classic guessed-password shape — check for an Accepted line nearby.`,
300
+ fingerprint: `auth-burst:${day}`,
301
+ }],
302
+ };
303
+ }
304
+
305
+ function checkPorts(policy, io, baseline) {
306
+ const res = io.listPorts();
307
+ if (!res.ok) {
308
+ return { signal: "ports", ok: true, available: false, summary: res.reason || "listener check unavailable", findings: [] };
309
+ }
310
+ const current = res.ports;
311
+ const known = Array.isArray(baseline.ports) ? baseline.ports : null;
312
+ if (!known) {
313
+ return { signal: "ports", ok: true, available: true, summary: `baseline established: ${current.length} listening ports`, findings: [], baseline: { ports: current } };
314
+ }
315
+ const knownSet = new Set(known);
316
+ const currentSet = new Set(current);
317
+ const added = current.filter((p) => !knownSet.has(p));
318
+ const removed = known.filter((p) => !currentSet.has(p));
319
+ const findings = [];
320
+ for (const port of added) {
321
+ findings.push({
322
+ severity: "high",
323
+ title: `New listening port: ${port}/tcp`,
324
+ detail: `Port ${port}/tcp was not listening at baseline. Verify against change records; an unexpected listener is a persistence or exposure signal.`,
325
+ fingerprint: `port-new:${port}`,
326
+ });
327
+ }
328
+ for (const port of removed) {
329
+ findings.push({
330
+ severity: "info",
331
+ title: `Listener gone: ${port}/tcp`,
332
+ detail: `Port ${port}/tcp listened at baseline and does not now. Expected after deploys; unexpected otherwise.`,
333
+ fingerprint: `port-gone:${port}`,
334
+ });
335
+ }
336
+ return {
337
+ signal: "ports",
338
+ ok: findings.every((f) => f.severity === "info"),
339
+ available: true,
340
+ summary: `${current.length} listening ports (${added.length} new, ${removed.length} gone)`,
341
+ findings,
342
+ baseline: { ports: current },
343
+ };
344
+ }
345
+
346
+ function checkFiles(policy, io, baseline) {
347
+ const known = baseline.files && typeof baseline.files === "object" ? baseline.files : null;
348
+ const current = {};
349
+ const findings = [];
350
+ let unreadable = 0;
351
+ for (const p of policy.watchPaths) {
352
+ const meta = io.hashFile(p);
353
+ current[p] = meta.hash ? { hash: meta.hash, size: meta.size } : { hash: null, state: meta.kind };
354
+ if (!meta.hash) unreadable += 1;
355
+ }
356
+ if (!known) {
357
+ return { signal: "files", ok: true, available: true, summary: `baseline established: ${policy.watchPaths.length} paths (${unreadable} unreadable)`, findings: [], baseline: { files: current } };
358
+ }
359
+ for (const p of policy.watchPaths) {
360
+ const before = known[p];
361
+ const after = current[p];
362
+ if (!before) continue;
363
+ if (before.hash && after.hash && before.hash !== after.hash) {
364
+ findings.push({
365
+ severity: "high",
366
+ title: `Watched file changed: ${p}`,
367
+ detail: `SHA-256 differs from baseline. Verify against change records before anything else — unexpected writes to identity, sudo, ssh, or cron configuration are compromise-shaped.`,
368
+ fingerprint: `file-changed:${p}`,
369
+ });
370
+ } else if (before.hash && !after.hash) {
371
+ findings.push({
372
+ severity: "high",
373
+ title: `Watched file unreadable or removed: ${p}`,
374
+ detail: `Readable at baseline, not now. Removal and permission changes both deserve a look.`,
375
+ fingerprint: `file-gone:${p}`,
376
+ });
377
+ }
378
+ }
379
+ const highs = findings.filter((f) => f.severity !== "info").length;
380
+ return {
381
+ signal: "files",
382
+ ok: highs === 0,
383
+ available: true,
384
+ summary: `${policy.watchPaths.length} paths checked (${findings.length} changed, ${unreadable} unreadable)`,
385
+ findings,
386
+ baseline: { files: current },
387
+ };
388
+ }
389
+
390
+ function checkResources(policy, io) {
391
+ const notes = [];
392
+ const findings = [];
393
+ try {
394
+ const load = io.load();
395
+ const cpus = io.cpus();
396
+ const mult = Number(policy.thresholds.loadMult) || 3.0;
397
+ notes.push(`load ${load.toFixed(2)} on ${cpus} cpus`);
398
+ if (load > cpus * mult) {
399
+ findings.push({
400
+ severity: "info",
401
+ title: `Load spike: ${load.toFixed(2)} on ${cpus} cpus (>${mult}x)`,
402
+ detail: `Sustained load far above core count. Legitimate batch work does this too — correlate with cron and deploys before escalating. Re-checks while elevated do not re-alert (fingerprint is hourly).`,
403
+ fingerprint: `load:${new Date().toISOString().slice(0, 13)}`,
404
+ });
405
+ }
406
+ } catch {
407
+ notes.push("load unavailable");
408
+ }
409
+ try {
410
+ const mem = io.mem();
411
+ notes.push(`mem ${mem.pct}%`);
412
+ if (mem.pct >= (Number(policy.thresholds.memPct) || 92)) {
413
+ findings.push({
414
+ severity: "info",
415
+ title: `Memory pressure: ${mem.pct}% used`,
416
+ detail: `Above the ${policy.thresholds.memPct}% threshold. OOM kills and swap storms follow; find the consumer.`,
417
+ fingerprint: `mem:${new Date().toISOString().slice(0, 13)}`,
418
+ });
419
+ }
420
+ } catch {
421
+ notes.push("mem unavailable");
422
+ }
423
+ try {
424
+ const disk = io.disk();
425
+ if (disk.ok) {
426
+ notes.push(`disk ${disk.pct}%`);
427
+ if (disk.pct >= (Number(policy.thresholds.diskPct) || 90)) {
428
+ findings.push({
429
+ severity: "high",
430
+ title: `Disk nearly full: ${disk.pct}% on /`,
431
+ detail: `Above the ${policy.thresholds.diskPct}% threshold. Full disks break logging first — which is exactly when you need logs.`,
432
+ fingerprint: `disk:${new Date().toISOString().slice(0, 10)}`,
433
+ });
434
+ }
435
+ } else {
436
+ notes.push("disk unavailable");
437
+ }
438
+ } catch {
439
+ notes.push("disk unavailable");
440
+ }
441
+ return {
442
+ signal: "resources",
443
+ ok: findings.every((f) => f.severity === "info"),
444
+ available: true,
445
+ summary: notes.join(", ") || "no resource counters",
446
+ findings,
447
+ };
448
+ }
449
+
450
+ // ---------------------------------------------------------------- runner
451
+
452
+ // One full pass over the enabled signals. Pure-ish: all host access via io,
453
+ // clock via now. Returns { results, incidents, baselinePatch }. Baseline
454
+ // patches merge on save — a signal that errored never clobbers a good one.
455
+ function runChecks(policy, baseline, io, now = Date.now()) {
456
+ const results = [];
457
+ const incidents = [];
458
+ const patch = {};
459
+ const run = (enabled, fn) => {
460
+ if (!enabled) return;
461
+ try {
462
+ const r = fn();
463
+ results.push(r);
464
+ for (const f of r.findings || []) incidents.push({ ...f, signal: r.signal, at: new Date(now).toISOString() });
465
+ if (r.baseline) Object.assign(patch, r.baseline);
466
+ } catch (error) {
467
+ results.push({ signal: "unknown", ok: true, available: false, summary: `check failed safely: ${error && error.message ? error.message : error}`, findings: [] });
468
+ }
469
+ };
470
+ run(policy.signals.auth, () => checkAuth(policy, io, now));
471
+ run(policy.signals.ports, () => checkPorts(policy, io, baseline));
472
+ run(policy.signals.files, () => checkFiles(policy, io, baseline));
473
+ run(policy.signals.resources, () => checkResources(policy, io));
474
+ return { results, incidents, baselinePatch: patch };
475
+ }
476
+
477
+ // ---------------------------------------------------------------- events
478
+
479
+ function appendEvent(home, event) {
480
+ try {
481
+ ensureDir(home);
482
+ const line = JSON.stringify({ at: new Date().toISOString(), ...event });
483
+ fs.appendFileSync(paths(home).events, `${line}\n`, { mode: 0o600 });
484
+ try {
485
+ const lines = fs.readFileSync(paths(home).events, "utf8").split("\n").filter(Boolean);
486
+ if (lines.length > 500) fs.writeFileSync(paths(home).events, `${lines.slice(-500).join("\n")}\n`, { mode: 0o600 });
487
+ } catch {
488
+ // Trim failure never blocks the record itself.
489
+ }
490
+ } catch {
491
+ // Event logging is a safety net, not a crash path.
492
+ }
493
+ }
494
+
495
+ function readEvents(home, limit = 20) {
496
+ try {
497
+ const lines = fs.readFileSync(paths(home).events, "utf8").split("\n").filter(Boolean);
498
+ return lines.slice(-Math.max(1, limit)).map((l) => JSON.parse(l));
499
+ } catch {
500
+ return [];
501
+ }
502
+ }
503
+
504
+ // ---------------------------------------------------------------- playbooks
505
+
506
+ // Response playbooks. Default OFF, always explicit. Each entry validates its
507
+ // argument ruthlessly and describes itself for `watch playbook` help. Either
508
+ // returns { ok, summary, detail } — never throws.
509
+ const PLAYBOOKS = {
510
+ blockIp: {
511
+ desc: "deny an attacking IP at the host firewall (ufw/iptables/firewall-cmd)",
512
+ usage: "blockIp <ipv4>",
513
+ validate(arg) {
514
+ const ip = String(arg || "").trim();
515
+ if (!/^\d{1,3}(\.\d{1,3}){3}$/.test(ip)) return "expected a single IPv4 address";
516
+ const octets = ip.split(".").map(Number);
517
+ if (octets.some((n) => n > 255)) return "expected a single IPv4 address";
518
+ if (octets[0] === 127 || octets[0] === 10 || (octets[0] === 192 && octets[1] === 168) || (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31)) {
519
+ return "refusing RFC-1918/loopback target — blocking local addresses locks you out, not the attacker";
520
+ }
521
+ return null;
522
+ },
523
+ },
524
+ killPid: {
525
+ desc: "terminate one process by pid (never pid 1, never self)",
526
+ usage: "killPid <pid>",
527
+ validate(arg) {
528
+ const pid = Number(String(arg || "").trim());
529
+ if (!Number.isInteger(pid) || pid <= 1) return "expected a pid greater than 1";
530
+ if (pid === process.pid) return "refusing to kill the watcher itself";
531
+ return null;
532
+ },
533
+ },
534
+ restartService: {
535
+ desc: "systemctl restart one named service (name charset only)",
536
+ usage: "restartService <name>",
537
+ validate(arg) {
538
+ const name = String(arg || "").trim();
539
+ if (!/^[A-Za-z0-9_@-]+(\.service)?$/.test(name)) return "expected a plain service name";
540
+ return null;
541
+ },
542
+ },
543
+ };
544
+
545
+ function playbookStatus(policy) {
546
+ return Object.entries(PLAYBOOKS).map(([name, meta]) => ({
547
+ name,
548
+ mode: (policy.playbooks && policy.playbooks[name]) || "off",
549
+ desc: meta.desc,
550
+ usage: meta.usage,
551
+ }));
552
+ }
553
+
554
+ // ---------------------------------------------------------------- daemon
555
+
556
+ // Stable machine id for phone-home dedupe (random, rotatable by deleting the
557
+ // file — it identifies the box to YOUR account, nothing else).
558
+ function hostId(home) {
559
+ ensureDir(home);
560
+ const file = path.join(watchDir(home), "host-id");
561
+ try {
562
+ const existing = fs.readFileSync(file, "utf8").trim();
563
+ if (/^[A-Za-z0-9_-]{8,64}$/.test(existing)) return existing;
564
+ } catch {
565
+ // fall through to mint
566
+ }
567
+ const id = `h-${crypto.randomBytes(9).toString("base64url")}`;
568
+ try {
569
+ fs.writeFileSync(file, `${id}\n`, { mode: 0o600 });
570
+ } catch {
571
+ // A lost id only weakens dedupe, never the checks.
572
+ }
573
+ return id;
574
+ }
575
+
576
+ // Daemon log with rotation: appends one line, keeps the last ~200KB so a
577
+ // chatty box cannot fill a disk (which would itself be an incident).
578
+ function logLine(home, msg) {
579
+ try {
580
+ ensureDir(home);
581
+ const file = paths(home).log;
582
+ fs.appendFileSync(file, `${new Date().toISOString()} ${msg}\n`, { mode: 0o600 });
583
+ try {
584
+ const st = fs.statSync(file);
585
+ if (st.size > 1024 * 1024) {
586
+ const text = fs.readFileSync(file, "utf8");
587
+ fs.writeFileSync(file, text.slice(-200 * 1024), { mode: 0o600 });
588
+ }
589
+ } catch {
590
+ // Rotation failure never blocks logging.
591
+ }
592
+ } catch {
593
+ // Logging is observability, not a crash path.
594
+ }
595
+ }
596
+
597
+ function readPid(home) {
598
+ try {
599
+ const pid = Number(fs.readFileSync(paths(home).pid, "utf8").trim());
600
+ if (!Number.isInteger(pid) || pid <= 0) return null;
601
+ try {
602
+ process.kill(pid, 0);
603
+ return pid;
604
+ } catch {
605
+ return null;
606
+ }
607
+ } catch {
608
+ return null;
609
+ }
610
+ }
611
+
612
+ function writePid(home, pid) {
613
+ ensureDir(home);
614
+ fs.writeFileSync(paths(home).pid, `${pid}\n`, { mode: 0o600 });
615
+ }
616
+
617
+ function clearPid(home) {
618
+ try {
619
+ fs.unlinkSync(paths(home).pid);
620
+ } catch {
621
+ // already stopped
622
+ }
623
+ }
624
+
625
+ // Execute one pre-authorized playbook. `execFn(cmd, args)` injects the
626
+ // subprocess layer for tests; default uses execFileSync (no shell, ever —
627
+ // argument arrays cannot inject). Never throws: { ok, summary, detail }.
628
+ function runPlaybook(name, arg, execFn) {
629
+ const meta = PLAYBOOKS[name];
630
+ if (!meta) return { ok: false, summary: "unknown playbook", detail: `No playbook named "${name}".` };
631
+ const problem = meta.validate(arg);
632
+ if (problem) return { ok: false, summary: "refused", detail: problem };
633
+ const clean = String(arg).trim();
634
+ const run = execFn || ((cmd, args) => execFileSync(cmd, args, { encoding: "utf8", timeout: 30000, windowsHide: true }));
635
+ try {
636
+ if (name === "blockIp") {
637
+ const tried = [];
638
+ const attempts = [
639
+ ["ufw", ["deny", "from", clean]],
640
+ ["iptables", ["-I", "INPUT", "-s", clean, "-j", "DROP"]],
641
+ ["firewall-cmd", ["--add-rich-rule", `rule family="ipv4" source address="${clean}" drop`]],
642
+ ];
643
+ for (const [cmd, args] of attempts) {
644
+ try {
645
+ run(cmd, args);
646
+ return { ok: true, summary: `blocked ${clean} via ${cmd}`, detail: `${cmd} ${args.join(" ")}` };
647
+ } catch (error) {
648
+ tried.push(`${cmd}: ${error && error.message ? error.message.split("\n")[0] : error}`);
649
+ }
650
+ }
651
+ return { ok: false, summary: "no firewall tool worked", detail: tried.join(" | ").slice(0, 400) };
652
+ }
653
+ if (name === "killPid") {
654
+ const pid = Number(clean);
655
+ process.kill(pid, "SIGTERM");
656
+ return { ok: true, summary: `SIGTERM sent to ${pid}`, detail: `process.kill(${pid}, SIGTERM)` };
657
+ }
658
+ if (name === "restartService") {
659
+ const svc = clean.endsWith(".service") ? clean : `${clean}.service`;
660
+ run("systemctl", ["restart", svc]);
661
+ return { ok: true, summary: `restarted ${svc}`, detail: `systemctl restart ${svc}` };
662
+ }
663
+ return { ok: false, summary: "not implemented", detail: `Playbook "${name}" has no executor.` };
664
+ } catch (error) {
665
+ return { ok: false, summary: "execution failed", detail: String((error && error.message) || error).slice(0, 400) };
666
+ }
667
+ }
668
+
669
+ module.exports = {
670
+ paths,
671
+ ensureDir,
672
+ POLICY_VERSION,
673
+ defaultPolicy,
674
+ loadPolicy,
675
+ savePolicy,
676
+ loadBaseline,
677
+ saveBaseline,
678
+ defaultIo,
679
+ readTail,
680
+ hashFile,
681
+ listPorts,
682
+ diskUsage,
683
+ checkAuth,
684
+ checkPorts,
685
+ checkFiles,
686
+ checkResources,
687
+ runChecks,
688
+ appendEvent,
689
+ readEvents,
690
+ PLAYBOOKS,
691
+ playbookStatus,
692
+ hostId,
693
+ logLine,
694
+ readPid,
695
+ writePid,
696
+ clearPid,
697
+ runPlaybook,
698
+ };