veltro-cli 0.15.7__py3-none-any.whl

veltro_cli/lib/demo_replay.py

@@ -0,0 +1,794 @@
+"""Replay demo datasets through VectorFlow, CHAD, and Warden.
+
+`veltro demo seed --dataset <id>` drives this module. For a `corpus`
+dataset it:
+
+1. resolves the VectorFlow-owned CHAD data source used by the deployed demo
+   pipeline;
+2. maps the Sigma fields the dataset's rule keys on;
+3. creates or reconciles the rule, records the positive-match sample evidence
+   CHAD's deploy floor requires, and deploys it through the normal approval
+   path;
+4. rebases the corpus onto wall-clock time and atomically drops JSONL into the
+   VectorFlow agent's file source;
+5. follows this run's `event.id` prefix through CHAD to the Warden case.
+
+`veltro demo reset` reverses what is reversible and names what is not. It
+removes replay files, undeploys corpus rules, deletes their alerts, and resolves
+then closes their Warden cases. Rule versions and audit rows remain as evidence.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Iterable, Mapping, Sequence
+
+from veltro_cli.lib.datasets import (
+    Dataset,
+    DEMO_LABEL_FIELD,
+    field_value,
+    rebase_events,
+    replay_event_prefix,
+)
+from veltro_cli.lib.errors import VeltroCliError
+from veltro_cli.lib.suite_http import Response, SuiteSession, trpc_data
+
+INGEST_SUFFIX_DEFAULT = "vectorflow"
+DEMO_MODE_PROCEDURE_GET = "demoMode.get"
+DEMO_MODE_PROCEDURE_SET = "demoMode.set"
+DEMO_MODE_PROCEDURE_DISABLE = "demoMode.disable"
+RESET_REASON = "veltro demo reset"
+SEED_REASON = "veltro demo seed"
+SAFE_REPLAY_NAME = re.compile(r"^[a-z0-9-]+$")
+# Every event `scripts/seed-demo.sh` writes carries an `event.id` under this
+# prefix (`golden-<batch>-<n>`, `golden-ioc-…`, `golden-novel-…`). It is the
+# golden path's equivalent of the corpus datasets' `labels.veltro_demo`.
+GOLDEN_EVENT_PREFIX = "golden-"
+
+
+@dataclass
+class Clock:
+    """Injected time, so seeding is testable without sleeping."""
+
+    now: Callable[[], datetime] = lambda: datetime.now(timezone.utc)
+    sleep: Callable[[float], None] = time.sleep
+
+
+@dataclass
+class IngestTarget:
+    data_source_id: str
+    suffix: str
+
+    @property
+    def index_pattern(self) -> str:
+        return f"chad-alerts-{self.suffix}"
+
+
+@dataclass
+class SeedResult:
+    dataset_id: str
+    engine: str
+    run_token: str = ""
+    rule_id: str = ""
+    events_replayed: int = 0
+    alert_ids: list[str] = field(default_factory=list)
+    case_keys: list[str] = field(default_factory=list)
+    event_prefix: str = ""
+    notes: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "dataset": self.dataset_id,
+            "engine": self.engine,
+            "run_token": self.run_token,
+            "rule_id": self.rule_id,
+            "events_replayed": self.events_replayed,
+            "alert_ids": list(self.alert_ids),
+            "case_keys": list(self.case_keys),
+            "event_prefix": self.event_prefix,
+            "notes": list(self.notes),
+        }
+
+
+@dataclass
+class ResetResult:
+    dataset_id: str
+    replay_files_deleted: int = 0
+    rules_undeployed: list[str] = field(default_factory=list)
+    alerts_deleted: int = 0
+    cases_closed: list[str] = field(default_factory=list)
+    retained: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "dataset": self.dataset_id,
+            "replay_files_deleted": self.replay_files_deleted,
+            "rules_undeployed": list(self.rules_undeployed),
+            "alerts_deleted": self.alerts_deleted,
+            "cases_closed": list(self.cases_closed),
+            "retained": list(self.retained),
+            "notes": list(self.notes),
+        }
+
+
+def _rows(payload: Any, *keys: str) -> list[dict[str, Any]]:
+    """CHAD and Warden list endpoints answer either a list or a keyed object."""
+    if isinstance(payload, list):
+        return [row for row in payload if isinstance(row, dict)]
+    if isinstance(payload, Mapping):
+        for key in keys:
+            value = payload.get(key)
+            if isinstance(value, list):
+                return [row for row in value if isinstance(row, dict)]
+    return []
+
+
+def _fail(response: Response, what: str, remedy: str) -> None:
+    raise VeltroCliError(
+        f"{what} (HTTP {response.status}): {response.detail()}",
+        remedy=remedy,
+    )
+
+
+def resolve_ingest(session: SuiteSession, *, suffix: str = INGEST_SUFFIX_DEFAULT) -> IngestTarget:
+    """The VectorFlow-owned CHAD push data source the demo replays through."""
+    response = session.get("/chad/api/data-sources")
+    if not response.ok:
+        _fail(
+            response,
+            "could not list CHAD data sources",
+            "log in as a suite admin and check CHAD is ready (`veltro status`)",
+        )
+    for row in _rows(response.json(), "data_sources", "patterns"):
+        pattern = str(row.get("pattern") or "")
+        if row.get("suffix") == suffix or pattern in (suffix, f"{suffix}-*") or row.get("name") == "VectorFlow (suite)":
+            return IngestTarget(data_source_id=str(row.get("id")), suffix=suffix)
+    raise VeltroCliError(
+        f"no CHAD push data source for the {suffix!r} pattern",
+        remedy=(
+            "seed the golden path first (`veltro demo seed --dataset brute-force`): it provisions the "
+            "VectorFlow pipeline and the CHAD push data source the corpus datasets replay through"
+        ),
+    )
+
+
+def map_fields(session: SuiteSession, dataset: Dataset, target: IngestTarget) -> list[str]:
+    """Map every Sigma field the dataset's rule keys on. 409 means already mapped."""
+    assert dataset.detection is not None
+    mapped: list[str] = []
+    for sigma_field, target_field in dataset.detection.field_mappings:
+        response = session.post(
+            "/chad/api/field-mappings",
+            json_body={
+                "sigma_field": sigma_field,
+                "target_field": target_field,
+                "data_source_id": target.data_source_id,
+            },
+        )
+        if response.ok or response.status == 409:
+            mapped.append(sigma_field)
+            continue
+        _fail(
+            response,
+            f"could not map {sigma_field} -> {target_field}",
+            "grant the seeding user manage_data_sources in CHAD, or map the field by hand",
+        )
+    return mapped
+
+
+def _rule_body(dataset: Dataset, target: IngestTarget, *, change_reason: str | None) -> dict[str, Any]:
+    detection = dataset.detection
+    assert detection is not None
+    body: dict[str, Any] = {
+        "title": detection.rule_title,
+        "description": detection.description,
+        "yaml_content": detection.yaml_content(),
+        "severity": detection.severity,
+        "data_source_id": target.data_source_id,
+    }
+    if detection.threshold is not None:
+        body.update(
+            {
+                "threshold_enabled": True,
+                "threshold_count": detection.threshold.count,
+                "threshold_window_minutes": detection.threshold.window_minutes,
+                "threshold_group_by": detection.threshold.group_by,
+            }
+        )
+    if change_reason:
+        body["change_reason"] = change_reason
+    return body
+
+
+def find_rule(session: SuiteSession, title: str) -> dict[str, Any] | None:
+    response = session.get("/chad/api/rules")
+    if not response.ok:
+        _fail(response, "could not list CHAD rules", "check the seeding session has view_rules in CHAD")
+    for row in _rows(response.json(), "rules"):
+        if row.get("title") == title:
+            return row
+    return None
+
+
+def ensure_rule(session: SuiteSession, dataset: Dataset, target: IngestTarget) -> str:
+    """Create or reconcile the dataset's rule; return its id."""
+    detection = dataset.detection
+    assert detection is not None
+    existing = find_rule(session, detection.rule_title)
+    if existing is None:
+        response = session.post("/chad/api/rules", json_body=_rule_body(dataset, target, change_reason=None))
+        if not response.ok:
+            _fail(response, f"could not create rule {detection.rule_title!r}", "check the rule YAML and field mappings")
+        rule_id = str((response.json({}) or {}).get("id") or "")
+        if not rule_id:
+            _fail(response, "CHAD accepted the rule but returned no id", "inspect the response body")
+        return rule_id
+    rule_id = str(existing.get("id"))
+    response = session.request(
+        "PATCH",
+        f"/chad/api/rules/{rule_id}",
+        json_body=_rule_body(dataset, target, change_reason=f"{SEED_REASON}: {dataset.id} reconciliation"),
+    )
+    if not response.ok:
+        _fail(
+            response,
+            f"rule {detection.rule_title!r} exists but could not be reconciled",
+            "resolve the rule by hand in CHAD, or delete it if it was never deployed",
+        )
+    return rule_id
+
+
+def record_sample_evidence(session: SuiteSession, dataset: Dataset, target: IngestTarget, rule_id: str) -> str:
+    """Run the positive-match sample test CHAD's deploy floor requires."""
+    detection = dataset.detection
+    assert detection is not None
+    sample = dataset.events()[detection.sample_event_index]
+    response = session.post(
+        "/chad/api/rules/test",
+        json_body={
+            "rule_id": rule_id,
+            "data_source_id": target.data_source_id,
+            "yaml_content": detection.yaml_content(),
+            "sample_logs": [sample],
+            "expected_matches": [0],
+        },
+    )
+    if not response.ok:
+        _fail(
+            response,
+            f"sample test for {detection.rule_title!r} was refused",
+            "check the rule's fields are mapped for this data source",
+        )
+    body = response.json({}) or {}
+    matched = next(
+        (bool(match.get("matched")) for match in body.get("matches") or [] if match.get("log_index") == 0),
+        False,
+    )
+    if not matched:
+        raise VeltroCliError(
+            f"{dataset.id}: the rule did not match its own sample event "
+            f"(corpus index {detection.sample_event_index})",
+            remedy="fix the rule or the manifest's detection.sample.event_index; a rule that cannot fire on its own corpus must not deploy",
+        )
+    evidence_id = str(body.get("evidence_id") or "")
+    if not evidence_id:
+        raise VeltroCliError(
+            f"{dataset.id}: CHAD recorded no deploy-floor evidence for the sample test",
+            remedy="both rule_id and a non-empty expected_matches are required to persist evidence",
+        )
+    return evidence_id
+
+
+def deploy_rule(session: SuiteSession, dataset: Dataset, rule_id: str, *, clock: Clock, timeout: int = 60) -> None:
+    """Deploy the rule, approving its own deployment request when gated."""
+    response = session.post(
+        f"/chad/api/rules/{rule_id}/deploy",
+        json_body={"change_reason": f"{SEED_REASON}: {dataset.id}"},
+    )
+    if response.status == 202:
+        request_id = str((response.json({}) or {}).get("deployment_request_id") or "")
+        if not request_id:
+            _fail(response, "CHAD gated the deploy but named no deployment request", "inspect the response body")
+        approval = session.post(
+            f"/chad/api/deployment-requests/{request_id}/approve",
+            json_body={"reason": f"{SEED_REASON}: suite-admin approval for the {dataset.id} demo dataset"},
+        )
+        if not approval.ok:
+            _fail(
+                approval,
+                f"deployment request {request_id} could not be approved",
+                "approve it in CHAD as a second user with approve_deployments, then re-run",
+            )
+    elif not response.ok:
+        _fail(response, f"deploy of {dataset.id} rule was refused", "read the named validation floor and fix the rule")
+
+    deadline = clock.now().timestamp() + timeout
+    while clock.now().timestamp() < deadline:
+        state = session.get(f"/chad/api/rules/{rule_id}")
+        body = state.json({}) or {}
+        if str(body.get("status") or "").lower() == "deployed" or body.get("deployed_at"):
+            return
+        clock.sleep(3)
+    raise VeltroCliError(
+        f"{dataset.id}: rule {rule_id} never reached deployed status within {timeout}s",
+        remedy="check CHAD's deployment requests and worker logs",
+    )
+
+
+def replay_corpus(
+    dataset: Dataset,
+    *,
+    replay_dir: Path,
+    run_token: str,
+    clock: Clock,
+) -> int:
+    """Queue rebased JSONL for the VectorFlow agent's file source."""
+    if not SAFE_REPLAY_NAME.fullmatch(dataset.id) or not SAFE_REPLAY_NAME.fullmatch(run_token):
+        raise VeltroCliError(
+            "dataset id and run token must contain only lowercase letters, digits, and hyphens",
+            remedy="use a catalog dataset and let `veltro demo seed` generate the run token",
+        )
+    events = rebase_events(dataset, now=clock.now(), run_token=run_token)
+    replay_dir.mkdir(mode=0o755, parents=True, exist_ok=True)
+    replay_dir.chmod(0o755)
+    final_path = replay_dir / f"{dataset.id}-{run_token}.jsonl"
+    temporary_path = replay_dir / f".{dataset.id}-{run_token}.tmp"
+    with temporary_path.open("w", encoding="utf-8") as handle:
+        for event in events:
+            handle.write(json.dumps(event, separators=(",", ":"), sort_keys=True))
+            handle.write("\n")
+        handle.flush()
+        os.fsync(handle.fileno())
+    temporary_path.chmod(0o644)
+    os.replace(temporary_path, final_path)
+    return len(events)
+
+
+def collect_alerts(
+    session: SuiteSession,
+    dataset: Dataset,
+    target: IngestTarget,
+    rule_id: str,
+    *,
+    run_token: str,
+) -> tuple[list[str], list[str]]:
+    """Alert ids and Warden case keys for THIS run's events only."""
+    prefix = replay_event_prefix(dataset, run_token)
+    response = session.get(
+        f"/chad/api/alerts?index_pattern={target.index_pattern}&cluster=false&limit=100&rule_id={rule_id}"
+    )
+    if not response.ok:
+        return [], []
+    alert_ids: list[str] = []
+    case_keys: list[str] = []
+    for row in _rows(response.json(), "alerts"):
+        document = row.get("log_document") or {}
+        # This run only: Warden correlates repeated alerts into one open case,
+        # so an earlier run's alert would otherwise be accepted as proof.
+        event_id = str(field_value(document, "event.id") or "")
+        if not event_id.startswith(prefix):
+            continue
+        identifier = str(row.get("id") or row.get("alert_id") or "")
+        if identifier and identifier not in alert_ids:
+            alert_ids.append(identifier)
+        reference = row.get("warden_case_ref") or row.get("warden_case") or {}
+        if isinstance(reference, Mapping):
+            key = str(reference.get("case_key") or "")
+            if key and key not in case_keys:
+                case_keys.append(key)
+    return alert_ids, case_keys
+
+
+def case_exists(session: SuiteSession, case_key: str) -> bool:
+    response = session.get("/warden/api/cases?limit=100")
+    if not response.ok:
+        return False
+    return any(row.get("key") == case_key for row in _rows(response.json(), "cases"))
+
+
+def seed_dataset(
+    session: SuiteSession,
+    dataset: Dataset,
+    *,
+    run_token: str,
+    replay_dir: Path,
+    clock: Clock | None = None,
+    ingest: IngestTarget | None = None,
+    settle_seconds: int = 90,
+) -> SeedResult:
+    """Provision, replay and follow one corpus dataset end to end."""
+    clock = clock or Clock()
+    if not dataset.is_corpus:
+        raise VeltroCliError(
+            f"{dataset.id} is provisioned by the golden-path seeder, not the corpus engine",
+            remedy="run `veltro demo seed --dataset brute-force`, which shells out to scripts/seed-demo.sh",
+        )
+    target = ingest or resolve_ingest(session)
+    result = SeedResult(dataset_id=dataset.id, engine=dataset.engine, run_token=run_token)
+    result.event_prefix = replay_event_prefix(dataset, run_token)
+    map_fields(session, dataset, target)
+    result.rule_id = ensure_rule(session, dataset, target)
+    record_sample_evidence(session, dataset, target, result.rule_id)
+    deploy_rule(session, dataset, result.rule_id, clock=clock)
+    result.events_replayed = replay_corpus(dataset, replay_dir=replay_dir, run_token=run_token, clock=clock)
+
+    deadline = clock.now().timestamp() + settle_seconds
+    while True:
+        alert_ids, case_keys = collect_alerts(
+            session, dataset, target, result.rule_id, run_token=run_token
+        )
+        result.alert_ids = alert_ids
+        result.case_keys = case_keys
+        enough_alerts = len(alert_ids) >= dataset.min_alerts
+        case_ready = (not dataset.expect_warden_case) or (
+            bool(case_keys) and case_exists(session, case_keys[0])
+        )
+        if enough_alerts and case_ready:
+            return result
+        if clock.now().timestamp() >= deadline:
+            break
+        clock.sleep(5)
+
+    if len(result.alert_ids) < dataset.min_alerts:
+        raise VeltroCliError(
+            f"{dataset.id}: replayed {result.events_replayed} events but CHAD raised "
+            f"{len(result.alert_ids)} alert(s), expected at least {dataset.min_alerts}",
+            remedy="check the rule is deployed and its fields are mapped, then re-run the seed",
+        )
+    raise VeltroCliError(
+        f"{dataset.id}: alert {result.alert_ids[0]} did not open a Warden case within {settle_seconds}s",
+        remedy="check CHAD -> Warden delivery (Settings > Warden) and the Warden automation bindings",
+    )
+
+
+# --- reset ------------------------------------------------------------------
+
+
+def _demo_alerts(session: SuiteSession, dataset: Dataset, target: IngestTarget, rule_id: str) -> list[str]:
+    response = session.get(
+        f"/chad/api/alerts?index_pattern={target.index_pattern}&cluster=false&limit=500&rule_id={rule_id}"
+    )
+    if not response.ok:
+        return []
+    identifiers: list[str] = []
+    for row in _rows(response.json(), "alerts"):
+        document = row.get("log_document") or {}
+        if str(field_value(document, f"labels.{DEMO_LABEL_FIELD}") or "") != dataset.id:
+            continue
+        identifier = str(row.get("id") or row.get("alert_id") or "")
+        if identifier:
+            identifiers.append(identifier)
+    return identifiers
+
+
+def _close_case(session: SuiteSession, case: Mapping[str, Any], dataset_id: str) -> bool:
+    """Resolve then close a demo case. Warden has no case delete, by design."""
+    case_id = str(case.get("id") or "")
+    if not case_id:
+        return False
+    note = f"{RESET_REASON}: synthetic data from the {dataset_id} demo dataset"
+    status = str(case.get("status") or "")
+    if status not in {"resolved", "closed"}:
+        resolved = session.post(
+            f"/warden/api/cases/{case_id}/status",
+            json_body={"status": "resolved", "note": note},
+        )
+        if not resolved.ok:
+            return False
+    if status != "closed":
+        closed = session.post(
+            f"/warden/api/cases/{case_id}/status",
+            json_body={"status": "closed", "note": note, "disposition": "true_positive"},
+        )
+        return closed.ok
+    return True
+
+
+def _data_source_suffix(session: SuiteSession, data_source_id: str) -> str:
+    """The alert-index suffix CHAD writes for one data source, or "" if unknown.
+
+    `resolve_ingest` reads the data-source table suffix-first; this reads the
+    same table id-first. A row names its suffix directly or through its index
+    pattern (`<suffix>-*`), which is the shape `scripts/seed-demo.sh` creates
+    when it takes its documented `ssh-bruteforce-demo` fallback because the
+    suite-seeded push pattern is not there yet.
+    """
+    if not data_source_id:
+        return ""
+    response = session.get("/chad/api/data-sources")
+    if not response.ok:
+        return ""
+    for row in _rows(response.json(), "data_sources", "patterns"):
+        if str(row.get("id") or "") != data_source_id:
+            continue
+        suffix = str(row.get("suffix") or "")
+        if suffix:
+            return suffix
+        pattern = str(row.get("pattern") or "")
+        return pattern[:-2] if pattern.endswith("-*") else pattern
+    return ""
+
+
+def _golden_path_alerts(session: SuiteSession, rule_id: str, suffix: str) -> tuple[list[str], str]:
+    """The seeder's own alerts on one rule, and a note if CHAD could not answer.
+
+    `_demo_alerts` recognises a corpus dataset by the `labels.veltro_demo`
+    marker its replay stamps on every event. The golden-path corpus is
+    generated by `scripts/seed-demo.sh`, which stamps no label — but every
+    event it writes carries a `golden-…` `event.id` (`golden-<batch>-<n>`,
+    `golden-ioc-…`, `golden-novel-…`). That prefix is checked on the returned
+    row rather than trusted to the `rule_id` query parameter, so an alert an
+    operator's own telemetry raised can never be deleted here even if CHAD
+    ignored the filter.
+    """
+    pattern = IngestTarget(data_source_id="", suffix=suffix).index_pattern
+    response = session.get(
+        f"/chad/api/alerts?index_pattern={pattern}&cluster=false&limit=500&rule_id={rule_id}"
+    )
+    if not response.ok:
+        return [], (
+            f"could not list alerts for rule {rule_id} (HTTP {response.status}); "
+            "only the alerts the handoff named were deleted"
+        )
+    identifiers: list[str] = []
+    for row in _rows(response.json(), "alerts"):
+        document = row.get("log_document") or {}
+        if not str(field_value(document, "event.id") or "").startswith(GOLDEN_EVENT_PREFIX):
+            continue
+        identifier = str(row.get("id") or row.get("alert_id") or "")
+        if identifier:
+            identifiers.append(identifier)
+    return identifiers, ""
+
+
+def reset_golden_path(
+    session: SuiteSession,
+    *,
+    replay_dir: Path,
+    rule_title: str,
+    rule_id: str,
+    alert_ids: Sequence[str],
+    case_keys: Sequence[str],
+    ingest_suffix: str = INGEST_SUFFIX_DEFAULT,
+) -> ResetResult:
+    """Reset the golden-path records, by handoff id or by rule title.
+
+    `scripts/seed-demo.sh` writes its private handoff (`.seed-demo.env`) at the
+    very end, so a run that died anywhere before that names no rule, no alert
+    and no case — and the golden-path dataset has no `detection` block to fall
+    back on. That left a deployed synthetic rule, its alert and its open Warden
+    case behind while `reset` turned the banner off over them (veltro#984). So
+    the rule is resolved by its manifest title when the handoff names none, and
+    its alerts and cases are then reached through the rule itself — including
+    the CHAD index its alerts landed in, which the rule's own data source
+    names. The seeder falls back to a demo-owned `ssh-bruteforce-demo` pattern
+    when the suite-seeded push pattern is not there yet, so assuming
+    `ingest_suffix` in this path would look for the alert in an index the run
+    never wrote to.
+    """
+    result = ResetResult(dataset_id="brute-force")
+    if replay_dir.is_dir():
+        for path in replay_dir.glob("brute-force-*.jsonl"):
+            path.unlink()
+            result.replay_files_deleted += 1
+
+    resolved_id = rule_id
+    resolved_suffix = ingest_suffix
+    if not resolved_id:
+        existing = find_rule(session, rule_title)
+        resolved_id = str(existing.get("id") or "") if existing else ""
+        if resolved_id:
+            result.notes.append(
+                f"the golden-path handoff named no rule; found {rule_title!r} by title "
+                f"({resolved_id}) and undeployed it"
+            )
+            from_rule = _data_source_suffix(
+                session, str((existing or {}).get("data_source_id") or "")
+            )
+            if from_rule and from_rule != resolved_suffix:
+                result.notes.append(
+                    f"the rule ingests through the {from_rule!r} pattern, not the "
+                    f"{resolved_suffix!r} default; its alerts were looked for there"
+                )
+                resolved_suffix = from_rule
+        else:
+            result.notes.append(
+                f"no CHAD rule titled {rule_title!r} exists; the golden-path seeder "
+                "created none, so none was undeployed"
+            )
+
+    if resolved_id:
+        undeploy = session.post(
+            f"/chad/api/rules/{resolved_id}/undeploy",
+            json_body={"change_reason": RESET_REASON},
+        )
+        if undeploy.ok or undeploy.status in (404, 409):
+            result.rules_undeployed.append(resolved_id)
+        else:
+            _fail(
+                undeploy,
+                "could not undeploy the brute-force rule",
+                "undeploy it in CHAD, then re-run the reset",
+            )
+
+    found_ids: list[str] = []
+    if resolved_id:
+        found_ids, listing_note = _golden_path_alerts(session, resolved_id, resolved_suffix)
+        if listing_note:
+            result.notes.append(listing_note)
+    unique_alert_ids = list(
+        dict.fromkeys(identifier for identifier in (*alert_ids, *found_ids) if identifier)
+    )
+    if unique_alert_ids:
+        deletion = session.post(
+            "/chad/api/alerts/bulk/delete",
+            json_body={"alert_ids": unique_alert_ids, "change_reason": RESET_REASON},
+        )
+        if deletion.ok:
+            body = deletion.json({}) or {}
+            deleted = body.get("success")
+            result.alerts_deleted = (
+                len(deleted) if isinstance(deleted, list) else len(unique_alert_ids)
+            )
+        else:
+            result.notes.append(
+                f"CHAD refused to delete {len(unique_alert_ids)} golden-path alert(s) "
+                f"(HTTP {deletion.status}): {deletion.detail(120)}"
+            )
+    else:
+        result.notes.append("no golden-path alert was recorded or found; none was deleted")
+
+    # Warden correlates a case on the rule title (scripts/seed-demo.sh), so a
+    # case carrying the golden-path title came from this synthetic rule even
+    # when the run died before recording its key.
+    wanted = set(case_keys)
+    cases = session.get("/warden/api/cases?limit=200")
+    if cases.ok:
+        for row in _rows(cases.json(), "cases"):
+            titled = rule_title in str(row.get("title") or "")
+            if (row.get("key") in wanted or titled) and _close_case(session, row, "brute-force"):
+                result.cases_closed.append(str(row.get("key") or row.get("id")))
+    else:
+        result.notes.append(f"could not list Warden cases (HTTP {cases.status}); no case was closed")
+
+    if resolved_id:
+        result.retained.append(f"CHAD rule {resolved_id} and its immutable version history")
+    result.retained.append(
+        "CHAD field mappings event.action, SourceIp, and User used by the golden-path "
+        "data source (the shell seeder may create missing mappings, but does not record "
+        "which shared mappings predated the run)"
+    )
+    result.retained.append("Warden cases are closed with a disposition, not deleted")
+    result.retained.append("audit rows for every reset action")
+    return result
+
+
+def reset_dataset(
+    session: SuiteSession,
+    dataset: Dataset,
+    *,
+    replay_dir: Path,
+    ingest: IngestTarget | None = None,
+    case_keys: Sequence[str] = (),
+) -> ResetResult:
+    """Stop the dataset's detection, remove replay files, delete alerts, and close cases."""
+    result = ResetResult(dataset_id=dataset.id)
+    if replay_dir.is_dir():
+        for path in replay_dir.glob(f"{dataset.id}-*.jsonl"):
+            path.unlink()
+            result.replay_files_deleted += 1
+    if not dataset.is_corpus:
+        raise VeltroCliError(
+            "golden-path cleanup requires its recorded rule, alert, and case identifiers",
+            remedy="use `veltro demo reset`, which reads the private golden-path handoff",
+        )
+
+    assert dataset.detection is not None
+    rule = find_rule(session, dataset.detection.rule_title)
+    if rule is None:
+        result.notes.append("rule not present; nothing to undeploy")
+        for sigma_field, target_field in dataset.detection.field_mappings:
+            result.retained.append(
+                f"CHAD field mapping {sigma_field} -> {target_field} "
+                "(shared configuration; the rule is absent, so its data source is unknown)"
+            )
+        return result
+    rule_id = str(rule.get("id"))
+    undeploy = session.post(
+        f"/chad/api/rules/{rule_id}/undeploy",
+        json_body={"change_reason": RESET_REASON},
+    )
+    if undeploy.ok or undeploy.status in (404, 409):
+        result.rules_undeployed.append(rule_id)
+        if undeploy.status == 409:
+            result.notes.append(f"rule {rule_id} was already undeployed")
+    else:
+        _fail(undeploy, f"could not undeploy the {dataset.id} rule", "undeploy it in CHAD, then re-run the reset")
+
+    target = ingest or resolve_ingest(session)
+    alert_ids = _demo_alerts(session, dataset, target, rule_id)
+    if alert_ids:
+        deletion = session.post("/chad/api/alerts/bulk/delete", json_body={"alert_ids": alert_ids})
+        if deletion.ok:
+            body = deletion.json({}) or {}
+            deleted = body.get("success")
+            result.alerts_deleted = len(deleted) if isinstance(deleted, list) else len(alert_ids)
+        else:
+            result.notes.append(
+                f"CHAD refused to delete {len(alert_ids)} demo alert(s) (HTTP {deletion.status}): {deletion.detail(120)}"
+            )
+
+    keys = list(case_keys)
+    cases = session.get("/warden/api/cases?limit=200")
+    if cases.ok:
+        for row in _rows(cases.json(), "cases"):
+            if keys and row.get("key") not in keys:
+                continue
+            if not keys and dataset.detection.rule_title not in str(row.get("title") or ""):
+                continue
+            if _close_case(session, row, dataset.id):
+                result.cases_closed.append(str(row.get("key") or row.get("id")))
+    else:
+        result.notes.append(f"could not list Warden cases (HTTP {cases.status}); no case was closed")
+
+    result.retained.append(
+        f"CHAD rule {rule_id} and its version history (CHAD refuses to delete an ever-deployed rule: "
+        "its versions are deploy evidence)"
+    )
+    result.retained.append("Warden cases are closed with a disposition, not deleted (Warden has no case delete)")
+    for sigma_field, target_field in dataset.detection.field_mappings:
+        result.retained.append(
+            f"CHAD field mapping {sigma_field} -> {target_field} on data source "
+            f"{target.data_source_id} (shared configuration; may predate this seed)"
+        )
+    result.retained.append("audit rows for every action above, in both products")
+    return result
+
+
+# --- identity demo mode -----------------------------------------------------
+
+
+def read_demo_mode(session: SuiteSession) -> dict[str, Any] | None:
+    response = session.trpc_query(DEMO_MODE_PROCEDURE_GET)
+    if not response.ok:
+        return None
+    data = trpc_data(response)
+    return data if isinstance(data, dict) else None
+
+
+def set_demo_mode(
+    session: SuiteSession,
+    dataset_ids: Iterable[str],
+    *,
+    seeded_at: datetime,
+) -> bool:
+    """Turn the suite-wide demo banner on, naming the seeded datasets."""
+    payload = {
+        "enabled": True,
+        "datasets": sorted({str(identifier) for identifier in dataset_ids}),
+        "seededAt": seeded_at.astimezone(timezone.utc).isoformat().replace("+00:00", "Z"),
+    }
+    response = session.trpc_mutation(DEMO_MODE_PROCEDURE_SET, payload)
+    if not response.ok:
+        raise VeltroCliError(
+            f"could not record demo mode in identity (HTTP {response.status}): {response.detail()}",
+            remedy="the seeding user must be a suite admin; the banner is driven by this setting",
+        )
+    return True
+
+
+def clear_demo_mode(session: SuiteSession) -> bool:
+    response = session.trpc_mutation(DEMO_MODE_PROCEDURE_DISABLE, {})
+    if not response.ok:
+        raise VeltroCliError(
+            f"could not clear demo mode in identity (HTTP {response.status}): {response.detail()}",
+            remedy="clear it from the identity console Demo mode panel, or re-run as a suite admin",
+        )
+    return True