"""A live run's discovery plan, built in code from every resource in scope (ADR 0017). The plan is fixed rules over a listing, so no model is called: one scan task per scope entry, a classification task per data store, one network task and one dependency task. A resource the run context excludes, or one outside its regions, is a declared coverage gap. If the listing is incomplete the step fails rather than plan part of the estate. """ from __future__ import annotations import json from typing import Any, Dict, List from app import run_context as rc from app import scope as sc BATCH = 10 SOURCE_IMPACT = { "cmdb": "Owners, cost attribution and business criticality cannot be established from CMDB records.", "itsm": "Change and incident history cannot be established.", "netflow": "Traffic patterns, bottlenecks and unknown traffic sources cannot be shown.", "schema": "Data cannot be classified beyond data-store metadata.", } class ScopeIncomplete(RuntimeError): """The scope couldn't be listed in full: a plan of part of the estate is refused.""" def run_context(source_documents: Any) -> Dict[str, Any]: """The run context file alone, even when other files were uploaded after it (ADR 0018).""" return rc.split(source_documents if isinstance(source_documents, str) else None)["context"] def _last(rid: str) -> str: return rid.rstrip("/").split("/")[-1] def build(payload: Dict[str, Any], call: sc.Call) -> Dict[str, Any]: provider = payload["provider"] doc = run_context(payload.get("source_documents")) ctx = doc.get("context") if isinstance(doc.get("context"), dict) else {} narrowing = ctx.get("scope") if isinstance(ctx.get("scope"), dict) else {} regions = {str(r).lower() for r in (narrowing.get("regions") or [])} exclude = {str(e).lower() for e in (narrowing.get("exclude") or [])} items, refs, issues = sc.list_all(provider, call) if issues: raise ScopeIncomplete("the scope could not be listed in full, so no plan was made: " + "; ".join(issues)) accounting = sc.account(provider, items) planned, gaps = [], [] for entry in accounting["entries"]: name, where = _last(entry["id"]).lower(), sc.region(entry["location"]).lower() if name in exclude or entry["id"].lower() in exclude: gaps.append({"scope_entry_id": entry["id"], "reason_code": "out_of_region", "reason": "excluded by the run context (context.scope.exclude)"}) elif regions and where not in regions: gaps.append({"scope_entry_id": entry["id"], "reason_code": "out_of_region", "reason": f"excluded by the run context: {where or 'no region'} is not in context.scope.regions"}) else: planned.append(entry) tasks: List[Dict[str, Any]] = [] def task(kind: str, agent: str, target: str, tool: str, evidence: str, depends: List[str], batch: Any = None, rps: Any = None) -> str: task_id = f"T-{len(tasks) + 1:03d}" tasks.append({"task_id": task_id, "type": kind, "assigned_agent": agent, "target_ref": target, "mcp_tool": tool, "depends_on": depends, "batch": batch, "declared_rps": rps, "evidence_artifact": evidence}) return task_id scans = {} for index, entry in enumerate(planned): scans[entry["id"]] = task("scan_target", "ALZ-DSC-02", entry["id"], f"{provider}-discovery.{provider}_get_resource_metadata", "resource_metadata.recorded", [], index // BATCH + 1, 1) for entry in planned: if entry["type"] in sc.DATA_STORES.get(provider, ()): task("classify_data", "ALZ-DSC-05", entry["id"], "alz-schema.scan_schema", "data_classification.recorded", [scans[entry["id"]]]) uploaded_cmdb = [u for u in rc.uploads_from(payload.get("source_documents") if isinstance( payload.get("source_documents"), str) else None, "cmdb") if u["text"] and u["text"].strip()] if payload.get("include_cmdb") == "yes": for upload in uploaded_cmdb: # ADR 0018: an uploaded export is the CMDB source, read by ALZ-DSC-04 task("ingest_cmdb", "ALZ-DSC-04", f"upload:{upload['name']}", "parse_assessment_files", "cmdb_cis.recorded", []) if uploaded_cmdb: # ADR 0019: a relationship export is read with the CIs it links text = payload.get("source_documents") if isinstance(payload.get("source_documents"), str) else None for upload in rc.uploads_from(text, "cmdb_relationships"): if upload["text"] and upload["text"].strip(): task("ingest_cmdb_relationships", "ALZ-DSC-04", f"upload:{upload['name']}", "parse_assessment_files", "cmdb_relationships.recorded", []) network = task("collect_network", "ALZ-DSC-07", "scope", "alz-network.collect_topology", "network_topology.recorded", []) task("trace_dependencies", "ALZ-DSC-06", "scope", "alz-dependency.trace", "dependency_graph.recorded", [t["task_id"] for t in tasks if t["task_id"] != network] + [network]) sources = ctx.get("sources") if isinstance(ctx.get("sources"), dict) else {} source_gaps = [] for source, wanted in (("cmdb", payload.get("include_cmdb")), ("itsm", payload.get("include_itsm"))): if source == "cmdb" and wanted == "yes" and uploaded_cmdb: continue # read from the uploaded export(s): not a gap note = f" The run context says: {sources[source]}." if sources.get(source) else "" source_gaps.append({"source": source, "reason": "not_requested" if wanted == "no" else "no_connection", "impact": SOURCE_IMPACT[source] + note}) for source in ("netflow", "schema"): source_gaps.append({"source": source, "reason": "no_connection", "impact": SOURCE_IMPACT[source]}) generated = doc.get("generated") if isinstance(doc.get("generated"), dict) else {} plan_name = (doc.get("plan") or {}).get("name") if isinstance(doc.get("plan"), dict) else None customer = (doc.get("customer") or {}).get("name") if isinstance(doc.get("customer"), dict) else None used = (f'The run context was used for plan "{plan_name}" for customer "{customer}". ' if doc else "No run context was supplied. ") if payload.get("include_cmdb") == "yes" and uploaded_cmdb: used += f"CMDB source: the uploaded {', '.join(u['name'] for u in uploaded_cmdb)}. " note = (used + f"{accounting['listed']} resources were listed under the scope root: {len(accounting['entries'])} " f"scope entries, {len(accounting['folded'])} child components folded into their parents and " f"{len(accounting['structure'])} structural items. {len(planned)} entries are planned; no task has run.") return { "plan_id": generated.get("plan_id") or f"PLAN-{payload.get('run_id') or payload['engagement_id']}", "engagement_id": payload["engagement_id"], "tasks": tasks, "coverage_gaps": gaps, "summary": {"scope_entries": len(accounting["entries"]), "planned": len(planned), "gaps": len(gaps), "scan_batches": (len(planned) + BATCH - 1) // BATCH}, "findings_note": note, "source_gaps": source_gaps, "scope_accounting": {"listed": accounting["listed"], "scope_entries": len(accounting["entries"]), "folded": accounting["folded"], "structure": len(accounting["structure"]), "evidence_refs": refs}, } def reply(payload: Dict[str, Any], call: sc.Call) -> str: return json.dumps(build(payload, call), ensure_ascii=False)