Feat/telemetry

README.md

@@ -89,6 +89,7 @@ Shannon is available in two editions:
 - [Architecture](#-architecture)
 - [Coverage and Roadmap](#-coverage-and-roadmap)
 - [Disclaimers](#-disclaimers)
+- [Telemetry](#-telemetry)
 - [License](#-license)
 - [Community & Support](#-community--support)
 - [Get in Touch](#-get-in-touch)
@@ -437,6 +438,38 @@ Shannon is designed for legitimate security auditing purposes only.
 Windows Defender may flag files in `xben-benchmark-results/` or `deliverables/` as malware. These are false positives caused by exploit code in the reports. Add an exclusion for the Shannon directory in Windows Defender, or use Docker/WSL2.
 
 
+## 📊 Telemetry
+
+Shannon collects anonymous usage telemetry to help improve the tool.
+
+### What We Collect
+
+- Workflow and agent lifecycle events (start, complete, fail)
+- Timing and cost metrics (duration, API costs)
+- Error types (NOT error messages or stack traces)
+
+### What We DO NOT Collect
+
+- Target URLs, repository paths, or configuration
+- Vulnerability findings or security reports
+- Error messages, stack traces, or debugging info
+- Any personally identifiable information (PII)
+
+### Opting Out
+
+Telemetry is enabled by default. To disable it, set one of:
+
+```bash
+# Standard opt-out
+export DO_NOT_TRACK=1
+
+# Shannon-specific opt-out
+export SHANNON_TELEMETRY=off
+```
+
+Or add `DO_NOT_TRACK=1` to your `.env` file.
+
+
 ## 📜 License
 
 Shannon Lite is released under the [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE).

docker-compose.yml

@@ -30,6 +30,7 @@ services:
       - ./audit-logs:/app/audit-logs
       - ${TARGET_REPO:-.}:/target-repo
       - ${BENCHMARKS_BASE:-.}:/benchmarks
+      - ${HOME}/.shannon:/tmp/.shannon
     shm_size: 2gb
     ipc: host
     security_opt:

package.json

@@ -24,6 +24,7 @@
     "figlet": "^1.9.3",
     "gradient-string": "^3.0.0",
     "js-yaml": "^4.1.0",
+    "posthog-node": "^5.20.0",
     "zod": "^3.22.4",
     "zx": "^8.0.0"
   },

src/telemetry/index.ts

@@ -0,0 +1,26 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Telemetry Module - Public API
+ *
+ * Usage:
+ *   import { telemetry, TelemetryEvent } from '../telemetry/index.js';
+ *
+ *   telemetry.initialize();
+ *   telemetry.track(TelemetryEvent.WORKFLOW_START, { has_config: true });
+ *   await telemetry.shutdown();
+ */
+
+export { telemetry, hashTargetUrl } from './telemetry-manager.js';
+export { TelemetryEvent } from './telemetry-events.js';
+export { getInstallationId } from './installation-id.js';
+export type {
+  BaseTelemetryProperties,
+  AgentEventProperties,
+  WorkflowEventProperties,
+} from './telemetry-events.js';
+export { loadTelemetryConfig } from './telemetry-config.js';

src/telemetry/installation-id.ts

@@ -0,0 +1,78 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Installation ID - Persistent anonymous identifier for telemetry.
+ *
+ * Generates a UUID and persists it to ~/.shannon/telemetry-id
+ * On subsequent runs, reads the existing ID from the file.
+ * Handles errors gracefully by returning a random UUID.
+ */
+
+import { randomUUID } from 'crypto';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const SHANNON_DIR = '.shannon';
+const TELEMETRY_ID_FILE = 'telemetry-id';
+
+/**
+ * Get the path to the telemetry ID file.
+ * Returns ~/.shannon/telemetry-id
+ */
+function getTelemetryIdPath(): string {
+  return join(homedir(), SHANNON_DIR, TELEMETRY_ID_FILE);
+}
+
+/**
+ * Get the path to the Shannon config directory.
+ * Returns ~/.shannon
+ */
+function getShannonDir(): string {
+  return join(homedir(), SHANNON_DIR);
+}
+
+/**
+ * Get or create a persistent installation ID.
+ *
+ * - If ~/.shannon/telemetry-id exists, reads and returns the ID
+ * - If not, generates a new UUID, persists it, and returns it
+ * - On any error, returns a random UUID (doesn't persist)
+ *
+ * @returns Promise<string> - The installation ID (UUID format)
+ */
+export async function getInstallationId(): Promise<string> {
+  const filePath = getTelemetryIdPath();
+
+  try {
+    // Try to read existing ID
+    const existingId = await readFile(filePath, 'utf-8');
+    const trimmedId = existingId.trim();
+
+    // Validate it looks like a UUID (basic check)
+    if (trimmedId.length >= 32) {
+      return trimmedId;
+    }
+  } catch {
+    // File doesn't exist or can't be read - will create new ID
+  }
+
+  // Generate new ID
+  const newId = randomUUID();
+
+  try {
+    // Ensure ~/.shannon directory exists
+    await mkdir(getShannonDir(), { recursive: true });
+
+    // Persist the new ID
+    await writeFile(filePath, newId, 'utf-8');
+  } catch {
+    // Failed to persist - return the ID anyway (won't be persistent)
+  }
+
+  return newId;
+}

src/telemetry/telemetry-config.ts

@@ -0,0 +1,68 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Telemetry configuration with opt-out support.
+ *
+ * Telemetry is enabled by default. Users can disable via:
+ * - DO_NOT_TRACK=1 (standard convention: https://consoledonottrack.com/)
+ * - SHANNON_TELEMETRY=off|false|0
+ */
+
+export interface TelemetryConfig {
+  enabled: boolean;
+  apiKey: string;
+  host: string;
+}
+
+// PostHog project configuration
+// This is a write-only key - safe to publish, users cannot read analytics
+const POSTHOG_API_KEY = 'phc_9EF2G6mm83rfLef5WmVLiNSyGQ4x0p8NzTRKiEAgvD4';
+const POSTHOG_HOST = 'https://us.i.posthog.com';
+
+/**
+ * Check if telemetry is enabled based on environment variables.
+ */
+function isTelemetryEnabled(): boolean {
+  // Standard opt-out: DO_NOT_TRACK
+  const doNotTrack = process.env.DO_NOT_TRACK;
+  if (doNotTrack === '1' || doNotTrack?.toLowerCase() === 'true') {
+    return false;
+  }
+
+  // Shannon-specific opt-out
+  const shannonTelemetry = process.env.SHANNON_TELEMETRY?.toLowerCase();
+  if (
+    shannonTelemetry === 'off' ||
+    shannonTelemetry === 'false' ||
+    shannonTelemetry === '0'
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Load telemetry configuration from environment.
+ * Never throws - returns disabled config on any error.
+ */
+export function loadTelemetryConfig(): TelemetryConfig {
+  try {
+    return {
+      enabled: isTelemetryEnabled(),
+      apiKey: POSTHOG_API_KEY,
+      host: POSTHOG_HOST,
+    };
+  } catch {
+    // Config loading should never fail - return disabled
+    return {
+      enabled: false,
+      apiKey: POSTHOG_API_KEY,
+      host: POSTHOG_HOST,
+    };
+  }
+}