# 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.
