Reports

azdocs report --format md|html|csv|xlsx|pdf|docx|all [--include-reference] [--theme <name>] [--snapshot <id|latest>] [--out <dir>]
              [--subscription <id>] [--resource-group <name>] [--severity high|medium|low|info]

Reports are generated from the stored snapshot — no network access, no external tools (PDF and DOCX are rendered natively; no Chromium, no Pandoc). Everything lands under ./output/ by default:

Use --tenant <reference-or-tenant-id> to select the estate. Explicit snapshot IDs remain usable offline without credentials; a supplied tenant selection enforces ownership. See tenant history.

Scoping

--subscription, --resource-group and --severity narrow every format to one part of the estate, the same way azdocs diagram does. The filter is applied once, right after the snapshot is read, so composition, figures, studies, findings, evidence tables and screenshots all describe the same subset. A scoped document describes its scope, not the estate: subscription comparisons and group studies are drawn from what is in scope.

• --subscription <id> keeps one subscription. Findings that name no stored resource are kept when their id lies under that subscription.
• --resource-group <name> keeps one group (case-insensitive; combine with --subscription when the name repeats). Estate-level findings are dropped.
• --severity <level> keeps findings at that severity or higher; a --severity high PDF is a findings-led brief. Resources are untouched.

The desktop’s Exports workspace offers the same three controls.

Changes since the previous snapshot

When the tenant has an earlier usable snapshot, every format describes what differs from it: resources added, removed and changed field by field, new and resolved findings, relationships and scope that appeared or disappeared, and a trend table over the last twelve usable snapshots. The PDF and DOCX print it as a chapter, Markdown and HTML as a section, the workbook as Changes and Trend sheets. The comparison is the one azdocs snapshots diff makes; see snapshots for what is ignored as noise.

Honest caps

The printed formats stop tables at [report] max_evidence_rows (default 20) and say how many rows they left out; the tag-key and worst-group summaries say how many keys or groups they were cut from; a resource page that drops scalar settings past its limit says so. Figures split past max_figure_nodes boxes and the technical reference draws at most max_group_diagrams groups. The CSV and XLSX exports carry the full tables. See configuration.

The PDF and DOCX

The default export is an assessment: architecture, recurring findings, selected configuration comparisons and traceable review actions. Both formats consume one shared PrintDocument, built from ReportContext.analysis and the stored snapshot. The main report contains:

1. Executive assessment: observations, significance and first decisions.
2. Estate composition: subscriptions, service families and regions (a world map sized by resource count, then the per-region chart).
3. Architecture and dependencies: observed connections, shared targets and focused figures.
4. Subscription profiles and up to three distinct group studies per subscription.
5. Security and data protection: one explanation per recorded check.
6. Governance and operational evidence, including limitations of collection.
7. Prioritised review actions linked to the relevant check assessment.
8. Collection coverage: successful, successfully empty, failed and unknown query outcomes, plus snapshot provenance.

Group studies are selected by recorded finding priority, cross-group connection count, then population. Each selection excludes earlier choices and resolves remaining ties by name and ID. Names are identifiers, never evidence of business purpose. Finding occurrences, unique resource IDs and unresolved references are counted separately. Historical severities are retained; explanatory wording does not reclassify findings. Custom checks keep their original evidence and receive generic verification guidance.

The intended depth is roughly 30–50 pages for a 307-resource estate, rather than a fixed quota. Smaller estates are shorter. Significant evidence is not discarded to meet a page count.

Optional technical reference

azdocs report --format pdf --include-reference
azdocs report --format docx --include-reference
azdocs report --format all --include-reference

The option defaults to false. It keeps report.pdf / report.docx as the main assessment and additionally writes technical-reference.pdf and/or technical-reference.docx for the selected print formats. The desktop offers an unchecked Include technical reference control for PDF and Word exports.

The reference uses a smaller working type scale, bordered settings and evidence tables, and Azure service icons beside resource names. Resource names in the type index link to their detailed entries; relationship-table endpoints and finding resource names link to the same entries whenever the resource is present. Links use normalized ARM IDs, so duplicate names remain distinct. Main-report evidence examples use bullet points; the explanatory sections retain the assessment’s regular body type.

