Threat Modeling Artefacts

Threat-modelling Artefacts

This skill turns threat-modelling analysis into shippable deliverables. The companion threat-modeling skill teaches you how to think about threats systematically; this skill produces the artefacts an appsec engineer or consultant actually ships in a real engagement.

It is a router: the SKILL.md body points you at one of seven deliverable workflows. Each workflow is documented in detail in references/ and shipped with a skeletal template in assets/templates/ plus a complete worked example in assets/worked-examples/ using a single fictional system, Acme Lending.

When to use this skill

Use this skill when the user asks for an artefact. Trigger words: produce, draft, generate, write, create, build, ship, render, output. Object words: threat model document, TM doc, risk register, kickoff pack, pre-mortem, acceptance criteria, security stories, squad kickstart, executive summary, exec summary, compliance evidence, control mapping, APRA mapping, ASVS evidence, ISO 27001 mapping, NIST CSF mapping.

Do not use this skill for analytical asks — "what is STRIDE", "what could go wrong with X", "is OAuth client credentials safe here", "build me a DFD" (the diagram alone is analysis, not a deliverable). Those go to the threat-modeling skill.

If the user asks for something that combines both (e.g. "threat model my partner API and produce the threat model document"), use the threat-modeling skill first to do the analysis, then use this skill to package the output.

The seven deliverable types

Each reference file documents the deliverable's purpose, required sections, customisation points, and rendering options. Each pairs with a skeletal template and a complete Acme Lending worked example so you can see the bar before you start filling in.

Capability detection — run this before producing any rendered output

Markdown and CSV outputs work everywhere with no tooling. DOCX, PDF, and XLSX require either an installed agent skill (docx, pdf, xlsx, pptx) or Python with pandoc / openpyxl on the host.

Run this probe before producing any rendered-output deliverable, in this order:

1. Inspect available_skills in the current session. If docx, pdf, xlsx, or pptx is present, prefer the agent skill for that format — they produce the cleanest output and route through the platform's sanctioned pipeline.
2. Probe Python. On Windows, the canonical command is python. On macOS and Linux, it is usually python3, sometimes python. Try python --version; if that fails, try python3 --version. If either succeeds, the bundled scripts under scripts/ can be used.
3. Probe pandoc (pandoc --version) if DOCX or PDF rendering is needed. Pandoc is the dependency for render_to_docx.py and render_to_pdf.py.
4. Probe openpyxl (python -c "import openpyxl") if XLSX rendering is needed via the bundled script.

If neither path is available, produce markdown and CSV only. Tell the user briefly what was used and what wasn't — e.g. "Produced markdown only — DOCX rendering wasn't available in this environment (neither the docx agent skill nor pandoc was found)."

Full algorithm and code snippets: references/capability-detection.md.

The fallback hierarchy by format

The Python scripts are optional fallbacks, not the default path. They exist for environments where agent skills aren't available but Python is. Markdown and CSV outputs are guaranteed regardless of environment.

Dependency on the threat-modeling skill

This skill is a soft dependency on threat-modeling. If that skill is installed in the session, route analytical content (STRIDE letters, OAuth threats, GraphQL hardening, OWASP API Top 10, MITRE ATLAS, OWASP LLM Top 10, etc.) through it rather than restating the analysis here.

Detection: check whether threat-modeling appears in available_skills. If yes, in any reference that needs analytical content, point to the right file in that skill — e.g. "For STRIDE detail, see threat-modeling/references/stride.md". If no, fall back to references/analytical-fallback.md which carries a minimal analytical summary so this skill still works standalone.

The fallback is intentionally minimal — it's a safety net, not a replacement. The output the user gets is richer when both skills are present.

Workflow per deliverable type

For every deliverable, follow this sequence:

