references/output-formats.md · 24000
T02.I | — | 🔄 Mitigated by Platform (Azure AD) |
Every threat from `2-stride-analysis.md` must appear in this table. Status is one of:
- `✅ Covered (FIND-XX)` — finding documents a vulnerability that needs remediation
- `✅ Mitigated (FIND-XX)` — finding documents an existing control the team built (gives credit for security work done)
- `🔄 Mitigated by Platform` — external system handles it (only for genuinely external platforms)
**⛔ THIS TABLE IS A FEEDBACK LOOP, NOT DOCUMENTATION:**
The purpose of this table is to force you to check your work. After filling it out:
1. If ANY threat has a `—` dash in the Finding ID column with status other than `🔄 Mitigated by Platform` → **you missed a finding. Go back and create one.**
2. If Platform count > 20% of total threats → **you are overusing Platform as an escape hatch. Re-examine.**
3. If any threat is listed as `⚠️ Accepted Risk` or `⚠️ Needs Review` → **VIOLATION. Create a finding or verify it's genuinely Platform.**
The table should drive you to 100% coverage: every threat maps to either a finding (`✅ Covered`) or a legitimate external platform mitigation (`🔄 Mitigated by Platform`). There is no third option.
**⛔ FINDING GENERATION RULE:**
If a threat in `2-stride-analysis.md` has a non-empty `Mitigation` column, it MUST become a finding. The mitigation text provides the remediation — use it. The only exception is threats genuinely mitigated by an EXTERNAL platform (Azure AD, K8s RBAC, TPM hardware) that this code cannot disable.
---
## 0-assessment.md
**Purpose:** Executive summary, risk rating, action plan, and metadata. The "front page" of the report.
> **⛔ IMPORTANT: Before writing this file, read [skeleton-assessment.md](./skeletons/skeleton-assessment.md) and copy the skeleton VERBATIM. Fill in the `[FILL]` placeholders. This prevents template drift.**
### Section Order (MANDATORY — ALL 7 sections REQUIRED, do NOT skip any)
1. **Report Files** (REQUIRED) — Links to all report deliverables
2. **Executive Summary** (REQUIRED) — Risk rating + coverage. NO separate "Key Recommendations" subsection
3. **Action Summary** (REQUIRED) — Tier-based prioritized action plan with `### Quick Wins` subsection
4. **Analysis Context & Assumptions** (REQUIRED) — Scope, infrastructure context, `### Needs Verification` table, finding overrides
5. **References Consulted** (REQUIRED) — Security standards + component documentation
6. **Report Metadata** (REQUIRED) — Model, timestamps, duration, git info
7. **Classification Reference** (REQUIRED) — MUST be the last section. Static table copied from skeleton.
⚠️ **Enforcement:** If a section has no data, include it with empty tables or "N/A" notes — NEVER omit the section entirely. The agent in previous iterations skipped sections 1, 4, 5, and 6 entirely. ALL SEVEN must be present.
### Report Files Template
The Report Files table MUST list `0-assessment.md` (this file) as the FIRST row, followed by the other files:
```markdown
## Report Files
| File | Description |
|------|-------------|
| [0-assessment.md](0-assessment.md) | This document — executive summary, risk rating, action plan, metadata |
| [0.1-architecture.md](0.1-architecture.md) | Architecture overview, components, scenarios, tech stack |
| [1-threatmodel.md](1-threatmodel.md) | Threat model DFD diagram with element, flow, and boundary tables |
| [1.1-threatmodel.mmd](1.1-threatmodel.mmd) | Pure Mermaid DFD source file |
| [1.2-threatmodel-summary.mmd](1.2-threatmodel-summary.mmd) | Summary DFD (only if generated) |
| [2-stride-analysis.md](2-stride-analysis.md) | Full STRIDE-A analysis for all components |
| [3-findings.md](3-findings.md) | Prioritized security findings with remediation |
⚠️ 0-assessment.md MUST be the first row. The model consistently lists 0.1-architecture.md first — that is WRONG. This file IS the front page of the report and lists itself first.
Risk Rating
The heading must be plain text with NO emojis: ### Risk Rating: Elevated, NOT ### Risk Rating: 🟠 Elevated
Threat Count Context Paragraph
Include at end of Executive Summary:
> **Note on threat counts:** This analysis identified [N] threats across [M] components. This count reflects comprehensive STRIDE-A coverage, not systemic insecurity. Of these, **[T1 count] are directly exploitable** without prerequisites (Tier 1). The remaining [T2+T3 count] represent conditional risks and defense-in-depth considerations.
Action Summary Template
⛔ FIXED PRIORITY MAPPING — The Priority column values are DETERMINISTIC, not judgment-based: | Tier | Priority | Always | |------|----------|--------| | Tier 1 | 🔴 Critical Risk | ALWAYS — regardless of threat/finding count | | Tier 2 | 🟠 Elevated Risk | ALWAYS — regardless of threat/finding count | | Tier 3 | 🟡 Moderate Risk | ALWAYS — regardless of threat/finding count |
NEVER change the priority based on how many threats or findings exist in that tier. Even if Tier 1 has 0 threats and 0 findings, the priority is still 🔴 Critical Risk — because IF a Tier 1 threat existed, it would be critical. The priority reflects the tier's inherent severity, not the count. A report with Tier 1 = "🟢 Low Risk" is WRONG and must be fixed.
## Action Summary
| Tier | Description | Threats | Findings | Priority |
|------|-------------|---------|----------|----------|
| Tier 1 | Directly exploitable | 5 | 3 | 🔴 Critical Risk |
| Tier 2 | Requires authenticated access | 8 | 4 | 🟠 Elevated Risk |
| Tier 3 | Requires prior compromise | 12 | 5 | 🟡 Moderate Risk |
| **Total** | | **25** | **12** | |
⛔ EXACTLY 4 ROWS: The Action Summary table MUST have exactly 4 data rows: Tier 1, Tier 2, Tier 3, and Total. Do NOT add rows for "Mitigated", "Platform", "Fixed", "Accepted", or any other status. Mitigated threats are distributed across their respective tiers — they are NOT a separate tier. If you find yourself adding a "Mitigated" row, STOP and remove it.
### Quick Wins
<!-- Tier 1 findings with Low remediation effort — high impact, quick fixes -->
| Finding | Title | Why Quick |
|---------|-------|-----------|
| FIND-XX | [title] | [reason] |
⚠️ Quick Wins is a REQUIRED subsection. The ### Quick Wins heading and table MUST appear after the tier summary table inside Action Summary. If no low-effort findings exist, write: ### Quick Wins\n\nNo low-effort findings identified. All findings require Medium or High effort.
Processing Rules for Action Summary:
- Populate the tier table with actual counts from
3-findings.md(findings per tier) and2-stride-analysis.md(threats per tier from T1/T2/T3 columns in summary table) - Quick Wins lists only Tier 1 findings with
Remediation Effort: Low— highest-impact, lowest-effort items - If no Tier 1 Low-effort findings exist, show Tier 2 Low-effort findings instead, with a note: "No Tier 1 quick wins identified. These Tier 2 items offer the best effort-to-impact ratio:"
- If no Low-effort findings exist at all, keep
### Quick Winsheading and add:No low-effort findings identified. All findings require Medium or High effort. - Verify: Findings column sums must equal total findings count in
3-findings.md - Verify: Threats column sums must equal total threats count in
2-stride-analysis.mdsummary table
⛔ PROHIBITED Content in Action Summary and All Output Files
NEVER generate ANY of the following:
### Priority Remediation by Phaseor any phase-based remediation roadmap- Sprint references (
Sprint 1-2,Sprint 3-4, etc.) - Time-based phases (
Phase 1 — Immediate,Phase 2 — Short-term,Phase 3 — Medium-term,Phase 4 — Long-term,Backlog) - Time-to-fix estimates (
~1 hour,~2 hours,~4 hours,1-2 days, etc.) - Timeline or scheduling language (
immediately,next quarter,within 30 days,addressed within) - Effort duration labels (
(hours),(days),(weeks)) after Low/Medium/High effort levels
The report identifies WHAT to fix and WHY (tier + severity + effort level). It does NOT prescribe WHEN to fix it. Scheduling is the team's responsibility. Only use Low, Medium, High for remediation effort — never attach time durations.
Analysis Context & Assumptions Template
⚠️ This ENTIRE section is REQUIRED. Previous iterations skipped it entirely. Include ALL sub-sections below, even if tables are empty.
## Analysis Context & Assumptions
### Analysis Scope
| Constraint | Description |
|------------|-------------|
| Scope | [Full repo or specific area] |
| Excluded | [What was excluded] |
| Focus Areas | [Special focus if any] |
### Infrastructure Context
| Category | Discovered from Codebase | Findings Affected |
|----------|--------------------------|-------------------|
**Every entry in "Discovered from Codebase" MUST include a relative link to the source file or document from which the information was inferred.** Example:
```
| Deployment Model | Air-gapped, single-admin workstation ([daemon.json](src/Container/Moby/daemon.json), [InstallAzureEdgeDiagnosticTool.ps1](src/Setup/InstallArtifacts/InstallAzureEdgeDiagnosticTool.ps1)) | All findings — no Tier 1 |
| Network Exposure | All services bind to localhost:80 only ([KustoContainerHelper.psm1](src/Container/Kusto/KustoContainerHelper.psm1)) | FIND-01, FIND-03 |
```
### Needs Verification
| Item | Question | What to Check | Why Uncertain |
|------|----------|---------------|---------------|
### Finding Overrides
| Finding ID | Original Severity | Override | Justification | New Status |
|------------|-------------------|----------|---------------|------------|
| — | — | — | No overrides applied. Update this section after review. | — |
### Additional Notes
<!-- Any other context from the user's prompt -->
[Freeform notes provided by user]
References Consulted Template
⛔ CRITICAL: This section MUST have TWO subsections with THREE-column tables including full URLs. Do NOT flatten into a simple 2-column
| Reference | Usage |table. The model ALWAYS tries to simplify this — do NOT simplify it.
## References Consulted
### Security Standards
| Standard | URL | How Used |
|----------|-----|----------|
| Microsoft SDL Bug Bar | https://www.microsoft.com/en-us/msrc/sdlbugbar | Severity classification |
| OWASP Top 10:2025 | https://owasp.org/Top10/2025/ | Threat categorization |
| CVSS 4.0 | https://www.first.org/cvss/v4.0/specification-document | Risk scoring |
| CWE | https://cwe.mitre.org/ | Weakness classification |
| STRIDE | https://learn.microsoft.com/en-us/azure/security/develop/threat-modeling-tool-threats | Threat enumeration methodology |
| NIST SP 800-53 Rev. 5 | https://csrc.nist.gov/pubs/sp/800-53/r5/upd1/final | Control mapping |
### Component Documentation
| Component | Documentation URL | Relevant Section |
|-----------|------------------|------------------|
| [e.g., Dapr] | [e.g., https://docs.dapr.io/operations/security/] | [e.g., mTLS configuration] |
| [e.g., Redis] | [e.g., https://redis.io/docs/management/security/] | [e.g., Authentication] |
Processing Rules:
- Always include the Security Standards table — populate with actual standards consulted
- Every row MUST have a full URL (https://...) — never omit the URL column
- Populate Component Documentation with technologies actually consulted during analysis
- Do not add documentation that was not used
Report Metadata Template
⛔ CRITICAL: ALL fields below are MANDATORY. Do NOT skip Model, Analysis Started, Analysis Completed, or Duration. The previous run omitted these — that is a critical failure. Run
Get-Dateat start and end to compute Duration.
## Report Metadata
| Field | Value |
|-------|-------|
| Source Location | `[Full path]` |
| Git Repository | `[Remote URL or "Unavailable"]` |
| Git Branch | `[Branch name or "Unavailable"]` |
| Git Commit | `[Short SHA]` (`[YYYY-MM-DD]` — run `git log -1 --format="%cs" [SHA]` to get commit date) |
| Model | `[Model name — ask the system or state the model you are running as]` |
| Machine Name | `[hostname]` |
| Analysis Started | `[UTC timestamp from command]` |
| Analysis Completed | `[UTC timestamp from command]` |
| Duration | `[Computed difference between started and completed]` |
| Output Folder | `[folder name]` |
| Prompt | `[The user's prompt text that triggered this analysis]` |
Gathering rules:
- START_TIME: Run
Get-Date -Format "yyyy-MM-dd HH:mm:ss" -AsUTCat workflow Step 1 - END_TIME: Run again before writing 0-assessment.md
- Git fields:
git remote get-url origin,git branch --show-current,git rev-parse --short HEAD - If any command fails → "Unavailable"
- NEVER estimate timestamps from folder names
- Model: State the model you are currently running as (e.g.,
Claude Opus 4.6,GPT-5.3 Codex,Gemini 3 Pro) - Machine: run
hostname
Coverage Counts Consistency
Before writing 0-assessment.md:
- Count elements from
1-threatmodel.mdElement Table - Count findings from
3-findings.md - Count threats from
2-stride-analysis.mdsummary table - Use these exact numbers in Executive Summary and Action Summary
Formatting Rules
---horizontal rules between every##section- Report Metadata values all wrapped in backticks
- Finding Overrides always uses table format (even when empty)
- Report Files section always first
0.1-architecture.mdalways listed in Report Files table
Common Mistakes Checklist
These are the most observed deviations. Check after writing each file:
- ❌ Organizing by severity → ✅ Organize by Exploitability Tier
- ❌ Flat STRIDE tables → ✅ Split into Tier 1/2/3 sub-sections per component
- ❌ Missing
Exploitability TierandRemediation Effort→ ✅ MANDATORY on every finding - ❌ STRIDE summary missing T1/T2/T3 columns → ✅ Include T1|T2|T3 columns
- ❌ Wrapping
.mdin```markdowncode fences → ✅ Start with# Headingon line 1. Thecreate_filetool writes raw content — fences become literal text in the file. - ❌ Wrapping
.mmdin```plaintextor```mermaid→ ✅ Start with%%{init:on line 1. The.mmdfile is raw Mermaid source. - ❌ Missing Action Summary → ✅ Section MUST be titled exactly
## Action Summary. MUST include### Quick Winssubsection with table of Tier 1 low-effort findings. - ❌ Missing threat count context paragraph → ✅ Include
> **Note on threat counts:**blockquote in Executive Summary - ❌ Omitting empty tier sections → ✅ Always include all three tiers per component
- ❌ Adding separate
### Key Recommendationsor### Top Recommendationsor### Priority Remediation Roadmap→ ✅ Action Summary IS the recommendations — no other name. - ❌ Drawing sidecars as separate nodes → ✅ See
diagram-conventions.mdRule 1 - ❌ Missing CVSS 4.0 vector string → ✅ Every finding MUST have both score AND full vector (e.g.,
CVSS:4.0/AV:N/AC:L/...) - ❌ Missing CWE or OWASP on findings → ✅ MANDATORY on every finding
- ❌ Using OWASP
:2021suffix → ✅ ALWAYS use:2025(e.g.,A01:2025 – Broken Access Control). The 2025 edition is current. - ❌ Missing Threat Coverage Verification table → ✅ Required at end of
3-findings.md - ❌ Architecture component not in STRIDE analysis → ✅ Every component in 0.1-architecture.md must have a STRIDE section
- ❌ Missing sequence diagrams for top scenarios → ✅ First 3 scenarios in 0.1-architecture.md MUST have Mermaid sequence diagrams
- ❌ Missing Needs Verification section in 0-assessment.md → ✅ Include under Analysis Context & Assumptions
- ❌ Missing
## Analysis Context & Assumptionssection entirely → ✅ REQUIRED. Previous iterations skipped this section. Must include Scope, Needs Verification, and Finding Overrides sub-tables. - ❌ Missing
### Quick Winssubsection → ✅ REQUIRED under Action Summary. List Tier 1 low-effort findings; if none, include heading with note. - ❌ Skipping
## Report Files,## References Consulted, or## Report Metadata→ ✅ ALL 7 sections in 0-assessment.md are MANDATORY. Never omit any. - ❌ Finding IDs out of order (FIND-06 before FIND-04) → ✅ Finding IDs MUST be sequential top-to-bottom: FIND-01, FIND-02, FIND-03, ... Renumber after sorting.
- ❌ CWE without hyperlink → ✅ CWE MUST include hyperlink:
[CWE-306](https://cwe.mitre.org/data/definitions/306.html): Missing Authentication for Critical Function - ❌ Time estimates or scheduling in output → ✅ NEVER generate
~1 hour,Sprint 1-2,Phase 1 — Immediate,(hours), or any timeline/duration in ANY output file. The report says WHAT to fix, not WHEN.
threat-inventory.json
Purpose: Structured JSON inventory of all components, data flows, boundaries, threats, and findings. This file enables automated comparison between two threat model runs.
When to generate: Every run (Step 8b). Generated AFTER all markdown files are written.
NOT linked in 0-assessment.md — this is a machine-readable artifact, not a human-readable report file.
Schema
{
"schema_version": "1.0",
"commit": "abc1234",
"commit_date": "2025-08-15",
"branch": "main",
"analysis_timestamp": "2025-08-15T14:30:00Z",
"repository": "https://github.com/org/repo",
"report_folder": "threat-model-20250815-143000",
"components": [
{
"id": "RedisStateStore",
"display": "Redis State Store",
"aliases": ["Redis", "StateStoreRedis"],
"type": "data_store",
"tmt_type": "SE.DS.TMCore.NoSQL",
"boundary": "DataLayer",
"boundary_kind": "ClusterBoundary",
"source_files": ["helmchart/myapp/templates/redis-statefulset.yaml"],
"fingerprint": {
"component_type": "data_store",
"boundary_kind": "ClusterBoundary",
"source_files": ["helmchart/myapp/templates/redis-statefulset.yaml"],
"source_directories": ["helmchart/myapp/templates/"],
"class_names": [],
"namespace": "",
"api_routes": [],
"config_keys": ["REDIS_HOST", "REDIS_PORT"],
"dependencies": [],
"inbound_from": ["InferencingFlow"],
"outbound_to": [],
"protocols": ["TCP"]
},
"sidecars": []
}
],
"boundaries": [
{
"id": "DataLayer",
"display": "Data Layer",
"aliases": ["Data Boundary", "Persistence Layer"],
"kind": "ClusterBoundary",
"contains": ["RedisStateStore", "VectorDB"],
"contains_fingerprint": "RedisStateStore|VectorDB"
}
],
"flows": [
{
"id": "DF_InferencingFlow_to_Redis",
"display": "DF25: InferencingFlow → Redis",
"from": "InferencingFlow",
"to": "RedisStateStore",
"protocol": "TCP",
"label": "State store operations",
"bidirectional": true,
"security": {
"encryption": "none",
"authentication": "none"
}
}
],
"threats": [
{
"id": "T05.I",
"identity_key": {
"component_id": "RedisStateStore",
"stride_category": "I",
"attack_surface": "helmchart/values.yaml:redis.tls.enabled",
"data_flow_id": "DF_InferencingFlow_to_Redis"
},
"title": "Information Disclosure — Redis unencrypted traffic",
"description": "Redis state store transmits data without TLS...",
"tier": 1,
"prerequisites": "None",
"affected_flow": "DF25",
"mitigation": "Enable TLS on Redis connections",
"status": "Open"
}
],
"findings": [
{
"id": "FIND-01",
"identity_key": {
"component_id": "RedisStateStore",
"vulnerability": "CWE-306",
"attack_surface": "helmchart/values.yaml:redis.auth"
},
"title": "Redis state store has no authentication",
"severity": "Critical",
"cvss_score": 9.4,
"cvss_vector": "CVSS:4.0/AV:N/AC:L/AT:N/PR:N/UI:N/VC:H/VI:H/VA:H/SC:N/SI:N/SA:N",
"cwe": "CWE-306",
"owasp": "A07:2025",
"tier": 1,
"effort": "Low",
"related_threats": ["T05.I", "T05.T"],
"evidence_files": ["helmchart/myapp/values.yaml"],
"component": "Redis State Store"
}
],
"metrics": {
"total_components": 15,
"total_flows": 30,
"total_boundaries": 7,
"total_threats": 97,
"total_findings": 18,
"threats_by_tier": { "T1": 12, "T2": 53, "T3": 32 },
"findings_by_tier": { "T1": 7, "T2": 7, "T3": 4 },
"findings_by_severity": { "Critical": 4, "Important": 8, "Moderate": 6 },
"threats_by_stride": { "S": 14, "T": 19, "R": 8, "I": 20, "D": 15, "E": 14, "A": 7 }
}
}
⛔ stride_category MUST be a SINGLE LETTER:
S,T,R,I,D,E, orA. NEVER use full names like"Spoofing"or"Denial of Service". The heatmap computation and comparison matching depend on single-letter codes. If you write"stride_category": "Denial of Service"instead of"stride_category": "D", the heatmap will show all zeros for STRIDE columns while tier columns have correct values — this is a critical data integrity bug.
Incremental Analysis Extensions
When generating threat-inventory.json for an incremental analysis (see incremental-orchestrator.md), add these fields:
Top-level fields:
"incremental": true— marks this as an incremental report"baseline_report": "threat-model-20260309-174425"— path to baseline report folder"baseline_commit": "2dd84ab"— the commit SHA of the baseline report"target_commit": "abc1234"— the commit being analyzed"schema_version": "1.1"— incremental reports use schema version 1.1
Per-component: "change_status" — one of:
"unchanged"— source files identical or cosmetic-only changes"modified"— security-relevant source file changes"restructured"— files moved/renamed, same logical component"removed"— source files deleted"new"— component didn't exist at baseline"merged_into:{id}"— merged into another component"split_into:{id1},{id2}"— split into multiple components
Per-threat: "change_status" — one of:
"still_present"— threat exists in current code, same as before"fixed"— vulnerability was remediated (must cite code change)"mitigated"— partial remediation applied"modified"— threat still exists but details changed"new_code"— threat from a genuinely new component"new_in_modified"— threat introduced by code changes in existing component"previously_unidentified"— threat existed in baseline code but wasn't in old report"removed_with_component"— component was removed
Per-finding: "change_status" — same values as per-threat, plus:
"partially_mitigated"— code changed partially, vulnerability partially remains
metrics.status_summary — counts per change_status for components, threats, and findings. See incremental-orchestrator.md §4f for the full schema.
Canonical Naming Rules
Component IDs — Derived from actual class/file names, PascalCase:
SupportabilityAgent.cs→SupportabilityAgentPowerShellCommandExecutor.cs→PowerShellCommandExecutor- "Redis State Store" →
RedisStateStore - "Ingress-NGINX" →
IngressNginx
Flow IDs — Deterministic from endpoints:
- Format:
DF_{Source}_to_{Target} DF_Operator_to_TerminalUIDF_InferencingFlow_to_RedisStateStore
Identity Keys — Each threat and finding gets a canonical identity key:
- Threats:
component_id+stride_category+attack_surface+data_flow_id - Findings:
component_id+vulnerability(CWE) +attack_surface - These keys are independent of LLM-generated prose — they anchor to code artifacts
Deterministic Identity Rules (MANDATORY)
Use these rules so repeated runs on unchanged code produce comparable inventories.
- Canonical ID vs display name
idis stable identity;displayis presentation text- Never derive identity from prose wording in findings or diagram labels
- Alias capture