- 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>
535 lines
36 KiB
Python
535 lines
36 KiB
Python
"""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>')
|