1. Read the reference for that deliverable type (e.g. references/threat-model-document.md).
2. Load analytical content from the threat-modeling skill (when present) or from references/analytical-fallback.md (when not). Anything STRIDE-related, OAuth threat catalogues, GraphQL threats, ML pipeline threats, etc. flows through that route.
3. Look at the worked example (assets/worked-examples/) for the same deliverable type. The Acme Lending examples are the shipping bar.
4. Run capability detection (above) if a rendered-output format is requested.
5. Fill in the template (assets/templates/). Templates have <!-- INSTRUCTION: ... --> and <!-- HOUSE STYLE: ... --> markers that explain section purpose and customisation points.
6. Render through the highest available path in the fallback hierarchy.
7. Validate with the bundled lints where applicable — validate_mermaid.py on any DFD, threat_id_check.py across the artefact set.
8. Output to the user with a one-sentence note describing the capability path used.

Customisation — house style

Templates default to common patterns (Mermaid, markdown, CSV, the canonical sections in the references). They are not meant to be opinionated — different organisations have different house styles. Customisation points are marked inline with <!-- HOUSE STYLE: ... --> comments.

Common house-style customisations and where to make them: references/house-style-customisation.md.

Critical rules

• Australian English throughout (organisation, analyse, behaviour, defence, customise, prioritise, authorise, artefacts).
• Imperative tone in references; declarative tone in templates and worked examples.
• Threat IDs are required. Format: TM-[component]-[number] — e.g. TM-AUTH-001, TM-WEBHOOK-014. Every threat in a template, worked example, or generated artefact has one. Acceptance criteria back-reference threat IDs. Risk register entries reference threat IDs. Compliance mappings reference threat IDs.
• Cross-reference, don't duplicate. Analytical content sits in the threat-modeling skill or in analytical-fallback.md. Don't restate STRIDE letters or OWASP categories here.
• Capability detection runs before rendered-output deliverables. Don't assume DOCX or XLSX is available; probe and adapt.
• Markdown and CSV are floors. Always produce these when relevant. DOCX, PDF, and XLSX are quality-of-life additions when the environment supports them.
• Acme Lending is fictional. The worked examples are illustrative. Never attribute Acme Lending content to a real organisation.
• No bullet points in declines or warnings. Use prose for those.

Quick reference — what to read for each deliverable

Detail references

Template index

Worked-example index — Acme Lending

assets/worked-examples/README.md describes the fictional Acme Lending scenario. The seven primary worked examples plus four compliance mappings demonstrate the deliverable shape and quality bar:

Threat IDs are reused consistently across the worked examples — TM-API-003 in the threat model document is the same TM-API-003 referenced in the risk register, the acceptance criteria, and the compliance mappings.

Scripts (optional fallback)

Each script supports --help, performs a dependency check at startup, and exits non-zero with a clear message if a dependency is missing — so a failed fallback degrades to markdown/CSV gracefully.

Embedding Mermaid diagrams in DOCX / PDF. Pandoc on its own embeds Mermaid blocks as fenced code, not as rendered diagrams. To get diagrams inside a Word doc or PDF, chain the two scripts: python scripts/prerender_mermaid.py input.md --output input-rendered.md then python scripts/render_to_docx.py input-rendered.md. The chain is designed for graceful degradation — if Mermaid CLI / Node / npx / a browser isn't available, prerender_mermaid.py copies its input to its output unchanged and exits 0, so the next step still produces a valid DOCX (with Mermaid blocks shown as fenced code rather than diagrams). When a single block fails to render, the others still render and the failed block stays as fenced code. Pass --strict to fail fast instead. Default output format is PNG at 3200px width and 2x scale — high enough that Word's downsample stays sharp. See references/capability-detection.md for the full contract, including when to switch to --format svg (PDF / HTML targets, or DOCX with rsvg-convert installed).

Notes on framework currency

The compliance evidence templates reference specific framework versions and clauses. If any of the version numbers look out of date, run the update-threat-modeling-resources skill, which keeps the threat-modelling reference material and its sister skills current.