"""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 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 []] 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())), (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."), ] 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")], "None was detected."), _table("CMDB drift", ["Id", "Type", "Asset", "Field", "Discovered", "CMDB", "Suggested action"], [[d.get("drift_id"), d.get("type"), d.get("canonical_id") or d.get("ci_ref"), 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 []], "No dependencies were reported."), _table("Can't be retired without mitigation", ["Asset", "Depended on by", "Depends on"], held, "No asset has this constraint."), ] 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"])], "tables": tables, "review": [("Inventory records", data.get("sme_review_queue")), ("Dependency edges", data.get("validation_queue")), ("Assets with no dependencies found", data.get("orphans"))], "critic_note": data.get("critic_note"), "issues": issues} 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"]], ["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"]]) + [""] 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", "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", "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."} 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'{_text(_plain(value))}' 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'
Estate discovery report
{_text(notice)}
') parts += [f'{_text(w)}
' for w in r["warnings"]] figures = "".join(f"Quality check {_value(r["verdict"])}' f'Scope entries: {_text(r["scope_entries"])}
{_text(INTROS[t["title"]])}
' if t["title"] in INTROS and t["rows"] else "" content = _html_table(t["headers"], t["rows"]) if t["rows"] else f'{_text(t["empty"])}
' parts.append(f'{_value(r["verdict"])}{passed}
{issues}