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:
@@ -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))
|
||||
@@ -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)
|
||||
@@ -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]
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user