@sonde/packs 0.1.1 → 0.1.3

package/src/system/probes/logs-journal.ts

@@ -0,0 +1,103 @@
+import { platform } from 'node:os';
+import type { ProbeHandler } from '../../types.js';
+
+export interface JournalEntry {
+  timestamp: string;
+  priority: number;
+  message: string;
+  pid: number;
+  uid: number;
+  unit?: string;
+}
+
+export interface JournalResult {
+  entries: JournalEntry[];
+  entryCount: number;
+  unit?: string;
+}
+
+/**
+ * Reads recent systemd journal entries via `journalctl -o json`.
+ * Linux only — fails with a clear message on macOS.
+ */
+export const logsJournal: ProbeHandler = async (params, exec) => {
+  if (platform() === 'darwin') {
+    throw new Error(
+      'system.logs.journal requires systemd (Linux only)',
+    );
+  }
+
+  const lines = Math.min(
+    Math.max(Number(params?.lines ?? 50), 1),
+    500,
+  );
+  const unit = params?.unit as string | undefined;
+  const priority = params?.priority as string | undefined;
+
+  const args = [
+    '-n',
+    String(lines),
+    '--no-pager',
+    '-o',
+    'json',
+  ];
+
+  if (unit) {
+    args.push('-u', unit);
+  }
+  if (priority) {
+    args.push('-p', priority);
+  }
+
+  const output = await exec('journalctl', args);
+  return parseJournalOutput(output, unit);
+};
+
+export function parseJournalOutput(
+  raw: string,
+  unit?: string,
+): JournalResult {
+  const entries: JournalEntry[] = [];
+
+  for (const line of raw.trim().split('\n')) {
+    if (!line) continue;
+
+    let obj: Record<string, unknown>;
+    try {
+      obj = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+
+    const timestamp =
+      typeof obj.__REALTIME_TIMESTAMP === 'string'
+        ? formatUsecTimestamp(obj.__REALTIME_TIMESTAMP)
+        : String(obj.__REALTIME_TIMESTAMP ?? '');
+
+    entries.push({
+      timestamp,
+      priority: Number(obj.PRIORITY ?? 6),
+      message: String(obj.MESSAGE ?? ''),
+      pid: Number(obj._PID ?? 0),
+      uid: Number(obj._UID ?? 0),
+      unit: obj._SYSTEMD_UNIT
+        ? String(obj._SYSTEMD_UNIT)
+        : undefined,
+    });
+  }
+
+  const result: JournalResult = {
+    entries,
+    entryCount: entries.length,
+  };
+  if (unit) {
+    result.unit = unit;
+  }
+  return result;
+}
+
+function formatUsecTimestamp(usec: string): string {
+  const ms = Math.floor(Number(usec) / 1000);
+  if (Number.isNaN(ms)) return usec;
+  return new Date(ms).toISOString();
+}

package/src/system/probes/logs-tail.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { LogTailResult } from './logs-tail.js';
+import {
+  logsTail,
+  parseLogTailOutput,
+  validateLogPath,
+} from './logs-tail.js';
+
+const SYSLOG_OUTPUT = `Jan 15 10:00:01 host systemd[1]: Started Session 1
+Jan 15 10:00:02 host sshd[512]: Accepted publickey
+Jan 15 10:00:03 host kernel: audit: type=1400`;
+
+describe('validateLogPath', () => {
+  it('accepts valid /var/log/ paths', () => {
+    expect(() =>
+      validateLogPath('/var/log/syslog'),
+    ).not.toThrow();
+    expect(() =>
+      validateLogPath('/var/log/nginx/access.log'),
+    ).not.toThrow();
+  });
+
+  it('accepts valid /tmp/ paths', () => {
+    expect(() =>
+      validateLogPath('/tmp/debug.log'),
+    ).not.toThrow();
+  });
+
+  it('rejects relative paths', () => {
+    expect(() =>
+      validateLogPath('var/log/syslog'),
+    ).toThrow('Path must be absolute');
+  });
+
+  it('rejects paths with ..', () => {
+    expect(() =>
+      validateLogPath('/var/log/../../etc/shadow'),
+    ).toThrow("must not contain '..'");
+  });
+
+  it('rejects paths outside allowed prefixes', () => {
+    expect(() =>
+      validateLogPath('/etc/shadow'),
+    ).toThrow('must start with one of');
+    expect(() =>
+      validateLogPath('/home/user/.bash_history'),
+    ).toThrow('must start with one of');
+    expect(() =>
+      validateLogPath('/root/.ssh/id_rsa'),
+    ).toThrow('must start with one of');
+  });
+});
+
+describe('parseLogTailOutput', () => {
+  it('parses multi-line log output', () => {
+    const result = parseLogTailOutput(
+      SYSLOG_OUTPUT,
+      '/var/log/syslog',
+    );
+
+    expect(result.logPath).toBe('/var/log/syslog');
+    expect(result.lineCount).toBe(3);
+    expect(result.lines[0]).toContain('Started Session');
+    expect(result.lines[2]).toContain('audit');
+  });
+
+  it('handles empty output', () => {
+    const result = parseLogTailOutput('', '/var/log/empty.log');
+
+    expect(result.lineCount).toBe(0);
+    expect(result.lines).toHaveLength(0);
+  });
+});
+
+describe('logsTail handler', () => {
+  it('throws when path is missing', async () => {
+    const mockExec: ExecFn = async () => '';
+    await expect(
+      logsTail(undefined, mockExec),
+    ).rejects.toThrow('Missing required parameter: path');
+    await expect(
+      logsTail({}, mockExec),
+    ).rejects.toThrow('Missing required parameter: path');
+  });
+
+  it('throws for invalid paths before calling exec', async () => {
+    const calls: string[] = [];
+    const mockExec: ExecFn = async (cmd) => {
+      calls.push(cmd);
+      return '';
+    };
+
+    await expect(
+      logsTail({ path: '/etc/shadow' }, mockExec),
+    ).rejects.toThrow('must start with one of');
+    expect(calls).toHaveLength(0);
+  });
+
+  it('passes correct args with defaults', async () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    const mockExec: ExecFn = async (cmd, args) => {
+      calls.push({ cmd, args });
+      return SYSLOG_OUTPUT;
+    };
+
+    const result = (await logsTail(
+      { path: '/var/log/syslog' },
+      mockExec,
+    )) as LogTailResult;
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.cmd).toBe('tail');
+    expect(calls[0]?.args).toEqual([
+      '-n', '50', '/var/log/syslog',
+    ]);
+    expect(result.logPath).toBe('/var/log/syslog');
+    expect(result.lineCount).toBe(3);
+  });
+
+  it('clamps lines to valid range', async () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    const mockExec: ExecFn = async (cmd, args) => {
+      calls.push({ cmd, args });
+      return '';
+    };
+
+    await logsTail(
+      { path: '/var/log/syslog', lines: 9999 },
+      mockExec,
+    );
+    expect(calls[0]?.args).toContain('500');
+
+    await logsTail(
+      { path: '/var/log/syslog', lines: 0 },
+      mockExec,
+    );
+    expect(calls[1]?.args).toContain('1');
+  });
+});

