"""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", "classify_data", "trace_dependencies", "collect_network"} INGEST = {"ingest_cmdb", "ingest_itsm"} AFTER_INGEST = {"collect_network", "trace_dependencies", "reconcile_cmdb"} def scope_ids(scope: Any) -> List[str]: """The scope_entry_ids in an alz-scope.get_scope result, whichever shape it came back in.""" 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 _plan_issues(plan: Dict[str, Any], scope: List[str], scan_rps: Optional[float]) -> 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") # 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]: 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 = scope_ids(workspace.get(run, scope_ref)["content"]) 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)) 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 [])