chron-mcp 0.1.24 → 0.1.26

package/README.md

@@ -1,10 +1,10 @@
 <div align="center">
   <img src="assets/chron-icon-png-transperent.png" alt="Chron" width="96" />
   <h1>Chron</h1>
-  <p>A timestamped audit trail for every AI conversation — stored locally, owned by you.</p>
+  <p>Local-first, tamper-evident audit trails for AI conversations, tool calls, code changes, and secrets.</p>
 </div>
 
-AI tools show when you sent a message. Chron logs when the AI responded too — and keeps a permanent, queryable record of every exchange across every tool you use.
+AI tools show when you sent a message. Chron logs when the AI responded too — and keeps a permanent, queryable, tamper-evident record of the AI work happening across your tools.
 
 Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible AI tool.
 
@@ -16,9 +16,29 @@ AI tools produce no audit trail by default. You cannot answer:
 - What did the AI say, and when exactly?
 - How long did the AI take to respond?
 - What was the full conversation that produced this output?
+- Which tool calls, command results, and code diffs happened during the session?
+- Did a secret or credential get pasted into an AI prompt?
+- Has this audit record been edited after the fact?
 - What did I ask Claude last week about this codebase?
 
-Chron fixes that. Every exchange is logged with a precise local datetime (including timezone offset) to a SQLite file you own. No cloud, no vendor lock-in, no data leaving your machine.
+Chron fixes that. Every exchange is logged with a precise local datetime (including timezone offset) to a SQLite file you own. It can hash-chain every event, sign sessions with Ed25519, detect secrets/PII, produce SOC 2 evidence, and stream metadata-only events to your SIEM. No cloud, no vendor lock-in, no message content leaving your machine.
+
+---
+
+## What Chron captures
+
+Chron stores a local audit trail of:
+
+- User and assistant messages
+- Tool calls and tool results
+- Code changes with file path, operation, and unified diff
+- Session start/resume metadata, including parent session and external refs
+- Secret/PII detections with masked values
+- Hash-chain integrity data
+- Optional Ed25519 session signatures
+- Optional NTP clock attestation metadata
+
+Chron's SIEM integrations send only metadata: session starts, role-only message events, and masked secret detections. Message content and raw secret values stay local.
 
 ---
 
@@ -49,6 +69,18 @@ npm install -g chron-mcp
 
 First run creates `~/.chron/chron.db` automatically. No database setup, no env vars, no migrations.
 
+Check your setup:
+
+```bash
+chron doctor
+```
+
+For CI or automation:
+
+```bash
+chron doctor --json
+```
+
 ---
 
 ## CLI
@@ -65,18 +97,61 @@ Commands:
   secrets         List detected secrets across sessions
   settings        View current configuration
   connect         Connect to a SIEM integration (crowdstrike, sentinel, splunk)
+  summary         Structured summary of a session (timeline, mutations, secrets)
+  sign            Sign a session with its Ed25519 key — produces a .chron.sig file
+  verify          Verify a session's hash chain and Ed25519 signature
+  prune           Delete sessions older than a retention cutoff
+  doctor          Check your Chron setup — Node version, DB, MCP configs, SIEM
+  import          Import conversations from external AI tools into Chron
 
 Options (history):
   --limit=<n>     Max sessions to show (default: 20)
+  --ref=<value>   Filter by external_ref prefix (e.g. --ref=jira:ENG-123)
   <id-prefix>     Show full log for the session with this ID prefix
 
 Options (report):