package/src/system/probes/logs-tail.ts

@@ -0,0 +1,70 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface LogTailResult {
+  logPath: string;
+  lines: string[];
+  lineCount: number;
+}
+
+const ALLOWED_PREFIXES = ['/var/log/', '/tmp/'];
+
+export function validateLogPath(path: string): void {
+  if (!path.startsWith('/')) {
+    throw new Error(
+      `Path must be absolute (start with /): ${path}`,
+    );
+  }
+
+  if (path.includes('..')) {
+    throw new Error(
+      `Path must not contain '..': ${path}`,
+    );
+  }
+
+  const allowed = ALLOWED_PREFIXES.some((prefix) =>
+    path.startsWith(prefix),
+  );
+  if (!allowed) {
+    throw new Error(
+      `Path must start with one of: ${ALLOWED_PREFIXES.join(', ')} — got: ${path}`,
+    );
+  }
+}
+
+/**
+ * Tails a log file at a given absolute path.
+ * Restricted to /var/log/ and /tmp/ for security.
+ */
+export const logsTail: ProbeHandler = async (params, exec) => {
+  const path = params?.path as string | undefined;
+  if (!path) {
+    throw new Error('Missing required parameter: path');
+  }
+
+  validateLogPath(path);
+
+  const lines = Math.min(
+    Math.max(Number(params?.lines ?? 50), 1),
+    500,
+  );
+
+  const output = await exec('tail', [
+    '-n',
+    String(lines),
+    path,
+  ]);
+
+  return parseLogTailOutput(output, path);
+};
+
+export function parseLogTailOutput(
+  raw: string,
+  logPath: string,
+): LogTailResult {
+  const lines = raw.split('\n').filter(Boolean);
+  return {
+    logPath,
+    lines,
+    lineCount: lines.length,
+  };
+}

