references/orchestrator.md
Orchestrator — Threat Model Analysis Workflow
This file contains the complete orchestration logic for performing a threat model analysis.
It is the primary workflow document for the /threat-model-analyst skill.
⚡ Context Budget — Read Files Selectively
Do NOT read all 10 skill files at session start. Read only what each phase needs. This preserves context window for the actual codebase analysis.
Phase 1 (context gathering): Read this file (orchestrator.md) + analysis-principles.md + tmt-element-taxonomy.md
Phase 2 (writing reports): Read the relevant skeleton from skeletons/ BEFORE writing each file. Read output-formats.md + diagram-conventions.md for rules — but use the skeleton as the structural template.
- Before
0.1-architecture.md: readskeletons/skeleton-architecture.md - Before
1.1-threatmodel.mmd: readskeletons/skeleton-dfd.md - Before
1-threatmodel.md: readskeletons/skeleton-threatmodel.md - Before
2-stride-analysis.md: readskeletons/skeleton-stride-analysis.md - Before
3-findings.md: readskeletons/skeleton-findings.md - Before
0-assessment.md: readskeletons/skeleton-assessment.md - Before
threat-inventory.json: readskeletons/skeleton-inventory.md - Before
incremental-comparison.html: readskeletons/skeleton-incremental-html.mdPhase 3 (verification): Delegate to a sub-agent and includeverification-checklist.mdin the sub-agent prompt. The sub-agent reads the full checklist with a fresh context window — the parent agent does NOT need to read it.
Key principle: Sub-agents get fresh context windows. Delegate verification and JSON generation to sub-agents rather than keeping everything in the parent context.
✅ Mandatory Rules — READ BEFORE STARTING
These are the required behaviors for every threat model report. Follow each rule exactly:
- Organize findings by Exploitability Tier (Tier 1/2/3), never by severity level
- Split each component's STRIDE table into Tier 1, Tier 2, Tier 3 sub-sections
- Include
Exploitability TierandRemediation Efforton every finding — both are MANDATORY - STRIDE summary table MUST include T1, T2, T3 columns 4b. STRIDE + Abuse Cases categories are exactly: Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege, Abuse (business logic abuse, workflow manipulation, feature misuse — an extension to standard STRIDE covering misuse of legitimate features). The A is ALWAYS "Abuse" — NEVER "AI Safety", "Authorization", or any other interpretation. Authorization issues belong under E (Elevation of Privilege).
.mdfiles: start with# Headingon line 1. Thecreate_filetool writes raw content — no code fences.mmdfiles: start with%%{init:on line 1. Raw Mermaid source, no fences- Section MUST be titled exactly
## Action Summary. Include### Quick Winssubsection with Tier 1 low-effort findings table - K8s sidecars: annotate host container with
<br/>+ Sidecar— never create separate sidecar nodes (seediagram-conventions.mdRule 1) - Intra-pod localhost flows are implicit — do NOT draw them in diagrams
- Action Summary IS the recommendations — no separate
### Key Recommendationssection - Include
> **Note on threat counts:**blockquote in Executive Summary - Every finding MUST have CVSS 4.0 (score AND full vector string), CWE (with hyperlink), and OWASP (
:2025suffix) - OWASP suffix is always
:2025(e.g.,A01:2025 – Broken Access Control) - Include Threat Coverage Verification table at end of
3-findings.mdmapping every threat → finding - Every component in
0.1-architecture.mdMUST appear in2-stride-analysis.md - First 3 scenarios in
0.1-architecture.mdMUST have Mermaid sequence diagrams 0-assessment.mdMUST include## Analysis Context & Assumptionswith### Needs Verificationand### Finding Overridestables### Quick Winssubsection is REQUIRED under Action Summary (include heading with note if none)- ALL 7 sections in
0-assessment.mdare MANDATORY: Report Files, Executive Summary, Action Summary, Analysis Context & Assumptions, References Consulted, Report Metadata, Classification Reference - Deployment Classification is BINDING. In
0.1-architecture.md, setDeployment Classificationand fill the Component Exposure Table. If classification isLOCALHOST_DESKTOPorLOCALHOST_SERVICE: zero T1 findings, zeroPrerequisites = None, zeroAV:Nfor non-listener components. Seeanalysis-principles.mdDeployment Context table. - Finding IDs MUST be sequential top-to-bottom: FIND-01, FIND-02, FIND-03... Renumber after sorting
- CWE MUST include hyperlink:
[CWE-306](https://cwe.mitre.org/data/definitions/306.html): Missing Authentication - After STRIDE, run the Technology-Specific Security Checklist in
analysis-principles.md. Every technology in the repo needs at least one finding or documented mitigation - CVSS
AV:LorPR:H→ finding CANNOT be Tier 1. Downgrade to T2/T3. See CVSS-to-Tier Consistency Check inanalysis-principles.md - Use only
Low/Medium/Higheffort labels. NEVER generate time estimates, sprint phases, or scheduling. See Prohibited Content inoutput-formats.md - References Consulted: use the exact two-subsection format from
output-formats.md—### Security Standards(3-column table with full URLs) and### Component Documentation(3-column table with URLs) - Report Metadata: include ALL fields from
output-formats.mdtemplate — Model, Analysis Started, Analysis Completed, Duration. RunGet-Date -Format "yyyy-MM-dd HH:mm:ss" -AsUTCat Step 1 and before writing0-assessment.md ## Summarytable in2-stride-analysis.mdMUST appear at the TOP, immediately after## Exploitability Tiers, BEFORE individual component sections- Related Threats: every threat ID MUST be a hyperlink to
2-stride-analysis.md#component-anchor. Format:[T02.S](2-stride-analysis.md#component-name) - Diagram colors: copy classDef lines VERBATIM from
diagram-conventions.md. Only allowed fills:#6baed6(process),#fdae61(external),#74c476(datastore). Only allowed strokes:#2171b5,#d94701,#238b45,#e31a1c. Use ONLY%%{init: {'theme': 'base', 'themeVariables': { 'background': '#ffffff', 'primaryColor': '#ffffff', 'lineColor': '#666666' }}}%%— no other themeVariables keys - Summary DFD: after creating
1.1-threatmodel.mmd, run the POST-DFD GATE in Step 4. The gate andskeleton-summary-dfd.mdcontrol whether1.2-threatmodel-summary.mmdis generated. - Report Files table in
0-assessment.md: list0-assessment.md(this document) as the FIRST row, followed by 0.1-architecture.md, 1-threatmodel.md, etc. Use the exact template fromoutput-formats.md threat-inventory.jsonMUST be generated for every analysis run (Step 8b). This file enables future comparisons. Seeoutput-formats.mdfor schema.- NEVER delete, modify, or remove any existing
threat-model-*orthreat-model-compare-*folders in the repository. Only write to your own timestamped output folder. Cleaning up temporary git worktrees you created is allowed; deleting other report folders is FORBIDDEN.
Rule Precedence (when guidance conflicts)
Apply rules in this order:
- Literal skeletons in
skeletons/skeleton-*.md— exact section/table headers and attribute rows - Mandatory Rules in
orchestrator.md(this list) - Examples in
output-formats.md(examples are illustrative, not authoritative when they differ from literal skeletons)
If any conflict is detected, follow the highest-precedence item.
Post-generation: The verification sub-agent will scan your output for all known deviations listed in verification-checklist.md Phase 0. Fix any failures before finalizing.
Workflow
Exclusions: Skip these directories:
threat-model-*(previous reports)node_modules,.git,dist,build,vendor,__pycache__
Pre-work: Before writing any output file, scan verification-checklist.md Phase 1 (Per-File Structural Checks) and Phase 2 (Diagram Rendering Checks). This internalizes the quality gates so output is correct on the first pass — preventing costly rework. Do NOT run the full verification yet; that happens in Step 10.
⛔ Sub-Agent Governance (MANDATORY — prevents duplicate work)
Sub-agents are independent execution contexts — they have no memory of the parent's state, instructions, or other sub-agents. Without strict governance, sub-agents will independently perform the ENTIRE analysis, creating duplicate report folders and wasting ~15 min compute + ~100K tokens per duplication.
Rule 1 — Parent owns ALL file creation. The parent agent is the ONLY agent that calls create_file for report files (0.1-architecture.md, stride-analysis.md, findings.md, etc.). Sub-agents NEVER write report files.
Rule 2 — Sub-agents are READ-ONLY helpers. Sub-agents may:
- Search source code for specific patterns (e.g., "find all auth-related code")
- Read and analyze files, then return structured data to the parent
- Run verification checks and return PASS/FAIL results
- Execute terminal commands (git diff, grep) and return output
Rule 3 — Sub-agent prompts must be NARROW and SPECIFIC. Never tell a sub-agent to "perform threat model analysis" or "generate the report." Instead:
- ✅ "Read these 5 Go files and list every function that handles credentials. Return a table of function name, file, line number."
- ✅ "Run the verification checklist against the files in {folder}. Return PASS/FAIL for each check."
- ✅ "Read threat-inventory.json from {path} and verify all array lengths match metrics. Return mismatches."
- ❌ "Analyze this codebase and write the threat model files."
- ❌ "Generate 0.1-architecture.md and stride-analysis.md for this component."
Rule 4 — Output folder path. The parent creates the timestamped output folder in Step 1 and uses that exact path for ALL create_file calls. If a sub-agent needs to read previously written report files, pass the folder path in the sub-agent prompt.
Rule 5 — The ONLY exception is threat-inventory.json generation (Step 8b), where the parent MAY delegate JSON writing to a sub-agent IF the data is too large. In that case, the sub-agent prompt MUST include: (a) the exact output file path, (b) the data to serialize, and (c) explicit instruction: "Write ONLY this one file. Do NOT create any other files or folders."
Steps
-
Record start time & gather context
- Run
Get-Date -Format "yyyy-MM-dd HH:mm:ss" -AsUTCand store asSTART_TIME - Get git info:
git remote get-url origin,git branch --show-current,git rev-parse --short HEAD,git log -1 --format="%ai" HEAD(commit date — NOT today's date),hostname - Map the system: identify components, trust boundaries, data flows
- Reference:
analysis-principles.mdfor security infrastructure inventory
⛔ DEPLOYMENT CLASSIFICATION (MANDATORY — do this BEFORE analyzing code for threats): Determine the system's deployment class from code evidence (see
skeleton-architecture.mdfor values). Record in0.1-architecture.md→ Deployment Model section. Then fill the Component Exposure Table — one row per component showing listen address, auth barrier, external reachability, and minimum prerequisite. This table is the single source of truth for prerequisite floors. No threat or finding may have a lower prerequisite than what the exposure table permits for its component.⛔ DETERMINISTIC NAMING — Apply BEFORE writing any files:
When identifying components, assign each a canonical PascalCase
id. The naming MUST be deterministic — two independent runs on the same codebase MUST produce the same component IDs.⛔ ABSOLUTE RULE: Every component ID MUST be anchored to a real code artifact. For every component you identify, you MUST be able to point to a specific class, file, or manifest in the codebase that is the "anchor" for that component. If no such artifact exists, the component does not exist.
Naming procedure (follow IN ORDER — stop at the first match):
- Primary class name — Use the EXACT class name from the source code. Do NOT abbreviate, expand, or rephrase it.
TaskProcessor.cs→TaskProcessor(NOTTaskServer, NOTTaskService)SessionStore.cs→SessionStore(NOTFileSessionStore, NOTSessionService)TerminalUserInterface.cs→TerminalUserInterface(NOTTerminalUI)PowerShellCommandExecutor.cs→PowerShellCommandExecutor(NOTPowerShellExecutor)ResponsesAPIService.cs→ResponsesAPIService(NOTLLMService— that's a DIFFERENT class)MCPHost.cs→MCPHost(NOTOrchestrationHost)
- Primary script name →
Import-Images.ps1→ImportImages - Primary config/manifest name →
Dockerfile→DockerContainer,values.yaml→HelmChart - Directory name (if component spans multiple files) →
src/ParquetParsing/→ParquetParser - Technology name (for external services/datastores) → "Azure OpenAI" →
AzureOpenAI, "Redis" →Redis - External actor role →
Operator,EndUser(never drop these)
⛔ Helm/Kubernetes Deployment Naming (CRITICAL for comparison stability): When a component is deployed via Helm chart or Kubernetes manifests, use the Kubernetes workload name (from the Deployment/StatefulSet metadata.name) as the component ID — NOT the Helm template filename or directory structure:
- Look at
metadata.namein deployment YAML → use that as the component ID (PascalCase normalized) - Example:
metadata.name: devportalintemplates/knowledge/devportal-deployment.yml→ component ID isDevPortal - Example:
metadata.name: phi-modelintemplates/knowledge/phi-deployment.yml→ component ID isPhiModel - Why: Helm templates frequently get reorganized (e.g., moved from
templates/totemplates/knowledge/) but the Kubernetes workload name stays the same. Using the workload name ensures the component ID survives directory reorganizations. source_filesMUST include the deployment YAML path AND the application source code path (e.g., bothhelmchart/myapp/templates/knowledge/devportal-deployment.ymlANDdeveloper-portal/src/)source_directoriesMUST include BOTH the Helm template directory AND the source code directory
External Service Anchoring (for components without repo source code): External services (cloud APIs, managed databases, SaaS endpoints) don't have source files in the repository. Anchor them to their integration point in the codebase:
source_files→ the client class or config file that defines the connection (e.g.,src/MCP/appsettings.jsonfor Azure OpenAI connection config,helmchart/values.yamlfor Redis endpoint config)source_directories→ the directory containing the integration code (e.g.,src/MCP/Core/Services/LLM/for the LLM client)class_names→ the CLIENT class in YOUR repo that talks to the service (e.g.,ResponsesAPIService), NOT the vendor's SDK class (e.g., NOTOpenAIClient). If no dedicated client class exists, leave empty.namespace→ leave empty""(external services don't have repo namespaces)config_keys→ the env vars / config keys for the service connection (e.g.,["AZURE_OPENAI_ENDPOINT", "RESPONSES_API_DEPLOYMENT"]). These are the most stable anchors for external services.api_routes→ leave empty (external services expose their own routes, not yours)dependencies→ the SDK package used (e.g.,["Azure.AI.OpenAI"]for NuGet,["pymilvus"]for pip)
Why this matters: External services frequently change display names across LLM runs (e.g., "Azure OpenAI" vs "GPT-4 Endpoint" vs "LLM Backend"). The
config_keysanddependenciesfields are what make them matchable across runs.⛔ FORBIDDEN naming patterns — NEVER use these:
- NEVER invent abstract names that don't correspond to a real class:
ConfigurationStore,LocalFileSystem,DataLayer,IngestionPipeline,BackendServer - NEVER abbreviate a class name:
TerminalUIforTerminalUserInterface,PSExecutorforPowerShellCommandExecutor - NEVER substitute a synonym:
TaskServerforTaskProcessor,LLMServiceforResponsesAPIService - NEVER merge two separate classes into one component:
ResponsesAPIServiceandLLMServiceare two different classes → two different components - NEVER create a component for something that doesn't exist in the code: if there's no Windows Registry access code, don't create a
WindowsRegistrycomponent - NEVER rename between runs: if you called it
TaskProcessorin run 1, it MUST beTaskProcessorin run 2
⛔ COMPONENT ANCHOR VERIFICATION (MANDATORY — do this BEFORE Step 2): After identifying all components, create a mental checklist:
For EACH component: Q: What is the EXACT filename or class that anchors this component? A: [must cite a real file path, e.g., "src/Core/TaskProcessor.cs"] If you cannot cite a real file → DELETE the component from your listThis verification catches invented components like
WindowsRegistry(no registry code exists),ConfigurationStore(no such class),LocalFileSystem(abstract concept, not a class).⛔ COMPONENT SELECTION STABILITY (when multiple related classes exist): Many systems have clusters of related classes (e.g.,
CredentialManager,AzureCredentialProvider,AzureAuthenticationHandler). To ensure deterministic selection:- Pick the class that OWNS the security-relevant behavior — the one that makes the trust decision, holds the credential, or processes the data
- Prefer the class registered in dependency injection over helpers/utilities
- Prefer the higher-level orchestrator over its internal implementation classes
- Once you pick a class, its alternatives become aliases — add them to the
aliasesarray, not as separate components - Example: If
CredentialManagerorchestrates credential lookup and usesAzureCredentialProviderinternally,CredentialManageris the component andAzureCredentialProvideris an alias - Example: Do NOT include both
SessionStoreandSessionFiles—SessionStoreis the class,SessionFilesis an abstract concept - Count rule: Two runs on the same code MUST produce the same number of components (±1 for edge cases). A difference of ≥3 components indicates the selection rules were not followed.
⛔ STABILITY ANCHORS (for comparison matching): When recording each component in
threat-inventory.json, thefingerprintfieldssource_directories,class_names, andnamespaceserve as stability anchors — immutable identifiers that persist even when:- The class is renamed (directory stays the same)
- The file is moved to a different directory (class name stays the same)
- The component ID changes between analysis runs (namespace stays the same)
The comparison matching algorithm relies on these anchors MORE than on the component
idfield. Therefore: source_directoriesMUST be populated for every process-type component (never empty[])class_namesMUST include at least the primary class namenamespaceMUST be the actual code namespace (e.g.,MyApp.Core.Servers.Health), not a made-up grouping- These fields are what make a component identifiable across independent analysis runs, even if two LLMs pick different display names
⛔ COMPONENT ELIGIBILITY — What qualifies as a threat model component: A class/service becomes a threat model component ONLY if it meets ALL of these criteria:
- It crosses a trust boundary OR handles security-sensitive data (credentials, user input, network I/O, file I/O, process execution)
- It is a top-level service, not an internal helper (registered in DI, or the main entry point, or an agent with its own responsibility)
- It would appear in a deployment diagram — you could point to it and say "this runs here, talks to that"
ALWAYS include these component types (if they exist in the code):
- ALL agent classes (HealthAgent, InfrastructureAgent, InvestigatorAgent, SupportabilityAgent, etc.)
- ALL MCP server classes (HealthServer, InfrastructureServer, etc.)
- The main host/orchestrator (MCPHost, etc.)
- ALL external service connections (AzureOpenAI, AzureAD, etc.)
- ALL credential/auth managers
- The user interface entry point
- ALL tool execution services (PowerShellCommandExecutor, etc.)
- ALL session/state persistence services
- ALL LLM service classes (ResponsesAPIService, LLMService — if they are separate classes, they are separate components)
- External actors (Operator, EndUser)
NEVER include these as separate components:
- Loggers (LocalFileLogger, TelemetryLogger) — these are cross-cutting concerns, not threat model components
- Static helper classes
- Model/DTO classes
- Configuration builders (unless they handle secrets)
- Infrastructure-as-code classes that don't exist at runtime (AzureStackHCI cluster reference, deployment scripts)
The goal: Every run on the same code should identify the SAME set of ~12-20 components. If you're including a logger or excluding an agent, you're doing it wrong.
Boundary naming rules:
- Boundary IDs MUST be PascalCase (never
Layer,Zone,Group,Tiersuffixes) - Derive from deployment topology, NOT from code architecture layers
- Deployment topology determines boundaries:
- Single-process app → EXACTLY 2 boundaries:
Application(the process) +External(external services). NEVER use 1 boundary. NEVER use 3+ boundaries. This is mandatory for single-process apps. - Multi-container app → boundaries per container/pod
- K8s deployment →
K8sCluster+ per-namespace boundaries if relevant - Client-server →
Client+Server
- Single-process app → EXACTLY 2 boundaries:
- K8s multi-service deployments (CRITICAL for microservice architectures):
When a K8s namespace contains multiple Deployments/StatefulSets with DIFFERENT security characteristics, create sub-boundaries based on workload type:
BackendServices— API services (FastAPI, Express, etc.) that handle user requestsDataStorage— Databases and persistent storage (Redis, Milvus, PostgreSQL, NFS) — these have different access controls, persistence, and backup policiesMLModels— ML model servers running on GPU nodes — these have different compute resources, attack surfaces (adversarial inputs), and scaling characteristicsAgentic— Agent runtime/manager services if present- The outer
K8sClustercontains these sub-boundaries - This is NOT "code layers" — each sub-boundary represents a different Kubernetes Deployment/StatefulSet with its own security context, resource limits, and network policies
- Test: If two components are in DIFFERENT Kubernetes Deployments with different service accounts, different network exposure, or different resource requirements → they SHOULD be in different sub-boundaries
- FORBIDDEN boundary schemes (for SINGLE-PROCESS apps only):
- Do NOT create boundaries based on code layers:
PresentationBoundary,OrchestrationBoundary,AgentBoundary,ServiceBoundaryare CODE LAYERS, not deployment boundaries. All these run in the SAME process. - Do NOT split a single process into 4+ boundaries. If all components run in one .exe, they are in ONE boundary.
- Do NOT create boundaries based on code layers:
- Example: An application where
TerminalUserInterface,MCPHost,HealthAgent,ResponsesAPIServiceall run in the same process → they are ALL inApplication. External services likeAzureOpenAI
- Run