How to Use the diagram-generator Module for Attack Path Diagrams

The diagram-generator module in the reverse-skill repository converts natural-language attack path descriptions into editable diagram source code (Mermaid, Graphviz, or PlantUML) and can render them to PNG, SVG, or PDF using scripts/render_diagram.py.

The diagram-generator skill is a core component of the zhaoxuya520/reverse-skill framework, purpose-built for security analysts who need to visualize attack chains, system architectures, and process flows. Located at skills/diagram-generator/, this module outputs version-controllable text that integrates directly with the docs-generator and attack-chain skills.

---

Architecture of the diagram-generator Module

The module follows a three-stage pipeline: decision, generation, and optional rendering. Understanding this flow is essential for using the diagram-generator module effectively.

Decision Table: Choosing the Right Diagram Language

The skill automatically selects the optimal diagram language based on your input characteristics. The decision table in skills/diagram-generator/SKILL.md guides this selection:

Scenario	Recommended Language	Rationale
Linear attack paths, quick iteration	Mermaid	Human-readable, native markdown support
Dense dependency graphs, fine-grained layout control	Graphviz DOT	Sophisticated ranking and clustering
Formal UML, sequence diagrams, or architectural specs	PlantUML	Standardized notation, extensive libraries

Source Generation Rules

Once the language is selected, the module applies concise style rules documented in the same SKILL.md file:

• Mermaid generation: Uses flowchart TD (top-down) or LR (left-right) directives, explicit node labels in brackets, and subgraphs for logical grouping
• Graphviz DOT generation: Enforces rankdir, consistent node [shape=...] declarations, and edge attributes for styling

The output is always plain text—store it in git, diff it, and modify it programmatically.

---

Generating Attack Path Diagrams: Step-by-Step

Step 1: Describe Your Attack Path in Natural Language

The skill accepts descriptions like "attacker sends phishing email, executes payload, steals credentials, moves laterally, exfiltrates data."

Step 2: Receive Generated Source Code

The module returns ready-to-use diagram source. Here's a typical Mermaid output for the attack path above:

下面是可编辑的 Mermaid 版本：

```mermaid
flowchart TD
    attacker[Attacker] --> phish[Phishing Email]
    phish --> exec[Execute Payload]
    exec --> cred[Steal Credentials]
    cred --> lateral[lateral movement]
    lateral --> exfil[Data Exfiltration]

Assumptions:

• The chain is linear and only includes the listed steps.

Note the Chinese prefix "下面是可编辑的 Mermaid 版本：" (translated: "Below is the editable Mermaid version:")—this is the skill's standard output format indicating editable source follows.

### Step 3: Optional—Render to Image Format

When you need a visual artifact instead of source code, invoke the rendering helper. Save the source to a file first:

```bash

# Save Mermaid source to attack_path.mmd, then render

python "skills/diagram-generator/scripts/render_diagram.py" attack_path.mmd --format svg --out attack_path.svg

The render_diagram.py script detects file extensions (.mmd, .dot, .puml) and dispatches to the appropriate local renderer.

---

Using render_diagram.py for Attack Path Visualization

The helper script at skills/diagram-generator/scripts/render_diagram.py is the rendering engine for all diagram types. It provides dependency-tolerant execution—if a renderer is missing, it prints installation instructions rather than failing.

Supported Input Formats and Renderers

Extension	Language	Required Tool
.mmd	Mermaid	mmdc (Mermaid CLI via npm)
.dot	Graphviz	dot (system package)
.puml	PlantUML	plantuml (Java + jar or system package)

Rendering Examples

Mermaid to SVG:

python "skills/diagram-generator/scripts/render_diagram.py" attack_path.mmd --format svg --out attack_path.svg

Graphviz DOT to PNG (better for complex attack paths with branching):

下面是可编辑的 Graphviz DOT 版本：

```dot
digraph G {
    rankdir=LR;
    node [shape=box];
    A -> B;
    A -> C;
    B -> D;
    C -> D;
    D -> E;
}

Assumptions:

• Nodes represent components; edges represent dependencies.

Then render:

```bash
python "skills/diagram-generator/scripts/render_diagram.py" deps.dot --format png --out deps.png

The script validates outputs and reports the final file path on success.

---

Integrating with the Broader reverse-skill Framework

The diagram-generator module doesn't operate in isolation. It feeds into two complementary skills:

1. attack-chain skill (skills/attack-chain/SKILL.md): Automatically consumes generated diagrams to visualize complete attack chains from reconnaissance through impact
2. docs-generator skill (skills/docs-generator/SKILL.md): Embeds diagrams into final security reports, handling format conversion and styling

The routing context section in SKILL.md explains how the framework orchestrates these handoffs—diagram source flows from generator to document assembler without manual intervention.

---

Key Files for Attack Path Diagram Generation

File	Purpose
skills/diagram-generator/SKILL.md	Complete workflow documentation, decision tables, generation rules, rendering instructions
skills/diagram-generator/scripts/render_diagram.py	CLI renderer supporting .mmd, .dot, .puml → PNG/SVG/PDF
skills/diagram-generator/references/diagram-patterns.md	Reusable pattern library for rapid diagram construction
skills/attack-chain/SKILL.md	Attack-path specific use cases and integration patterns
skills/docs-generator/SKILL.md	Report embedding and publication workflows

---

Summary

• The diagram-generator module outputs editable, version-controllable diagram source in Mermaid, Graphviz, or PlantUML format
• Use skills/diagram-generator/scripts/render_diagram.py to convert source files to images when visual artifacts are required
• The module auto-detects file types and tolerates missing dependencies with helpful installation hints
• Generated diagrams feed directly into the attack-chain and docs-generator skills for end-to-end security documentation
• All generation rules and style conventions are documented in skills/diagram-generator/SKILL.md

---

Frequently Asked Questions

What diagram format should I use for attack path visualization?

Mermaid is the default choice for linear attack paths and rapid iteration—it renders in most markdown viewers without additional tools. Use Graphviz DOT when your attack graph has complex branching, cycles, or requires precise node positioning. PlantUML is optimal for sequence diagrams showing temporal attack progression or when UML standards compliance matters.

Can I use the diagram-generator module without installing renderers?

Yes. The module produces source code that renders in many environments natively—GitHub, GitLab, Notion, and VS Code all preview Mermaid diagrams without local tools. The render_diagram.py script is only needed when generating static image files (PNG/SVG/PDF) for reports or presentations.

How does the module handle errors when renderers are missing?

The render_diagram.py script detects missing dependencies and prints installation hints rather than throwing exceptions. For example, if mmdc is absent, it displays npm installation commands. This design ensures the skill degrades gracefully in restricted environments.

Where can I find reusable patterns for common attack path structures?

The skills/diagram-generator/references/diagram-patterns.md file contains a curated library of compact snippets—including lateral movement patterns, credential theft flows, and exfiltration sequences—that accelerate diagram authoring for security scenarios.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}