chore(#223): add Data Flow Diagram section to threat-model template by atlas-apex · Pull Request #225 · me2resh/apexyard

atlas-apex · 2026-05-11T23:11:31Z

Summary

Add a ## Data Flow Diagram section to templates/audits/threat-model.md (between the H1 and the existing ## Attack surface). The section ships a Mermaid flowchart LR skeleton with three trust boundaries drawn as dashed subgraph blocks (public internet, backend network, third-party service), realistic node placeholders (external user, web frontend, API service, primary data store, external service), and labelled arrows naming the data that crosses each boundary (auth tokens, user PII, transaction records, callbacks).
Update .claude/skills/threat-model/SKILL.md Step 1 ("Map the attack surface") to instruct the operator to populate the DFD section of the per-run artefact first, and to drive the Step 2 STRIDE walk from the DFD's trust-boundary crossings rather than inventing threats ad-hoc.
Why: proper STRIDE analysis starts with a DFD identifying trust boundaries — without one the threat catalogue is per-run improvisation. Mermaid is the framework's chosen diagram language per AgDR-0003 (templates/architecture/c4-context.md and c4-container.md already use it), so adopters render the skeleton in any GitHub markdown view with zero build step.

Testing

Open templates/audits/threat-model.md in GitHub's rendered preview (or a Mermaid-aware viewer like https://mermaid.live/) and confirm the Mermaid block parses without errors.
Confirm three subgraphs render with dashed outlines (the style <id> stroke-dasharray: 5 5 declarations apply to each boundary).
Confirm every cross-boundary arrow displays its data label (e.g. auth token, user PII).
Edit the skeleton — replace placeholders with a real system's entities — and re-render to confirm the structure is editable, not just decorative.
Open .claude/skills/threat-model/SKILL.md and confirm Step 1 now leads with the DFD-population instruction and references the template section by name.

Glossary

Term	Definition
DFD (Data Flow Diagram)	The canonical input artefact for STRIDE: a graph of external entities, processes, data stores, and the data flowing between them, partitioned by trust boundary. STRIDE iterates the DFD's elements rather than free-form brainstorming, which is what makes the resulting catalogue systematic.
STRIDE	Microsoft-originated threat-modelling taxonomy: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege. Each STRIDE category has a natural target element class on a DFD (e.g. spoofing applies most acutely to external entities and processes; tampering applies to data flows and stores).
Trust boundary	A border in a DFD across which the level of trust changes — e.g. public internet ↔ backend network, backend ↔ third-party service. Threats apply most acutely to data crossing a trust boundary, because the data leaves a context where assumptions hold and enters one where they don't.
Mermaid `flowchart`	A text-based diagram language renderable in any GitHub markdown view without a build step. The framework chose Mermaid over Structurizr DSL / PlantUML / D2 in AgDR-0003; the C4 architecture templates already use it, so this PR keeps diagram tooling consistent.
`stroke-dasharray: 5 5`	An SVG/CSS stroke attribute that renders the line as 5px-on / 5px-off dashes. Mermaid passes this through `style <node_or_subgraph_id> ...` — the convention the apexyard `c4-container.md` template already uses for soft (logical) boundaries. Used here to visually distinguish trust boundaries from the system's internal structure.
Per-run artefact	The output Markdown file `/threat-model` writes via `_lib-audit-history.sh` for each invocation. Each run gets its own artefact stamped with a timestamp; the trend across runs is visible via `audit_render_trend`. The DFD section lives in this artefact (one DFD per run), not in a global doc, so it captures the system's shape at the SHA the threat model was run against.

Closes #223

atlas-apex

Code Review: PR #225

Commit: a19ae5f60cce6dda32d097b974d0385add5b2254

Summary

Doc-only / template change adding a ## Data Flow Diagram section (Mermaid flowchart LR skeleton with three dashed-subgraph trust boundaries + labelled cross-boundary arrows) to templates/audits/threat-model.md, plus a Step 1 update in .claude/skills/threat-model/SKILL.md pointing the operator at the new DFD as the natural starting artefact for STRIDE.

Checklist Results

Architecture & Design: Pass (no code change; Mermaid choice already settled in AgDR-0003, correctly cited)
Code Quality: Pass (template-only)
Testing: N/A (template change, no logic)
Security: Pass (no auth/secret/PII surface; this PR strengthens security workflow rigor)
Performance: N/A
PR Description & Glossary: Pass (Summary + Testing + Glossary all present; glossary covers DFD, STRIDE, trust boundary, Mermaid flowchart, stroke-dasharray: 5 5, per-run artefact — substantive, not boilerplate)
Technical Decisions (AgDR):N/A (no new decision; AgDR-0003 already governs Mermaid choice and is cited)

Verification of requested checks

Mermaid syntax valid — confirmed. flowchart LR, three subgraph <id> ["..."] blocks (internet, backend, thirdparty), node IDs with proper shapes (user([...]), web[...], db[(...)]), -->|label| arrow annotations on every cross-boundary flow, three style <id> stroke-dasharray: 5 5 declarations matching the subgraph IDs. Renders cleanly in GitHub's mermaid pipeline.
DFD precedes Attack surface — confirmed. Section ordering: H1 → frontmatter blurb → ## Data Flow Diagram → ## Attack surface → STRIDE table → priority → OWASP → notes. Operator populates the DFD before deriving the attack surface, as intended.
SKILL.md Step 1 references the DFD section — confirmed. Step 1 opens with "Populate the Data Flow Diagram first in this run's per-run artefact (per templates/audits/threat-model.md § Data Flow Diagram)" and explicitly states "The STRIDE walk in Step 2 then iterates the DFD's trust-boundary crossings rather than inventing threats ad-hoc" — exactly the workflow shift the change is meant to enforce.
PR body — ## Summary / ## Testing / ## Glossary all present. Glossary is unusually substantive (6 terms, each with reasoning, not just definitions).
Commit format — chore(#223): add Data Flow Diagram section to threat-model template matches type(#NN): description. Body has bulleted what + why + Closes #223.
Leak protection — no private project names in PR body or commit messages.

Issues Found

None blocking on the DFD scope.

Notes (non-blocking)

Stacked-branch artefact: gh pr view reports 9 files / 1552 additions because the branch is stacked on feature/GH-218-audit-artefact-persistence (PR #222). The DFD-scope diff is correctly limited to the two target files; the other 7 files belong to #222 and will collapse out of this PR's view once #222 merges and #225 rebases. Reviewer of record on those 7 files is whoever reviews #222 — Rex's verdict here is scoped to the DFD change only.
CI red — not caused by this PR: the markdownlint-cli2 check is FAILING (MD032/blanks-around-lists in .claude/skills/launch-check/SKILL.md:358), but the offending line is part of the #222 changes, not the DFD. The merge-gate red-CI rule (.claude/rules/pr-quality.md § "No Red CI Before Merge") still applies — do not merge #225 until either (a) #222 merges first and #225 is rebased, or (b) the lint failure is fixed in this stack. Raising as an advisory because the cause is upstream of this PR's scope.

Verdict

APPROVED (DFD scope). Hold the merge until the markdown-lint failure is resolved per the rule above — it's not in this PR's diff, but the gate still applies.

Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: a19ae5f60cce6dda32d097b974d0385add5b2254

- Add `## Data Flow Diagram` section to `templates/audits/threat-model.md` before the existing `## Attack surface` section. Section ships a Mermaid `flowchart` skeleton with three trust boundaries drawn as dashed subgraphs (public internet, backend network, third-party service), realistic node placeholders (external user, web frontend, API, primary data store, external service), and labelled arrows naming the data that crosses each boundary (auth tokens, user PII, transaction records, callbacks). - Update `.claude/skills/threat-model/SKILL.md` Step 1 ("Map the attack surface") to instruct the operator to populate the DFD section first and to drive the Step 2 STRIDE walk from the DFD's trust-boundary crossings rather than ad-hoc threat brainstorming. Why: proper STRIDE analysis starts with a DFD identifying trust boundaries — without one, the threat catalogue is invented per-run rather than systematically derived. Mermaid was chosen as the diagram language per AgDR-0003 (templates/architecture/c4-context.md and container.md already use it), so adopters render the skeleton in any GitHub markdown view with zero build step. Closes #223

atlas-apex

Re-review after rebase onto post-#222 dev.

Verified:

New HEAD 7dc4dfa6eefce22cdddd714d8de5f55ddebcde2d contains identical content to previously-approved a19ae5f: DFD section added before ## Attack surface in templates/audits/threat-model.md + Step 1 reference update in .claude/skills/threat-model/SKILL.md.
No scope creep, no rebase artefacts, no missed conflicts.
CI green: lychee, markdownlint-cli2, Verify Ticket ID all SUCCESS.

Verdict: APPROVED (posted as comment — gh blocks self-approve on own PR).

Approval marker refreshed at .claude/session/reviews/225-rex.approved with new SHA.

Reviewed by Rex (Code Reviewer Agent)
Reviewed commit: 7dc4dfa6eefce22cdddd714d8de5f55ddebcde2d

…225) - Add `## Data Flow Diagram` section to `templates/audits/threat-model.md` before the existing `## Attack surface` section. Section ships a Mermaid `flowchart` skeleton with three trust boundaries drawn as dashed subgraphs (public internet, backend network, third-party service), realistic node placeholders (external user, web frontend, API, primary data store, external service), and labelled arrows naming the data that crosses each boundary (auth tokens, user PII, transaction records, callbacks). - Update `.claude/skills/threat-model/SKILL.md` Step 1 ("Map the attack surface") to instruct the operator to populate the DFD section first and to drive the Step 2 STRIDE walk from the DFD's trust-boundary crossings rather than ad-hoc threat brainstorming. Why: proper STRIDE analysis starts with a DFD identifying trust boundaries — without one, the threat catalogue is invented per-run rather than systematically derived. Mermaid was chosen as the diagram language per AgDR-0003 (templates/architecture/c4-context.md and container.md already use it), so adopters render the skeleton in any GitHub markdown view with zero build step. Closes #223 Co-authored-by: me2resh <ahmed.abdelaliem@gmail.com>

github-actions Bot added github-issue has-ticket labels May 11, 2026

atlas-apex commented May 12, 2026

View reviewed changes

me2resh force-pushed the chore/GH-223-threat-model-dfd branch from a19ae5f to 7dc4dfa Compare May 12, 2026 07:59

atlas-apex commented May 12, 2026

View reviewed changes

atlas-apex merged commit 403f282 into dev May 12, 2026
3 checks passed

atlas-apex deleted the chore/GH-223-threat-model-dfd branch May 12, 2026 12:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(#223): add Data Flow Diagram section to threat-model template#225

chore(#223): add Data Flow Diagram section to threat-model template#225
atlas-apex merged 1 commit into
devfrom
chore/GH-223-threat-model-dfd

atlas-apex commented May 11, 2026

Uh oh!

atlas-apex left a comment

Uh oh!

atlas-apex left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

atlas-apex commented May 11, 2026

Summary

Testing

Glossary

Uh oh!

atlas-apex left a comment

Choose a reason for hiding this comment

Code Review: PR #225

Summary

Checklist Results

Verification of requested checks

Issues Found

Notes (non-blocking)

Verdict

Uh oh!

atlas-apex left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants