Orchestrator report phase (ADR 0013) and fetching in code (ADR 0014), with the report renderer. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
351 lines
15 KiB
Python
351 lines
15 KiB
Python
"""The discovery rules that must not depend on a model's arithmetic.
|
|
|
|
Each rule here is written in the ALZ-DSC story files as pseudo-code. As a
|
|
function it gives the same answer every time, a sub-agent can call it instead
|
|
of working it out, and post_process can run it again to check the reply.
|
|
|
|
Every function returns a small dict -- {"error": ...} for input it cannot use --
|
|
because the framework hands the return value straight back to the model.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import ipaddress
|
|
from itertools import combinations
|
|
from typing import Any, Dict, Iterable, List, Optional, Set
|
|
|
|
from app import workspace
|
|
|
|
SCAN_LIKE = {"scan_target"}
|
|
INGEST = {"ingest_cmdb", "ingest_itsm"}
|
|
AFTER_INGEST = {"collect_network", "trace_dependencies", "reconcile_cmdb"}
|
|
|
|
|
|
def _result(stored: Any) -> Any:
|
|
"""An MCP result's own data: results are stored as they came back, in the {"success", "data"} wrapper."""
|
|
if isinstance(stored, dict) and "success" in stored and isinstance(stored.get("data"), dict):
|
|
return stored["data"]
|
|
return stored
|
|
|
|
|
|
def scope_ids(scope: Any) -> List[str]:
|
|
"""The scope_entry_ids in an alz-scope.get_scope result, whichever shape it came back in."""
|
|
scope = _result(scope)
|
|
if isinstance(scope, dict):
|
|
for key in ("entries", "scope_entries", "scope", "items"):
|
|
if isinstance(scope.get(key), list):
|
|
scope = scope[key]
|
|
break
|
|
if not isinstance(scope, list):
|
|
return []
|
|
return [str(e["scope_entry_id"]) for e in scope if isinstance(e, dict) and e.get("scope_entry_id")]
|
|
|
|
|
|
def scope_sites(scope: Any) -> List[str]:
|
|
"""The sites in an alz-scope.get_scope result: its `sites`, or the entries' own when it lists none."""
|
|
scope = _result(scope)
|
|
if isinstance(scope, dict) and isinstance(scope.get("sites"), list):
|
|
return [str(s) for s in scope["sites"]]
|
|
entries = scope.get("entries") if isinstance(scope, dict) else scope
|
|
return sorted({str(e["site"]) for e in entries or [] if isinstance(e, dict) and e.get("site")})
|
|
|
|
|
|
def _plan_issues(plan: Dict[str, Any], scope: List[str], scan_rps: Optional[float],
|
|
sites: Optional[List[str]] = None) -> List[str]:
|
|
issues: List[str] = []
|
|
tasks = plan.get("tasks") or []
|
|
gaps = plan.get("coverage_gaps") or []
|
|
in_scope = set(scope)
|
|
|
|
# Scope lock: a scan-like task names a scope entry the scope returned.
|
|
for t in tasks:
|
|
if t.get("type") in SCAN_LIKE and str(t.get("target_ref")) not in in_scope:
|
|
issues.append(f"scope_lock: task {t.get('task_id')} targets {t.get('target_ref')!r}, not in scope")
|
|
|
|
# Network coverage: every site has a collect_network task, and no task names another site.
|
|
if sites is not None:
|
|
network = {str(t.get("target_ref")) for t in tasks if t.get("type") == "collect_network"}
|
|
for site in sorted(network - set(sites)):
|
|
issues.append(f"scope_lock: collect_network targets {site!r}, not a site in scope")
|
|
for site in sorted(set(sites) - network):
|
|
issues.append(f"network_coverage: no collect_network task for site {site!r}")
|
|
|
|
# Source sequencing: everything after ingest depends on every ingest task.
|
|
ingest_ids = {t.get("task_id") for t in tasks if t.get("type") in INGEST}
|
|
for t in tasks:
|
|
if t.get("type") in AFTER_INGEST and not ingest_ids <= set(t.get("depends_on") or []):
|
|
issues.append(f"sequencing: task {t.get('task_id')} ({t.get('type')}) does not wait for CMDB/ITSM ingest")
|
|
|
|
# Rate budget per scan batch.
|
|
if scan_rps is not None:
|
|
per_batch: Dict[Any, float] = {}
|
|
for t in tasks:
|
|
if t.get("type") == "scan_target":
|
|
per_batch[t.get("batch")] = per_batch.get(t.get("batch"), 0.0) + float(t.get("declared_rps") or 0)
|
|
for batch, rps in sorted(per_batch.items(), key=lambda kv: str(kv[0])):
|
|
if rps > scan_rps:
|
|
issues.append(f"rate_budget: batch {batch} declares {rps:g} rps, over the {scan_rps:g} budget")
|
|
|
|
# Scope accounting: every entry exactly once, planned or a declared gap.
|
|
planned = {str(t.get("target_ref")) for t in tasks if t.get("type") in SCAN_LIKE}
|
|
gap_ids = {str(g.get("scope_entry_id")) for g in gaps}
|
|
for missing in sorted(in_scope - planned - gap_ids):
|
|
issues.append(f"scope_accounting: {missing} is neither planned nor a declared gap")
|
|
for both in sorted(planned & gap_ids):
|
|
issues.append(f"scope_accounting: {both} is both planned and a declared gap")
|
|
|
|
# Evidence and tool named on every task.
|
|
for t in tasks:
|
|
if not t.get("evidence_artifact"):
|
|
issues.append(f"evidence: task {t.get('task_id')} names no evidence_artifact")
|
|
if not t.get("mcp_tool"):
|
|
issues.append(f"tool: task {t.get('task_id')} names no mcp_tool")
|
|
return issues
|
|
|
|
|
|
def scan_rps_budget(budgets: Any) -> Optional[float]:
|
|
budgets = _result(budgets)
|
|
if isinstance(budgets, dict):
|
|
for key in ("scan_rps", "scan_rps_budget"):
|
|
if isinstance(budgets.get(key), (int, float)):
|
|
return float(budgets[key])
|
|
nested = budgets.get("budgets")
|
|
if isinstance(nested, dict):
|
|
return scan_rps_budget(nested)
|
|
return None
|
|
|
|
|
|
def check_plan(plan_ref: str = "plan/task-graph", scope_ref: str = "plan/scope",
|
|
budgets_ref: str = "plan/budgets") -> dict:
|
|
"""Check a stored task graph against the stored scope and budgets.
|
|
|
|
Call it after dsc_01_planner has answered and before you finish the plan
|
|
phase. The answer is final: report its issues, do not argue with them.
|
|
|
|
Args:
|
|
plan_ref: the planner's task graph in the workspace.
|
|
scope_ref: the alz-scope.get_scope result you stored.
|
|
budgets_ref: the alz-scope.get_budgets result you stored.
|
|
|
|
Returns:
|
|
{"ok": bool, "issues": [...], "scope_entries", "planned", "gaps"}, or {"error": ...}.
|
|
"""
|
|
try:
|
|
run = workspace.current_run()
|
|
plan = workspace.get(run, plan_ref)["content"]
|
|
scope_record = workspace.get(run, scope_ref)["content"]
|
|
scope = scope_ids(scope_record)
|
|
budgets = workspace.get(run, budgets_ref)["content"]
|
|
except workspace.WorkspaceError as exc:
|
|
return {"error": str(exc)}
|
|
if not isinstance(plan, dict):
|
|
return {"error": f"{plan_ref} is not a task graph object"}
|
|
issues = _plan_issues(plan, scope, scan_rps_budget(budgets), scope_sites(scope_record))
|
|
planned = {str(t.get("target_ref")) for t in plan.get("tasks") or [] if t.get("type") in SCAN_LIKE}
|
|
return {"ok": not issues, "issues": issues[:50], "scope_entries": len(scope),
|
|
"planned": len(planned), "gaps": len(plan.get("coverage_gaps") or [])}
|
|
|
|
|
|
# --- dsc_03_inventory --------------------------------------------------------
|
|
|
|
_MATCH = [("serial", 1.0), ("cloud_resource_id", 0.95), ("fqdn", 0.9), ("hostname", 0.7), ("ip", 0.5)]
|
|
|
|
|
|
def match_score(record_a: dict, record_b: dict) -> dict:
|
|
"""How strongly two source records describe the same asset.
|
|
|
|
Compares serial, cloud_resource_id, fqdn, hostname and ip (case-insensitive).
|
|
Merge the records only when `merge` is true; an IP match alone never merges.
|
|
|
|
Args:
|
|
record_a: one source record, with any of the keys above.
|
|
record_b: the other source record.
|
|
|
|
Returns:
|
|
{"score": 0..1, "basis": [keys that matched], "merge": bool}
|
|
"""
|
|
basis, score = [], 0.0
|
|
for key, weight in _MATCH:
|
|
a, b = (record_a or {}).get(key), (record_b or {}).get(key)
|
|
if a and b and str(a).strip().lower() == str(b).strip().lower():
|
|
basis.append(key)
|
|
score = max(score, weight)
|
|
return {"score": score, "basis": basis, "merge": score >= 0.7}
|
|
|
|
|
|
def record_confidence(match_score_value: float, conflict_count: int, source_count: int) -> dict:
|
|
"""A canonical record's confidence, and whether it goes to SME review.
|
|
|
|
Args:
|
|
match_score_value: the score from match_score (1.0 for a single-source record).
|
|
conflict_count: how many fields the sources disagree on.
|
|
source_count: how many source records were merged.
|
|
|
|
Returns:
|
|
{"confidence": 0..1, "sme_review": bool}
|
|
"""
|
|
confidence = float(match_score_value)
|
|
if conflict_count > 0:
|
|
confidence = min(confidence, 0.79)
|
|
if source_count == 1:
|
|
confidence = min(confidence, 0.85)
|
|
return {"confidence": round(confidence, 2), "sme_review": confidence < 0.8}
|
|
|
|
|
|
# --- dsc_04_cmdb_reconciliation ---------------------------------------------
|
|
|
|
def ghost_action(ci_status: str, ci_location: str, unscanned_sites: List[str]) -> dict:
|
|
"""The suggested action for a ghost CI (in the CMDB, not discovered).
|
|
|
|
Args:
|
|
ci_status: the CI's status as recorded, e.g. "operational".
|
|
ci_location: the CI's site as recorded.
|
|
unscanned_sites: sites the plan did not scan.
|
|
|
|
Returns:
|
|
{"suggested_action": "investigate" | "retire_ci", "why": ...}
|
|
"""
|
|
unscanned = {str(s).strip().lower() for s in unscanned_sites or []}
|
|
if str(ci_status).strip().lower() == "operational" and str(ci_location).strip().lower() in unscanned:
|
|
return {"suggested_action": "investigate",
|
|
"why": "operational CI at a site outside scan coverage; it may exist but was not scanned"}
|
|
return {"suggested_action": "retire_ci", "why": "not discovered at a scanned site"}
|
|
|
|
|
|
# --- dsc_05_data_classification ---------------------------------------------
|
|
|
|
_CLASS_ORDER = ["PCI", "PHI", "PII", "none"]
|
|
|
|
|
|
def roll_up_store(column_classes: List[str]) -> dict:
|
|
"""A data store's classification from its columns' classes.
|
|
|
|
Args:
|
|
column_classes: the class of every tagged column: PII, PCI, PHI, none or review_required.
|
|
|
|
Returns:
|
|
{"highest_class", "class_counts", "requires_disposition_controls"}
|
|
"""
|
|
classes = [str(c) for c in column_classes or []]
|
|
counts = {k: classes.count(k) for k in ("PII", "PCI", "PHI", "review_required")}
|
|
highest = next((c for c in _CLASS_ORDER if c in classes), "none")
|
|
return {"highest_class": highest, "class_counts": counts,
|
|
"requires_disposition_controls": highest in ("PCI", "PHI", "PII")}
|
|
|
|
|
|
# --- dsc_06_dependency_mapping ----------------------------------------------
|
|
|
|
_EDGE_BASE = {"trace": 0.9, "flow": 0.85, "config": 0.85, "cmdb_relationship": 0.7, "declared": 0.6}
|
|
|
|
|
|
def score_edge(evidence_kinds: List[str]) -> dict:
|
|
"""An edge's confidence and validation band from the kinds of evidence behind it.
|
|
|
|
Args:
|
|
evidence_kinds: the kind of each piece of evidence: trace, flow, config,
|
|
cmdb_relationship or declared. Repeats are fine.
|
|
|
|
Returns:
|
|
{"confidence": 0..0.99, "validation": auto_approved | sme_review_recommended |
|
|
sme_validation_required}, or {"error": ...} with no usable evidence.
|
|
"""
|
|
kinds = {k for k in (evidence_kinds or []) if k in _EDGE_BASE}
|
|
if not kinds:
|
|
return {"error": "an edge needs at least one piece of evidence of a known kind; do not emit it"}
|
|
confidence = min(max(_EDGE_BASE[k] for k in kinds) + 0.05 * (len(kinds) - 1), 0.99)
|
|
band = ("auto_approved" if confidence >= 0.95 else
|
|
"sme_review_recommended" if confidence >= 0.80 else "sme_validation_required")
|
|
return {"confidence": round(confidence, 2), "validation": band}
|
|
|
|
|
|
def node_metrics(edges: List[dict]) -> dict:
|
|
"""Fan-in, fan-out and retire constraint for every node in a set of edges.
|
|
|
|
Args:
|
|
edges: [{"source": canonical_id, "target": canonical_id}, ...] -- the target
|
|
is the node depended on.
|
|
|
|
Returns:
|
|
{"nodes": [{"canonical_id", "fan_in", "fan_out", "depended_on", "retire_constraint"}]}
|
|
"""
|
|
fan_in: Dict[str, int] = {}
|
|
fan_out: Dict[str, int] = {}
|
|
for e in edges or []:
|
|
s, t = str(e.get("source")), str(e.get("target"))
|
|
fan_out[s] = fan_out.get(s, 0) + 1
|
|
fan_in[t] = fan_in.get(t, 0) + 1
|
|
nodes = []
|
|
for node in sorted(set(fan_in) | set(fan_out)):
|
|
depended = fan_in.get(node, 0) > 0
|
|
nodes.append({"canonical_id": node, "fan_in": fan_in.get(node, 0), "fan_out": fan_out.get(node, 0),
|
|
"depended_on": depended,
|
|
"retire_constraint": "cannot_retire_without_mitigation" if depended else "none"})
|
|
return {"nodes": nodes}
|
|
|
|
|
|
# --- dsc_07_network ---------------------------------------------------------
|
|
|
|
def find_overlaps(ranges: List[dict]) -> dict:
|
|
"""Address ranges at different sites that overlap.
|
|
|
|
Args:
|
|
ranges: [{"cidr": "10.20.0.0/16", "site": "LON-DC1"}, ...]
|
|
|
|
Returns:
|
|
{"overlaps": [{"cidr", "site", "overlap_with": [cidr, ...]}], "invalid": [cidr, ...]}
|
|
"""
|
|
parsed, invalid = [], []
|
|
for r in ranges or []:
|
|
try:
|
|
parsed.append((ipaddress.ip_network(str(r.get("cidr")), strict=False), str(r.get("cidr")), r.get("site")))
|
|
except ValueError:
|
|
invalid.append(str(r.get("cidr")))
|
|
found: Dict[str, Dict[str, Any]] = {}
|
|
for (na, ca, sa), (nb, cb, sb) in combinations(parsed, 2):
|
|
if sa != sb and na.version == nb.version and na.overlaps(nb):
|
|
found.setdefault(ca, {"cidr": ca, "site": sa, "overlap_with": []})["overlap_with"].append(cb)
|
|
found.setdefault(cb, {"cidr": cb, "site": sb, "overlap_with": []})["overlap_with"].append(ca)
|
|
return {"overlaps": list(found.values()), "invalid": invalid}
|
|
|
|
|
|
def bottleneck_severity(p95_utilisation: float, window_days: int) -> dict:
|
|
"""Whether a link is a bottleneck, and how severe.
|
|
|
|
Args:
|
|
p95_utilisation: the link's p95 utilisation as a fraction, e.g. 0.86.
|
|
window_days: how many days the measurement covers.
|
|
|
|
Returns:
|
|
{"bottleneck": bool, "severity": "high" | "medium" | null, "why": ...}
|
|
"""
|
|
if window_days < 14:
|
|
return {"bottleneck": False, "severity": None,
|
|
"why": "fewer than 14 days of measurement; a bottleneck needs a 14-day window"}
|
|
if p95_utilisation >= 0.80:
|
|
return {"bottleneck": True, "severity": "high" if p95_utilisation >= 0.90 else "medium",
|
|
"why": f"p95 {p95_utilisation:.0%} over {window_days} days"}
|
|
return {"bottleneck": False, "severity": None, "why": f"p95 {p95_utilisation:.0%} is under 80%"}
|
|
|
|
|
|
# --- dsc_08_critic ----------------------------------------------------------
|
|
|
|
def coverage(scope: Iterable[str], findings: Iterable[str], declared_gaps: Iterable[str]) -> Dict[str, Any]:
|
|
scope_set: Set[str] = {str(s) for s in scope}
|
|
declared = sorted(scope_set & {str(g) for g in declared_gaps})
|
|
gaps = sorted(scope_set - {str(f) for f in findings} - set(declared))
|
|
return {"coverage_complete": not gaps, "coverage_gaps": gaps, "declared_gaps": declared}
|
|
|
|
|
|
def coverage_check(scope_ids_list: List[str], finding_ids: List[str], declared_gap_ids: List[str]) -> dict:
|
|
"""Coverage of the scope by the findings, measured against the scope list.
|
|
|
|
Args:
|
|
scope_ids_list: every scope_entry_id from alz-scope.get_scope.
|
|
finding_ids: the scope_entry_id of every finding.
|
|
declared_gap_ids: the scope_entry_ids the planner declared as gaps.
|
|
|
|
Returns:
|
|
{"coverage_complete": bool, "coverage_gaps": [...], "declared_gaps": [...]}
|
|
"""
|
|
return coverage(scope_ids_list or [], finding_ids or [], declared_gap_ids or [])
|