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

> Learn to use the diagram-generator module from reverse-skill to create attack path diagrams. Convert text to Mermaid, Graphviz, or PlantUML and render to PNG, SVG, or PDF.

- Repository: [ZhaoXu/reverse-skill](https://github.com/zhaoxuya520/reverse-skill)
- Tags: how-to-guide
- Published: 2026-08-16

---

**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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/scripts/render_diagram.py).**

The `diagram-generator` skill is a core component of the [zhaoxuya520/reverse-skill](https://github.com/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:

```markdown
下面是可编辑的 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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:**

```bash
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):**

```markdown
下面是可编辑的 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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/docs-generator/SKILL.md)): Embeds diagrams into final security reports, handling format conversion and styling

The **routing context** section in [`SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/SKILL.md) | Complete workflow documentation, decision tables, generation rules, rendering instructions |
| [`skills/diagram-generator/scripts/render_diagram.py`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/scripts/render_diagram.py) | CLI renderer supporting `.mmd`, `.dot`, `.puml` → PNG/SVG/PDF |
| [`skills/diagram-generator/references/diagram-patterns.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/diagram-generator/references/diagram-patterns.md) | Reusable pattern library for rapid diagram construction |
| [`skills/attack-chain/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/skills/attack-chain/SKILL.md) | Attack-path specific use cases and integration patterns |
| [`skills/docs-generator/SKILL.md`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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`](https://github.com/zhaoxuya520/reverse-skill/blob/main/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.