package/src/system/probes/ping.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { PingResult } from './ping.js';
+import { parsePingOutput, ping } from './ping.js';
+
+const LINUX_OUTPUT = `PING 10.0.0.1 (10.0.0.1) 56(84) bytes of data.
+64 bytes from 10.0.0.1: icmp_seq=1 ttl=64 time=0.543 ms
+64 bytes from 10.0.0.1: icmp_seq=2 ttl=64 time=0.401 ms
+64 bytes from 10.0.0.1: icmp_seq=3 ttl=64 time=0.387 ms
+64 bytes from 10.0.0.1: icmp_seq=4 ttl=64 time=0.392 ms
+
+--- 10.0.0.1 ping statistics ---
+4 packets transmitted, 4 received, 0% packet loss, time 3005ms
+rtt min/avg/max/mdev = 0.387/0.430/0.543/0.065 ms
+`;
+
+const MACOS_OUTPUT = `PING 192.168.1.1 (192.168.1.1): 56 data bytes
+64 bytes from 192.168.1.1: icmp_seq=0 ttl=64 time=1.234 ms
+64 bytes from 192.168.1.1: icmp_seq=1 ttl=64 time=1.456 ms
+64 bytes from 192.168.1.1: icmp_seq=2 ttl=64 time=1.123 ms
+64 bytes from 192.168.1.1: icmp_seq=3 ttl=64 time=1.345 ms
+
+--- 192.168.1.1 ping statistics ---
+4 packets transmitted, 4 packets received, 0.0% packet loss
+round-trip min/avg/max/stddev = 1.123/1.289/1.456/0.122 ms
+`;
+
+const FULL_LOSS_OUTPUT = `PING 10.99.99.99 (10.99.99.99) 56(84) bytes of data.
+
+--- 10.99.99.99 ping statistics ---
+4 packets transmitted, 0 received, 100% packet loss, time 3003ms
+`;
+
+const PARTIAL_LOSS_OUTPUT = `PING 10.0.0.5 (10.0.0.5) 56(84) bytes of data.
+64 bytes from 10.0.0.5: icmp_seq=1 ttl=64 time=0.500 ms
+64 bytes from 10.0.0.5: icmp_seq=3 ttl=64 time=0.600 ms
+
+--- 10.0.0.5 ping statistics ---
+4 packets transmitted, 2 received, 50% packet loss, time 3004ms
+rtt min/avg/max/mdev = 0.500/0.550/0.600/0.050 ms
+`;
+
+describe('parsePingOutput', () => {
+  it('parses valid Linux ping output', () => {
+    const result = parsePingOutput(LINUX_OUTPUT, '10.0.0.1');
+
+    expect(result.host).toBe('10.0.0.1');
+    expect(result.packetsTransmitted).toBe(4);
+    expect(result.packetsReceived).toBe(4);
+    expect(result.packetLossPercent).toBe(0);
+    expect(result.rttMs).toEqual({
+      min: 0.387,
+      avg: 0.43,
+      max: 0.543,
+      stddev: 0.065,
+    });
+  });
+
+  it('parses valid macOS ping output', () => {
+    const result = parsePingOutput(MACOS_OUTPUT, '192.168.1.1');
+
+    expect(result.host).toBe('192.168.1.1');
+    expect(result.packetsTransmitted).toBe(4);
+    expect(result.packetsReceived).toBe(4);
+    expect(result.packetLossPercent).toBe(0);
+    expect(result.rttMs).toEqual({
+      min: 1.123,
+      avg: 1.289,
+      max: 1.456,
+      stddev: 0.122,
+    });
+  });
+
+  it('handles 100% packet loss', () => {
+    const result = parsePingOutput(FULL_LOSS_OUTPUT, '10.99.99.99');
+
+    expect(result.packetsTransmitted).toBe(4);
+    expect(result.packetsReceived).toBe(0);
+    expect(result.packetLossPercent).toBe(100);
+    expect(result.rttMs).toBeUndefined();
+  });
+
+  it('handles partial packet loss with RTT', () => {
+    const result = parsePingOutput(PARTIAL_LOSS_OUTPUT, '10.0.0.5');
+
+    expect(result.packetsTransmitted).toBe(4);
+    expect(result.packetsReceived).toBe(2);
+    expect(result.packetLossPercent).toBe(50);
+    expect(result.rttMs).toBeDefined();
+    expect(result.rttMs?.avg).toBeCloseTo(0.55);
+  });
+});
+
+describe('ping handler', () => {
+  it('throws when host param is missing', async () => {
+    const mockExec: ExecFn = async () => '';
+    await expect(ping(undefined, mockExec)).rejects.toThrow(
+      'Missing required parameter: host',
+    );
+    await expect(ping({}, mockExec)).rejects.toThrow(
+      'Missing required parameter: host',
+    );
+  });
+
+  it('passes correct args to exec with default count', async () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    const mockExec: ExecFn = async (cmd, args) => {
+      calls.push({ cmd, args });
+      return LINUX_OUTPUT;
+    };
+
+    const result = (await ping(
+      { host: '10.0.0.1' },
+      mockExec,
+    )) as PingResult;
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.cmd).toBe('ping');
+    expect(calls[0]?.args).toContain('-c');
+    expect(calls[0]?.args).toContain('4');
+    expect(calls[0]?.args).toContain('10.0.0.1');
+    expect(result.host).toBe('10.0.0.1');
+    expect(result.packetsTransmitted).toBe(4);
+  });
+
+  it('respects custom count param', async () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    const mockExec: ExecFn = async (cmd, args) => {
+      calls.push({ cmd, args });
+      return LINUX_OUTPUT;
+    };
+
+    await ping({ host: '10.0.0.1', count: 2 }, mockExec);
+
+    expect(calls[0]?.args).toContain('2');
+  });
+
+  it('clamps count to valid range', async () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    const mockExec: ExecFn = async (cmd, args) => {
+      calls.push({ cmd, args });
+      return LINUX_OUTPUT;
+    };
+
+    await ping({ host: '10.0.0.1', count: 100 }, mockExec);
+    expect(calls[0]?.args).toContain('20');
+
+    await ping({ host: '10.0.0.1', count: 0 }, mockExec);
+    expect(calls[1]?.args).toContain('1');
+  });
+
+  it('handles exec failure (DNS resolution error)', async () => {
+    const mockExec: ExecFn = async () => {
+      throw new Error(
+        'ping: unknown host nosuchhost.invalid',
+      );
+    };
+
+    await expect(
+      ping({ host: 'nosuchhost.invalid' }, mockExec),
+    ).rejects.toThrow('unknown host');
+  });
+});

