Files
Jonathan Boniface 8bb62a4a42 ALZ-F01 Discovery sub-agent pattern: report phase and fetch in code
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>
2026-11-05 22:13:25 +00:00

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 [])