-  --since=<range> Filter by date: 7d, 30d, or YYYY-MM-DD (default: all time)
-
-Options (export / secrets):
-  <id-prefix>     Scope to a single session
+  --since=<range>   Filter by date: 7d, 30d, or YYYY-MM-DD (default: all time)
+  --format=soc2     Generate SOC 2 HTML evidence package
+  --output=<file>   Output file for --format=soc2
+
+Options (export):
+  <id-prefix>       Markdown export for a single session
+  --signed          Tamper-evident bundle (JSONL + manifest + Ed25519 sig)
+  --session=<id>    Filter bundle to a single session
+  --since=<range>   Filter bundle by date: 7d, 30d, or YYYY-MM-DD
+  --output=<file>   Output path (default: bundle.chron.tar.gz)
+
+Options (verify):
+  <id-prefix>       Verify a session's hash chain + Ed25519 signature
+  --bundle=<file>   Verify a signed bundle offline (no DB needed)
+
+Options (prune):
+  --older-than=<n>d  Cutoff in days (falls back to retention_days in config)
+  --dry-run          Show what would be deleted without deleting
+  --confirm          Required flag to actually delete
+
+Options (doctor):
+  --json             Machine-readable JSON output
+
+Options (import):
+  chatgpt <file>     Import from ChatGPT export (.zip or conversations.json)
 ```
 
+### `chron doctor`
+
+`chron doctor` validates the pieces that make Chron useful in real life:
+
+- Node.js version (v18+ required)
+- Local Chron version vs npm latest
+- `npx chron-mcp --version`
+- DB directory and key directory write access
+- Claude Desktop, Claude Code, Cursor, and Windsurf MCP config presence
+- Whether Chron is configured in each MCP client
+- Optional HTTP mode health check on `/health`
+- Splunk, Sentinel, and LogScale configuration via env vars or `~/.chron/config.json`
+
+Warnings for optional integrations do not fail the command. Real failures exit with code `1`.
+
 ---
 
 ## What it logs
@@ -186,21 +261,26 @@ Chron ships with `skills/chron.skill.md` — a plain-text instruction file that
 | `init_session` | Initialize or resume a session — returns session_id, message count, and recent messages in one call |
 | `start_session` | Create a new named audit session (legacy — prefer `init_session`) |
 | `log_message` | Record a single message with the current local datetime |
+| `log_tool_call` | Record an AI tool invocation as an audit event |
+| `log_tool_result` | Record tool output and link it to a tool call |
+| `log_code_change` | Record a file edit with operation and unified diff |
 | `log_exchange` | Log a user/assistant pair atomically (for batch imports) |
 | `list_sessions` | List all sessions ordered by most recently active |
 | `get_session_history` | Retrieve the full timestamped log for a session |
 | `verify_session` | Verify the tamper-evident hash chain — detects any post-log edits |
 | `scan_prompt` | Scan text for secrets (API keys, credentials) before logging — returns masked detections |
 | `rehydrate_response` | Restore redacted placeholders in an assistant response back to their original values |
+| `delete_session` | Delete a session and cascade its messages/secrets |
+| `summarize_session` | Return a timeline summary with latency, mutations, secrets, and prod references |
 
 ---
 
-## Tamper-evident hash chaining
+## Integrity and signing
 
-Every message is linked to the previous one via a SHA-256 chain:
+Every new audit event is linked to the previous one via a SHA-256 chain:
 
 ```
