@sonde/packs 0.1.1 → 0.1.3

package/src/integrations/vcenter.ts

@@ -0,0 +1,261 @@
+import type {
+  FetchFn,
+  IntegrationConfig,
+  IntegrationCredentials,
+  IntegrationPack,
+  IntegrationProbeHandler,
+} from '@sonde/shared';
+
+// --- Session-based auth ---
+
+/** Session token cache: token + expiry timestamp */
+let cachedSession: { token: string; expiresAt: number } | null = null;
+
+/** Acquire a vCenter session token via POST /api/session */
+async function getSessionToken(
+  config: IntegrationConfig,
+  credentials: IntegrationCredentials,
+  fetchFn: FetchFn,
+): Promise<string> {
+  const now = Date.now();
+  if (cachedSession && cachedSession.expiresAt > now) {
+    return cachedSession.token;
+  }
+
+  const { username, password } = credentials.credentials;
+  if (!username || !password) {
+    throw new Error('vCenter requires username and password credentials');
+  }
+
+  const encoded = Buffer.from(`${username}:${password}`).toString('base64');
+  const url = `${config.endpoint.replace(/\/$/, '')}/api/session`;
+  const res = await fetchFn(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Basic ${encoded}`,
+      Accept: 'application/json',
+      ...config.headers,
+    },
+  });
+
+  if (!res.ok) {
+    throw new Error(`vCenter session auth failed: ${res.status} ${res.statusText}`);
+  }
+
+  const token = ((await res.json()) as string).replace(/^"|"$/g, '');
+  cachedSession = { token, expiresAt: now + 5 * 60 * 1000 };
+  return token;
+}
+
+// --- REST helper ---
+
+async function vcenterGet<T>(
+  path: string,
+  config: IntegrationConfig,
+  credentials: IntegrationCredentials,
+  fetchFn: FetchFn,
+  params?: Record<string, string>,
+): Promise<T> {
+  const token = await getSessionToken(config, credentials, fetchFn);
+  const base = `${config.endpoint.replace(/\/$/, '')}${path}`;
+  const url = new URL(base);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      url.searchParams.set(key, value);
+    }
+  }
+
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    'vmware-api-session-id': token,
+    ...config.headers,
+  };
+
+  const res = await fetchFn(url.toString(), { headers });
+  if (!res.ok) {
+    throw new Error(`vCenter API returned ${res.status}: ${res.statusText}`);
+  }
+  return (await res.json()) as T;
+}
+
+// --- Probe handlers ---
+
+const vmList: IntegrationProbeHandler = async (_params, config, credentials, fetchFn) => {
+  const vms = await vcenterGet<
+    Array<{
+      vm: string;
+      name: string;
+      power_state: string;
+      cpu_count?: number;
+      memory_size_MiB?: number;
+    }>
+  >('/api/vcenter/vm', config, credentials, fetchFn);
+
+  return {
+    vms: vms.map((vm) => ({
+      vm: vm.vm,
+      name: vm.name,
+      powerState: vm.power_state,
+      cpuCount: vm.cpu_count ?? null,
+      memorySizeMiB: vm.memory_size_MiB ?? null,
+    })),
+    count: vms.length,
+  };
+};
+
+const vmDetail: IntegrationProbeHandler = async (params, config, credentials, fetchFn) => {
+  const vm = params?.vm as string;
+  if (!vm) throw new Error('vm parameter is required (VM identifier)');
+
+  return vcenterGet(`/api/vcenter/vm/${vm}`, config, credentials, fetchFn);
+};
+
+const hostList: IntegrationProbeHandler = async (_params, config, credentials, fetchFn) => {
+  const hosts = await vcenterGet<
+    Array<{
+      host: string;
+      name: string;
+      connection_state: string;
+      power_state?: string;
+    }>
+  >('/api/vcenter/host', config, credentials, fetchFn);
+
+  return {
+    hosts: hosts.map((h) => ({
+      host: h.host,
+      name: h.name,
+      connectionState: h.connection_state,
+      powerState: h.power_state ?? null,
+    })),
+    count: hosts.length,
+  };
+};
+
+const datastoreList: IntegrationProbeHandler = async (_params, config, credentials, fetchFn) => {
+  const datastores = await vcenterGet<
+    Array<{
+      datastore: string;
+      name: string;
+      type: string;
+      capacity?: number;
+      free_space?: number;
+    }>
+  >('/api/vcenter/datastore', config, credentials, fetchFn);
+
+  return {
+    datastores: datastores.map((ds) => ({
+      datastore: ds.datastore,
+      name: ds.name,
+      type: ds.type,
+      capacity: ds.capacity ?? 0,
+      freeSpace: ds.free_space ?? 0,
+    })),
+    count: datastores.length,
+  };
+};
+
+const clusterList: IntegrationProbeHandler = async (_params, config, credentials, fetchFn) => {
+  const clusters = await vcenterGet<
+    Array<{
+      cluster: string;
+      name: string;
+      ha_enabled?: boolean;
+      drs_enabled?: boolean;
+    }>
+  >('/api/vcenter/cluster', config, credentials, fetchFn);
+
+  return {
+    clusters: clusters.map((cl) => ({
+      cluster: cl.cluster,
+      name: cl.name,
+      haEnabled: cl.ha_enabled ?? false,
+      drsEnabled: cl.drs_enabled ?? false,
+    })),
+    count: clusters.length,
+  };
+};
+
+const health: IntegrationProbeHandler = async (_params, config, credentials, fetchFn) => {
+  return vcenterGet('/api/vcenter/system/health', config, credentials, fetchFn);
+};
+
+// --- Pack definition ---
+
+export const vcenterPack: IntegrationPack = {
+  manifest: {
+    name: 'vcenter',
+    type: 'integration',
+    version: '0.1.0',
+    description: 'VMware vCenter — VMs, ESXi hosts, datastores, clusters, and health status',
+    requires: { groups: [], files: [], commands: [] },
+    probes: [
+      {
+        name: 'vm.list',
+        description: 'List all VMs with power state, CPU, and memory',
+        capability: 'observe',
+        params: {},
+        timeout: 15000,
+      },
+      {
+        name: 'vm.detail',
+        description: 'Detailed info for a single VM by identifier',
+        capability: 'observe',
+        params: {
+          vm: { type: 'string', description: 'VM identifier (e.g. vm-42)', required: true },
+        },
+        timeout: 15000,
+      },
+      {
+        name: 'host.list',
+        description: 'List ESXi hosts with connection state',
+        capability: 'observe',
+        params: {},
+        timeout: 15000,
+      },
+      {
+        name: 'datastore.list',
+        description: 'List datastores with capacity and free space',
+        capability: 'observe',
+        params: {},
+        timeout: 15000,
+      },
+      {
+        name: 'cluster.list',
+        description: 'List clusters with HA and DRS status',
+        capability: 'observe',
+        params: {},
+        timeout: 15000,
+      },
+      {
+        name: 'health',
+        description: 'Overall vCenter health status',
+        capability: 'observe',
+        params: {},
+        timeout: 15000,
+      },
+    ],
+    runbook: {
+      category: 'vmware',
+      probes: ['health', 'host.list', 'vm.list'],
+      parallel: true,
+    },
+  },
+
+  handlers: {
+    'vm.list': vmList,
+    'vm.detail': vmDetail,
+    'host.list': hostList,
+    'datastore.list': datastoreList,
+    'cluster.list': clusterList,
+    health,
+  },
+
+  testConnection: async (config, credentials, fetchFn) => {
+    try {
+      await getSessionToken(config, credentials, fetchFn);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+};

package/src/system/index.ts

@@ -2,7 +2,12 @@ import type { Pack } from '../types.js';
 import { systemManifest } from './manifest.js';
 import { cpuUsage } from './probes/cpu-usage.js';
 import { diskUsage } from './probes/disk-usage.js';
+import { logsDmesg } from './probes/logs-dmesg.js';
+import { logsJournal } from './probes/logs-journal.js';
+import { logsTail } from './probes/logs-tail.js';
 import { memoryUsage } from './probes/memory-usage.js';
+import { ping } from './probes/ping.js';
+import { traceroute } from './probes/traceroute.js';
 
 export const systemPack: Pack = {
   manifest: systemManifest,
@@ -10,5 +15,10 @@ export const systemPack: Pack = {
     'system.disk.usage': diskUsage,
     'system.memory.usage': memoryUsage,
     'system.cpu.usage': cpuUsage,
+    'system.network.ping': ping,
+    'system.logs.journal': logsJournal,
+    'system.logs.dmesg': logsDmesg,
+    'system.logs.tail': logsTail,
+    'system.network.traceroute': traceroute,
   },
 };

package/src/system/manifest.ts

@@ -2,12 +2,20 @@ import type { PackManifest } from '@sonde/shared';
 
 export const systemManifest: PackManifest = {
   name: 'system',
-  version: '0.1.0',
-  description: 'Basic system metrics: disk usage, memory usage, CPU load',
+  version: '0.2.0',
+  description:
+    'System metrics, logs, and network diagnostics: disk, memory, CPU, journal, dmesg, log tail, ping, traceroute',
   requires: {
     groups: [],
     files: [],
-    commands: ['df'],
+    commands: [
+      'df',
+      'ping',
+      'journalctl',
+      'dmesg',
+      'tail',
+      'traceroute',
+    ],
   },
   probes: [
     {
@@ -28,6 +36,108 @@ export const systemManifest: PackManifest = {
       capability: 'observe',
       timeout: 10_000,
     },
+    {
+      name: 'network.ping',
+      description:
+        'Ping a remote host to test ICMP reachability and measure latency',
+      capability: 'observe',
+      timeout: 20_000,
+      params: {
+        host: {
+          type: 'string',
+          description: 'Hostname or IP address to ping',
+          required: true,
+        },
+        count: {
+          type: 'number',
+          description:
+            'Number of ping packets to send (default 4, max 20)',
+          required: false,
+        },
+      },
+    },
+    {
+      name: 'logs.journal',
+      description:
+        'Recent systemd journal entries (Linux only)',
+      capability: 'observe',
+      timeout: 15_000,
+      params: {
+        unit: {
+          type: 'string',
+          description:
+            'Filter to a specific systemd unit (e.g. "nginx")',
+          required: false,
+        },
+        lines: {
+          type: 'number',
+          description:
+            'Number of entries to return (default 50, max 500)',
+          required: false,
+        },
+        priority: {
+          type: 'string',
+          description:
+            'Syslog priority filter (e.g. "err", "warning")',
+          required: false,
+        },
+      },
+    },
+    {
+      name: 'logs.dmesg',
+      description: 'Kernel ring buffer (dmesg) output',
+      capability: 'observe',
+      timeout: 10_000,
+      params: {
+        lines: {
+          type: 'number',
+          description:
+            'Number of lines to return (default 50, max 500)',
+          required: false,
+        },
+      },
+    },
+    {
+      name: 'logs.tail',
+      description:
+        'Tail a log file (restricted to /var/log/ and /tmp/)',
+      capability: 'observe',
+      timeout: 10_000,
+      params: {
+        path: {
+          type: 'string',
+          description:
+            'Absolute path to log file (must be under /var/log/ or /tmp/)',
+          required: true,
+        },
+        lines: {
+          type: 'number',
+          description:
+            'Number of lines to return (default 50, max 500)',
+          required: false,
+        },
+      },
+    },
+    {
+      name: 'network.traceroute',
+      description:
+        'Trace network path to a host showing each hop and latency',
+      capability: 'observe',
+      timeout: 60_000,
+      params: {
+        host: {
+          type: 'string',
+          description: 'Hostname or IP address to trace',
+          required: true,
+        },
+        maxHops: {
+          type: 'number',
+          description:
+            'Maximum number of hops (default 30, max 64)',
+          required: false,
+        },
+      },
+    },
   ],
   runbook: {
     category: 'system',

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

@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { DmesgResult } from './logs-dmesg.js';
+import { logsDmesg, parseDmesgOutput } from './logs-dmesg.js';
+
+const DMESG_OUTPUT = `[2024-01-15T10:00:01+0000] EXT4-fs (sda1): mounted filesystem
+[2024-01-15T10:00:02+0000] audit: type=1400 msg=avc:
+[2024-01-15T10:00:03+0000] NET: Registered PF_INET6
+[2024-01-15T10:00:04+0000] usb 1-1: new high-speed USB device
+[2024-01-15T10:00:05+0000] e1000: Intel(R) PRO/1000 Network Driver`;
+
+describe('parseDmesgOutput', () => {
+  it('returns last N lines', () => {
+    const result = parseDmesgOutput(DMESG_OUTPUT, 3);
+
+    expect(result.lineCount).toBe(3);
+    expect(result.lines).toHaveLength(3);
+    expect(result.lines[0]).toContain('NET: Registered PF_INET6');
+    expect(result.lines[2]).toContain('e1000');
+  });
+
+  it('returns all lines when lines exceeds total', () => {
+    const result = parseDmesgOutput(DMESG_OUTPUT, 100);
+
+    expect(result.lineCount).toBe(5);
+    expect(result.lines).toHaveLength(5);
+  });
+
+  it('handles empty output', () => {
+    const result = parseDmesgOutput('', 50);
+
+    expect(result.lineCount).toBe(0);
+    expect(result.lines).toHaveLength(0);
+  });
+
+  it('handles single line', () => {
+    const result = parseDmesgOutput(
+      '[0.000000] Linux version 6.1.0',
+      50,
+    );
+
+    expect(result.lineCount).toBe(1);
+    expect(result.lines[0]).toContain('Linux version');
+  });
+});
+
+describe('logsDmesg handler', () => {
+  it('passes correct args on Linux', async () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    const mockExec: ExecFn = async (cmd, args) => {
+      calls.push({ cmd, args });
+      return DMESG_OUTPUT;
+    };
+
+    const result = (await logsDmesg(
+      undefined,
+      mockExec,
+    )) as DmesgResult;
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.cmd).toBe('dmesg');
+    // On the CI/test runner platform, args will vary
+    // but the handler should call dmesg
+    expect(result.lineCount).toBeGreaterThan(0);
+  });
+
+  it('clamps lines to valid range', async () => {
+    const mockExec: ExecFn = async () => DMESG_OUTPUT;
+
+    const result = (await logsDmesg(
+      { lines: 2 },
+      mockExec,
+    )) as DmesgResult;
+    expect(result.lineCount).toBe(2);
+
+    const result2 = (await logsDmesg(
+      { lines: 9999 },
+      mockExec,
+    )) as DmesgResult;
+    // 500 clamped but only 5 lines in fixture
+    expect(result2.lineCount).toBe(5);
+  });
+});

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

@@ -0,0 +1,38 @@
+import { platform } from 'node:os';
+import type { ProbeHandler } from '../../types.js';
+
+export interface DmesgResult {
+  lines: string[];
+  lineCount: number;
+}
+
+/**
+ * Reads the kernel ring buffer via `dmesg`.
+ * On Linux uses `--time-format iso` for readable timestamps.
+ * On macOS uses plain `dmesg` (no --time-format support).
+ */
+export const logsDmesg: ProbeHandler = async (params, exec) => {
+  const lines = Math.min(
+    Math.max(Number(params?.lines ?? 50), 1),
+    500,
+  );
+
+  const isMac = platform() === 'darwin';
+  const dmesgArgs = isMac ? [] : ['--time-format', 'iso'];
+
+  const output = await exec('dmesg', dmesgArgs);
+  return parseDmesgOutput(output, lines);
+};
+
+export function parseDmesgOutput(
+  raw: string,
+  lines: number,
+): DmesgResult {
+  const allLines = raw.trim().split('\n').filter(Boolean);
+  const tailLines = allLines.slice(-lines);
+
+  return {
+    lines: tailLines,
+    lineCount: tailLines.length,
+  };
+}

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

@@ -0,0 +1,142 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { JournalResult } from './logs-journal.js';
+import { logsJournal, parseJournalOutput } from './logs-journal.js';
+
+vi.mock('node:os', () => ({ platform: () => 'linux' }));
+
+const JOURNAL_JSON_OUTPUT = [
+  JSON.stringify({
+    __REALTIME_TIMESTAMP: '1700000000000000',
+    PRIORITY: '6',
+    MESSAGE: 'Started Session 42 of User root.',
+    _PID: '1',
+    _UID: '0',
+    _SYSTEMD_UNIT: 'session-42.scope',
+  }),
+  JSON.stringify({
+    __REALTIME_TIMESTAMP: '1700000001000000',
+    PRIORITY: '3',
+    MESSAGE: 'Failed to start nginx.service',
+    _PID: '512',
+    _UID: '0',
+    _SYSTEMD_UNIT: 'nginx.service',
+  }),
+].join('\n');
+
+const SINGLE_ENTRY = JSON.stringify({
+  __REALTIME_TIMESTAMP: '1700000000000000',
+  PRIORITY: '4',
+  MESSAGE: 'Warning from sshd',
+  _PID: '100',
+  _UID: '0',
+});
+
+describe('parseJournalOutput', () => {
+  it('parses multiple JSON journal entries', () => {
+    const result = parseJournalOutput(JOURNAL_JSON_OUTPUT);
+
+    expect(result.entries).toHaveLength(2);
+    expect(result.entryCount).toBe(2);
+    expect(result.unit).toBeUndefined();
+
+    expect(result.entries[0]).toEqual({
+      timestamp: '2023-11-14T22:13:20.000Z',
+      priority: 6,
+      message: 'Started Session 42 of User root.',
+      pid: 1,
+      uid: 0,
+      unit: 'session-42.scope',
+    });
+
+    expect(result.entries[1]).toEqual({
+      timestamp: '2023-11-14T22:13:21.000Z',
+      priority: 3,
+      message: 'Failed to start nginx.service',
+      pid: 512,
+      uid: 0,
+      unit: 'nginx.service',
+    });
+  });
+
+  it('sets unit in result when filtering by unit', () => {
+    const result = parseJournalOutput(SINGLE_ENTRY, 'sshd');
+
+    expect(result.unit).toBe('sshd');
+    expect(result.entries).toHaveLength(1);
+  });
+
+  it('skips malformed JSON lines', () => {
+    const input = `not json at all\n${SINGLE_ENTRY}\n{broken`;
+    const result = parseJournalOutput(input);
+
+    expect(result.entries).toHaveLength(1);
+    expect(result.entries[0]?.message).toBe('Warning from sshd');
+  });
+
+  it('handles empty output', () => {
+    const result = parseJournalOutput('');
+    expect(result.entries).toHaveLength(0);
+    expect(result.entryCount).toBe(0);
+  });
+
+  it('handles entry without _SYSTEMD_UNIT', () => {
+    const result = parseJournalOutput(SINGLE_ENTRY);
+    expect(result.entries[0]?.unit).toBeUndefined();
+  });
+});
+
+describe('logsJournal handler', () => {
+  it('passes correct args to exec with defaults', async () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    const mockExec: ExecFn = async (cmd, args) => {
+      calls.push({ cmd, args });
+      return SINGLE_ENTRY;
+    };
+
+    const result = (await logsJournal(
+      undefined,
+      mockExec,
+    )) as JournalResult;
+
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.cmd).toBe('journalctl');
+    expect(calls[0]?.args).toEqual([
+      '-n', '50', '--no-pager', '-o', 'json',
+    ]);
+    expect(result.entryCount).toBe(1);
+  });
+
+  it('passes unit and priority params', async () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+    const mockExec: ExecFn = async (cmd, args) => {
+      calls.push({ cmd, args });
+      return SINGLE_ENTRY;
+    };
+
+    await logsJournal(
+      { unit: 'nginx', priority: 'err', lines: 100 },
+      mockExec,
+    );
+
+    expect(calls[0]?.args).toEqual([
+      '-n', '100', '--no-pager', '-o', 'json',
+      '-u', 'nginx',
+      '-p', 'err',
+    ]);
+  });
+
+  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 SINGLE_ENTRY;
+    };
+
+    await logsJournal({ lines: 9999 }, mockExec);
+    expect(calls[0]?.args).toContain('500');
+
+    await logsJournal({ lines: 0 }, mockExec);
+    expect(calls[1]?.args).toContain('1');
+  });
+});