Files
Jonathan Boniface 9e503885cc ALZ-F01 Discovery: package step, value scorecard, application grouping, cases
- New cp1-discovery-package-agent (ADR 0020): one package per reviewed run, every part
  hashed (sha256 over canonical JSON), with a manifest and a value scorecard.
- Applications grouped CMDB -> tag -> resource group with a judged model fallback (ADR 0021):
  CMDB 0.7.0 carries ownership, dependency mapping 0.6.0 groups, report 0.9.0 shows them.
- Critic 0.6.1 accepts the producers' enums; build_workflow.py refuses a consumer enum
  narrower than its producer's.
- Code hooks, sub-agents and tests for the inventory, CMDB, dependency, planner and critic
  agents; the report and Well-Architected review agents; ADRs 0012-0021.
- Workflow cases with value bars and run limits; run evaluation and usage collection scripts;
  the run context template and the field-by-field review for ADR 0016.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-05 22:13:25 +00:00

137 lines
7.6 KiB
Python

"""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)