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

535 lines
36 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""The Discovery report, rendered from the step outputs as Markdown and HTML.
No model is involved, so it holds only what the steps recorded. `build` gathers the content once, so the two formats
can't disagree. Step outputs are data: every value is escaped before it reaches a page.
"""
import html
import re
from datetime import date
from typing import Any, Dict, List, Optional
from app import run_context as rc
SEVERITY = {"high": 0, "medium": 1, "low": 2}
# Values that need a reader's attention are shown as a coloured label in the HTML.
TONES = {"high": "bad", "fail": "bad", "pci": "bad", "retire_ci": "bad", "sme_validation_required": "bad",
"medium": "warn", "investigate": "warn", "sme_review_recommended": "warn", "pii": "warn", "unclassified": "warn",
"low": "ok", "pass": "ok", "auto_approved": "ok"}
STYLE = """
/* A customer deliverable: a cover band, the verdict and priorities first, then numbered sections that print cleanly. */
:root {
--ground: #f4f6f8; --surface: #ffffff; --ink: #16202c; --muted: #566373; --line: #dbe1e8; --band: #10283f; --band-ink: #f2f6fa;
--band-muted: #b5c4d3; --accent: #1b6496;
--bad: #9f2229; --bad-bg: #fbe8e9; --warn: #855700; --warn-bg: #fcf0d5; --ok: #1a6640; --ok-bg: #e1f2e8;
--sans: "Segoe UI", system-ui, -apple-system, Roboto, "Helvetica Neue", Arial, sans-serif;
--serif: Georgia, "Times New Roman", serif;
}
@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) {
--ground: #10161d; --surface: #182029; --ink: #e6ebf1; --muted: #9dabb9; --line: #2e3945; --band: #0b1f33; --accent: #84bbe0;
--bad: #ff9fa3; --bad-bg: #40191d; --warn: #f0c46e; --warn-bg: #3a2c10; --ok: #84d9a8; --ok-bg: #153223; color-scheme: dark;
} }
:root[data-theme="dark"] {
--ground: #10161d; --surface: #182029; --ink: #e6ebf1; --muted: #9dabb9; --line: #2e3945; --band: #0b1f33; --accent: #84bbe0;
--bad: #ff9fa3; --bad-bg: #40191d; --warn: #f0c46e; --warn-bg: #3a2c10; --ok: #84d9a8; --ok-bg: #153223; color-scheme: dark;
}
* { box-sizing: border-box; }
body { margin: 0; background: var(--ground); color: var(--ink); font: 16px/1.55 var(--sans); }
.wrap { max-width: 68rem; margin: 0 auto;
padding-left: max(16px, env(safe-area-inset-left, 0px)); padding-right: max(16px, env(safe-area-inset-right, 0px)); }
.cover { background: var(--band); color: var(--band-ink); }
.cover .wrap { padding-block: 3rem 2.5rem; display: grid; gap: .6rem; }
.eyebrow { margin: 0; color: var(--band-muted); font-size: .8rem; letter-spacing: .08em; text-transform: uppercase; }
h1 { margin: 0; font: 400 2.6rem/1.15 var(--serif); text-wrap: balance; }
.cover .meta { margin: 0; color: var(--band-muted); font-size: .95rem; }
main.wrap { padding-block: 2rem 4rem; display: grid; gap: 2.5rem; }
main > * { min-width: 0; }
h2 { margin: 0 0 .75rem; font: 400 1.5rem/1.25 var(--serif); text-wrap: balance; }
.num { color: var(--muted); margin-right: .5rem; font-variant-numeric: tabular-nums; }
.intro { margin: 0 0 .75rem; max-width: 65ch; color: var(--muted); }
.notice { margin: 0; padding: .75rem 1rem; border-radius: 4px; background: var(--warn-bg); color: var(--warn); }
.notice.bad { background: var(--bad-bg); color: var(--bad); font-weight: 600; }
.status { display: flex; flex-wrap: wrap; gap: .5rem .75rem; align-items: center; margin: 0 0 1rem; }
.figures { display: grid; grid-template-columns: repeat(4, 1fr); gap: 1px; margin: 0;
background: var(--line); border: 1px solid var(--line); }
.figures div { background: var(--surface); padding: .8rem 1rem; }
.figures dt { color: var(--muted); font-size: .8rem; }
.figures dd { margin: 0; font: 400 2rem/1.2 var(--serif); font-variant-numeric: tabular-nums; }
nav ol { margin: 0; padding-left: 1.4rem; columns: 2 16rem; font-size: .92rem; }
nav a, .link { color: var(--accent); }
a:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
.scroll { overflow-x: auto; background: var(--surface); border: 1px solid var(--line); }
table { border-collapse: collapse; width: 100%; font-size: .9rem; }
th { text-align: left; color: var(--muted); font-size: .8rem; font-weight: 600; white-space: nowrap; }
th, td { padding: .55rem .8rem; border-bottom: 1px solid var(--line); vertical-align: top; }
tr:last-child td { border-bottom: 0; }
td { font-variant-numeric: tabular-nums; }
.pill { display: inline-block; padding: 0 .45rem; border-radius: 3px; font-size: .8rem; font-weight: 600; white-space: nowrap; }
.pill.bad { background: var(--bad-bg); color: var(--bad); }
.pill.warn { background: var(--warn-bg); color: var(--warn); }
.pill.ok { background: var(--ok-bg); color: var(--ok); }
.empty { margin: 0; color: var(--muted); }
ul { margin: 0; padding-left: 1.2rem; }
@media (max-width: 40rem) { .figures { grid-template-columns: repeat(2, 1fr); } }
@media (max-width: 30rem) { h1 { font-size: 2rem; } }
@media print {
body { background: #fff; font-size: 11pt; }
.cover { print-color-adjust: exact; -webkit-print-color-adjust: exact; }
.pill, .notice { print-color-adjust: exact; -webkit-print-color-adjust: exact; }
nav { display: none; }
section { break-inside: avoid-page; }
tr { break-inside: avoid; }
.scroll { overflow: visible; }
}
"""
SOURCES = {"cmdb": "CMDB", "itsm": "Service management (ITSM)", "netflow": "Traffic and link data", "schema": "Database schemas"}
WHY = {"not_requested": "Not requested for this run", "no_connection": "No connection available"}
NOT_CHECKED = {"cmdb": "Not checked: the CMDB wasn't used in this run.", "itsm": "Not checked: service management data wasn't used in this run.",
"netflow": "Traffic and link measurements weren't available, so these findings come from topology only, and none were raised.",
"schema": "Not checked: no database schemas were available."}
def _table(title: str, headers: List[str], rows: List[List[Any]], empty: str) -> Dict[str, Any]:
return {"title": title, "headers": headers, "rows": rows, "empty": empty}
def _freeze(freeze: Any) -> Any:
"""The change that froze an asset, or None: an inactive freeze still arrives as an object."""
if not isinstance(freeze, dict):
return freeze
return f"{freeze.get('change_ref')} until {freeze.get('until')}" if freeze.get("active") else None
def counts(data: Dict[str, Any]) -> Dict[str, int]:
return {"records": len(data.get("records") or []), "declared_gaps": len(data.get("coverage_gaps") or []),
"drift_items": len(data.get("drift_items") or []), "stores": len(data.get("stores") or []),
"network_findings": len(data.get("network_findings") or []), "edges": len(data.get("edges") or []),
"sme_edges": len(data.get("validation_queue") or [])}
def build(data: Dict[str, Any], notice: Optional[str] = None) -> Dict[str, Any]:
"""Everything the report says, ready for either format."""
verdict = data.get("verdict") or "not supplied"
records, scan = data.get("records") or [], data.get("scan_findings") or []
network = sorted(data.get("network_findings") or [], key=lambda f: SEVERITY.get(f.get("severity"), 3))
total = counts(data)
scanned = {f.get("scope_entry_id") for f in scan}
gaps = {g.get("source"): g.get("impact") for g in data.get("source_gaps") or []}
why = {g.get("source"): WHY.get(g.get("reason"), "Not available") for g in data.get("source_gaps") or []}
warnings = []
if gaps:
warnings.append("Not every source was used. Sections marked as not checked hold no findings because they weren't examined.")
if verdict != "pass":
warnings.append("This run didn't pass the critic. Treat every finding below as unconfirmed.")
if data.get("obeyed_injection"):
warnings.append("The critic found output that reflects an injected instruction.")
conflicts = [[r.get("canonical_id"), c.get("field"), "; ".join(str(v.get("value")) for v in c.get("values") or [])]
for r in records for c in r.get("conflicts") or []]
owner_of = {o.get("canonical_id"): o.get("owner") for o in data.get("asset_owners") or []}
apps = data.get("applications") or []
held = [[n.get("canonical_id"), n.get("fan_in"), n.get("fan_out")] for n in data.get("nodes") or []
if n.get("retire_constraint") == "cannot_retire_without_mitigation"]
tables = [
_table("Sources not checked", ["Source", "Why", "What that means"], [[SOURCES.get(k, k), why[k], v] for k, v in gaps.items()], "Every source was available."),
_table("Coverage gaps", ["Scope entry", "Reason code", "Reason"],
[[g.get("scope_entry_id"), g.get("reason_code"), g.get("reason")] for g in data.get("coverage_gaps") or []],
"No coverage gaps were declared."),
_table("Inventory", ["Asset", "Hostname", "Class", "Site", "OS", "Owner", "Scanned", "Confidence"],
[[r.get("canonical_id"), r.get("hostname"), r.get("asset_class"), (r.get("facts") or {}).get("site"),
" ".join(dict.fromkeys(str(v) for v in (r.get("os") or {}).values())),
owner_of.get(r.get("canonical_id")) or (r.get("facts") or {}).get("owner"),
"yes" if r.get("scope_entry_id") in scanned else "no", r.get("confidence")] for r in records],
"No inventory was supplied."),
]
tables[2:2] = _estate_tables(data, records) # overview first, then the inventory and its detail
if apps or data.get("ungrouped_assets"): # ADR 0021: right after the inventory
tables.insert(tables.index(next(x for x in tables if x["title"] == "Inventory")) + 1, _table(
"Applications", ["Id", "Application", "Grouped by", "Assets", "Owner", "Review"],
[[a.get("application_id"), a.get("name"), BASIS.get(a.get("basis"), a.get("basis")), len(a.get("members") or []),
a.get("owner") or ("owners disagree" if a.get("owners_disagree") else "-"),
"; ".join(a.get("review_reasons") or []) if a.get("review_required") else "no"] for a in apps]
+ [["-", "Not grouped", "-", len(data.get("ungrouped_assets") or []), "-", ", ".join(data.get("ungrouped_assets") or [])]]
* bool(data.get("ungrouped_assets")),
"No applications were grouped."))
if conflicts:
tables.append(_table("Source conflicts", ["Asset", "Field", "Values"], conflicts, ""))
tables += [
_table("Migration risks", ["Scope entry", "Hostname", "Risk"],
[[f.get("scope_entry_id"), f.get("hostname"), risk] for f in scan for risk in f.get("migration_risks") or []],
"No migration risks were recorded."),
_table("Prompt injection", ["Scope entry", "Text found in the data, quoted and not acted on"],
[[f.get("scope_entry_id"), f.get("injection_note")] for f in scan if f.get("prompt_injection_detected")]
+ [["CMDB upload", note] for note in data.get("cmdb_injections") or []],
"None was detected."),
_table("CMDB files read", ["File", "Sheet", "Rows", "CIs", "Rows that are not CIs"],
[[s.get("file"), s.get("sheet") or "-", s.get("rows"), s.get("cis"), s.get("skipped")]
for s in data.get("cmdb_sources") or []],
NOT_CHECKED["cmdb"] if "cmdb" in gaps else "No CMDB export was uploaded to this run."),
_table("CMDB drift", ["Id", "Type", "Asset", "CMDB record", "Field", "Discovered", "CMDB", "Suggested action"],
[[d.get("drift_id"), d.get("type"), d.get("canonical_id") or "-", d.get("ci_ref") or "-", d.get("field"),
d.get("discovered_value"), d.get("cmdb_value"), d.get("suggested_action")] for d in data.get("drift_items") or []],
NOT_CHECKED["cmdb"] if "cmdb" in gaps else "No drift was reported."),
_table("ITSM signals", ["Asset", "Incidents", "P1 and P2", "Failed changes", "Active freeze"],
[[s.get("canonical_id"), s.get("incidents_total"), s.get("incidents_p1_p2"), s.get("changes_failed"),
_freeze(s.get("active_freeze"))] for s in data.get("itsm_signals") or []],
NOT_CHECKED["itsm"] if "itsm" in gaps else "No ITSM signals were reported."),
_table("Data classification", ["Asset", "Store", "Highest class", "Disposition controls", "Reason"],
[[s.get("canonical_id"), s.get("store_name"), s.get("highest_class"),
"yes" if s.get("requires_disposition_controls") else "no", s.get("reason")] for s in data.get("stores") or []],
NOT_CHECKED["schema"] if "schema" in gaps else "No data stores were classified."),
_table("Address ranges", ["Range", "Site", "Segment", "Overlaps"],
[[x.get("cidr"), x.get("site"), x.get("segment"), x.get("overlap_with")] for x in data.get("ranges") or []],
"No address ranges were collected."),
_table("Network findings", ["Id", "Severity", "Type", "Subject", "Measurement", "Window"],
[[f.get("finding_id"), f.get("severity"), f.get("type"), f.get("subject"), f.get("measurement"), f.get("window")] for f in network],
NOT_CHECKED["netflow"] if "netflow" in gaps else "No network findings were reported."),
_table("Dependencies", ["Id", "Source", "Target", "Type", "Port", "Confidence", "Validation"],
[[e.get("edge_id"), e.get("source"), e.get("target"), e.get("type"), e.get("protocol_port"), e.get("confidence"),
e.get("validation")] for e in data.get("edges") or [] if e.get("type") != "represents"],
"No dependencies were reported."),
_table("Dependencies outside this discovery", ["Resource", "Type", "Resource group or project", "Depended on by"],
[[n.get("id"), n.get("type"), n.get("container"), n.get("referenced_by")]
for n in data.get("nodes") or [] if n.get("kind") == "external"],
"No dependency points outside the scope."),
_table("CMDB relationships compared with the cloud", ["Result", "CMDB parent", "CMDB child", "Cloud source", "Cloud target"],
[[COMPARISON.get(c.get("result"), c.get("result")), c.get("parent_ci"), c.get("child_ci"),
c.get("source_resource") or c.get("source"), c.get("target_resource") or c.get("target")]
for c in data.get("graph_comparison") or []],
NOT_CHECKED["cmdb"] if "cmdb" in gaps else "No CMDB relationships were compared."),
_table("CMDB relationships that point at no CI", ["Parent", "Child", "Relationship", "Not found"],
[[d.get("parent"), d.get("child"), d.get("type_raw"), d.get("unresolved")] for d in data.get("dangling") or []],
NOT_CHECKED["cmdb"] if "cmdb" in gaps else "None."),
_table("Can't be retired without mitigation", ["Asset", "Depended on by", "Depends on"], held, "No asset has this constraint."),
]
waf = data.get("waf_pillars") or []
if waf or data.get("waf_status"):
tables.append(_table("Well-Architected review", ["Pillar", "Status", "Checks passed", "Checks failed", "No evidence"],
[[w.get("title"), WAF_STATUS.get(w.get("status"), w.get("status")), w.get("checks_passed"), w.get("checks_failed"),
w.get("checks_no_evidence")] for w in waf],
data.get("waf_note") or "The Well-Architected review was not applicable to this estate."))
not_examined = [t["title"] for t in tables if not t["rows"] and t["empty"] in NOT_CHECKED.values()]
tables = [t for t in tables if t["title"] not in not_examined]
issues = [[kind.replace("_", " "), item] for kind in ("consistency_issues", "unsupported_claims", "tool_call_issues", "parse_failures")
for item in data.get(kind) or []]
return {"engagement": data.get("engagement_id"), "run": data.get("run_id"), "verdict": verdict, "notice": notice, "warnings": warnings,
"scope_entries": (data.get("plan_summary") or {}).get("scope_entries"),
"gaps": gaps, "figures": [("Assets", total["records"]), ("Sources not checked", len(gaps)), ("Coverage gaps", total["declared_gaps"]), ("CMDB differences", total["drift_items"]),
("Data stores", total["stores"]), ("Network findings", total["network_findings"]),
("High severity", sum(1 for f in network if f.get("severity") == "high")),
("Dependencies", total["edges"]), ("Awaiting SME review", total["sme_edges"])]
+ ([("Applications", len(apps))] if apps else []),
"tables": tables,
"review": [("Inventory records", data.get("sme_review_queue")), ("Dependency edges", data.get("validation_queue")),
("Assets with no dependencies found", data.get("orphans"))]
+ ([("Application groups", [a.get("name") for a in apps if a.get("review_required")])] if apps else []),
"critic_note": data.get("critic_note"), "issues": issues, "not_examined": not_examined,
"provider": data.get("provider") or "sample", "edges": data.get("edges") or [], "records": records,
"nodes": data.get("nodes") or [],
"context": _upload(data)["context_text"].strip(), "declared": _declared(data.get("source_documents"))}
def _upload(data: Dict[str, Any]) -> Dict[str, Any]:
"""The run context file alone, and the files it lists (ADR 0018). The uploads' text is never shown raw."""
text = data.get("source_documents")
return rc.split(text if isinstance(text, str) else None)
WAF_STATUS = {"reviewed": "Reviewed", "attention": "Needs attention", "not_assessed": "Not assessed"}
BASIS = {"cmdb_business_service": "CMDB business service", "tag": "Application tag", "container": "Resource group or project",
"model": "Proposed by the model"}
SHOWN = ("type", "resource_type", "region", "zone", "machine_type", "size", "state", "status", "os_image", "public_address",
"deletion_protection", "secure_boot", "encryption", "backups", "versioning", "labels", "tags")
def _fact(value: Any) -> str:
if isinstance(value, dict):
return ", ".join(f"{k}={v}" for k, v in value.items())
if isinstance(value, (list, tuple)):
return ", ".join(str(v) for v in value)
return str(value)
def _attrs(record: Dict[str, Any]) -> str:
"""A record's provider facts, the useful ones first, as `key: value` pairs."""
pa = record.get("provider_attributes") or {}
keys = [k for k in SHOWN if k in pa] + [k for k in pa if k not in SHOWN]
return "; ".join(f"{k}: {_fact(pa[k])}" for k in keys[:12])
def _estate_tables(data: Dict[str, Any], records: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
"""The estate overview, asset detail and network topology, for a live run (nothing for the sample)."""
if (data.get("provider") or "sample") == "sample":
return []
sites = sorted({str((r.get("facts") or {}).get("site")) for r in records if (r.get("facts") or {}).get("site")})
classes: Dict[str, int] = {}
for r in records:
classes[r.get("asset_class") or "unknown"] = classes.get(r.get("asset_class") or "unknown", 0) + 1
overview = [["Provider", data.get("provider")], ["Regions", sites or "-"]] + [[f"Assets: {k}", v] for k, v in sorted(classes.items())]
detail = [[r.get("canonical_id"), r.get("hostname"), r.get("asset_class"), (r.get("facts") or {}).get("site"), _attrs(r)] for r in records]
topo = [[k.replace("_", " "), v] for k, v in sorted((data.get("topology_summary") or {}).items())]
return [_table("Estate overview", ["Item", "Value"], overview, ""),
_table("Asset details", ["Asset", "Name", "Class", "Region", "Provider facts"], detail, "No provider facts were recorded."),
_table("Network topology", ["Kind", "Items read"], topo, "No topology summary was recorded.")]
def _declared(text: Any) -> List[Any]:
"""The run context file's `customer:`, `plan:` and `generated:` sections as tables; nothing if it can't be read."""
parsed = rc.split(text if isinstance(text, str) else None)
doc = parsed["context"]
out = []
for key, title in (("customer", "Customer"), ("plan", "Engagement plan"), ("generated", "Run identifiers")):
section = doc.get(key) if isinstance(doc, dict) else None
if isinstance(section, dict) and section:
out.append((title, [[k.replace("_", " ").capitalize(), _fact(v) if v not in ("", [], {}, None) else "-"]
for k, v in section.items()]))
if parsed["uploads"]:
out.append(("Uploaded files", [[u["name"], f"{u['source'] or 'unspecified'} source"
+ ("" if u["text"] else ", not received")] for u in parsed["uploads"]]))
return out
UNSAFE = re.compile(r"[^\w .:/-]")
COMPARISON = {"confirmed": "Confirmed by the cloud", "cmdb_only": "In the CMDB only",
"discovered_only": "Missing from the CMDB", "not_comparable": "Can't be compared"}
def _mermaid(records: List[Dict[str, Any]], edges: List[Dict[str, Any]],
nodes: Optional[List[Dict[str, Any]]] = None) -> List[str]:
"""The one dependency graph as Mermaid lines (ADR 0019). Nodes are numbered and labelled by name, with punctuation
removed, and drawn by kind: a resource as a box, an external resource dashed, a CMDB CI as a hexagon. A CI's
`represents` link to its resource is dotted."""
names = {r.get("canonical_id"): r.get("hostname") or r.get("canonical_id") for r in records}
kinds = {}
for n in nodes or []:
names[n.get("id")] = (f"{n.get('ci_ref')} {n.get('name') or ''}".strip() if n.get("kind") == "ci"
else n.get("name") or n.get("id"))
kinds[n.get("id")] = n.get("kind")
ids: Dict[str, str] = {}
def node(value: Any) -> str:
key = str(value)
if key not in ids:
ids[key] = f"n{len(ids) + 1}"
return ids[key]
links = [f" {node(e.get('source'))} -.->|represents| {node(e.get('target'))}" if e.get("type") == "represents" else
f" {node(e.get('source'))} -->|{UNSAFE.sub('', str(e.get('type') or ''))}| {node(e.get('target'))}" for e in edges]
labels, styled = [], []
for key, n in ids.items():
label = UNSAFE.sub("", str(names.get(key, key)).rsplit("/", 1)[-1])
kind = kinds.get(key, "resource")
labels.append(f' {n}{{{{"{label}"}}}}' if kind == "ci" else f' {n}["{label}"]')
if kind in ("external", "ci"):
styled.append(f" class {n} {kind}")
classes = ([" classDef external stroke-dasharray: 5 5", " classDef ci fill:#eef"] if styled else [])
return labels + links + classes + styled
def cell(value: Any) -> str:
"""One value, safe in a Markdown table."""
if value is None or value == "" or value == []:
return "-"
if isinstance(value, (list, tuple)):
value = ", ".join(str(v) for v in value)
text = " ".join(str(value).split())
for char in ("\\", "|", "`", "*", "_", "<", ">", "[", "]"):
text = text.replace(char, f"\\{char}")
return text
def _md_table(headers: List[str], rows: List[List[Any]]) -> List[str]:
return ["| " + " | ".join(headers) + " |", "|" + "---|" * len(headers)] + ["| " + " | ".join(cell(v) for v in row) + " |" for row in rows]
def render(data: Dict[str, Any], notice: Optional[str] = None) -> str:
"""The report as Markdown."""
r = build(data, notice)
lines = [f"# Discovery report: {cell(r['engagement'])}", ""]
lines += [f"> {cell(notice)}", ""] if notice else []
lines += _md_table(["Item", "Value"], [["Run", r["run"]], ["Provider", r["provider"]], ["Critic verdict", r["verdict"]],
["Scope entries", r["scope_entries"]]]) + [""]
for warning in r["warnings"]:
lines += [f"> **{warning}**", ""]
lines += ["## Summary", ""] + [f"- {label}: {value}" for label, value in r["figures"]] + [""]
for t in r["tables"]:
lines += [f"## {t['title']}", ""] + (_md_table(t["headers"], t["rows"]) if t["rows"] else [t["empty"]]) + [""]
if r["not_examined"]:
lines += ["## Not examined", "", "These sections hold nothing because their source wasn't available in this run, not because they're clean:", ""]
lines += [f"- {cell(title)}" for title in r["not_examined"]] + [""]
if r["edges"]:
lines += ["## Dependency diagram", "", "```mermaid", "flowchart LR", *_mermaid(r["records"], r["edges"], r["nodes"]), "```", ""]
for title, rows in r["declared"]:
lines += [f"## {title}", ""] + _md_table(["Item", "Value"], rows) + [""]
if r["context"]:
lines += ["## Run context", "", "The parameters and context this run was started with:", "", "```yaml", r["context"].replace("```", "ʼʼʼ"), "```", ""]
lines += ["## For a person to review", ""] + [f"- {label}: {cell(value)}" for label, value in r["review"]] + [""]
lines += ["## Critic", "", f"Verdict: **{cell(r['verdict'])}**. {cell(r['critic_note'])}", ""]
lines += _md_table(["Check", "Issue"], r["issues"]) + [""] if r["issues"] else ["The critic reported no issues.", ""]
return "\n".join(lines)
# The HTML is written for the customer, so internal codes become plain words.
LABELS = {"sme_validation_required": "Your team must confirm", "sme_review_recommended": "Review recommended",
"auto_approved": "Confirmed by evidence", "retire_ci": "Retire the record", "add_ci": "Add to CMDB",
"update_attribute": "Update the record", "investigate": "Investigate", "stale_attribute": "Out-of-date record",
"orphan": "Found, but not in CMDB", "ghost": "In CMDB, but not found", "app_to_app": "Application to application",
"app_to_db": "Application to database", "app_to_shared_service": "Application to shared service",
"hosted_on": "Hosted on", "address_overlap": "Overlapping addresses", "unknown_source": "Unknown source",
"legacy_protocol": "Legacy protocol", "unowned_rule": "Firewall rule with no owner", "bottleneck": "Capacity bottleneck",
"single_point_of_failure": "Single point of failure", "unsupported_device": "Unsupported device",
"crypto_appliance": "Cryptographic appliance", "network_device": "Network device", "high": "High", "medium": "Medium",
"low": "Low", "server": "Server", "database": "Database", "unknown": "Unknown", "yes": "Yes", "no": "No",
"os": "Operating system", "pass": "Passed", "fail": "Not passed", "pci": "Payment card data", "pii": "Personal data",
"unclassified": "Not yet classified", "network_attachment": "Attached to network", "storage_array": "Storage",
"cloud_resource": "Cloud resource", "none": "None"}
GAPS = {"unsupported_asset_class": "This asset type has no read-only scan interface, so it couldn't be scanned.",
"no_connector": "No data connection was available for this asset.",
"no_read_only_credential": "No read-only access was available for this asset.",
"out_of_region": "This asset is outside the regions covered by this discovery.",
"insufficient_metadata": "Too little information was available to plan a scan.",
"no_mcp_source": "No data source was available for this asset."}
HEADINGS = {"Coverage gaps": "What we couldn't scan", "Inventory": "Assets discovered", "Source conflicts": "Where sources disagree",
"CMDB drift": "Differences from your CMDB", "CMDB files read": "CMDB exports read", "ITSM signals": "Service management signals",
"Prompt injection": "Suspicious text found in your data", "Network findings": "Network findings",
"Dependencies": "How your systems depend on each other",
"Dependencies outside this discovery": "Dependencies outside this discovery",
"CMDB relationships compared with the cloud": "Your CMDB's relationships against what the cloud shows",
"CMDB relationships that point at no CI": "CMDB relationships that point at no record", "Sources not checked": "What this report doesn't cover"}
INTROS = {"Sources not checked": "These sources weren't used. Where a section below depends on one, an empty result doesn't mean nothing is wrong.",
"Coverage gaps": "These assets are in scope, but discovery couldn't read them directly. Treat anything said about them as unconfirmed.",
"Prompt injection": "This text was found in a record and looks like an instruction aimed at automated tools. It was reported and not acted on.",
"Can't be retired without mitigation": "Other systems rely on these assets, so plan for those systems before any change.",
"Dependencies outside this discovery": "These weren't scanned. Include their resource group or project in the scope to discover them.",
"CMDB relationships compared with the cloud": "Confirmed relationships appear in both. The others are in only one of them, so check which is right."}
CODE = re.compile(r"\b[a-z]+(?:_[a-z]+)+\b")
FIGURES = {"Coverage gaps": "Assets not scanned", "CMDB differences": "Differences from CMDB", "High severity": "High-severity findings",
"Awaiting SME review": "Awaiting your review"}
EVIDENCE = re.compile(r"\s*\(?\b(?:evidence|snmp|netflow|ipam|config):[^\s),;]+\)?")
def _text(value: Any) -> str:
"""One value, safe in HTML and free of internal references."""
if value is None or value == "" or value == []:
return "-"
if isinstance(value, (list, tuple)):
value = ", ".join(str(v) for v in value)
text = EVIDENCE.sub("", str(value)).strip()
return html.escape(CODE.sub(lambda m: m.group(0).replace("_", " "), text))
def _plain(value: Any) -> str:
text = str(value)
if text.lower() in LABELS:
return LABELS[text.lower()]
if re.fullmatch(r"[a-z]+(_[a-z]+)+", text):
return text.replace("_", " ").capitalize()
return text
def _value(value: Any) -> str:
tone = TONES.get(str(value).lower())
return f'<span class="pill {tone}">{_text(_plain(value))}</span>' if tone else _text(_plain(value) if value is not None else value)
def _html_table(headers: List[str], rows: List[List[Any]]) -> str:
head = "".join(f'<th scope="col">{_text(h)}</th>' for h in headers)
body = "".join("<tr>" + "".join(f"<td>{_value(v)}</td>" for v in row) + "</tr>" for row in rows)
return f'<div class="scroll"><table><thead><tr>{head}</tr></thead><tbody>{body}</tbody></table></div>'
def _customer_table(t: Dict[str, Any], names: Dict[Any, str]) -> Dict[str, Any]:
"""A table with internal fields reworded for the customer."""
headers, rows = t["headers"], t["rows"]
if t["title"] == "Coverage gaps":
return {**t, "headers": ["Asset", "Why"], "rows": [[names.get(r[0], r[0]), GAPS.get(r[1], r[2])] for r in rows]}
if "Confidence" in headers:
at = headers.index("Confidence")
rows = [[f"{v:.0%}" if i == at and isinstance(v, (int, float)) else v for i, v in enumerate(r)] for r in rows]
return {**t, "rows": rows}
def _names(data: Dict[str, Any]) -> Dict[Any, str]:
"""Scope entries by the name a customer knows them by."""
return {r.get("scope_entry_id"): f"{r.get('hostname')} ({r.get('scope_entry_id')})" for r in data.get("records") or [] if r.get("hostname")}
def _priorities(data: Dict[str, Any]) -> List[List[Any]]:
"""The findings to act on first, in the order a reader should take them."""
rows: List[List[Any]] = []
names = _names(data)
for f in sorted(data.get("network_findings") or [], key=lambda x: SEVERITY.get(x.get("severity"), 3)):
if f.get("severity") == "high":
rows.append(["high", _plain(f.get("type")), f.get("subject")])
for s in data.get("stores") or []:
if s.get("requires_disposition_controls"):
rows.append(["high", "Regulated data", f"{s.get('store_name')} holds {_plain(s.get('highest_class')).lower()}"])
for g in data.get("source_gaps") or []:
rows.append(["medium", "Source not checked", SOURCES.get(g.get("source"), g.get("source"))])
for s in data.get("stores") or []:
if s.get("highest_class") == "unclassified":
rows.append(["medium", "Data not classified", s.get("store_name")])
for g in data.get("coverage_gaps") or []:
rows.append(["medium", "Not scanned", names.get(g.get("scope_entry_id"), g.get("scope_entry_id"))])
for d in data.get("drift_items") or []:
if d.get("type") == "ghost":
rows.append(["medium", "In CMDB, but not found", d.get("cmdb_value")])
return rows
def render_html(data: Dict[str, Any], notice: Optional[str] = None) -> str:
"""The customer's report as one self-contained HTML page: it loads nothing from elsewhere, and it prints cleanly."""
r = build(data, notice)
engagement, priorities = _text(r["engagement"]), _priorities(data)
names = _names(data)
tables = [_customer_table(t, names) for t in r["tables"]]
titles = ["Summary"] + (["Priority findings"] if priorities else [])
numbered = titles + [HEADINGS.get(t["title"], t["title"]) for t in tables] + ["For your team to confirm", "Quality check"]
anchors = {title: f"s{i}" for i, title in enumerate(numbered, 1)}
def heading(title: str) -> str:
return f'<h2><span class="num">{numbered.index(title) + 1}</span>{_text(title)}</h2>'
who = dict(r["declared"][0][1]).get("Name") if r["declared"] and r["declared"][0][0] == "Customer" else None
cover = (f'<header class="cover"><div class="wrap"><p class="eyebrow">Estate discovery report{" · " + _text(who) if who else ""}</p><h1>{engagement}</h1>'
f'<p class="meta">Run {_text(r["run"])} · {date.today():%-d %B %Y}</p></div></header>')
parts = []
if notice:
parts.append(f'<p class="notice">{_text(notice)}</p>')
parts += [f'<p class="notice bad">{_text(w)}</p>' for w in r["warnings"]]
figures = "".join(f"<div><dt>{_text(k)}</dt><dd>{_text(v)}</dd></div>" for k, v in ((FIGURES.get(k, k), v) for k, v in r["figures"]))
parts.append(f'<section id="{anchors["Summary"]}">{heading("Summary")}<p class="status">Quality check {_value(r["verdict"])}'
f'<span>Scope entries: {_text(r["scope_entries"])}</span></p><dl class="figures">{figures}</dl></section>')
contents = "".join(f'<li><a href="#{anchors[t]}">{_text(t)}</a></li>' for t in numbered[1:])
parts.append(f'<nav aria-label="Contents"><ol start="2">{contents}</ol></nav>')
if priorities:
parts.append(f'<section id="{anchors["Priority findings"]}">{heading("Priority findings")}'
f'{_html_table(["Priority", "Finding", "Where"], priorities)}</section>')
for t in tables:
title = HEADINGS.get(t["title"], t["title"])
intro = f'<p class="intro">{_text(INTROS[t["title"]])}</p>' if t["title"] in INTROS and t["rows"] else ""
content = _html_table(t["headers"], t["rows"]) if t["rows"] else f'<p class="empty">{_text(t["empty"])}</p>'
parts.append(f'<section id="{anchors[title]}">{heading(title)}{intro}{content}</section>')
if r["not_examined"]:
missed = "".join(f"<li>{_text(HEADINGS.get(x, x))}</li>" for x in r["not_examined"])
parts.append(f'<section><h2>Not examined</h2><p class="intro">These hold nothing because their source wasn\'t available in this run, '
f'not because they\'re clean.</p><ul>{missed}</ul></section>')
for title, rows in r["declared"]:
parts.append(f"<section><h2>{_text(title)}</h2>{_html_table(['Item', 'Value'], rows)}</section>")
if r["context"]:
parts.append(f'<section><h2>Run context</h2><p class="intro">The parameters and context this run was started with.</p>'
f'<div class="scroll"><pre style="margin:0;padding:.8rem 1rem;white-space:pre-wrap">{html.escape(r["context"])}</pre></div></section>')
items = "".join(f"<li>{_text(label)}: {_text(value)}</li>" for label, value in r["review"])
parts.append(f'<section id="{anchors["For your team to confirm"]}">{heading("For your team to confirm")}<ul>{items}</ul></section>')
passed = "Automated checks found problems with this report."
if r["verdict"] == "pass":
passed = ("Automated checks found no problems in what was examined. They can't speak for the sources not checked."
if r["gaps"] else "Automated checks found no coverage, evidence or consistency problems.")
issues = _html_table(["Check", "Issue"], r["issues"]) if r["issues"] else ""
parts.append(f'<section id="{anchors["Quality check"]}">{heading("Quality check")}<p class="status">{_value(r["verdict"])}<span>{passed}</span></p>{issues}</section>')
return (f'<!doctype html><html lang="en"><head><meta charset="utf-8">'
f'<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">'
f'<meta name="claude:viewport-fit-sides" content="cover"><title>Discovery report {engagement}</title><style>{STYLE}</style></head>'
f'<body>{cover}<main class="wrap">{"".join(parts)}</main></body></html>')