RDX Reader: online viewer that diagrams each RDX data element and reports content + quality

[JohnASRG]

Motivation

Reviewing an RDX document today means reading JSON. That works for tool authors, but it does not work for the audiences who actually need to consume TARA output — engineering managers, auditors, OEM cyber leads, supplier liaisons, and PSIRT/MDR teams. The format already encodes architecture, assets, damage scenarios, threat scenarios, attack paths, AFR/impact ratings, risk values, controls, treatment decisions, CAL/TAF, and relationships. We need a companion online reader that turns any RDX document into the diagrams those audiences expect, plus a structured content-and-quality overview.

This is the most direct adoption lever for RDX: a stakeholder who can drop a .json or .xml onto a web page and immediately see "what is in this document and is it complete?" is far more likely to advocate for RDX inside their org than one who has to read a schema.

The Reader is also the natural consumer for the visualization metadata in #62 (graph layout), the conformance profiles in #50, and the structured attackSteps from #48.

Proposed change

Build a static, client-side single-page application — no backend, no telemetry, no upload-to-server — that:

1. Loads an RDX document from local file, clipboard paste, drag-and-drop, or a ?url= query param (CORS permitting).
2. Validates the document in-browser against spec/json/rdx.schema.json (and XSD for XML inputs via libxml.js or similar), surfacing every validation error inline with a click-to-jump-to-source affordance.
3. Renders one diagram per major data element, each with downloadable SVG/PNG:
   • Item definition / architecture: components, trust zones, interfaces, and data flows as a system diagram (honors visualization metadata from #62 when present).
   • Asset → damage scenario → threat scenario → attack path chains as a flow graph.
   • Structured attack trees (per #48) with AND/OR branching, step types, and external-knowledge-base references rendered as badges.
   • Risk matrix: impact × AFR heatmap with riskLevels / riskThresholdMatrix bands shaded.
   • CAL / TAF coverage map: controls grouped by required vs achieved CAL level.
   • Relationships graph: an interactive force-directed view of all relationships[] entries, filterable by type.
   • Coverage matrix: use-case → required objects → present-in-document (depends on #50).
4. Reports content and quality in a structured "Overview" panel:
   • Counts per object type, completeness ratio, distribution of risk bands.
   • Broken-reference detection (IDs referenced that do not exist).
   • Rationale-gap detection (AFR / impact / risk value entries with no rationale or evidence).
   • Control-coverage gap detection (threats with no mitigating control).
   • Provenance summary (per #63): how much of the document is human-authored vs ai-generated vs unreviewed.
   • Profile conformance check against a chosen conformance profile from #50.
5. Compares two RDX documents side-by-side (e.g., a delta TARA per #59 against its baseline): added/removed/changed objects per type, with a focused diff per object id.
6. Exports the overview as a one-page printable HTML/PDF report suitable for sharing with non-technical reviewers.

Technology and hosting

• Static SPA (React or Svelte) built to plain HTML/JS/CSS, hosted on GitHub Pages from the repo (/docs or a gh-pages branch) at e.g. https://asrg.github.io/rdx-reader.
• Diagram rendering: a vetted lightweight library (Mermaid for flow/sequence views; D3 or ELK for force-directed + layered graphs).
• Validation: Ajv with ajv-formats and Draft 2020-12 — same configuration as tools/validate.sh, compiled to a browser bundle.
• Schema bundled at build time so the Reader is pinned to a specific RDX version; a version-selector UI lets the user pick which schema to validate against.
• All processing in-browser. The Reader never transmits the loaded document anywhere; this must be testable (no network requests after page load).

Repo layout

Add the Reader as a subdirectory of this repo (e.g., reader/) so the schema and Reader version together, or as a sibling repository under the ASRG org if the maintainers prefer separation. Decide as part of triage.

References

• Related: #48 structured attack steps, #50 use-case coverage + profiles, #59 delta TARA, #62 visualization metadata, #63 provenance metadata
• Existing examples to use as render fixtures: examples/headlight-tara-iso21434.json, examples/rdx-infotainment-comprehensive-example.json, examples/rdx-xml-comprehensive.xml
• Existing validation behavior to match: tools/validate.sh, spec/json/rdx.schema.json, spec/xml/rdx.xsd

Acceptance criteria

• Reader is deployed at a public URL (GitHub Pages or equivalent) and linked from README.md
• Reader loads every bundled examples/*.json and examples/*.xml without manual fixup
• All seven diagram views listed above render for the comprehensive infotainment example
• Schema validation in the Reader produces the same pass/fail result as tools/validate.sh for every bundled example (CI test enforces parity)
• Overview panel reports counts, broken references, rationale gaps, control-coverage gaps, and provenance summary
• Two-document diff view works against a baseline + delta TARA pair (becomes meaningful after #59 lands)
• Reader honors visualization.graph metadata (per #62) when present and falls back to auto-layout when absent
• No network requests are issued after initial page load (verified in browser devtools and in an automated test)
• One-page printable HTML/PDF export is downloadable
• Source lives in this repo under reader/ (or a sibling repo, decided in triage) with its own CI and a tagged release that pins the RDX schema version it ships against

---

Filed by maintainer; not generated by the AI Idea Scout.