Skip to content

Commit f4f5f05

Browse files
stacknilstacknil
committed
docs: add config-change reviewer pack
1 parent 2f76913 commit f4f5f05

7 files changed

Lines changed: 215 additions & 0 deletions

File tree

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ python -m telemetry_window_demo.cli run-config-change-demo
2626

2727
Generated artifacts are written to `demos/config-change-investigation-demo/artifacts/`.
2828

29+
For offline review without running the demo, see [`docs/config-change-investigation-reviewer-pack.md`](../../docs/config-change-investigation-reviewer-pack.md).
30+
2931
## Demo Inputs
3032

3133
- config changes: `data/raw/config_changes.jsonl`

‎docs/config-change-investigation-reviewer-pack.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
# Config-Change Investigation Reviewer Pack
2+
3+
This page describes the small, sanitized reviewer pack for `config-change-investigation-demo`.
4+
5+
Pack directory:
6+
7+
- `docs/reviewer-pack-v0.6.0/`
8+
9+
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.
10+
11+
## Pack Contents
12+
13+
| File | Path | What It Proves |
14+
| --- | --- | --- |
15+
| `MANIFEST.md` | artifact index | The pack scope, source type, and intended reviewer use |
16+
| `benign-change-example.json` | benign change with no investigation | A benign config change remains visible in normalized input but does not become an investigation |
17+
| `risky-change-with-evidence-example.json` | risky change with nearby evidence | A risky config change becomes an investigation and carries bounded supporting evidence |
18+
| `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 |
19+
| `investigation-summary-example.json` | reduced summary path | The reduced summary stays deterministic and preserves the same evidence counts and bounded-correlation explanation |
20+
21+
## Benign Change With No Investigation
22+
23+
Relevant file:
24+
25+
- `docs/reviewer-pack-v0.6.0/benign-change-example.json`
26+
27+
Inspect:
28+
29+
- `change_event.config_key`
30+
- `change_event.new_value`
31+
- `reviewer_expectation.appears_in`
32+
- `reviewer_expectation.not_expected_in`
33+
34+
Reviewer conclusion:
35+
36+
- 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`.
37+
38+
## Risky Change With Nearby Evidence
39+
40+
Relevant files:
41+
42+
- `docs/reviewer-pack-v0.6.0/risky-change-with-evidence-example.json`
43+
- `docs/reviewer-pack-v0.6.0/investigation-summary-example.json`
44+
45+
Inspect:
46+
47+
- `investigation.rule_id`
48+
- `investigation.correlation_window_minutes`
49+
- `investigation.evidence_counts`
50+
- `investigation.attached_policy_denials`
51+
- `investigation.attached_follow_on_events`
52+
- `summary_record.summary`
53+
54+
Reviewer conclusion:
55+
56+
- 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.
57+
58+
## Risky Change With Bounded Case But No Nearby Evidence
59+
60+
Relevant files:
61+
62+
- `docs/reviewer-pack-v0.6.0/bounded-case-no-evidence-example.json`
63+
- `docs/reviewer-pack-v0.6.0/investigation-summary-example.json`
64+
65+
Inspect:
66+
67+
- `investigation.evidence_counts`
68+
- `investigation.attached_policy_denials`
69+
- `investigation.attached_follow_on_events`
70+
- `investigation.bounded_correlation_reason`
71+
72+
Reviewer conclusion:
73+
74+
- 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.

‎docs/reviewer-pack-v0.6.0/MANIFEST.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# v0.6.0 Reviewer Pack Manifest
2+
3+
This pack is a small, sanitized reviewer artifact set for `config-change-investigation-demo`.
4+
5+
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.
6+
7+
| File | Path Proven | Source Type | What It Proves |
8+
| --- | --- | --- | --- |
9+
| `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 |
10+
| `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 |
11+
| `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 |
12+
| `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 |

‎docs/reviewer-pack-v0.6.0/benign-change-example.json‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
{
2+
"artifact_kind": "benign_change_example",
3+
"source_note": "Representative sanitized example aligned with the demo's synthetic sample semantics. Non-production.",
4+
"maps_to_artifact": "change_events_normalized.json",
5+
"reviewer_expectation": {
6+
"appears_in": [
7+
"change_events_normalized.json"
8+
],
9+
"not_expected_in": [
10+
"investigation_hits.json",
11+
"investigation_summary.json",
12+
"investigation_report.md"
13+
]
14+
},
15+
"change_event": {
16+
"change_id": "cfg-003",
17+
"timestamp": "2026-03-22T09:40:00Z",
18+
"actor": "deploy-automation",
19+
"target_system": "payments-api",
20+
"config_key": "log_level",
21+
"old_value": "info",
22+
"new_value": "debug",
23+
"change_result": "success",
24+
"change_ticket": "CHG-1003"
25+
}
26+
}