package/src/system/probes/ping.ts

@@ -0,0 +1,89 @@
+import { platform } from 'node:os';
+import type { ProbeHandler } from '../../types.js';
+
+export interface PingResult {
+  host: string;
+  packetsTransmitted: number;
+  packetsReceived: number;
+  packetLossPercent: number;
+  rttMs?: {
+    min: number;
+    avg: number;
+    max: number;
+    stddev: number;
+  };
+}
+
+/**
+ * Pings a remote host and returns packet loss and RTT statistics.
+ * Cross-platform: uses -W (Linux) or -t (macOS) for per-packet timeout.
+ */
+export const ping: ProbeHandler = async (params, exec) => {
+  const host = params?.host as string | undefined;
+  if (!host) {
+    throw new Error('Missing required parameter: host');
+  }
+
+  const count = Math.min(
+    Math.max(Number(params?.count ?? 4), 1),
+    20,
+  );
+
+  const isMac = platform() === 'darwin';
+  const timeoutFlag = isMac ? '-t' : '-W';
+
+  const output = await exec('ping', [
+    '-c',
+    String(count),
+    timeoutFlag,
+    '3',
+    host,
+  ]);
+
+  return parsePingOutput(output, host);
+};
+
+export function parsePingOutput(
+  raw: string,
+  host: string,
+): PingResult {
+  const result: PingResult = {
+    host,
+    packetsTransmitted: 0,
+    packetsReceived: 0,
+    packetLossPercent: 100,
+  };
+
+  // Match "X packets transmitted, Y received" or "Y packets received"
+  const statsMatch = raw.match(
+    /(\d+)\s+packets?\s+transmitted,\s+(\d+)\s+(?:packets?\s+)?received/,
+  );
+  if (statsMatch) {
+    result.packetsTransmitted = Number(statsMatch[1]);
+    result.packetsReceived = Number(statsMatch[2]);
+  }
+
+  // Match "X% packet loss"
+  const lossMatch = raw.match(
+    /([\d.]+)%\s+packet\s+loss/,
+  );
+  if (lossMatch) {
+    result.packetLossPercent = Number(lossMatch[1]);
+  }
+
+  // Match RTT line: "min/avg/max/stddev = X/X/X/X ms"
+  // or "min/avg/max/mdev = X/X/X/X ms" (Linux)
+  const rttMatch = raw.match(
+    /=\s+([\d.]+)\/([\d.]+)\/([\d.]+)\/([\d.]+)\s+ms/,
+  );
+  if (rttMatch) {
+    result.rttMs = {
+      min: Number(rttMatch[1]),
+      avg: Number(rttMatch[2]),
+      max: Number(rttMatch[3]),
+      stddev: Number(rttMatch[4]),
+    };
+  }
+
+  return result;
+}