-content_hash = SHA256(session_id | role | content | created_at | prev_hash)
+content_hash = SHA256(session_id | role | content | created_at | prev_hash | event_type)
 ```
 
 `verify_session` walks the chain and returns:
@@ -209,6 +289,58 @@ content_hash = SHA256(session_id | role | content | created_at | prev_hash)
 
 This turns your local log into a verifiable audit artifact. Any edit to a stored message — content, timestamp, or role — breaks the chain and is detected immediately.
 
+Chron also generates an Ed25519 keypair per new session when possible. The private key stays under `~/.chron/keys`. Use:
+
+```bash
+chron sign <session-id-prefix>
+chron verify <session-id-prefix>
+```
+
+For portable evidence:
+
+```bash
+chron export --signed --session=<session-id-prefix> --output=evidence.chron.tar.gz
+chron verify --bundle=evidence.chron.tar.gz
+```
+
+`chron verify` also reports NTP clock attestation metadata for sessions created with clock-check support.
+
+---
+
+## Secrets and PII detection
+
+Chron can detect and mask:
+
+- API keys: OpenAI, Anthropic, AWS, Google, GitHub, Slack, Stripe, SendGrid, HuggingFace
+- Private keys, JWTs, URL credentials, password assignments, env-style secrets
+- Credit cards, IBANs, SSNs, DOBs, passports
+- Email addresses, US/E.164 phone numbers, internal RFC-1918 IPs
+
+Use:
+
+```bash
+chron secrets
+chron secrets <session-id-prefix>
+```
+
+MCP tools can also call `scan_prompt` before sending content to an AI tool. Redaction uses `$CHRON_*` placeholders and `rehydrate_response` can restore values from the returned token map.
+
+---
+
+## Reports and evidence
+
+```bash
+chron history
+chron summary <session-id-prefix>
+chron report --since=30d
+chron report --format=soc2 --output=soc2-report.html
+chron export <session-id-prefix>
+chron export --signed --since=30d --output=bundle.chron.tar.gz
+chron prune --older-than=90d --dry-run
+```
+
+The SOC 2 report and signed bundles are designed for audit review, legal hold, and incident reconstruction without sending conversation content to Chron infrastructure.
+
 ---
 
 ## CrowdStrike LogScale integration
@@ -484,6 +616,7 @@ All six must be set for events to flow. Token refresh is automatic (1-hour Azure
 | `CHRON_SENTINEL_STREAM` | _(none)_ | Stream name (e.g. `Custom-ChronEvents_CL`) |
 | `CHRON_SPLUNK_URL` | _(none)_ | Splunk HEC base URL (enables Splunk integration) |
 | `CHRON_SPLUNK_TOKEN` | _(none)_ | Splunk HEC ingest token |
+| `CHRON_SPLUNK_INSECURE` | _(none)_ | Set to `1` to skip TLS verification for local Splunk/self-signed certs |
 | `CHRON_RELAY_URL` | _(none)_ | Generic relay endpoint (any SIEM or webhook) |
 | `CHRON_RELAY_TOKEN` | _(none)_ | Bearer token for generic relay |
 
@@ -514,6 +647,34 @@ Point your MCP config at the URL:
 
 ---
 
+## ChatGPT import
+
+Bring your existing ChatGPT history into Chron's tamper-evident audit trail.
+
+```bash
+# From a ChatGPT data export ZIP
+chron import chatgpt ~/Downloads/chatgpt-export.zip
+
+# Or from an extracted conversations.json
+chron import chatgpt ~/Downloads/conversations.json
+```
+
+**How to get your ChatGPT export:**
+ChatGPT → Settings → Data Controls → Export data → wait for email → download the ZIP.
+
+**What gets imported:**
+- One Chron session per conversation, with `ai_tool=chatgpt`
+- Original message timestamps from the export
+- `external_ref=chatgpt:<conversation_id>` on every session (visible in `chron history`)
+- Full SHA-256 hash chain across all imported messages
+- Secret detection runs on all user messages
+
+**Re-running is safe** — already-imported conversations are skipped by `external_ref` match.
+
+After import, sessions appear in `chron history` and `chron verify` works on them the same as any natively-logged session.
+
+---
+
 ## Your data
 
 Your audit log lives at `~/.chron/chron.db` — a single SQLite file on your machine. Query it directly with any SQLite tool:

package/dashboards/logscale/README.md

@@ -73,7 +73,7 @@ The dashboard includes five widgets:
 - **AI Tool Usage** — breakdown by tool (Claude, Cursor, Windsurf, etc.)
 - **Secrets Detected by Type** — credential exposures over time
 - **Sessions by Developer** — per-machine session count with AI tool
-- **Credential Exposures** — full table of api_key, jwt, aws_key detections for SOC review
+- **Credential Exposures** — full table of API keys, tokens, passwords, and private-key detections for SOC review
 
 ## Step 6 — Set up the API key alert (optional)
 
@@ -81,7 +81,7 @@ In LogScale, create a **Scheduled Search** using `api-key-alert.lql`:
 
 ```
 event_type = "secret_detected"
