references/output-formats.md · 48000
- Every component and boundary must include an
aliasesarray- Include discovered synonyms from architecture/DFD/STRIDE/findings (deduplicated, sorted)
- Keep canonical
idstable even if display wording changes across runs
- Boundary kind taxonomy (TMT-aligned)
- Use
boundary_kind/kindfrom this set — describes the NATURE of the trust transition, not what's inside:MachineBoundary— between different hosts/VMs (e.g., host ↔ guest, VM1 ↔ VM2)NetworkBoundary— between network zones (e.g., corporate LAN ↔ internet, DMZ ↔ internal)ClusterBoundary— between K8s/container cluster and outside (e.g., cluster ↔ external services)ProcessBoundary— between OS processes or containers on same host (e.g., sidecar ↔ main container)PrivilegeBoundary— between different privilege levels (e.g., user mode ↔ kernel, unprivileged ↔ admin)SandboxBoundary— between sandboxed and unsandboxed execution (e.g., browser sandbox, WASM)
- Each value answers: "what changes when you cross this line?" (different machine, network, cluster, process, privilege, sandbox)
- Do NOT use component-grouping labels (DataStorage, ApplicationCore, AgentExecution) as boundary kinds — those describe WHAT's inside, not the nature of the trust transition
3b. Boundary ID derivation (MANDATORY — apply the same deterministic naming as components)
- Derive boundary IDs from deployment/infrastructure names, NOT abstract concepts:
- Docker host →
Docker(neverDockerEnvironmentorContainerRuntime) - Kubernetes cluster →
K8sCluster(neverKubernetesEnvironment) - Operator's machine →
OperatorWorkstation(neverHostOSorLocalMachine) - External cloud services →
ExternalServices(neverCloudBoundary) - Data storage grouped →
DataStorage(neverDataLayerorPersistenceLayer) - Backend application services →
BackendServices(neverAppBoundaryorApplicationCore) - ML/AI inference models →
MLModels(neverInferenceModelsorModelBoundary) - DMZ/public zone →
PublicZone(neverDMZBoundaryorIngressZone) - Agent execution →
AgentExecution(keep this exact ID) - Tool execution →
ToolExecution(keep this exact ID)
- Docker host →
- Once a boundary ID is chosen in Step 1, use it EVERYWHERE (DFD, tables, JSON)
- Never restructure containment between runs on the same code (same component → same boundary)
- Component fingerprint
fingerprintmust be built from stable evidence:- sorted
source_files— full file paths to primary source files - sorted
source_directories— parent directory paths of source files (more stable than filenames across refactors) - sorted
class_names— primary class, struct, or interface names defined in the component's source files (e.g.,["HealthServer", "IHealthService"]). For non-code components (datastores, external services), leave empty. namespace— the primary namespace/package (e.g.,"MCP.Core.Servers.Health"for C#,"ragapp.src.ingestflow"for Python). Empty for non-code components.- sorted
api_routes— HTTP API endpoint patterns exposed by this component (e.g.,["/api/health", "/api/v1/chat"]). Empty if not an HTTP service. - sorted
config_keys— environment variables and configuration keys consumed by this component (e.g.,["AZURE_OPENAI_ENDPOINT", "REDIS_HOST"]). Extract from appsettings.json, .env files, Helm values, or code that reads env vars. - sorted
dependencies— external package/library dependencies specific to this component (e.g.,["Microsoft.SemanticKernel", "Azure.AI.OpenAI"]for NuGet,["pymilvus", "fastapi"]for pip). Only include packages that are characteristic of this component, not framework-wide dependencies. - sorted
inbound_fromandoutbound_tocomponent IDs - sorted
protocols component_typeandboundary_kind
- sorted
- Do not include mutable prose in the fingerprint
- Deterministic matching priority:
source_directories>class_names>namespace>api_routes>config_keysare all highly stable signals that survive component renames. Two components sharing any of these are almost certainly the same real component.
Fingerprint Field → Comparison Matching Signal Map:
| Fingerprint Field | Comparison Signal | Max Points | Stability |
|---|---|---|---|
| source_files | Signal 2 — Source file/directory overlap | +30 | High (files rarely move) |
| source_directories | Signal 2 — Source file/directory overlap | +25 | Very High (directories almost never change) |
| class_names | Signal 3 — Class/Namespace match | +25 | Very High (classes rarely rename) |
| namespace | Signal 3 — Class/Namespace match | +20 | Very High (namespaces are structural) |
| api_routes | Signal 4 — API route / Config key overlap | +15 | High (API contracts are versioned) |
| config_keys | Signal 4 — API route / Config key overlap | +10 | High (config keys are stable) |
| dependencies | Signal 4 — API route / Config key overlap | +5 | Medium (packages change with upgrades) |
| inbound_from / outbound_to | Signal 5 — Topology overlap | +15 | Low (uses component IDs which may drift) |
| component_type + boundary_kind | Signal 6 — Type + boundary kind | +10 | Medium (boundary naming may vary) |
| protocols | (Not directly scored — used as tiebreaker) | — | Medium |
Every field in this table MUST be populated during analysis (Step 8b). Empty arrays [] are acceptable when the field genuinely doesn't apply (e.g., api_routes for a datastore). But source_directories and class_names must NEVER be empty for process-type components — these are the primary matching anchors.
- Boundary containment fingerprint
contains_fingerprint= sortedcontainsjoined with|- Use this for boundary rename detection during comparison
- Deterministic ordering
- Sort all arrays and nested list fields before writing JSON
- This makes diffs stable and prevents accidental churn
Processing Rules
- Generate AFTER all markdown files are written (Step 8b)
- Populate from the same analysis data used to write the markdown files
- Ensure component IDs use PascalCase derived from actual class/file names
- Ensure flow IDs use the canonical
DF_{Source}_to_{Target}format - All threat and finding identity keys must reference actual code artifacts (file paths, config keys)
- Include git metadata from Step 1 (commit, branch, date)
- The
metricsobject must match the counts in the markdown reports - This file is NOT listed in the Report Files table of
0-assessment.md - Populate
aliases,boundary_kind/kind,fingerprint, andcontains_fingerprintfor deterministic matching - If a component has multiple observed names in the same run, keep one canonical
idand store all alternates inaliases
⚠️ CRITICAL — Array completeness: The
threatsarray MUST contain one entry for every threat listed in2-stride-analysis.md. Thefindingsarray MUST contain one entry for every finding in3-findings.md. Thecomponentsarray MUST contain one entry for every component in the Element Table. Verify:threats.length == metrics.total_threats,findings.length == metrics.total_findings,components.length == metrics.total_components. If mismatched, the JSON is incomplete — go back and add the missing entries. Do NOT truncate arrays to save space.
Self-Check — Run After Writing Each File
⛔ MANDATORY: After writing each file, verify these checks and report results. Fix any ❌ before proceeding.
After 2-stride-analysis.md:
- [ ] Summary table appears BEFORE individual component sections
- [ ] 3 tier sub-sections per component (Tier 1, Tier 2, Tier 3)
- [ ] Status column uses only:
Open,Mitigated,Platform(noAccepted Risk, noNeeds Review) - [ ] Platform ratio within limit (≤20% standalone, ≤35% K8s operator)
- [ ] Every threat has single-letter STRIDE category (S/T/R/I/D/E/A)
After 3-findings.md:
- [ ] 3 tier headings:
## Tier 1,## Tier 2,## Tier 3(all present) - [ ] Zero occurrences of "Accepted Risk" anywhere in the file
- [ ] Every finding has CVSS 4.0 vector string
- [ ] Action Summary: T1=Critical, T2=Elevated, T3=Moderate priorities
- [ ] 4th column header is "Assignment Rule" (not "Example")
After threat-inventory.json:
- [ ]
threats.length == metrics.total_threats(zero tolerance) - [ ]
findings.length == metrics.total_findings(zero tolerance) - [ ] If threats > 50, used sub-agent/Python/chunked — NOT single
create_file - [ ] Every component has non-empty
fingerprint.source_directories - [ ] Arrays sorted by canonical key
- [ ] Field names match schema exactly: components use
display(NOTdisplay_name), threats usestride_category(NOTcategory), threat→component link is insideidentity_key.component_id(NOT top-levelcomponent_id), threats have BOTHtitle(short name) ANDdescription(longer prose) — NOT justdescriptionalone
After 0-assessment.md:
- [ ] Exactly 7 sections: Report Files, Executive Summary, Action Summary, Analysis Context & Assumptions, References Consulted, Report Metadata, Classification Reference
- [ ]
---horizontal rule between every pair of##sections
Enumeration Reference
All reports MUST use these exact values. Do NOT abbreviate, substitute, or invent alternatives.
Component Types: process | data_store | external_service | external_interactor
Boundary Kinds (TMT-aligned): MachineBoundary | NetworkBoundary | ClusterBoundary | ProcessBoundary | PrivilegeBoundary | SandboxBoundary
Exploitability Tiers: Tier 1 (Direct Exposure — no prerequisites) | Tier 2 (Conditional Risk — single prerequisite) | Tier 3 (Defense-in-Depth — multiple prerequisites)
STRIDE + Abuse Categories: S Spoofing | T Tampering | R Repudiation | I Information Disclosure | D Denial of Service | E Elevation of Privilege | A Abuse
SDL Bugbar Severity: Critical | Important | Moderate | Low
Remediation Effort: Low | Medium | High
Mitigation Type (OWASP-aligned): Redesign | Standard Mitigation | Custom Mitigation | Existing Control | Accept Risk | Transfer Risk
Threat Status: Open | Mitigated | Platform
Finding Change Status (incremental): Still Present | Fixed | New | New (Code) | New (Previously Unidentified) | Removed
OWASP Top 10:2025 suffix: Always :2025 (e.g., A01:2025 – Broken Access Control)
- [ ] Quick Wins, Needs Verification, Finding Overrides subsections present
- [ ] Deployment pattern documented (K8s operator vs standalone)
- [ ] All metadata values in backticks
Also verify (applies to ALL files): No leaked directives (⛔, RIGID, NON-NEGOTIABLE in output), no time estimates, no nested output folders. See verification-checklist.md Phase 0 for the full common deviation list.