redact-visualization-for-disclosure

# Redact Visualization for Disclosure A diagram leaks differently than prose: the sensitive names sit in node labels, tooltip text, and embedded `<text>` nodes, while the *shape* of the graph is exactly the generalizable insight worth publishing. This skill redacts the labels and keeps the structure — replacing each internal identifier with a descriptive stand-in through an ordered mapping table, re-rendering the image from the redacted source, and then asserting over both that no mapped identifier survives. ## When to Use - Publishing an architecture/flow diagram (Mermaid `.mmd`, rendered `.svg`) built from internal findings - Shipping an HTML dashboard whose cells/tooltips name internal flags, functions, or endpoints - Promoting an investigation visualization into a public guide while keeping the named internals private - Re-deriving a public image after the private source diagram changed (redaction must re-run, not be hand-patched) ## Inputs - **Required**: The source visual artifact (`.mmd`, `.svg`, `.html`) in the private repo - **Required**: A mapping table — sensitive identifier → descriptive stand-in. `enforce-redaction-gate` Step 1 covers how to derive the shapes it should cover - **Optional**: The render toolchain (e.g. a Mermaid CLI) to regenerate the image from the redacted source - **Optional**: A target path in the public mirror for the redacted output ## Procedure ### Step 1: Separate Structure from Labels Decide, per artifact, what carries the leak and what carries the insight. In every diagram format the *structure* (which node connects to which) is the shareable pattern; the *labels* are the sensitive part. | Format | Sensitive (redact) | Structural (preserve) | |---|---|---| | Mermaid | node labels, edge labels, subgraph titles | node ids, edge directions, layout | | SVG | `<text>`, `<title>`, `id`/`data-*` attrs | path geometry, viewBox, styles | | HTML | cell text, tooltips, captions | table shape, headings, layout | The rule that prevents the most damage: **redact labels, preserve ids.** A Mermaid `A1[acme_widget_gate]` becomes `A1[widget-gate]` — the id `A1` is structural and carries nothing; the label is the leak. **Expected:** A per-format list of which token positions get rewritten and which are left untouched. **On failure:** If a node id itself encodes a sensitive name (rare), treat it as a label and remap it consistently across every edge that references it. ### Step 2: Build the Ordered Mapping Table Map each sensitive identifier to a descriptive stand-in. Order matters: **longest/most-specific first**, so a precise label wins before a namespace label before the catch-all. Otherwise a generic prefix rewrite eats the specific case. ```python # Ordered tiers. Within each dict, apply longest-key-first. SPECIFIC = { # exact internal name -> descriptive stand-in "acme_widget_autoinstall_gate": "[autoinstall-gate]", "acme_relay_chain_v1": "[relay-chain-gate]", } NAMESPACE = { # family prefix -> namespace label "acme_widget_": "[widget-namespace]", } FUNCTIONS = { # minified identifier (whole-word) -> role name r"\bQ3\(\)": "resolveProvider()", r"\bAb\b": "flagResolver", } def redact(text): for src in sorted(SPECIFIC, key=len, reverse=True): text = text.replace(src, SPECIFIC[src]) for src in sorted(NAMESPACE, key=len, reverse=True): text = text.replace(src, NAMESPACE[src]) for pat, repl in FUNCTIONS.items(): text = re.sub(pat, repl, text) text = re.sub(r"acme_[A-Za-z0-9_]+", "[feature-flag]", text) # catch-all, last text = re.sub(r"\b(\w+(?:\(\))?) \1\b", r"\1", text) # collapse "name name" pairs return text ``` Two non-obvious rules baked in above: **whole-word boundaries** for minified identifiers (so `Ab` does not match inside `Abstract`), and a **collapse pass** that removes adjacent duplicate stand-ins left when an original label paired a name with its minified twin (`scheduleWakeup Y8z` → both map to `scheduleWakeup` → collapse to one). **Expected:** Every sensitive identifier in the source maps to a descriptive stand-in; the catch-all only ever fires on tokens the specific/namespace tiers missed. **On failure:** If the catch-all fires often, a real identifier family is unmapped — add a specific or namespace entry rather than relying on the generic placeholder, which erases teaching value. ### Step 3: Apply to the Source, Write to the Public Path Run the mapping over the source text and write the redacted artifact to the public-mirror path. Never edit the public copy by hand — it must be a pure function of the private source so re-runs are deterministic. ```bash # Write Step 2's table to a mapping file — one `source<TAB>replacement` pair per line, or a # JSON object. Order does not matter in the file: the tool sorts longest-source-first, so a # namespace prefix can never eat a more specific name. cat > /tmp/viz-map.tsv <<'MAP' acme_widget_autoinstall_gate [autoinstall-gate] acme_widget_ [widget-namespace] MAP python3 tools/redact-artifact.py --type mermaid --mapping /tmp/viz-map.tsv \ docs/flow.mmd -o publish/docs/flow.mmd ``` For SVG/HTML pass `--type html`: replacements still apply to the whole text, but the verification tier additionally parses the document and asserts that no source term survives in a text node or an attribute value, reporting the position (`text[2]`, `attr:data-id[0]`) and never the content. **Expected:** Exit 0, and the redacted artifact has identical structure to the source with descriptive stand-ins in every label position. A non-zero exit means the tool refused to hand back output it could not verify — exit 1 for a surviving term, 2 for could-not-measure (an empty mapping, an unreadable input). Terms that may appear in an encoding your mapping does not spell — base64, a different case — go in `--also-deny`, which asserts without substituting. **On failure:** If a diff shows a structural change (a dropped edge, a renamed id), the mapping over-matched — scope it to label positions and re-run. ### Step 4: Re-render the Derived Image If the artifact has a rendered form (an `.svg`/`.png` generated from the `.mmd`), regenerate it from the *redacted* source. A stale rendered image is the classic leak: the source got redacted, the image did not. ```bash mmdc -i publish/docs/flow.mmd -o publish/docs/flow.svg ``` **Expected:** The rendered image is regenerated from the redacted source and shows only stand-in labels. **On failure:** If the render tool is unavailable, do not ship the old image — remove it from the publish set until it can be regenerated, and note the gap. ### Step 5: Verify Through the Redaction Gate Step 3 already verified the redacted source: `redact-artifact` asserts its own output before returning it, so a clean exit there *is* the gate for the text artifact. What Step 3 cannot cover is the RENDERED image, which a different tool produced from the redacted source — re-assert over it, because a renderer can reintroduce a label from a cache or a theme file. ```bash # --assert-only is load-bearing. Without it the mapping SUBSTITUTES first, so a label the # renderer reintroduced is rewritten before the assertion looks and this check cannot fail for # the one case it exists to catch (measured: rc=0, "0 survivor(s)", over an SVG containing the # private label). With it, the mapping's keys become deny terms and nothing is rewritten. python3 tools/redact-artifact.py --type html --assert-only --mapping /tmp/viz-map.tsv \ publish/docs/flow.svg || { echo "rendered image still leaks; re-render from the redacted source"; exit 1; } ``` **Expected:** Exit 0 on the rendered image, the redacted source having already been asserted in Step 3. A non-zero exit is the check working: 1 means a term survived into the render, 2 means it refused to run. **On failure:** A gate hit means the mapping table is incomplete — add the missing shape to the mapping (Step 2) and the deny-list, then re-run from Step 3. Do not hand-edit the public file to silence the gate. ## Validation - [ ] The redacted artifact has byte-identical structure to the source (only labels changed) - [ ] Node ids/edges are preserved; only labels/text nodes are rewritten - [ ] The rendered image was regenerated from the redacted source, not carried over - [ ] The mapping is ordered longest-first; the catch-all only fires on genuinely unmapped tokens - [ ] `redact-artifact` exits 0 on the redacted source (Step 3) and on the rendered image (Step 5) - [ ] The public artifact is a pure function of the private source (re-running is deterministic) ## Common Pitfalls - **Stale rendered image.** Redacting the `.mmd` but shipping the old `.svg` publishes everything you just removed. Always regenerate. - **Hand-editing the public copy.** Once the public file diverges from the source mapping, the next re-run either reverts your edit or, worse, re-introduces the leak. Fix the mapping, not the output. - **Catch-all over-reliance.** Replacing every internal name with `[feature-flag]` strips the teaching value that justified publishing the diagram. Map families to descriptive namespaces. - **Unscoped substring rewrite.** Regexing the whole SVG/HTML can rewrite an attribute or a path id that merely contains a matching substring. Parse and scope to text nodes. - **Wrong mapping order.** Applying the namespace tier before the specific tier erases the precise stand-in. Longest/most-specific first, always. - **Redacting ids that other edges reference.** If you must remap an id, remap it everywhere it is referenced, or the graph breaks. ## Related Skills - `enforce-redaction-gate` — how to build a redaction boundary for artifacts you hold the deny-list for; defines the shape vocabulary the mapping table draws on. Note it teaches building one rather than shipping one: this repository ships the post-condition half (`tools/redact-artifact.py`), and #853 records why a public tree gate is not possible - `redact-for-public-disclosure` — the methodology umbrella that decides *what* is publishable before this skill decides *how* to scrub the diagram - `redact-wire-capture` — the sibling transform for network/MITM captures rather than rendered artifacts - `generate-workflow-diagram` — produces the kind of Mermaid diagram this skill redacts for publication - `annotate-source-files` — upstream annotation step whose output diagrams may carry internal identifiers into the visual