sre-agent-cli 0.2.0__py3-none-any.whl

sre_agent/policy.py

@@ -0,0 +1,208 @@
+"""The policy engine: the only path between a proposal and an action.
+
+Pure functions over explicit inputs. No model output is ever trusted here;
+a proposal arrives as structured data and leaves as a decision with a reason.
+See docs/safety-model.md for the contract this code implements.
+
+What this module decides, in plain words:
+
+- **Classification.** Every action names a runbook, and every runbook the
+  agent may ever propose is listed in one fixed catalogue in this file.
+  The catalogue says whether the action only reads (it changes nothing)
+  or mutates reversibly (it changes something that can be undone, like a
+  restart, a scale, or a rollback). A runbook that is not in the
+  catalogue is unknown, and unknown actions are denied — a made-up
+  runbook name can never slip through as "needs approval".
+- **Blast radius.** A mutating action is checked against the limits of
+  its environment: how many replicas it touches, which namespaces are
+  allowed at all, which namespaces are on the no-touch list, and whether
+  its target is still the target pinned on the incident it belongs to.
+- **Tier gate.** What remains is decided by the environment's tier
+  (Section 6 of the plan): read-only actions are allowed, mutations
+  need a human's approval at Tier 2, and only pre-approved runbook
+  classes run without one at Tier 3.
+
+Recording the decision is the audit log's job (``audit.py``); this
+module only decides. ``audit.evaluate_and_audit`` is the normal way to
+call both together, so no decision goes unrecorded.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from .models import Target
+
+
+class Tier(int, Enum):
+    OBSERVE = 0
+    ADVISE = 1
+    ACT_WITH_APPROVAL = 2
+    ACT_WITHIN_BOUNDS = 3
+
+
+class Decision(str, Enum):
+    ALLOW = "allow"
+    REQUIRE_APPROVAL = "require_approval"
+    DENY = "deny"
+
+
+class ActionClass(str, Enum):
+    """What kind of action a runbook is. Fixed by the catalogue below."""
+
+    READ_ONLY = "read_only"
+    REVERSIBLE_MUTATION = "reversible_mutation"
+
+
+# The allow-list. Every runbook id the agent may propose must be named
+# here, with its class. Anything not named here is unknown and denied.
+# The three read-only entries are the tool layer's tools; the three
+# mutating entries are the runbook library's first runbooks (Phase 2).
+RUNBOOK_CATALOG: dict[str, ActionClass] = {
+    "query-metrics": ActionClass.READ_ONLY,
+    "search-logs": ActionClass.READ_ONLY,
+    "get-service-status": ActionClass.READ_ONLY,
+    "restart-workload": ActionClass.REVERSIBLE_MUTATION,
+    "scale-replicas": ActionClass.REVERSIBLE_MUTATION,
+    "rollback-deployment": ActionClass.REVERSIBLE_MUTATION,
+}
+
+
+def classify_action(runbook_id: str) -> ActionClass | None:
+    """Return the class of a runbook, or None if it is not allow-listed."""
+    return RUNBOOK_CATALOG.get(runbook_id)
+
+
+class ProposedAction(BaseModel):
+    """A structured proposal. Free-form commands are not representable."""
+
+    runbook_id: str
+    target: Target
+    parameters: dict[str, str | int | float | bool] = Field(default_factory=dict)
+    replicas_affected: int = Field(default=0, ge=0)
+    rationale: str
+
+
+class EnvironmentPolicy(BaseModel):
+    """What the agent may do in one environment. Defaults are restrictive."""
+
+    environment: str
+    granted_tier: Tier = Tier.ADVISE
+    # runbook classes allowed to run at Tier 3 in this environment
+    tier3_runbooks: set[str] = Field(default_factory=set)
+    max_replicas_affected: int = 1
+    # if non-empty, only these namespaces may be touched at all
+    allowed_namespaces: set[str] = Field(default_factory=set)
+    denied_namespaces: set[str] = Field(default_factory=set)
+    halted: bool = False
+
+
+class PolicyResult(BaseModel):
+    decision: Decision
+    reason: str
+    action_class: ActionClass | None = None
+
+
+def evaluate(
+    action: ProposedAction,
+    policy: EnvironmentPolicy,
+    *,
+    incident_target: Target | None = None,
+) -> PolicyResult:
+    """Decide whether a proposed action may run, needs approval, or is denied.
+
+    Order matters: hard stops are checked before any allowance, so a halted
+    or out-of-scope environment can never be overridden by a grant.
+
+    ``incident_target`` is the target pinned on the incident the action
+    belongs to, when the caller has one. An action aimed anywhere else is
+    denied: actions cannot retarget mid-flight.
+    """
+    action_class = classify_action(action.runbook_id)
+
+    if action.target.environment != policy.environment:
+        return PolicyResult(
+            decision=Decision.DENY,
+            reason="action target environment does not match this policy",
+            action_class=action_class,
+        )
+
+    if action.target.namespace in policy.denied_namespaces:
+        return PolicyResult(
+            decision=Decision.DENY,
+            reason=f"namespace '{action.target.namespace}' is on the no-touch list",
+            action_class=action_class,
+        )
+
+    if incident_target is not None and action.target != incident_target:
+        return PolicyResult(
+            decision=Decision.DENY,
+            reason="action target does not match the target pinned on the incident",
+            action_class=action_class,
+        )
+
+    if action_class is None:
+        return PolicyResult(
+            decision=Decision.DENY,
+            reason=f"runbook '{action.runbook_id}' is not on the allow-list",
+            action_class=None,
+        )
+
+    if action_class is ActionClass.READ_ONLY:
+        # Reads change nothing, so the tier gate and the halt switch do
+        # not block them (docs/safety-model.md: "Reads may continue").
+        return PolicyResult(
+            decision=Decision.ALLOW,
+            reason="read-only action; it changes nothing",
+            action_class=action_class,
+        )
+
+    if policy.halted:
+        return PolicyResult(
+            decision=Decision.DENY,
+            reason="agent is halted in this environment",
+            action_class=action_class,
+        )
+
+    if policy.allowed_namespaces and action.target.namespace not in policy.allowed_namespaces:
+        return PolicyResult(
+            decision=Decision.DENY,
+            reason=f"namespace '{action.target.namespace}' is not in this environment's "
+            "allowed namespaces",
+            action_class=action_class,
+        )
+
+    if action.replicas_affected > policy.max_replicas_affected:
+        return PolicyResult(
+            decision=Decision.DENY,
+            reason=(
+                f"blast radius too large: {action.replicas_affected} replicas affected, "
+                f"limit is {policy.max_replicas_affected}"
+            ),
+            action_class=action_class,
+        )
+
+    if policy.granted_tier < Tier.ACT_WITH_APPROVAL:
+        return PolicyResult(
+            decision=Decision.DENY,
+            reason=f"environment is at Tier {policy.granted_tier}; mutations are not granted",
+            action_class=action_class,
+        )
+
+    if (
+        policy.granted_tier >= Tier.ACT_WITHIN_BOUNDS
+        and action.runbook_id in policy.tier3_runbooks
+    ):
+        return PolicyResult(
+            decision=Decision.ALLOW,
+            reason="pre-approved runbook class within blast-radius limits (Tier 3)",
+            action_class=action_class,
+        )
+
+    return PolicyResult(
+        decision=Decision.REQUIRE_APPROVAL,
+        reason="mutation requires a human to approve this specific action (Tier 2)",
+        action_class=action_class,
+    )

sre_agent/postmortems.py

@@ -0,0 +1,296 @@
+"""Postmortem draft generation: the incident report, from the record.
+
+In plain words, this is the last step of an incident: after the
+problem is fixed, someone has to write down what happened. This
+module writes the *first draft* of that report, using only what
+the incident record itself holds — its evidence, its diagnosis,
+the actions recorded on it, and the audit records the caller
+hands in for it. A human edits and publishes the draft; nothing
+here publishes anything.
+
+How honesty is kept, in plain words:
+
+- **The draft invents nothing.** It is a pure reader of the
+  record: it changes no incident, runs no tool and proposes no
+  action. If the record holds no diagnosis, the draft says the
+  cause was not recorded instead of guessing one. If no action
+  was recorded, it says so. What the record does not know is
+  listed, in its own section, as not known.
+- **The timeline uses only timestamps the record really has.**
+  Incidents do not stamp each status change — a transition only
+  moves ``updated_at`` — so the timeline is built from the
+  incident's creation time, each evidence record's observation
+  time, and each audit record's decision time, and it ends with
+  the record's last update. No time is made up for a change the
+  record did not date.
+- **An unfinished incident gets a preliminary draft, labelled
+  as one.** A draft can be generated at any point — it is useful
+  mid-incident too — but until the incident is resolved the
+  draft says plainly that it is not a final postmortem.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, Field
+
+from .approvals import approve_pending, create_pending, execute_approved
+from .audit import AuditLog, evaluate_and_audit
+from .logging_config import get_logger
+from .models import AuditRecord, Evidence, Hypothesis, Incident, IncidentStatus, Target
+from .policy import EnvironmentPolicy, Tier
+from .reasoning import ReasoningLoop
+from .runbooks import build_action, demo_runbooks
+from .tools import demo_tool_layer
+
+log = get_logger(__name__)
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class TimelineEntry(BaseModel):
+    """One dated line in the draft's timeline, from the record."""
+
+    at: datetime
+    text: str
+
+
+class PostmortemDraft(BaseModel):
+    """A first draft of an incident's postmortem, ready to edit."""
+
+    incident_id: str
+    title: str
+    target: Target
+    status: IncidentStatus
+    resolved: bool
+    generated_at: datetime = Field(default_factory=_utcnow)
+    diagnosis: str | None = None
+    timeline: list[TimelineEntry] = Field(default_factory=list)
+    hypotheses: list[Hypothesis] = Field(default_factory=list)
+    evidence: list[Evidence] = Field(default_factory=list)
+    actions: list[Evidence] = Field(default_factory=list)
+    audit_records: list[AuditRecord] = Field(default_factory=list)
+    unknowns: list[str] = Field(default_factory=list)
+
+    def render_markdown(self) -> str:
+        """Write the draft as Markdown a human can edit and publish.
+
+        Every section is present even when the record behind it is
+        empty; an empty section says so in plain words rather than
+        being quietly dropped, so a reader can tell the difference
+        between "none" and "not written yet".
+        """
+        target = self.target
+        lines = [
+            f"# Postmortem draft: {self.title}",
+            "",
+            f"Incident: {self.incident_id}",
+            (
+                f"Target: {target.service} in {target.namespace} "
+                f"({target.environment})"
+            ),
+            f"Status: {self.status.value}",
+        ]
+        if not self.resolved:
+            lines.append(
+                "**Preliminary draft — this incident is not resolved yet, "
+                "so this is not a final postmortem.**"
+            )
+        lines += ["", "## Timeline", ""]
+        if self.timeline:
+            for entry in self.timeline:
+                lines.append(f"- {entry.at.isoformat()} — {entry.text}")
+        else:
+            lines.append("- No dated events were recorded.")
+        lines += ["", "## Diagnosis", ""]
+        lines.append(
+            self.diagnosis
+            if self.diagnosis
+            else "Not recorded: the record holds no diagnosis, so no cause is stated."
+        )
+        lines += ["", "## Possible causes, as recorded", ""]
+        if self.hypotheses:
+            for hyp in self.hypotheses:
+                lines.append(
+                    f"- {hyp.statement} (confidence {hyp.confidence:.2f}, "
+                    f"supported by {len(hyp.supporting_evidence)} evidence record(s))"
+                )
+        else:
+            lines.append("- None were recorded.")
+        lines += ["", "## Evidence", ""]
+        if self.evidence:
+            for ev in self.evidence:
+                lines.append(
+                    f"- [{ev.kind}] {ev.summary} (query: {ev.query})"
+                )
+        else:
+            lines.append("- No evidence was recorded.")
+        lines += ["", "## Actions taken", ""]
+        if self.actions:
+            for ev in self.actions:
+                lines.append(f"- {ev.summary} (query: {ev.query})")
+        else:
+            lines.append("- No action was recorded on this incident.")
+        lines += ["", "## Decisions and approvals (audit log)", ""]
+        if self.audit_records:
+            for record in self.audit_records:
+                approver = (
+                    f", approved by {record.approved_by}" if record.approved_by else ""
+                )
+                lines.append(
+                    f"- {record.action_summary} — decision: {record.decision} "
+                    f"({record.reason}){approver}"
+                )
+        else:
+            lines.append("- No audit records were supplied for this incident.")
+        lines += ["", "## What is not known", ""]
+        if self.unknowns:
+            for unknown in self.unknowns:
+                lines.append(f"- {unknown}")
+        else:
+            lines.append("- Nothing: the record covers every section above.")
+        lines.append("")
+        return "\n".join(lines)
+
+
+def generate_postmortem(
+    incident: Incident,
+    audit_records: list[AuditRecord] | None = None,
+    *,
+    now: datetime | None = None,
+) -> PostmortemDraft:
+    """Build a postmortem draft from *incident*'s own record.
+
+    Pure: the incident is read, never changed, and nothing is run.
+    Audit records are taken from the caller's list but filtered to
+    this incident, so one incident's draft can never carry another
+    incident's decisions.
+    """
+    records = [r for r in audit_records or [] if r.incident_id == incident.id]
+    records.sort(key=lambda r: r.decided_at)
+
+    timeline = [
+        TimelineEntry(
+            at=incident.created_at,
+            text=f"Incident opened: {incident.title}",
+        )
+    ]
+    for ev in sorted(incident.evidence, key=lambda e: e.observed_at):
+        timeline.append(
+            TimelineEntry(
+                at=ev.observed_at,
+                text=f"Evidence ({ev.kind}): {ev.summary}",
+            )
+        )
+    for record in records:
+        timeline.append(
+            TimelineEntry(
+                at=record.decided_at,
+                text=(
+                    f"Decision recorded: {record.action_summary} — "
+                    f"{record.decision}"
+                ),
+            )
+        )
+    timeline.append(
+        TimelineEntry(
+            at=incident.updated_at,
+            text=f"Record last updated; status is {incident.status.value}.",
+        )
+    )
+    timeline.sort(key=lambda e: e.at)
+
+    unknowns: list[str] = []
+    if incident.status is not IncidentStatus.RESOLVED:
+        unknowns.append(
+            f"The incident is not resolved yet (status: {incident.status.value}); "
+            "this draft is preliminary and the ending is not known."
+        )
+    if not incident.diagnosis:
+        unknowns.append(
+            "No diagnosis was recorded, so the cause is not stated in this draft."
+        )
+    if not incident.hypotheses:
+        unknowns.append("No possible causes were recorded.")
+    if not incident.evidence:
+        unknowns.append("No evidence was recorded.")
+    actions = [ev for ev in incident.evidence if ev.kind == "action"]
+    if not actions:
+        unknowns.append("No runbook action was recorded on this incident.")
+    if not records:
+        unknowns.append("No audit records were supplied for this incident.")
+
+    log.info(
+        "postmortem draft generated for incident %s (status %s, %d unknown(s))",
+        incident.id,
+        incident.status.value,
+        len(unknowns),
+    )
+    return PostmortemDraft(
+        incident_id=incident.id,
+        title=incident.title,
+        target=incident.target,
+        status=incident.status,
+        resolved=incident.status is IncidentStatus.RESOLVED,
+        generated_at=now if now is not None else _utcnow(),
+        diagnosis=incident.diagnosis,
+        timeline=timeline,
+        hypotheses=list(incident.hypotheses),
+        evidence=list(incident.evidence),
+        actions=actions,
+        audit_records=records,
+        unknowns=unknowns,
+    )
+
+
+def demo_postmortem() -> PostmortemDraft:
+    """A full demo postmortem, built end to end with no setup.
+
+    One seeded demo incident is diagnosed by the real reasoning
+    loop, fixed by the real Tier 2 path (propose, approve by name,
+    run the restart once), and resolved — then drafted here. The
+    draft therefore shows a real diagnosis, a real action record
+    and real audit records, all about the demo checkout workload
+    and nothing real.
+    """
+    target = Target(environment="demo", namespace="shop", service="checkout")
+    incident = Incident(
+        id="demo-incident-1",
+        title="HighErrorRate on checkout",
+        target=target,
+    )
+    ReasoningLoop(demo_tool_layer()).diagnose(incident)
+
+    executor, backend = demo_runbooks()
+    action = build_action(
+        "restart-workload",
+        target,
+        {},
+        backend,
+        rationale=incident.diagnosis or "demo diagnosis",
+    )
+    policy = EnvironmentPolicy(
+        environment="demo",
+        granted_tier=Tier.ACT_WITH_APPROVAL,
+        max_replicas_affected=5,
+    )
+    audit = AuditLog()
+    result = evaluate_and_audit(
+        action, policy, audit, incident_id=incident.id, incident_target=target
+    )
+    pending = create_pending(action, result, incident_id=incident.id)
+    grant, allowed = approve_pending(
+        pending,
+        approved_by="Demo Approver",
+        policy=policy,
+        audit_log=audit,
+        incident_target=target,
+    )
+    incident.transition(IncidentStatus.MITIGATING)
+    run_result = execute_approved(executor, pending, grant, allowed)
+    incident.add_evidence(run_result.to_evidence())
+    incident.transition(IncidentStatus.RESOLVED)
+    return generate_postmortem(incident, audit.for_incident(incident.id))