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>
This commit is contained in:
2026-11-05 22:13:25 +00:00
parent f659564208
commit 9e503885cc
211 changed files with 18170 additions and 158 deletions

View File

@@ -0,0 +1,13 @@
"""A live run's plan is built in code from every resource in scope (ADR 0017); the sample estate keeps the agent loop."""
from typing import Any, Optional
from kyndryl_agent_runtime.request_cycle import Reply
from kyndryl_agent_runtime.tools import call_tool
from app import plan
def pre_process(payload: dict) -> Optional[Any]:
if payload.get("provider", "sample") not in ("azure", "gcp"):
return None # the Meridian sample estate: prompt.md and the alz-scope tools, unchanged
return Reply(plan.reply(payload, call_tool))

View File

@@ -0,0 +1,136 @@
"""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)

View File

@@ -0,0 +1,109 @@
"""The workflow's upload step, split into the run context file and the files it lists (ADR 0018).
`parse_assessment_files` hands every step one string: the files in upload order, joined by FILE_SEPARATOR, with no
file names in the text. The run context file is always first (kab_run_workflow.py uploads it first), and its
`uploads:` list names the files after it, in order.
This file is identical in the planner, inventory, reconciliation and report agents (a test in each compares it with
the planner's). It knows no column of any file: a table is a header line and one line per row. No runtime imports.
"""
from __future__ import annotations
import re
from typing import Any, Dict, List, Optional, Tuple
import yaml
FILE_SEPARATOR = "\n\n---\n\n" # data_file_processing.FILE_SEPARATOR
SHEET_HEADER = re.compile(r"^=== Sheet: (.*) ===$") # data_file_processing.SHEET_HEADER, one per XLSX sheet
EMPTY_FRAME = "Empty DataFrame" # pandas' rendering of a sheet or CSV with no rows
PARSE_ERRORS = ("Excel parsing error:", "CSV parsing error:", "PDF parsing error:", "Error parsing ",
"[Error parsing file:") # the platform returns a failed parse as text, not an error
ROW_INDEX = r"^\s*(\d+)\s" # pandas puts the row index first on each row line
class UploadUnreadable(ValueError):
"""A listed upload is missing, or the platform couldn't parse it."""
def _yaml(text: str) -> Dict[str, Any]:
try:
data = yaml.safe_load(text)
except yaml.YAMLError:
return {}
return data if isinstance(data, dict) else {}
def _entry(item: Any) -> Dict[str, Any]:
if isinstance(item, dict):
return {"name": str(item.get("name") or ""), "source": str(item.get("source") or "").lower() or None,
"format": item.get("format")}
return {"name": str(item), "source": None, "format": None}
def split(parsed_content: Optional[str]) -> Dict[str, Any]:
"""{"context": the run context as a dict ({} if it isn't YAML), "context_text": its text,
"uploads": [{"name", "source", "format", "text"}] for each entry in its `uploads:`, in order}.
The text is split at most once per listed upload, so a separator inside the last upload never cuts it short.
A listed upload with no part of its own has text None.
"""
text = parsed_content or ""
first = text.split(FILE_SEPARATOR, 1)[0]
doc = _yaml(first)
listed = doc.get("uploads") if isinstance(doc.get("uploads"), list) else []
parts = text.split(FILE_SEPARATOR, len(listed)) if listed else [text]
uploads = []
for index, item in enumerate(listed, start=1):
entry = _entry(item)
entry["text"] = parts[index] if index < len(parts) else None
uploads.append(entry)
return {"context": doc, "context_text": parts[0], "uploads": uploads}
def context_section(parsed_content: Optional[str]) -> Dict[str, Any]:
"""The run context's `context:` section, or {}."""
section = split(parsed_content)["context"].get("context")
return section if isinstance(section, dict) else {}
def uploads_from(parsed_content: Optional[str], source: str) -> List[Dict[str, Any]]:
"""The listed uploads whose `source:` is this one (e.g. cmdb)."""
return [u for u in split(parsed_content)["uploads"] if u["source"] == source]
def _rows(lines: List[str]) -> List[Tuple[int, str]]:
found = [re.match(ROW_INDEX, line) for line in lines]
numbers = [int(m.group(1)) for m in found if m]
if len(numbers) == len(lines) and len(set(numbers)) == len(numbers):
return list(zip(numbers, lines))
return list(enumerate(lines)) # not a pandas table (a raw CSV, say): number rows by position
def _table(sheet: Optional[str], lines: List[str]) -> Dict[str, Any]:
lines = [line.rstrip() for line in lines if line.strip()]
if not lines or lines[0].strip().startswith(EMPTY_FRAME):
return {"sheet": sheet, "header": lines[0] if lines else "", "rows": []}
return {"sheet": sheet, "header": lines[0], "rows": _rows(lines[1:])}
def tables(upload: Dict[str, Any]) -> List[Dict[str, Any]]:
"""[{"sheet": name or None, "header": the header line, "rows": [(row number, line)]}] for one upload.
Raises UploadUnreadable for a missing upload or one the platform failed to parse."""
text = upload.get("text")
if text is None or not text.strip():
raise UploadUnreadable(f"{upload.get('name')}: listed in the run context's uploads but not uploaded")
if text.strip().startswith(PARSE_ERRORS):
raise UploadUnreadable(f"{upload.get('name')}: the platform could not parse it: {text.strip()[:200]}")
sheets: List[Tuple[Optional[str], List[str]]] = []
current: Tuple[Optional[str], List[str]] = (None, [])
for line in text.split("\n"):
header = SHEET_HEADER.match(line.strip())
if header:
if current[0] is not None or any(x.strip() for x in current[1]):
sheets.append(current)
current = (header.group(1), [])
else:
current[1].append(line)
sheets.append(current)
return [_table(sheet, lines) for sheet, lines in sheets]

View File

@@ -0,0 +1,111 @@
"""A live run's scope: every resource under the connection's scope root (ADR 0017).
The planner plans from this listing and the critic checks coverage against its own run of it, so both copies of
this file must stay identical (tests/test_scope.py in each agent compares them). No runtime imports.
Every resource listed ends in exactly one place:
- a scope entry: an asset the run scans, inventories and reports;
- folded: a child component recorded with its parent's rule (a disk, a network interface, a node pool), never
dropped;
- structure: the estate's subscriptions, resource groups, projects and folders, which are not assets.
"""
from __future__ import annotations
from typing import Any, Callable, Dict, List, Optional, Tuple
PAGE_SIZE = 200 # the servers' maximum page
MAX_PAGES = 100 # 20,000 resources bounds a runaway; the largest estate seen so far is about 650
STRUCTURE = {
"azure": ("microsoft.resources/subscriptions", "microsoft.resources/subscriptions/resourcegroups",
"microsoft.management/managementgroups"),
"gcp": ("cloudresourcemanager.googleapis.com/project", "cloudresourcemanager.googleapis.com/folder",
"cloudresourcemanager.googleapis.com/organization"),
}
FOLDED = {
"azure": {
"microsoft.compute/disks": "a disk is part of the VM it is attached to",
"microsoft.network/networkinterfaces": "a network interface is part of the resource it is attached to",
"microsoft.compute/virtualmachines/extensions": "an extension is part of its VM",
"microsoft.compute/virtualmachinescalesets/virtualmachines": "an instance is part of its scale set",
},
"gcp": {
"compute.googleapis.com/disk": "a disk is part of the instance it is attached to",
"container.googleapis.com/nodepool": "a node pool is part of its cluster",
},
}
DATA_STORES = { # the types the servers' list_data_stores kinds cover; each gets a classify_data task
"azure": ("microsoft.sql/servers", "microsoft.sql/servers/databases", "microsoft.documentdb/databaseaccounts",
"microsoft.storage/storageaccounts", "microsoft.dbforpostgresql/flexibleservers",
"microsoft.dbforpostgresql/servers", "microsoft.dbformysql/flexibleservers",
"microsoft.dbformysql/servers", "microsoft.cache/redis", "microsoft.cache/redisenterprise"),
"gcp": ("sqladmin.googleapis.com/instance", "firestore.googleapis.com/database", "storage.googleapis.com/bucket"),
}
Call = Callable[[str, Dict[str, Any]], Any]
def identity(provider: str, item: Dict[str, Any]) -> Tuple[str, str, str]:
"""(id, type in lower case, location) of one listed resource."""
if provider == "gcp":
return str(item.get("name") or ""), str(item.get("assetType") or "").lower(), str(item.get("location") or "")
return str(item.get("id") or ""), str(item.get("type") or "").lower(), str(item.get("location") or "")
def _data(result: Any) -> Dict[str, Any]:
if isinstance(result, str):
import json
result = json.loads(result)
if not isinstance(result, dict) or result.get("success") is False:
error = (result or {}).get("error") if isinstance(result, dict) else None
raise RuntimeError((error or {}).get("message") or "the tool refused the call")
return result.get("data") or {}
def list_all(provider: str, call: Call) -> Tuple[List[Dict[str, Any]], List[str], List[str]]:
"""(every resource listed, evidence refs, issues). An issue means the listing is incomplete."""
tool = f"{provider}_list_resources"
items: List[Dict[str, Any]] = []
refs: List[str] = []
token: Optional[str] = None
for _ in range(MAX_PAGES):
args: Dict[str, Any] = {"page_size": PAGE_SIZE}
if token:
args["page_token"] = token
try:
data = _data(call(tool, args))
except Exception as error: # noqa: BLE001 - a refused or failed page is an incomplete listing
return items, refs, [f"{tool}: {str(error)[:200]}"]
items += list(data.get("items") or [])
if data.get("evidence_ref"):
refs.append(data["evidence_ref"])
token = data.get("next_page_token")
if not token:
return items, refs, []
return items, refs, [f"{tool}: stopped after {MAX_PAGES} pages"]
def account(provider: str, items: List[Dict[str, Any]]) -> Dict[str, Any]:
"""Every listed resource in exactly one place: entries, folded or structure. Repeats are counted once."""
entries, folded, structure, seen = [], [], [], set()
for item in items:
rid, rtype, location = identity(provider, item)
if not rid or rid in seen:
continue
seen.add(rid)
if rtype in STRUCTURE.get(provider, ()):
structure.append(rid)
elif rtype in FOLDED.get(provider, {}):
folded.append({"id": rid, "type": rtype, "reason": FOLDED[provider][rtype]})
else:
entries.append({"id": rid, "type": rtype, "location": location})
entries.sort(key=lambda e: e["id"].lower())
return {"listed": len(seen), "entries": entries, "folded": folded, "structure": structure}
def region(location: str) -> str:
"""A GCP zone such as europe-west2-b is its region europe-west2; anything else is used as it is."""
parts = location.split("-")
if len(parts) == 3 and len(parts[2]) == 1 and parts[2].isalpha():
return "-".join(parts[:2])
return location