diff --git a/demos/config-change-investigation-demo/README.md b/demos/config-change-investigation-demo/README.md index e1c9bc6..ed2ba4f 100644 --- a/demos/config-change-investigation-demo/README.md +++ b/demos/config-change-investigation-demo/README.md @@ -26,6 +26,8 @@ python -m telemetry_window_demo.cli run-config-change-demo Generated artifacts are written to `demos/config-change-investigation-demo/artifacts/`. +For offline review without running the demo, see [`docs/config-change-investigation-reviewer-pack.md`](../../docs/config-change-investigation-reviewer-pack.md). + ## Demo Inputs - config changes: `data/raw/config_changes.jsonl` diff --git a/docs/config-change-investigation-reviewer-pack.md b/docs/config-change-investigation-reviewer-pack.md new file mode 100644 index 0000000..e2a7b72 --- /dev/null +++ b/docs/config-change-investigation-reviewer-pack.md @@ -0,0 +1,74 @@ +# Config-Change Investigation Reviewer Pack + +This page describes the small, sanitized reviewer pack for `config-change-investigation-demo`. + +Pack directory: + +- `docs/reviewer-pack-v0.6.0/` + +The pack is suitable for release attachment or offline review. All examples are representative sanitized examples aligned with the demo's synthetic sample semantics. They are non-production artifacts and do not contain secrets, machine-specific paths, or deployment claims. + +## Pack Contents + +| File | Path | What It Proves | +| --- | --- | --- | +| `MANIFEST.md` | artifact index | The pack scope, source type, and intended reviewer use | +| `benign-change-example.json` | benign change with no investigation | A benign config change remains visible in normalized input but does not become an investigation | +| `risky-change-with-evidence-example.json` | risky change with nearby evidence | A risky config change becomes an investigation and carries bounded supporting evidence | +| `bounded-case-no-evidence-example.json` | risky change with bounded case but no nearby evidence | A risky config change still produces an explicit investigation even when bounded correlation finds zero nearby evidence | +| `investigation-summary-example.json` | reduced summary path | The reduced summary stays deterministic and preserves the same evidence counts and bounded-correlation explanation | + +## Benign Change With No Investigation + +Relevant file: + +- `docs/reviewer-pack-v0.6.0/benign-change-example.json` + +Inspect: + +- `change_event.config_key` +- `change_event.new_value` +- `reviewer_expectation.appears_in` +- `reviewer_expectation.not_expected_in` + +Reviewer conclusion: + +- A benign change is kept in normalized input context, but it does not match a risky-change rule and should not appear in `investigation_hits.json` or `investigation_summary.json`. + +## Risky Change With Nearby Evidence + +Relevant files: + +- `docs/reviewer-pack-v0.6.0/risky-change-with-evidence-example.json` +- `docs/reviewer-pack-v0.6.0/investigation-summary-example.json` + +Inspect: + +- `investigation.rule_id` +- `investigation.correlation_window_minutes` +- `investigation.evidence_counts` +- `investigation.attached_policy_denials` +- `investigation.attached_follow_on_events` +- `summary_record.summary` + +Reviewer conclusion: + +- A deterministic risky-change rule creates an investigation, and bounded correlation attaches only nearby evidence that shares the same `target_system` and falls inside the configured window. + +## Risky Change With Bounded Case But No Nearby Evidence + +Relevant files: + +- `docs/reviewer-pack-v0.6.0/bounded-case-no-evidence-example.json` +- `docs/reviewer-pack-v0.6.0/investigation-summary-example.json` + +Inspect: + +- `investigation.evidence_counts` +- `investigation.attached_policy_denials` +- `investigation.attached_follow_on_events` +- `investigation.bounded_correlation_reason` + +Reviewer conclusion: + +- A risky change stays explicit as an investigation even when bounded correlation finds zero nearby denials or follow-on events. The demo does not silently discard this case. diff --git a/docs/reviewer-pack-v0.6.0/MANIFEST.md b/docs/reviewer-pack-v0.6.0/MANIFEST.md new file mode 100644 index 0000000..81cdd56 --- /dev/null +++ b/docs/reviewer-pack-v0.6.0/MANIFEST.md @@ -0,0 +1,12 @@ +# v0.6.0 Reviewer Pack Manifest + +This pack is a small, sanitized reviewer artifact set for `config-change-investigation-demo`. + +It is intended for release attachment or offline review. The files are portable, contain no secrets or machine-specific paths, and are representative non-production examples aligned with the demo's public portfolio story. + +| File | Path Proven | Source Type | What It Proves | +| --- | --- | --- | --- | +| `benign-change-example.json` | benign change with no investigation | representative sanitized example aligned with committed sample semantics | A benign config change remains normalized input and does not become an investigation | +| `risky-change-with-evidence-example.json` | risky change with nearby evidence | representative sanitized example aligned with committed artifact semantics | A risky config change becomes an explicit investigation with bounded supporting evidence | +| `bounded-case-no-evidence-example.json` | risky change with bounded case but no nearby evidence | representative sanitized example aligned with committed artifact semantics | A risky config change still produces a visible investigation even when bounded correlation finds zero nearby evidence | +| `investigation-summary-example.json` | reduced summary path | representative sanitized example aligned with committed artifact semantics | The reduced summary preserves deterministic counts and the same bounded-correlation explanation | diff --git a/docs/reviewer-pack-v0.6.0/benign-change-example.json b/docs/reviewer-pack-v0.6.0/benign-change-example.json new file mode 100644 index 0000000..8849050 --- /dev/null +++ b/docs/reviewer-pack-v0.6.0/benign-change-example.json @@ -0,0 +1,26 @@ +{ + "artifact_kind": "benign_change_example", + "source_note": "Representative sanitized example aligned with the demo's synthetic sample semantics. Non-production.", + "maps_to_artifact": "change_events_normalized.json", + "reviewer_expectation": { + "appears_in": [ + "change_events_normalized.json" + ], + "not_expected_in": [ + "investigation_hits.json", + "investigation_summary.json", + "investigation_report.md" + ] + }, + "change_event": { + "change_id": "cfg-003", + "timestamp": "2026-03-22T09:40:00Z", + "actor": "deploy-automation", + "target_system": "payments-api", + "config_key": "log_level", + "old_value": "info", + "new_value": "debug", + "change_result": "success", + "change_ticket": "CHG-1003" + } +} diff --git a/docs/reviewer-pack-v0.6.0/bounded-case-no-evidence-example.json b/docs/reviewer-pack-v0.6.0/bounded-case-no-evidence-example.json new file mode 100644 index 0000000..41e97c0 --- /dev/null +++ b/docs/reviewer-pack-v0.6.0/bounded-case-no-evidence-example.json @@ -0,0 +1,33 @@ +{ + "artifact_kind": "bounded_case_no_evidence_example", + "source_note": "Representative sanitized example aligned with committed artifact semantics. Non-production.", + "maps_to_artifacts": [ + "investigation_hits.json", + "investigation_summary.json", + "investigation_report.md" + ], + "reviewer_expectation": "The risky change remains explicit as an investigation even though bounded correlation found zero nearby evidence records.", + "investigation": { + "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", + "config_key": "break_glass_mode", + "old_value": "disabled", + "new_value": "enabled" + }, + "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.", + "evidence_counts": { + "policy_denials": 0, + "follow_on_events": 0 + }, + "attached_policy_denials": [], + "attached_follow_on_events": [] + } +} diff --git a/docs/reviewer-pack-v0.6.0/investigation-summary-example.json b/docs/reviewer-pack-v0.6.0/investigation-summary-example.json new file mode 100644 index 0000000..5507f8a --- /dev/null +++ b/docs/reviewer-pack-v0.6.0/investigation-summary-example.json @@ -0,0 +1,17 @@ +{ + "artifact_kind": "investigation_summary_example", + "source_note": "Representative sanitized example aligned with committed artifact semantics. Non-production.", + "maps_to_artifact": "investigation_summary.json", + "summary_record": { + "investigation_id": "CCI-001", + "severity": "critical", + "target_system": "identity-proxy", + "triggering_change_id": "cfg-001", + "summary": "disable_admin_mfa changed from false to true on identity-proxy, followed by 2 policy denials and 2 follow-on events within 15 minutes.", + "evidence_counts": { + "policy_denials": 2, + "follow_on_events": 2 + }, + "bounded_correlation_reason": "Attached evidence shares target_system 'identity-proxy' and falls within 15 minutes after the triggering change." + } +} diff --git a/docs/reviewer-pack-v0.6.0/risky-change-with-evidence-example.json b/docs/reviewer-pack-v0.6.0/risky-change-with-evidence-example.json new file mode 100644 index 0000000..7c0a2c9 --- /dev/null +++ b/docs/reviewer-pack-v0.6.0/risky-change-with-evidence-example.json @@ -0,0 +1,51 @@ +{ + "artifact_kind": "risky_change_with_evidence_example", + "source_note": "Representative sanitized example aligned with committed artifact semantics. Non-production.", + "maps_to_artifacts": [ + "investigation_hits.json", + "investigation_report.md" + ], + "investigation": { + "investigation_id": "CCI-001", + "severity": "critical", + "rule_id": "cfg_disable_admin_mfa", + "target_system": "identity-proxy", + "actor": "admin-operator", + "triggering_change": { + "change_id": "cfg-001", + "timestamp": "2026-03-22T09:00:00Z", + "config_key": "disable_admin_mfa", + "old_value": "false", + "new_value": "true" + }, + "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.", + "evidence_counts": { + "policy_denials": 2, + "follow_on_events": 2 + }, + "attached_policy_denials": [ + { + "denial_id": "den-001", + "policy_name": "admin-login-guard", + "decision": "denied" + }, + { + "denial_id": "den-002", + "policy_name": "token-exchange-guard", + "decision": "denied" + } + ], + "attached_follow_on_events": [ + { + "event_id": "fo-001", + "event_type": "auth_fail_burst" + }, + { + "event_id": "fo-002", + "event_type": "service_restart" + } + ] + } +}