SecLab

Diagrams in a post

Diagrams here are text, not images — and every example below is a live diagram rendered through the same path your post takes.

Open the editor

Why mermaid, not an image

A text diagram lives in the diff, so a reviewer sees what the picture changed; fixing a wrong label is a one-word edit, not a request for the source file; the text is searchable and readable by a screen reader; and it follows the site's light/dark theme. A PNG does none of those four.

External images are also blocked because of bait-and-switch: approving a clean image and then replacing the file on your own server routes around the whole review gate with one scp.

Data flow — for experience and incident posts

Diagram source
flowchart LR  U[User] --> A[API]  A -->|"fetch(url), unchecked"| M[169.254.169.254]  M -->|"temporary credentials"| A

SSRF into the metadata endpoint: the flaw is the API trusting a user-supplied URL.

Wrap labels containing special characters in quotes: A[Client] -->|"fetch(url)"| B.

Timeline — incident posts

Diagram source
timeline  title Key leaked through CI logs  09:12 : Detected via GitHub alert  09:40 : Key rotated, artifacts locked  11:05 : Older artifacts rescanned  14:00 : Post-mortem, scan added before upload

Four moments, and only the last one fixes the cause.

Sequence — token, callback and webhook flows

Diagram source
sequenceDiagram  participant B as Browser  participant W as Web (BFF)  participant A as API  B->>W: POST /auth/login  W->>A: /v1/auth/login  A-->>W: access + refresh  W-->>B: Set-Cookie (HttpOnly)  Note over B,W: Tokens never reach the browser

The refresh token stays server-side; the browser only holds a cookie.

Before / after the fix — patch posts

Diagram source
flowchart TD  subgraph Before    A1[GET /orders/42] --> B1[No ownership check] --> C1[Someone else's order]  end  subgraph After    A2[GET /orders/42] --> B2["WHERE user_id = @subject"] --> C2[404]  end

BOLA and its fix. 404, not 403 — a 403 confirms the id exists.

Four common errors

ErrorWhat you seeFix
No diagram type"No diagram type detected"First line must be flowchart LR, sequenceDiagram, timeline…
Unquoted (, :, , in a label"Parse error on line N"Wrap the label in "…"
Wrong arrowNothing renders--> in flowcharts, ->> in sequences
Missing endError on the last lineEvery subgraph needs an end

Three limits and one warning

  • At most 10 diagrams per post, 120 lines per diagram, and a 2 second render timeout.
  • Mermaid's click and href directives are stripped — they are script and link injection

through the back door of a "diagram" block.

  • A diagram should carry a one-line caption. That caption is the text description for people who

cannot see the picture, and it is what search indexes. Missing it is a warning, not a block.