chron-mcp 0.1.14 → 0.1.18

package/dashboards/splunk/README.md

@@ -0,0 +1,138 @@
+# Chron → Splunk
+
+Stream AI session telemetry from developer machines into Splunk via HTTP Event Collector (HEC). Works with Splunk Enterprise, Splunk Cloud, and a local Docker instance for testing.
+
+## Quickest way to see it working — Splunk Docker
+
+The fastest path to visually verify the integration with no accounts or licenses:
+
+```bash
+docker run -d \
+  --name splunk-chron \
+  --platform linux/amd64 \
+  -p 8000:8000 \
+  -p 8088:8088 \
+  -e SPLUNK_START_ARGS=--accept-license \
+  -e SPLUNK_PASSWORD=Admin1234! \
+  -e SPLUNK_HEC_TOKEN=chron-test-token \
+  splunk/splunk:latest
+```
+
+> **Apple Silicon (M1/M2/M3):** The `--platform linux/amd64` flag is required — the Splunk image has no ARM64 manifest. Docker Desktop uses Rosetta 2 to emulate it automatically.
+
+Wait ~2 minutes for Splunk to start, then:
+
+```bash
+chron connect splunk
+# URL:   https://localhost:8088   ← HTTPS (Splunk 9.x uses SSL by default)
+# Token: chron-test-token
+```
+
+> Certificate verification is automatically skipped for localhost URLs — no extra flags needed.
+
+Add to your MCP config and use your AI tool. Open [http://localhost:8000](http://localhost:8000) (admin / Admin1234!) and search:
+
+```
+sourcetype="chron:event"
+```
+
+Events appear in real time as you have AI conversations.
+
+> Note: The default Docker image auto-creates a HEC token with the value you set in `SPLUNK_HEC_TOKEN`. If events aren't arriving, verify HEC is enabled under **Settings → Data Inputs → HTTP Event Collector**.
+
+---
+
+## Production setup — Splunk Enterprise or Cloud
+
+### Step 1 — Enable HTTP Event Collector
+
+**Splunk Enterprise:** Settings → Data Inputs → HTTP Event Collector → Global Settings → Enable
+
+**Splunk Cloud:** Settings → Data Inputs → HTTP Event Collector → New Token
+
+### Step 2 — Create a HEC token
+
+1. Settings → Data Inputs → HTTP Event Collector → New Token
+2. Name: `chron-ingest`
+3. Source type: `chron:event` (create new if prompted)
+4. Index: `main` (or a dedicated `chron` index)
+5. Copy the token value
+
+### Step 3 — Connect from the developer machine
+
+```bash
+chron connect splunk
+```
+
+Enter the HEC base URL and token when prompted. The command sends a test event and confirms before saving.
+
+### Step 4 — Add env vars to your MCP client
+
+The `connect` command prints the exact block to paste. For Claude Code, add to the `chron` entry in `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "chron": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/dist/index.js"],
+      "env": {
+        "CHRON_SPLUNK_URL": "https://your-splunk-host:8088",
+        "CHRON_SPLUNK_TOKEN": "<your-hec-token>"
+      }
+    }
+  }
+}
+```
+
+### Step 5 — Run SPL queries
+
+In Splunk → Search & Reporting, run queries from this directory:
+
+| File | Use |
+|---|---|
+| `events-by-type.spl` | Time-series — event volume by type |
+| `sessions-by-developer.spl` | Table — sessions per host and AI tool |
+| `secrets-detected.spl` | Table — credential exposures for SOC review |
+| `ai-tool-usage.spl` | Summary — tool adoption breakdown |
+| `daily-active-developers.spl` | Time-series — distinct active machines per day |
+| `secrets-alert.spl` | Alert search — credential exposures (last 1h) |
+
+### Step 6 — Set up the credential alert (recommended)
+
+1. Search & Reporting → paste `secrets-alert.spl` → Save As → Alert
+2. Schedule: Run every hour
+3. Trigger: Number of results is greater than 0
+4. Action: Send email or create a notable event
+
+---
+
+## Event schema
+
+All events arrive with `sourcetype=chron:event` and these fields:
+
+| Field | Present on |
+|---|---|
+| `host` | All events: developer's machine hostname |
+| `source` | All events: `chron-mcp` |
+| `event_type` | All: `session_started`, `message_logged`, `secret_detected` |
+| `session_id_prefix` | All events |
+| `ai_tool` | All events: `claude`, `cursor`, `windsurf`, etc. |
+| `os` | All events: `darwin`, `linux`, `win32` |
+| `chron_version` | All events |
+| `role` | `message_logged` only: `user` or `assistant` |
+| `detection_type` | `secret_detected` only: `api_key`, `aws_key`, `jwt`, etc. |
+| `masked_value` | `secret_detected` only: e.g. `AKIA****F3K2` |
+
+**What is never transmitted:** message content, actual secret values, file paths, or any user-typed text.
+
+## Env vars
+
+| Env var | Description |
+|---|---|
+| `CHRON_SPLUNK_URL` | Splunk HEC base URL, e.g. `https://localhost:8088` or `https://your-host:8088` |
+| `CHRON_SPLUNK_TOKEN` | HEC ingest token |
+| `CHRON_SPLUNK_INSECURE` | Set to `1` to skip TLS certificate verification (local Docker with self-signed cert) |
+
+`CHRON_SPLUNK_URL` and `CHRON_SPLUNK_TOKEN` must both be set for events to flow. If unset, the integration is silently disabled.

package/dashboards/splunk/ai-tool-usage.spl

@@ -0,0 +1,3 @@
+sourcetype="chron:event" event_type="session_started" earliest=-30d
+| stats count AS Sessions BY ai_tool
+| sort -Sessions

package/dashboards/splunk/daily-active-developers.spl

@@ -0,0 +1,2 @@
+sourcetype="chron:event" event_type="session_started" earliest=-30d
+| timechart span=1d dc(host) AS ActiveDevelopers

package/dashboards/splunk/events-by-type.spl

@@ -0,0 +1,2 @@
+| tstats count WHERE index=* sourcetype="chron:event" BY event_type _time span=1d
+| timechart span=1d count BY event_type

package/dashboards/splunk/secrets-alert.spl

@@ -0,0 +1,3 @@
+sourcetype="chron:event" event_type="secret_detected" earliest=-1h
+| where detection_type IN ("api_key","aws_key","gcp_key","azure_key","private_key","jwt")
+| table _time, host, ai_tool, detection_type, masked_value, session_id_prefix

package/dashboards/splunk/secrets-detected.spl

@@ -0,0 +1,4 @@
+sourcetype="chron:event" event_type="secret_detected" earliest=-30d
+| where detection_type IN ("api_key","aws_key","gcp_key","azure_key","private_key","jwt")
+| table _time, host, ai_tool, detection_type, masked_value, session_id_prefix
+| sort -_time

package/dashboards/splunk/sessions-by-developer.spl

@@ -0,0 +1,3 @@
+sourcetype="chron:event" event_type="session_started" earliest=-30d
+| stats count AS Sessions BY host, ai_tool
+| sort -Sessions