@sonde/agent 0.0.0

package/src/runtime/connection.ts

@@ -0,0 +1,389 @@
+import fs from 'node:fs';
+import {
+  HEARTBEAT_INTERVAL_MS,
+  type MessageEnvelope,
+  MessageEnvelope as MessageEnvelopeSchema,
+  type ProbeRequest,
+  ProbeRequest as ProbeRequestSchema,
+  signPayload,
+  verifyPayload,
+} from '@sonde/shared';
+import WebSocket from 'ws';
+import type { AgentConfig } from '../config.js';
+import { saveCerts } from '../config.js';
+import { generateAttestation } from './attestation.js';
+import { AgentAuditLog } from './audit.js';
+import type { ProbeExecutor } from './executor.js';
+
+export interface ConnectionEvents {
+  onConnected?: (agentId: string) => void;
+  onDisconnected?: () => void;
+  onError?: (error: Error) => void;
+  onRegistered?: (agentId: string) => void;
+  onProbeCompleted?: (probe: string, status: string, durationMs: number) => void;
+}
+
+/** Minimum/maximum reconnect delays */
+const MIN_RECONNECT_MS = 1_000;
+const MAX_RECONNECT_MS = 60_000;
+
+const ENROLL_TIMEOUT_MS = 10_000;
+
+/**
+ * One-shot enrollment: connect to hub, register, get agentId, disconnect.
+ * If enrollmentToken is set in config, includes it in registration for cert-based enrollment.
+ * Returns { agentId, certIssued } — certIssued is true if certs were saved.
+ */
+export function enrollWithHub(
+  config: AgentConfig,
+  executor: ProbeExecutor,
+): Promise<{ agentId: string; certIssued: boolean }> {
+  return new Promise((resolve, reject) => {
+    const wsUrl = `${config.hubUrl.replace(/^http/, 'ws')}/ws/agent`;
+
+    const ws = new WebSocket(wsUrl, {
+      headers: { Authorization: `Bearer ${config.apiKey}` },
+    });
+
+    const timeout = setTimeout(() => {
+      ws.close();
+      reject(new Error('Enrollment timed out waiting for hub acknowledgement'));
+    }, ENROLL_TIMEOUT_MS);
+
+    ws.on('open', () => {
+      const payload: Record<string, unknown> = {
+        name: config.agentName,
+        os: `${process.platform} ${process.arch}`,
+        agentVersion: '0.1.0',
+        packs: executor.getLoadedPacks(),
+        attestation: generateAttestation(config, executor),
+      };
+      if (config.enrollmentToken) {
+        payload.enrollmentToken = config.enrollmentToken;
+      }
+
+      ws.send(
+        JSON.stringify({
+          id: crypto.randomUUID(),
+          type: 'agent.register',
+          timestamp: new Date().toISOString(),
+          signature: '',
+          payload,
+        }),
+      );
+    });
+
+    ws.on('message', (data) => {
+      let envelope: MessageEnvelope;
+      try {
+        envelope = MessageEnvelopeSchema.parse(JSON.parse(data.toString()));
+      } catch {
+        return;
+      }
+
+      if (envelope.type === 'hub.ack') {
+        clearTimeout(timeout);
+        const ackPayload = envelope.payload as {
+          agentId?: string;
+          error?: string;
+          certPem?: string;
+          keyPem?: string;
+          caCertPem?: string;
+        };
+
+        ws.close();
+
+        if (ackPayload.error) {
+          reject(new Error(ackPayload.error));
+          return;
+        }
+
+        const agentId = ackPayload.agentId;
+        if (!agentId) {
+          reject(new Error('Hub ack did not contain agentId'));
+          return;
+        }
+
+        // If hub issued certs, save them
+        let certIssued = false;
+        if (ackPayload.certPem && ackPayload.keyPem && ackPayload.caCertPem) {
+          saveCerts(config, ackPayload.certPem, ackPayload.keyPem, ackPayload.caCertPem);
+          certIssued = true;
+        }
+
+        resolve({ agentId, certIssued });
+      }
+    });
+
+    ws.on('error', (err) => {
+      clearTimeout(timeout);
+      reject(err);
+    });
+  });
+}
+
+/** Build WebSocket options, including TLS client cert if available. */
+function buildWsOptions(config: AgentConfig): WebSocket.ClientOptions {
+  const options: WebSocket.ClientOptions = {
+    headers: {
+      Authorization: `Bearer ${config.apiKey}`,
+    },
+  };
+
+  if (config.certPath && config.keyPath && config.caCertPath) {
+    try {
+      options.cert = fs.readFileSync(config.certPath, 'utf-8');
+      options.key = fs.readFileSync(config.keyPath, 'utf-8');
+      options.ca = [fs.readFileSync(config.caCertPath, 'utf-8')];
+      options.rejectUnauthorized = false; // Hub uses self-signed CA cert
+    } catch {
+      // Cert files missing or unreadable — fall back to API key only
+    }
+  }
+
+  return options;
+}
+
+export class AgentConnection {
+  private ws: WebSocket | null = null;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectAttempts = 0;
+  private agentId: string | undefined;
+  private running = false;
+  private privateKeyPem: string | undefined;
+  private caCertPem: string | undefined;
+  private auditLog = new AgentAuditLog();
+
+  constructor(
+    private config: AgentConfig,
+    private executor: ProbeExecutor,
+    private events: ConnectionEvents = {},
+  ) {
+    // Load private key for signing outbound messages
+    if (config.keyPath) {
+      try {
+        this.privateKeyPem = fs.readFileSync(config.keyPath, 'utf-8');
+      } catch {
+        // Key not available — messages will be sent unsigned
+      }
+    }
+    // Load CA cert for verifying hub messages
+    if (config.caCertPath) {
+      try {
+        this.caCertPem = fs.readFileSync(config.caCertPath, 'utf-8');
+      } catch {
+        // CA cert not available — skip verification
+      }
+    }
+  }
+
+  /** Start the connection (connect + auto-reconnect loop) */
+  start(): void {
+    this.running = true;
+    this.connect();
+  }
+
+  /** Stop the connection cleanly */
+  stop(): void {
+    this.running = false;
+    this.clearTimers();
+    if (this.ws) {
+      this.ws.close(1000, 'Agent shutting down');
+      this.ws = null;
+    }
+  }
+
+  /** Whether we're currently connected */
+  isConnected(): boolean {
+    return this.ws?.readyState === WebSocket.OPEN;
+  }
+
+  /** Get the assigned agent ID (set after registration) */
+  getAgentId(): string | undefined {
+    return this.agentId;
+  }
+
+  private connect(): void {
+    const wsUrl = `${this.config.hubUrl.replace(/^http/, 'ws')}/ws/agent`;
+    const options = buildWsOptions(this.config);
+
+    this.ws = new WebSocket(wsUrl, options);
+
+    this.ws.on('open', () => {
+      this.reconnectAttempts = 0;
+      this.sendRegister();
+      this.startHeartbeat();
+    });
+
+    this.ws.on('message', (data) => {
+      this.handleMessage(data.toString());
+    });
+
+    this.ws.on('close', () => {
+      this.clearTimers();
+      this.events.onDisconnected?.();
+      if (this.running) {
+        this.scheduleReconnect();
+      }
+    });
+
+    this.ws.on('error', (err) => {
+      this.events.onError?.(err);
+    });
+  }
+
+  private handleMessage(raw: string): void {
+    let envelope: MessageEnvelope;
+    try {
+      envelope = MessageEnvelopeSchema.parse(JSON.parse(raw));
+    } catch {
+      return; // Invalid message, ignore
+    }
+
+    // Verify hub signature if we have a CA cert and the message is signed
+    if (this.caCertPem && envelope.signature !== '') {
+      const valid = verifyPayload(envelope.payload, envelope.signature, this.caCertPem);
+      if (!valid) {
+        this.events.onError?.(new Error(`Signature verification failed for ${envelope.type}`));
+        return;
+      }
+    }
+
+    switch (envelope.type) {
+      case 'hub.ack':
+        this.handleAck(envelope);
+        break;
+      case 'probe.request':
+        this.handleProbeRequest(envelope);
+        break;
+      default:
+        break;
+    }
+  }
+
+  private handleAck(envelope: MessageEnvelope): void {
+    const payload = envelope.payload as { agentId?: string };
+    if (payload.agentId) {
+      this.agentId = payload.agentId;
+      this.events.onRegistered?.(this.agentId);
+    }
+    this.events.onConnected?.(this.agentId ?? '');
+  }
+
+  private async handleProbeRequest(envelope: MessageEnvelope): Promise<void> {
+    if (!this.agentId) return;
+
+    let request: ProbeRequest;
+    try {
+      request = ProbeRequestSchema.parse(envelope.payload);
+    } catch {
+      this.sendError(envelope.id, 'Invalid probe request payload');
+      return;
+    }
+
+    const response = await this.executor.execute(request);
+
+    this.auditLog.log(request.probe, response.status, response.durationMs);
+    this.events.onProbeCompleted?.(request.probe, response.status, response.durationMs);
+
+    this.send({
+      id: crypto.randomUUID(),
+      type: response.status === 'success' ? 'probe.response' : 'probe.error',
+      timestamp: new Date().toISOString(),
+      agentId: this.agentId,
+      signature: '',
+      payload: response,
+    });
+  }
+
+  /** Get the agent-side audit log (for testing/inspection) */
+  getAuditLog(): AgentAuditLog {
+    return this.auditLog;
+  }
+
+  private sendRegister(): void {
+    this.send({
+      id: crypto.randomUUID(),
+      type: 'agent.register',
+      timestamp: new Date().toISOString(),
+      signature: '',
+      payload: {
+        name: this.config.agentName,
+        os: `${process.platform} ${process.arch}`,
+        agentVersion: '0.1.0',
+        packs: this.executor.getLoadedPacks(),
+        attestation: generateAttestation(this.config, this.executor),
+      },
+    });
+  }
+
+  private startHeartbeat(): void {
+    this.heartbeatTimer = setInterval(() => {
+      if (!this.agentId) return;
+      this.send({
+        id: crypto.randomUUID(),
+        type: 'agent.heartbeat',
+        timestamp: new Date().toISOString(),
+        agentId: this.agentId,
+        signature: '',
+        payload: {},
+      });
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  private sendError(requestId: string, message: string): void {
+    if (!this.agentId) return;
+    this.send({
+      id: crypto.randomUUID(),
+      type: 'probe.error',
+      timestamp: new Date().toISOString(),
+      agentId: this.agentId,
+      signature: '',
+      payload: {
+        probe: 'unknown',
+        status: 'error',
+        data: { error: message },
+        durationMs: 0,
+        metadata: {
+          agentVersion: '0.1.0',
+          packName: 'unknown',
+          packVersion: '0.0.0',
+          capabilityLevel: 'observe',
+        },
+      },
+    });
+  }
+
+  private send(envelope: MessageEnvelope): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      // Sign the payload if we have a private key
+      if (this.privateKeyPem && envelope.signature === '') {
+        envelope.signature = signPayload(envelope.payload, this.privateKeyPem);
+      }
+      this.ws.send(JSON.stringify(envelope));
+    }
+  }
+
+  private scheduleReconnect(): void {
+    const delay = Math.min(MIN_RECONNECT_MS * 2 ** this.reconnectAttempts, MAX_RECONNECT_MS);
+    this.reconnectAttempts++;
+
+    this.reconnectTimer = setTimeout(() => {
+      if (this.running) {
+        this.connect();
+      }
+    }, delay);
+  }
+
+  private clearTimers(): void {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+  }
+}

package/src/runtime/executor.test.ts

@@ -0,0 +1,112 @@
+import type { ExecFn, Pack } from '@sonde/packs';
+import type { ProbeRequest } from '@sonde/shared';
+import { describe, expect, it, vi } from 'vitest';
+import { ProbeExecutor } from './executor.js';
+
+function createMockPack(overrides?: Partial<Pack>): Pack {
+  return {
+    manifest: {
+      name: 'test',
+      version: '1.0.0',
+      description: 'Test pack',
+      requires: { groups: [], files: [], commands: [] },
+      probes: [{ name: 'echo', description: 'Echo test', capability: 'observe', timeout: 5000 }],
+    },
+    handlers: {
+      'test.echo': vi.fn().mockResolvedValue({ message: 'hello' }),
+    },
+    ...overrides,
+  };
+}
+
+function makeRequest(probe: string, params?: Record<string, unknown>): ProbeRequest {
+  return {
+    probe,
+    params,
+    timeout: 30_000,
+    requestedBy: 'test',
+  };
+}
+
+describe('ProbeExecutor', () => {
+  it('executes a probe and returns success response', async () => {
+    const pack = createMockPack();
+    const packs = new Map([['test', pack]]);
+    const executor = new ProbeExecutor(packs);
+
+    const result = await executor.execute(makeRequest('test.echo'));
+
+    expect(result.status).toBe('success');
+    expect(result.probe).toBe('test.echo');
+    expect(result.data).toEqual({ message: 'hello' });
+    expect(result.durationMs).toBeGreaterThanOrEqual(0);
+    expect(result.metadata.packName).toBe('test');
+    expect(result.metadata.packVersion).toBe('1.0.0');
+  });
+
+  it('passes params and exec to handler', async () => {
+    const handler = vi.fn().mockResolvedValue({ ok: true });
+    const mockExec: ExecFn = vi.fn();
+    const pack = createMockPack({ handlers: { 'test.echo': handler } });
+    const packs = new Map([['test', pack]]);
+    const executor = new ProbeExecutor(packs, mockExec);
+
+    await executor.execute(makeRequest('test.echo', { verbose: true }));
+
+    expect(handler).toHaveBeenCalledWith({ verbose: true }, mockExec);
+  });
+
+  it('returns error for unknown pack', async () => {
+    const executor = new ProbeExecutor(new Map());
+
+    const result = await executor.execute(makeRequest('missing.probe'));
+
+    expect(result.status).toBe('error');
+    expect(result.data).toEqual({ error: "Pack 'missing' not loaded" });
+  });
+
+  it('returns error for unknown probe within pack', async () => {
+    const pack = createMockPack();
+    const packs = new Map([['test', pack]]);
+    const executor = new ProbeExecutor(packs);
+
+    const result = await executor.execute(makeRequest('test.nonexistent'));
+
+    expect(result.status).toBe('error');
+    expect(result.data).toEqual({ error: 'Unknown probe: test.nonexistent' });
+  });
+
+  it('returns error when handler throws', async () => {
+    const pack = createMockPack({
+      handlers: {
+        'test.echo': vi.fn().mockRejectedValue(new Error('Command failed')),
+      },
+    });
+    const packs = new Map([['test', pack]]);
+    const executor = new ProbeExecutor(packs);
+
+    const result = await executor.execute(makeRequest('test.echo'));
+
+    expect(result.status).toBe('error');
+    expect(result.data).toEqual({ error: 'Command failed' });
+    expect(result.metadata.packName).toBe('test');
+  });
+
+  it('returns error for invalid probe name', async () => {
+    const executor = new ProbeExecutor(new Map());
+
+    const result = await executor.execute(makeRequest(''));
+
+    expect(result.status).toBe('error');
+  });
+
+  it('reports loaded packs', () => {
+    const pack = createMockPack();
+    const packs = new Map([['test', pack]]);
+    const executor = new ProbeExecutor(packs);
+
+    const loaded = executor.getLoadedPacks();
+
+    expect(loaded).toEqual([{ name: 'test', version: '1.0.0', status: 'active' }]);
+  });
+});

package/src/runtime/executor.ts

@@ -0,0 +1,107 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { type ExecFn, type Pack, packRegistry } from '@sonde/packs';
+import type { ProbeRequest, ProbeResponse } from '@sonde/shared';
+import { type ScrubPattern, buildPatterns, scrubData } from './scrubber.js';
+
+const execFileAsync = promisify(execFile);
+
+const AGENT_VERSION = '0.1.0';
+
+/** Default exec function that shells out to real commands */
+async function defaultExec(command: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync(command, args, {
+    timeout: 30_000,
+    maxBuffer: 1024 * 1024,
+  });
+  return stdout;
+}
+
+export class ProbeExecutor {
+  private packs: ReadonlyMap<string, Pack>;
+  private exec: ExecFn;
+  private scrubPatterns: ScrubPattern[];
+
+  constructor(packs?: ReadonlyMap<string, Pack>, exec?: ExecFn, scrubPatterns?: ScrubPattern[]) {
+    this.packs = packs ?? packRegistry;
+    this.exec = exec ?? defaultExec;
+    this.scrubPatterns = scrubPatterns ?? buildPatterns();
+  }
+
+  /** Get list of loaded packs with status info */
+  getLoadedPacks(): Array<{ name: string; version: string; status: string }> {
+    return [...this.packs.values()].map((pack) => ({
+      name: pack.manifest.name,
+      version: pack.manifest.version,
+      status: 'active',
+    }));
+  }
+
+  /** Get a pack by name */
+  getPackByName(name: string): Pack | undefined {
+    return this.packs.get(name);
+  }
+
+  /** Execute a probe request and return a probe response */
+  async execute(request: ProbeRequest): Promise<ProbeResponse> {
+    const start = Date.now();
+
+    // Find the handler by full probe name (e.g. "system.disk.usage")
+    const probeName = request.probe;
+    const packName = probeName.split('.')[0];
+
+    if (!packName) {
+      return this.errorResponse(probeName, start, `Invalid probe name: ${probeName}`);
+    }
+
+    const pack = this.packs.get(packName);
+    if (!pack) {
+      return this.errorResponse(probeName, start, `Pack '${packName}' not loaded`);
+    }
+
+    const handler = pack.handlers[probeName];
+    if (!handler) {
+      return this.errorResponse(probeName, start, `Unknown probe: ${probeName}`);
+    }
+
+    try {
+      const rawData = await handler(request.params, this.exec);
+      const data = scrubData(rawData, this.scrubPatterns);
+      return {
+        probe: probeName,
+        status: 'success',
+        data,
+        durationMs: Date.now() - start,
+        metadata: {
+          agentVersion: AGENT_VERSION,
+          packName: pack.manifest.name,
+          packVersion: pack.manifest.version,
+          capabilityLevel: 'observe',
+        },
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unknown error';
+      return this.errorResponse(probeName, start, message, pack);
+    }
+  }
+
+  private errorResponse(
+    probe: string,
+    startMs: number,
+    message: string,
+    pack?: Pack,
+  ): ProbeResponse {
+    return {
+      probe,
+      status: 'error',
+      data: { error: message },
+      durationMs: Date.now() - startMs,
+      metadata: {
+        agentVersion: AGENT_VERSION,
+        packName: pack?.manifest.name ?? 'unknown',
+        packVersion: pack?.manifest.version ?? '0.0.0',
+        capabilityLevel: 'observe',
+      },
+    };
+  }
+}

package/src/runtime/privilege.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { checkNotRoot, sondeUserExists, suggestGroupAdd } from './privilege.js';
+
+describe('privilege', () => {
+  it('checkNotRoot does not throw for non-root', () => {
+    // Tests run as non-root, so this should not exit
+    expect(() => checkNotRoot()).not.toThrow();
+  });
+
+  it('sondeUserExists returns a boolean', () => {
+    const result = sondeUserExists();
+    expect(typeof result).toBe('boolean');
+  });
+
+  it('suggestGroupAdd returns correct command', () => {
+    expect(suggestGroupAdd('docker')).toBe('sudo usermod -aG docker sonde');
+    expect(suggestGroupAdd('systemd-journal')).toBe('sudo usermod -aG systemd-journal sonde');
+  });
+
+  it('suggestGroupAdd with different groups', () => {
+    const cmd = suggestGroupAdd('adm');
+    expect(cmd).toContain('adm');
+    expect(cmd).toContain('sonde');
+  });
+});

package/src/runtime/privilege.ts

@@ -0,0 +1,36 @@
+import { execFileSync } from 'node:child_process';
+
+/** Exit with error if running as root (uid 0) */
+export function checkNotRoot(): void {
+  if (process.getuid?.() === 0) {
+    console.error('Error: sonde agent must not run as root.');
+    console.error('Run as the dedicated "sonde" user or a non-root account.');
+    console.error('See: packages/agent/scripts/install.sh');
+    process.exit(1);
+  }
+}
+
+/** Check if the 'sonde' system user exists */
+export function sondeUserExists(): boolean {
+  try {
+    execFileSync('id', ['-u', 'sonde'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Return group list for the sonde user */
+export function getSondeGroups(): string[] {
+  try {
+    const output = execFileSync('id', ['-Gn', 'sonde'], { encoding: 'utf-8' }).trim();
+    return output ? output.split(/\s+/) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Return the command to add the sonde user to a group */
+export function suggestGroupAdd(group: string): string {
+  return `sudo usermod -aG ${group} sonde`;
+}