-| detection_type in ["api_key", "aws_key", "gcp_key", "azure_key", "private_key", "jwt"]
+| detection_type in ["private_key", "aws_access_key", "anthropic_api_key", "openai_api_key", "google_api_key", "github_token", "slack_token", "stripe_key", "sendgrid_key", "huggingface_token", "jwt", "url_credentials", "password", "credential_pair"]
 | table([#host, ai_tool, detection_type, masked_value, session_id_prefix, @timestamp])
 ```
 
@@ -104,7 +104,7 @@ All events arrive in LogScale with:
 | `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. |
+| `detection_type` | `secret_detected` only: `openai_api_key`, `aws_access_key`, `github_token`, `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.

package/dashboards/logscale/api-key-alert.lql

@@ -1,5 +1,5 @@
 // Alert: API key or credential sent to AI tool
 // Use as a Scheduled Search alert — notify SOC on any match
 event_type = "secret_detected"
-| detection_type in ["api_key", "aws_key", "gcp_key", "azure_key", "private_key", "jwt"]
+| detection_type in ["private_key", "aws_access_key", "anthropic_api_key", "openai_api_key", "google_api_key", "github_token", "slack_token", "stripe_key", "sendgrid_key", "huggingface_token", "jwt", "url_credentials", "password", "credential_pair"]
 | table([#host, ai_tool, detection_type, masked_value, session_id_prefix, @timestamp])

package/dashboards/logscale/chron-ai-activity.yaml

@@ -62,5 +62,5 @@ widgets:
     height: 4
     query: |
       event_type = "secret_detected"
-      | detection_type in ["api_key", "aws_key", "gcp_key", "azure_key", "private_key", "jwt"]
+      | detection_type in ["private_key", "aws_access_key", "anthropic_api_key", "openai_api_key", "google_api_key", "github_token", "slack_token", "stripe_key", "sendgrid_key", "huggingface_token", "jwt", "url_credentials", "password", "credential_pair"]
       | table([#host, ai_tool, detection_type, masked_value, session_id_prefix, @timestamp])

package/dashboards/sentinel/README.md

@@ -113,7 +113,7 @@ All events arrive in `ChronEvents_CL` with:
 | `ChronVersion` | All events |
 | `Computer` | All events: developer's machine hostname |
 | `Role` | `message_logged` only: `user` or `assistant` |
-| `DetectionType` | `secret_detected` only: `api_key`, `aws_key`, `jwt`, etc. |
+| `DetectionType` | `secret_detected` only: `openai_api_key`, `aws_access_key`, `github_token`, `jwt`, etc. |
 | `MaskedValue` | `secret_detected` only: e.g. `AKIA****F3K2` |
 
 **What is never transmitted:** message content, actual secret values, file paths, or any user-typed text.

package/dashboards/sentinel/secrets-alert.kql

@@ -3,5 +3,5 @@
 ChronEvents_CL
 | where TimeGenerated > ago(1h)
 | where EventType == "secret_detected"
-| where DetectionType in ("api_key", "aws_key", "gcp_key", "azure_key", "private_key", "jwt")
+| where DetectionType in ("private_key", "aws_access_key", "anthropic_api_key", "openai_api_key", "google_api_key", "github_token", "slack_token", "stripe_key", "sendgrid_key", "huggingface_token", "jwt", "url_credentials", "password", "credential_pair")
 | project TimeGenerated, Computer, AiTool, DetectionType, MaskedValue, SessionIdPrefix

package/dashboards/sentinel/secrets-detected.kql

@@ -2,6 +2,6 @@
 ChronEvents_CL
 | where TimeGenerated > ago(30d)
 | where EventType == "secret_detected"
-| where DetectionType in ("api_key", "aws_key", "gcp_key", "azure_key", "private_key", "jwt")
+| where DetectionType in ("private_key", "aws_access_key", "anthropic_api_key", "openai_api_key", "google_api_key", "github_token", "slack_token", "stripe_key", "sendgrid_key", "huggingface_token", "jwt", "url_credentials", "password", "credential_pair")
 | project TimeGenerated, Computer, AiTool, DetectionType, MaskedValue, SessionIdPrefix
 | sort by TimeGenerated desc

package/dashboards/splunk/README.md

@@ -122,7 +122,7 @@ All events arrive with `sourcetype=chron:event` and these fields:
 | `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. |
+| `detection_type` | `secret_detected` only: `openai_api_key`, `aws_access_key`, `github_token`, `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.

package/dashboards/splunk/secrets-alert.spl

@@ -1,3 +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")
+| where detection_type IN ("private_key","aws_access_key","anthropic_api_key","openai_api_key","google_api_key","github_token","slack_token","stripe_key","sendgrid_key","huggingface_token","jwt","url_credentials","password","credential_pair")
 | table _time, host, ai_tool, detection_type, masked_value, session_id_prefix

package/dashboards/splunk/secrets-detected.spl

@@ -1,4 +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")
+| where detection_type IN ("private_key","aws_access_key","anthropic_api_key","openai_api_key","google_api_key","github_token","slack_token","stripe_key","sendgrid_key","huggingface_token","jwt","url_credentials","password","credential_pair")
 | table _time, host, ai_tool, detection_type, masked_value, session_id_prefix
 | sort -_time