From 1a36b92c8db9fe4dd1df806917a0ef2c5eada2e1 Mon Sep 17 00:00:00 2001 From: stacknil Date: Fri, 19 Jun 2026 19:19:46 +0800 Subject: [PATCH] docs(contract): define bounded correlation --- README.md | 4 ++-- .../README.md | 5 ++++ .../README.md | 3 +++ docs/README.md | 2 +- docs/architecture.md | 1 + docs/reviewer-pack.md | 2 ++ docs/vocabulary.md | 16 +++++++++++++ tests/test_reviewer_docs.py | 24 +++++++++++++++++++ 8 files changed, 54 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3f7703b..edaa16f 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Latest tagged release: [v0.6.0 — fourth demo and config-change investigation]( - [`docs/reviewer-path.md`](docs/reviewer-path.md): choose the right demo by review question - [`docs/reviewer-pack.md`](docs/reviewer-pack.md): demo matrix, artifact contract, and v1 readiness gate - [`docs/evidence-pipeline-contract.md`](docs/evidence-pipeline-contract.md): JSON schema contracts for reviewer-facing evidence artifacts -- [`docs/vocabulary.md`](docs/vocabulary.md): cross-demo vocabulary for events, hits, signals, findings, summaries, reports, and audit traces +- [`docs/vocabulary.md`](docs/vocabulary.md): cross-demo vocabulary for events, hits, signals, bounded correlation, findings, summaries, reports, and audit traces - [`docs/README.md`](docs/README.md): current route, supporting docs, and historical release evidence ## Demos @@ -171,7 +171,7 @@ Cooldown behavior: - [`docs/reviewer-path.md`](docs/reviewer-path.md) maps common review questions to the right demo and artifacts - [`docs/architecture.md`](docs/architecture.md) diagrams the local file-based detection workflow - [`docs/event-time-model.md`](docs/event-time-model.md) defines event, observed, window, and artifact time semantics -- [`docs/vocabulary.md`](docs/vocabulary.md) defines the cross-demo evidence workflow terms +- [`docs/vocabulary.md`](docs/vocabulary.md) defines the cross-demo evidence workflow terms and bounded correlation boundaries - [`docs/sample-output.md`](docs/sample-output.md) summarizes the committed sample artifacts - [`docs/roadmap.md`](docs/roadmap.md) defines the v1 reviewer contract stabilization phase - [`data/processed/summary.json`](data/processed/summary.json) captures the default run in machine-readable form diff --git a/demos/cloud-iam-change-investigation-demo/README.md b/demos/cloud-iam-change-investigation-demo/README.md index a55c925..2a0a5ac 100644 --- a/demos/cloud-iam-change-investigation-demo/README.md +++ b/demos/cloud-iam-change-investigation-demo/README.md @@ -72,6 +72,11 @@ The deterministic rules are: - CloudTrail logging disabled near IAM change - security group ingress opened after identity change +Each rule uses bounded correlation: evidence must fall inside the rule's fixed +time window, match the rule's configured actor or entity scope, and match the +rule-local event family set. The demo does not perform cross-account, +cross-source, or whole-dataset attribution. + ## ATT&CK Mapping The config intentionally keeps the mapping set small: diff --git a/demos/config-change-investigation-demo/README.md b/demos/config-change-investigation-demo/README.md index 0a86235..4286050 100644 --- a/demos/config-change-investigation-demo/README.md +++ b/demos/config-change-investigation-demo/README.md @@ -50,6 +50,9 @@ 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 +3. the evidence family is one of the configured local evidence families for this demo + +It does not perform cross-host, cross-account, or cross-source global attribution. ## Expected Artifacts diff --git a/docs/README.md b/docs/README.md index 8154dbe..448bf92 100644 --- a/docs/README.md +++ b/docs/README.md @@ -8,7 +8,7 @@ This directory separates the current reviewer route from supporting design notes - [`reviewer-path.md`](reviewer-path.md): choose a demo by review question - [`reviewer-brief.md`](reviewer-brief.md): short problem, value, evidence, and boundary summary - [`evidence-pipeline-contract.md`](evidence-pipeline-contract.md): JSON schema contracts for reviewer-facing evidence artifacts -- [`vocabulary.md`](vocabulary.md): cross-demo vocabulary for evidence workflow terms +- [`vocabulary.md`](vocabulary.md): cross-demo vocabulary for evidence workflow terms and bounded correlation - [`architecture.md`](architecture.md): local file-based workflow diagram - [`roadmap.md`](roadmap.md): v1 reviewer contract stabilization phase diff --git a/docs/architecture.md b/docs/architecture.md index 92e7fc4..33e402d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -32,6 +32,7 @@ flowchart TD - Detection decisions stay deterministic and inspectable. - The AI-assisted demo is limited to bounded JSON-only case drafting. +- Bounded correlation stays inside fixed time windows, fixed entity or scope keys, and fixed event families or rule-local family sets. - Artifacts are file-based and suitable for local regeneration or GitHub review. - Artifact names are reviewer-visible contracts during the v1 reviewer contract stabilization phase. - The repository does not provide production monitoring, real-time ingestion, dashboards, alert routing, case management, autonomous response, or final incident verdicts. diff --git a/docs/reviewer-pack.md b/docs/reviewer-pack.md index 79bddc8..c367cfd 100644 --- a/docs/reviewer-pack.md +++ b/docs/reviewer-pack.md @@ -43,6 +43,8 @@ See [`docs/evidence-pipeline-contract.md`](evidence-pipeline-contract.md) for th See [`docs/vocabulary.md`](vocabulary.md) for the cross-demo meaning of `event`, `signal`, `hit`, `finding`, `case_bundle`, `summary`, `report`, and `audit_trace`. +In this repo, bounded correlation means evidence is attached only within fixed time windows, fixed entity or scope keys, and fixed event families or rule-local family sets. It is not cross-host, cross-account, or cross-source global attribution. + The current schema contract covers: - `schemas/rule_hits.schema.json` diff --git a/docs/vocabulary.md b/docs/vocabulary.md index 15e75ba..12d18b7 100644 --- a/docs/vocabulary.md +++ b/docs/vocabulary.md @@ -42,6 +42,22 @@ keeps the repo focused on reproducible evidence generation and review. - Use `report` for human-readable Markdown explanations. - Use `audit_trace` for structured guardrail, validation, and provenance records. +## Bounded Correlation + +`bounded correlation` means the demo may attach supporting evidence only inside +explicitly configured limits: + +- a fixed time window +- a fixed entity or scope key, such as `target_system`, `actor`, `account`, or + resolved cooldown scope +- a fixed event family, or a rule-local configured family set when a rule + intentionally compares more than one event family + +It does not perform global attribution across hosts, accounts, sources, or event +families. It does not infer a shared root cause from unrelated telemetry, search +the whole dataset for plausible context, or promote nearby evidence into a final +incident verdict. + ## Time Semantics Events, hits, signals, summaries, and reports should preserve the time semantics diff --git a/tests/test_reviewer_docs.py b/tests/test_reviewer_docs.py index 4f94d31..1fc57da 100644 --- a/tests/test_reviewer_docs.py +++ b/tests/test_reviewer_docs.py @@ -251,6 +251,11 @@ def test_vocabulary_defines_cross_demo_terms() -> None: assert "local evidence workflow vocabulary" in vocabulary assert "not a SIEM object model" in vocabulary assert "[`docs/event-time-model.md`](event-time-model.md)" in vocabulary + assert "## Bounded Correlation" in vocabulary + assert "fixed time window" in vocabulary + assert "fixed entity or scope key" in vocabulary + assert "fixed event family" in vocabulary + assert "does not perform global attribution across hosts, accounts, sources" in vocabulary for term in [ "event", @@ -273,6 +278,25 @@ def test_vocabulary_defines_cross_demo_terms() -> None: assert "Keep cross-demo vocabulary stable" in roadmap +def test_bounded_correlation_boundaries_are_documented() -> None: + architecture = _read_repo_file("docs/architecture.md") + reviewer_pack = _read_repo_file("docs/reviewer-pack.md") + config_demo = _read_repo_file("demos/config-change-investigation-demo/README.md") + cloud_iam_demo = _read_repo_file( + "demos/cloud-iam-change-investigation-demo/README.md" + ) + + for text in [architecture, reviewer_pack]: + assert "fixed time windows" in text + assert "fixed entity or scope keys" in text + assert "fixed event families or rule-local family sets" in text + + assert "evidence family" in config_demo + assert "cross-host, cross-account, or cross-source global attribution" in config_demo + assert "rule-local event family set" in cloud_iam_demo + assert "whole-dataset attribution" in cloud_iam_demo + + def test_architecture_doc_keeps_local_file_based_boundaries() -> None: architecture = _read_repo_file("docs/architecture.md")