feat: add config-change-investigation-demo (#24)

Author: stacknil

README.md

@@ -11,16 +11,18 @@ Latest milestone: [v0.5.0 — third demo and three-demo structure](https://githu
 - [telemetry-window-demo](#telemetry-window-demo)
 - [ai-assisted-detection-demo](demos/ai-assisted-detection-demo/README.md)
 - [rule-evaluation-and-dedup-demo](demos/rule-evaluation-and-dedup-demo/README.md)
+- [config-change-investigation-demo](demos/config-change-investigation-demo/README.md)
 
 | Demo | Input | Deterministic core | LLM role | Main artifacts | Guardrails / non-goals |
 | --- | --- | --- | --- | --- | --- |
 | [telemetry-window-demo](#telemetry-window-demo) | JSONL / CSV events | Windows<br>Features<br>Alert thresholds | None | `features.csv`<br>`alerts.csv`<br>`summary.json`<br>3 PNG plots | MVP only<br>No realtime<br>No case management |
 | [ai-assisted-detection-demo](demos/ai-assisted-detection-demo/README.md) | JSONL auth / web / process | Normalize<br>Rules<br>Grouping<br>ATT&CK mapping | JSON-only case drafting | `rule_hits.json`<br>`case_bundles.json`<br>`case_summaries.json`<br>`case_report.md`<br>`audit_traces.jsonl` | Human verification required<br>No autonomous response<br>No final verdict |
 | [rule-evaluation-and-dedup-demo](demos/rule-evaluation-and-dedup-demo/README.md) | JSON raw rule hits | Scope resolution<br>Cooldown grouping<br>Suppression reasoning | None | `rule_hits_before_dedup.json`<br>`rule_hits_after_dedup.json`<br>`dedup_explanations.json`<br>`dedup_report.md` | No realtime<br>No dashboard<br>No AI stage |
+| [config-change-investigation-demo](demos/config-change-investigation-demo/README.md) | JSONL config changes<br>Policy denials<br>Follow-on events | Normalize<br>Risky-change rules<br>Bounded correlation | None | `change_events_normalized.json`<br>`investigation_hits.json`<br>`investigation_summary.json`<br>`investigation_report.md` | No realtime<br>No dashboard<br>No AI stage |
 
 ## What This Repo Is
 
-`telemetry-lab` is a small portfolio repository for telemetry analytics and constrained detection-oriented workflows. It is organized as three local, file-based demos that are reproducible from committed sample data and intentionally scoped for public review rather than production use.
+`telemetry-lab` is a small portfolio repository for telemetry analytics and constrained detection-oriented workflows. It is organized as four local, file-based demos that are reproducible from committed sample data and intentionally scoped for public review rather than production use.
 
 ### telemetry-window-demo
 
@@ -32,7 +34,11 @@ Latest milestone: [v0.5.0 — third demo and three-demo structure](https://githu
 
 ### rule-evaluation-and-dedup-demo
 
-`rule-evaluation-and-dedup-demo` starts from raw rule hits and makes cooldown behavior legible. It shows which hits were kept, which were suppressed, how scope was resolved, and why repeated hits collapsed into fewer retained alerts.
+`rule-evaluation-and-dedup-demo` starts from raw rule hits and makes cooldown behavior legible. It shows which hits were kept, which were suppressed, how scope was resolved, and why repeated hits collapsed into fewer retained alerts.
+
+### config-change-investigation-demo
+
+`config-change-investigation-demo` follows risky configuration changes into bounded follow-on evidence such as policy denials and service signals. It stays deterministic, file-based, and review-oriented, with no added AI stage.
 
 ## Quick Run
 
@@ -44,7 +50,8 @@ python -m telemetry_window_demo.cli run --config configs/default.yaml
 Other demo entrypoints:
 
 - `python -m telemetry_window_demo.cli run-ai-demo`
-- `python -m telemetry_window_demo.cli run-rule-dedup-demo`
+- `python -m telemetry_window_demo.cli run-rule-dedup-demo`
+- `python -m telemetry_window_demo.cli run-config-change-demo`
 
 That command reads `data/raw/sample_events.jsonl` and regenerates:
 
@@ -109,6 +116,7 @@ Cooldown behavior:
 ## Repo Guide
 
 - [`demos/rule-evaluation-and-dedup-demo/README.md`](demos/rule-evaluation-and-dedup-demo/README.md) explains the third demo and links its committed before/after dedup artifacts
+- [`demos/config-change-investigation-demo/README.md`](demos/config-change-investigation-demo/README.md) explains the config-change investigation demo and its committed artifacts
 - [`docs/sample-output.md`](docs/sample-output.md) summarizes the committed sample artifacts
 - [`docs/roadmap.md`](docs/roadmap.md) sketches the next demo directions
 - [`data/processed/summary.json`](data/processed/summary.json) captures the default run in machine-readable form

demos/config-change-investigation-demo/README.md

@@ -0,0 +1,78 @@
+# Config-Change Investigation Demo
+
+This demo is part of `telemetry-lab` and stays intentionally small, local, and reviewer-friendly.
+
+It focuses on deterministic investigation logic for risky configuration changes and nearby evidence. There is no new AI stage in this demo.
+
+## Purpose
+
+The goal is to make one compact config-change investigation path legible from committed sample data.
+
+The demo starts from configuration changes, policy denials, and follow-on telemetry, then:
+
+- normalizes the inputs into shared internal records
+- applies deterministic risky-change rules
+- attaches nearby supporting evidence using bounded time and shared-system correlation
+- writes machine-readable summaries and a short reviewer-facing report
+
+## Quick Start
+
+From the repository root:
+
+```bash
+python -m pip install -e .
+python -m telemetry_window_demo.cli run-config-change-demo
+```
+
+Generated artifacts are written to `demos/config-change-investigation-demo/artifacts/`.
+
+## Demo Inputs
+
+- config changes: `data/raw/config_changes.jsonl`
+- policy denials: `data/raw/policy_denials.jsonl`
+- follow-on events: `data/raw/follow_on_events.jsonl`
+- investigation config: `config/investigation.yaml`
+
+The bundled sample includes:
+
+- one risky MFA-related change with nearby denials and follow-on signals
+- one risky public-bind change with nearby denials and service events
+- one benign config change that should not trigger an investigation
+- one risky break-glass change with no nearby supporting evidence inside the bounded window
+
+## Deterministic Correlation
+
+This demo uses a bounded correlation window after each triggering config change.
+
+Evidence is attached only when:
+
+1. `target_system` matches the triggering change
+2. the evidence timestamp falls within the configured correlation window after the change
+
+## Expected Artifacts
+
+- `artifacts/change_events_normalized.json`
+- `artifacts/investigation_hits.json`
+- `artifacts/investigation_summary.json`
+- `artifacts/investigation_report.md`
+
+## Artifact Semantics
+
+- `change_events_normalized.json`: normalized config changes before any rule match is applied
+- `investigation_hits.json`: full investigation records, including the triggering change and attached evidence
+- `investigation_summary.json`: reduced machine-readable summaries for each investigation
+- `investigation_report.md`: a short reviewer report showing the trigger, evidence counts, and bounded-correlation explanation
+
+## Reviewer Walkthrough
+
+1. Open `change_events_normalized.json` and identify the risky config keys and values.
+2. Open `investigation_hits.json` and verify which changes became investigations and which evidence records were attached.
+3. Open `investigation_summary.json` and confirm the final summaries stay deterministic and bounded.
+4. Open `investigation_report.md` and verify that a risky change with no nearby evidence remains explicit rather than silently discarded.
+
+## Limitations
+
+- synthetic sample data only
+- no realtime ingestion or service deployment
+- bounded correlation by system and time only
+- no model-generated reasoning or autonomous response

demos/config-change-investigation-demo/artifacts/change_events_normalized.json

@@ -0,0 +1,46 @@
+[
+  {
+    "change_id": "cfg-001",
+    "timestamp": "2026-03-22T09:00:00Z",
+    "actor": "ops-admin",
+    "target_system": "identity-proxy",
+    "config_key": "disable_admin_mfa",
+    "old_value": "false",
+    "new_value": "true",
+    "change_result": "success",
+    "change_ticket": "CHG-1001"
+  },
+  {
+    "change_id": "cfg-002",
+    "timestamp": "2026-03-22T09:20:00Z",
+    "actor": "deploy-bot",
+    "target_system": "payments-api",
+    "config_key": "public_bind_cidr",
+    "old_value": "10.20.0.0/24",
+    "new_value": "0.0.0.0/0",
+    "change_result": "success",
+    "change_ticket": "CHG-1002"
+  },
+  {
+    "change_id": "cfg-003",
+    "timestamp": "2026-03-22T09:40:00Z",
+    "actor": "deploy-bot",
+    "target_system": "payments-api",
+    "config_key": "log_level",
+    "old_value": "info",
+    "new_value": "debug",
+    "change_result": "success",
+    "change_ticket": "CHG-1003"
+  },
+  {
+    "change_id": "cfg-004",
+    "timestamp": "2026-03-22T10:00:00Z",
+    "actor": "sre-admin",
+    "target_system": "vault-gateway",
+    "config_key": "break_glass_mode",
+    "old_value": "disabled",
+    "new_value": "enabled",
+    "change_result": "success",
+    "change_ticket": "CHG-1004"
+  }
+]

demos/config-change-investigation-demo/artifacts/investigation_hits.json

@@ -0,0 +1,142 @@
+[
+  {
+    "investigation_id": "CCI-001",
+    "severity": "critical",
+    "rule_id": "cfg_disable_admin_mfa",
+    "target_system": "identity-proxy",
+    "actor": "ops-admin",
+    "triggering_change": {
+      "change_id": "cfg-001",
+      "timestamp": "2026-03-22T09:00:00Z",
+      "actor": "ops-admin",
+      "target_system": "identity-proxy",
+      "config_key": "disable_admin_mfa",
+      "old_value": "false",
+      "new_value": "true",
+      "change_result": "success",
+      "change_ticket": "CHG-1001"
+    },
+    "trigger_reason": "Admin MFA was disabled on a protected system.",
+    "correlation_window_minutes": 15,
+    "bounded_correlation_reason": "Attached evidence shares target_system 'identity-proxy' and falls within 15 minutes after the triggering change.",
+    "attached_policy_denials": [
+      {
+        "denial_id": "den-001",
+        "timestamp": "2026-03-22T09:04:00Z",
+        "actor": "ops-admin",
+        "target_system": "identity-proxy",
+        "policy_name": "admin-login-guard",
+        "decision": "denied",
+        "reason": "MFA policy blocked admin login after configuration drift."
+      },
+      {
+        "denial_id": "den-002",
+        "timestamp": "2026-03-22T09:09:00Z",
+        "actor": "service-account",
+        "target_system": "identity-proxy",
+        "policy_name": "token-exchange-guard",
+        "decision": "denied",
+        "reason": "Token exchange blocked after admin-auth policy divergence."
+      }
+    ],
+    "attached_follow_on_events": [
+      {
+        "event_id": "fo-001",
+        "timestamp": "2026-03-22T09:05:00Z",
+        "target_system": "identity-proxy",
+        "event_type": "auth_fail_burst",
+        "details": "5 privileged login failures from 203.0.113.24 after the config change."
+      },
+      {
+        "event_id": "fo-002",
+        "timestamp": "2026-03-22T09:11:00Z",
+        "target_system": "identity-proxy",
+        "event_type": "service_restart",
+        "details": "identity-proxy restarted after an auth-policy reload."
+      }
+    ],
+    "evidence_counts": {
+      "policy_denials": 2,
+      "follow_on_events": 2
+    }
+  },
+  {
+    "investigation_id": "CCI-002",
+    "severity": "high",
+    "rule_id": "cfg_public_bind_cidr",
+    "target_system": "payments-api",
+    "actor": "deploy-bot",
+    "triggering_change": {
+      "change_id": "cfg-002",
+      "timestamp": "2026-03-22T09:20:00Z",
+      "actor": "deploy-bot",
+      "target_system": "payments-api",
+      "config_key": "public_bind_cidr",
+      "old_value": "10.20.0.0/24",
+      "new_value": "0.0.0.0/0",
+      "change_result": "success",
+      "change_ticket": "CHG-1002"
+    },
+    "trigger_reason": "Public bind CIDR was expanded to all addresses.",
+    "correlation_window_minutes": 15,
+    "bounded_correlation_reason": "Attached evidence shares target_system 'payments-api' and falls within 15 minutes after the triggering change.",
+    "attached_policy_denials": [
+      {
+        "denial_id": "den-003",
+        "timestamp": "2026-03-22T09:23:00Z",
+        "actor": "deploy-bot",
+        "target_system": "payments-api",
+        "policy_name": "public-exposure-guard",
+        "decision": "denied",
+        "reason": "Public bind CIDR exceeded the approved network range."
+      }
+    ],
+    "attached_follow_on_events": [
+      {
+        "event_id": "fo-003",
+        "timestamp": "2026-03-22T09:26:00Z",
+        "target_system": "payments-api",
+        "event_type": "service_restart",
+        "details": "payments-api restarted after listener rebind."
+      },
+      {
+        "event_id": "fo-004",
+        "timestamp": "2026-03-22T09:31:00Z",
+        "target_system": "payments-api",
+        "event_type": "edge_warning",
+        "details": "Edge listener observed requests from the newly public CIDR."
+      }
+    ],
+    "evidence_counts": {
+      "policy_denials": 1,
+      "follow_on_events": 2
+    }
+  },
+  {
+    "investigation_id": "CCI-003",
+    "severity": "high",
+    "rule_id": "cfg_break_glass_mode",
+    "target_system": "vault-gateway",
+    "actor": "sre-admin",
+    "triggering_change": {
+      "change_id": "cfg-004",
+      "timestamp": "2026-03-22T10:00:00Z",
+      "actor": "sre-admin",
+      "target_system": "vault-gateway",
+      "config_key": "break_glass_mode",
+      "old_value": "disabled",
+      "new_value": "enabled",
+      "change_result": "success",
+      "change_ticket": "CHG-1004"
+    },
+    "trigger_reason": "Break-glass mode was enabled on a sensitive service.",
+    "correlation_window_minutes": 15,
+    "bounded_correlation_reason": "Attached evidence shares target_system 'vault-gateway' and falls within 15 minutes after the triggering change.",
+    "attached_policy_denials": [],
+    "attached_follow_on_events": [],
+    "evidence_counts": {
+      "policy_denials": 0,
+      "follow_on_events": 0
+    }
+  }
+]

demos/config-change-investigation-demo/artifacts/investigation_report.md

@@ -0,0 +1,58 @@
+# Config-Change Investigation Demo Report
+
+This deterministic demo correlates risky configuration changes with bounded follow-on evidence.
+It does not use an LLM and does not produce autonomous response actions.
+
+## Run Summary
+
+- normalized_change_events: 4
+- risky_change_hits: 3
+- investigations: 3
+- correlation_window_minutes: 15
+
+## CCI-001
+
+- Severity: critical
+- Target system: identity-proxy
+- Triggering change: cfg-001 (disable_admin_mfa -> true)
+- Trigger reason: Admin MFA was disabled on a protected system.
+- Attached policy denials: 2
+- Attached follow-on events: 2
+- Bounded correlation: Attached evidence shares target_system 'identity-proxy' and falls within 15 minutes after the triggering change.
+
+Policy denials:
+- den-001: admin-login-guard -> MFA policy blocked admin login after configuration drift.
+- den-002: token-exchange-guard -> Token exchange blocked after admin-auth policy divergence.
+
+Follow-on events:
+- fo-001: auth_fail_burst -> 5 privileged login failures from 203.0.113.24 after the config change.
+- fo-002: service_restart -> identity-proxy restarted after an auth-policy reload.
+
+## CCI-002
+
+- Severity: high
+- Target system: payments-api
+- Triggering change: cfg-002 (public_bind_cidr -> 0.0.0.0/0)
+- Trigger reason: Public bind CIDR was expanded to all addresses.
+- Attached policy denials: 1
+- Attached follow-on events: 2
+- Bounded correlation: Attached evidence shares target_system 'payments-api' and falls within 15 minutes after the triggering change.
+
+Policy denials:
+- den-003: public-exposure-guard -> Public bind CIDR exceeded the approved network range.
+
+Follow-on events:
+- fo-003: service_restart -> payments-api restarted after listener rebind.
+- fo-004: edge_warning -> Edge listener observed requests from the newly public CIDR.
+
+## CCI-003
+
+- Severity: high
+- Target system: vault-gateway
+- Triggering change: cfg-004 (break_glass_mode -> enabled)
+- Trigger reason: Break-glass mode was enabled on a sensitive service.
+- Attached policy denials: 0
+- Attached follow-on events: 0
+- Bounded correlation: Attached evidence shares target_system 'vault-gateway' and falls within 15 minutes after the triggering change.
+
+No nearby supporting evidence fell inside the bounded correlation window.