‎docs/reviewer-pack-v0.6.0/bounded-case-no-evidence-example.json‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
{
2+
"artifact_kind": "bounded_case_no_evidence_example",
3+
"source_note": "Representative sanitized example aligned with committed artifact semantics. Non-production.",
4+
"maps_to_artifacts": [
5+
"investigation_hits.json",
6+
"investigation_summary.json",
7+
"investigation_report.md"
8+
],
9+
"reviewer_expectation": "The risky change remains explicit as an investigation even though bounded correlation found zero nearby evidence records.",
10+
"investigation": {
11+
"investigation_id": "CCI-003",
12+
"severity": "high",
13+
"rule_id": "cfg_break_glass_mode",
14+
"target_system": "vault-gateway",
15+
"actor": "sre-admin",
16+
"triggering_change": {
17+
"change_id": "cfg-004",
18+
"timestamp": "2026-03-22T10:00:00Z",
19+
"config_key": "break_glass_mode",
20+
"old_value": "disabled",
21+
"new_value": "enabled"
22+
},
23+
"trigger_reason": "Break-glass mode was enabled on a sensitive service.",
24+
"correlation_window_minutes": 15,
25+
"bounded_correlation_reason": "Attached evidence shares target_system 'vault-gateway' and falls within 15 minutes after the triggering change.",
26+
"evidence_counts": {
27+
"policy_denials": 0,
28+
"follow_on_events": 0
29+
},
30+
"attached_policy_denials": [],
31+
"attached_follow_on_events": []
32+
}
33+
}

‎docs/reviewer-pack-v0.6.0/investigation-summary-example.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"artifact_kind": "investigation_summary_example",
3+
"source_note": "Representative sanitized example aligned with committed artifact semantics. Non-production.",
4+
"maps_to_artifact": "investigation_summary.json",
5+
"summary_record": {
6+
"investigation_id": "CCI-001",
7+
"severity": "critical",
8+
"target_system": "identity-proxy",
9+
"triggering_change_id": "cfg-001",
10+
"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.",
11+
"evidence_counts": {
12+
"policy_denials": 2,
13+
"follow_on_events": 2
14+
},
15+
"bounded_correlation_reason": "Attached evidence shares target_system 'identity-proxy' and falls within 15 minutes after the triggering change."
16+
}
17+
}

‎docs/reviewer-pack-v0.6.0/risky-change-with-evidence-example.json‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
{
2+
"artifact_kind": "risky_change_with_evidence_example",
3+
"source_note": "Representative sanitized example aligned with committed artifact semantics. Non-production.",
4+
"maps_to_artifacts": [
5+
"investigation_hits.json",
6+
"investigation_report.md"
7+
],
8+
"investigation": {
9+
"investigation_id": "CCI-001",
10+
"severity": "critical",
11+
"rule_id": "cfg_disable_admin_mfa",
12+
"target_system": "identity-proxy",
13+
"actor": "admin-operator",
14+
"triggering_change": {
15+
"change_id": "cfg-001",
16+
"timestamp": "2026-03-22T09:00:00Z",
17+
"config_key": "disable_admin_mfa",
18+
"old_value": "false",
19+
"new_value": "true"
20+
},
21+
"trigger_reason": "Admin MFA was disabled on a protected system.",
22+
"correlation_window_minutes": 15,
23+
"bounded_correlation_reason": "Attached evidence shares target_system 'identity-proxy' and falls within 15 minutes after the triggering change.",
24+
"evidence_counts": {
25+
"policy_denials": 2,
26+
"follow_on_events": 2
27+
},
28+
"attached_policy_denials": [
29+
{
30+
"denial_id": "den-001",
31+
"policy_name": "admin-login-guard",
32+
"decision": "denied"
33+
},
34+
{
35+
"denial_id": "den-002",
36+
"policy_name": "token-exchange-guard",
37+
"decision": "denied"
38+
}
39+
],
40+
"attached_follow_on_events": [
41+
{
42+
"event_id": "fo-001",
43+
"event_type": "auth_fail_burst"
44+
},
45+
{
46+
"event_id": "fo-002",
47+
"event_type": "service_restart"
48+
}
49+
]
50+
}
51+
}

0 commit comments

Comments
 (0)