Each resource shows its name, service type and selected operational settings: location, SKU, managed identity, service size and state, access controls, networking, retention and ownership tags where recorded. Disks, subnets, node pools and similar collections are counted instead of expanded. Settings use plain-language labels. Missing settings are omitted, never treated as a passed control. Definitions, scripts, provider capability lists, histories and hidden tags stay out of print. Individual values are abbreviated after 160 characters, tag lists after 200; standalone URLs remain complete.

Website screenshots form a gallery followed by a separate capture-details table for each website. External links show their complete URLs and wrap within the table cells.

The companion retains the complete resource register and subscription → resource group → resource navigation. Findings are grouped by check, resource and recorded severity, with counts covering every occurrence. A brief collection summary distinguishes successful, empty, failed and unknown outcomes; failed queries retain their diagnostic messages.

There is no Evidence appendix in either the assessment or the technical reference. Raw query rows, policy and role catalogues, original finding titles and evidence are not printed in the reference. The snapshot database retains the full stored values; use the Data Workbook, CSV or HTML for data-oriented review of their included fields. This keeps the reference useful for operational review without turning it into a dump of Azure provider metadata.

Diagrams and pagination

Main-report figures show selected relationships, fold known attachments, retain explicit counts, and split complex sets into smaller figures. Selection creates EstateGraphs; the shared page, layout, connector, icon, SVG and PNG code renders them. There is no separate report drawing engine. Only diagrams used by the selected document are generated. The main report has no tall estate hierarchy picture or repeated per-resource diagrams. See Diagram standards.

Both formats have a cover, contents and internal navigation. Word requests a field refresh for its contents and page numbers. If the editor suppresses this, select the contents and choose Update Field. Native pagination can differ: Typst embeds fonts; Word uses locally installed fonts and keeps the document editable. Both repeat comparison-table headers; the Word package adds the standard OOXML w:tblHeader flag where the library lacks an API.

Tag presence is separate from required-tag compliance. The application’s 60% tag-presence threshold is a descriptive indicator, not a compliance standard. Where historical required-tag scope was not recorded, a zero finding count is reported as unavailable audit scope. Monitoring and recovery resources show observed infrastructure; their existence does not establish delivery, health, successful backups or tested recovery.

Document design

Two document themes ship built in:

[branding] still supplies the company name, title, brand colour, logo and footer. Themes are TOML data, so an organisation can supply its own document system, including A4 SVG cover artwork. Select a theme with [branding] theme, for one CLI run with --theme <name>, or per export from the Document style picker on the desktop Exports page. See reference/themes.md.

The docs tree

output/docs/
├── index.md                     # estate summary: counts, types, locations, tag coverage
├── findings.md                  # all findings grouped by severity
├── networking.md  compute.md  … # per-category query result tables
├── subscriptions/<name>.md      # per-subscription inventory by resource group
└── resources/<sub>/<rg>.md      # per-resource detail pages

index.md embeds the estate hierarchy and network overview; each resource-group page opens with its summarised diagram. Every figure is written twice under docs/diagrams/: <slug>.svg for the image link and <slug>.mmd for the Mermaid source, which the page also inlines in a fenced block so GitHub and most wikis render it natively.

The detail pages are the deep end: one section per resource with settings flattened from its properties, warning callouts for findings on that resource, and related-resource links derived from the relationship edges. The Markdown and HTML docs tree keep their tabular settings presentation; the print technical reference uses selected, labelled operational settings in bordered tables.

The HTML report

output/report.html is one self-contained file (inline CSS/JS, dark-mode aware) with the overview diagrams inlined as SVG, severity badges and client-side table filtering — suitable for email or SharePoint. output/docs-html/ is the docs tree as static HTML with navigation.

Operational evidence and provenance

Operational and compliance summaries are computed once from the snapshot and shared by Markdown, HTML/site, XLSX, PDF and DOCX. They distinguish source states, missing evaluations and evidence age without requesting new Azure data.

Exports do not create a separate query-provenance.json file. Exact executed queries and settings, including failed attempts, remain in the snapshot database. HTML exposes expandable query definitions; Markdown/site adds a query-provenance page; XLSX adds a provenance sheet. The optional PDF/DOCX technical reference summarises collection outcomes without exporting query definitions. Old snapshots do not acquire invented provenance from today’s query pack.

See operational evidence for Microsoft sources, retention windows and review thresholds.

Next: Diagrams