references/incremental-orchestrator.md
Incremental Orchestrator — Threat Model Update Workflow
This file contains the complete orchestration logic for performing an incremental threat model analysis — generating a new threat model report that builds on an existing baseline report. It is invoked when the user requests an updated analysis and a prior threat-model-* folder exists.
Key difference from single analysis (orchestrator.md): Instead of discovering components from scratch, this workflow inherits the old report's component inventory, IDs, and conventions. It then verifies each item against the current code and discovers new items.
⚡ Context Budget — Read Files Selectively
Phase 1 (setup + change detection): Read this file (incremental-orchestrator.md) only. The old threat-inventory.json provides the structural skeleton — no need to read other skill files yet.
Phase 2 (report generation): Read orchestrator.md (for mandatory rules 1–34), output-formats.md, diagram-conventions.md — plus the relevant skeleton from skeletons/ before writing each file. See the incremental-specific rules below.
Phase 3 (verification): Delegate to a sub-agent with verification-checklist.md (all 9 phases, including Phase 8 for comparison HTML).
When to Use This Workflow
Use incremental analysis when ALL of these conditions are met:
- The user's request involves updating, re-running, or refreshing a threat model
- A prior
threat-model-*folder exists in the repository with a validthreat-inventory.json - The user provides or implies both: a baseline report folder AND a target commit (defaults to HEAD)
Trigger examples:
- "Update the threat model using threat-model-20260309-174425 as the baseline"
- "Run an incremental threat model analysis against the previous report"
- "What changed security-wise since the last threat model?"
- "Refresh the threat model for the latest commit"
NOT this workflow:
- First-time analysis (no baseline) → use
orchestrator.md - "Analyze the security of this repo" with no mention of a prior report → use
orchestrator.md
Inputs
| Input | Source | Required? |
|-------|--------|-----------|
| Baseline report folder | Path to threat-model-* directory | Yes |
| Baseline threat-inventory.json | {baseline_folder}/threat-inventory.json | Yes |
| Baseline commit SHA | From {baseline_folder}/0-assessment.md Report Metadata | Yes |
| Target commit | User-provided SHA or defaults to HEAD | Yes (default: HEAD) |
⛔ Sub-Agent Governance applies to ALL phases. See orchestrator.md Sub-Agent Governance section. Sub-agents are READ-ONLY helpers — they NEVER call create_file for report files.
Phase 0: Setup & Validation
-
Record start time:
Get-Date -Format "yyyy-MM-dd HH:mm:ss" -AsUTCStore as
START_TIME. -
Gather git info:
git remote get-url origin git branch --show-current git rev-parse --short HEAD hostname -
Validate inputs:
- Confirm baseline folder exists:
Test-Path {baseline_folder}/threat-inventory.json - Read baseline commit SHA from
0-assessment.md: search for| Git Commit |row - Confirm target commit is resolvable:
git rev-parse {target_sha} - Get commit dates:
git log -1 --format="%ai" {baseline_sha}andgit log -1 --format="%ai" {target_sha}— NOT today's date - Get code change counts (for HTML metrics bar):
Store asgit rev-list --count {baseline_sha}..{target_sha} git log --oneline --merges --grep="Merged PR" {baseline_sha}..{target_sha} | wc -lCOMMIT_COUNTandPR_COUNT.
- Confirm baseline folder exists:
-
Baseline code access — reuse or create worktree:
# Check for existing worktree git worktree list # If a worktree for baseline_sha exists → reuse it # Verify: git -C {worktree_path} rev-parse HEAD # If not → create one: git worktree add ../baseline-{baseline_sha_short} {baseline_sha}Store the worktree path as
BASELINE_WORKTREEfor old-code verification in later phases. -
Create output folder:
threat-model-{YYYYMMDD-HHmmss}/
Phase 1: Load Old Report Skeleton
Read the baseline threat-inventory.json and extract the structural skeleton:
From threat-inventory.json, load:
- components[] → all component IDs, types, boundaries, source_files, fingerprints
- flows[] → all flow IDs, from/to, protocols
- boundaries[] → all boundary IDs, contains lists
- threats[] → all threat IDs, component mappings, stride categories, tiers
- findings[] → all finding IDs, titles, severities, CWEs, component mappings
- metrics → totals for validation
Store as the "inherited inventory" — the structural foundation.
Do NOT read the full prose from the old report's markdown files yet. Only load structured data. Read old report prose on-demand when:
- Verifying if a specific code pattern was previously analyzed
- Resolving ambiguity about a component's role or classification
- Historical context needed for a finding status decision
Phase 2: Per-Component Change Detection
For each component in the inherited inventory, determine its change status:
For EACH component in inherited inventory:
1. Check source_files existence at target commit:
git ls-tree {target_sha} -- {each source_file}
2. If ALL source files missing:
→ change_status = "removed"
→ Mark all linked threats as "removed_with_component"
→ Mark all linked findings as "removed_with_component"
3. If source files exist, check for changes:
git diff --stat {baseline_sha} {target_sha} -- {source_files}
If NO changes → change_status = "unchanged"
If changes exist, check if security-relevant:
Read the diff: git diff {baseline_sha} {target_sha} -- {source_files}
Look for changes in:
- Auth/credential patterns (tokens, passwords, certificates)
- Network/API surface (new endpoints, changed listeners, port bindings)
- Input validation (sanitization, parsing, deserialization)
- Command execution patterns (shell exec, process spawn)
- Config values (TLS settings, CORS, security headers)
- Dependencies (new packages, version changes)
If security-relevant → change_status = "modified"
If cosmetic only (whitespace, comments, logging, docs) → change_status = "unchanged"
4. If files moved or renamed:
git log --follow --diff-filter=R {baseline_sha}..{target_sha} -- {source_files}
→ change_status = "restructured"
→ Update source_file references to new paths
Record the classification for every component — this drives all downstream decisions.
Phase 3: Scan for New Components
1. Enumerate source directories/files at {target_sha} that are NOT referenced
by any existing component's source_files or source_directories.
Focus on: new top-level directories, new *Service.cs/*Agent.cs/*Server.cs classes,
new Helm deployments, new API controllers.
2. Apply the same component discovery rules from orchestrator.md:
- Class-anchored naming (PascalCase from actual class names)
- Component eligibility criteria (crosses trust boundary or handles security data)
- Same naming procedure (primary class → script → config → directory → technology)
3. For each candidate new component:
- Verify it didn't exist at baseline: git ls-tree {baseline_sha} -- {path}
- If it existed at baseline → this is a "missed component" from the old analysis
→ Add to Needs Verification section with note: "Component existed at baseline
but was not in the previous analysis. May indicate an analysis gap."
- If genuinely new (files didn't exist at baseline):
→ change_status = "new"
→ Assign a new component ID following the same PascalCase naming rules
→ Full STRIDE analysis will be performed in Phase 4
Phase 4: Generate Report Files
Now generate all report files. Read the relevant skill files before starting:
orchestrator.md— mandatory rules 1–34 apply to all report filesoutput-formats.md— templates and format rulesdiagram-conventions.md— diagram colors and styles- Before writing EACH file, read the corresponding skeleton from
skeletons/skeleton-*.md— copy VERBATIM and fill[FILL]placeholders
⛔ SUB-AGENT GOVERNANCE (MANDATORY — prevents the dual-folder bug): The parent agent owns ALL file creation. Sub-agents are READ-ONLY helpers that search code, gather context, and run verification — they NEVER call create_file for report files. See the full Sub-Agent Governance rules in orchestrator.md. The ONLY exception is threat-inventory.json delegation for large repos — and even then, the sub-agent prompt must include the exact output file path and explicit instruction to write ONLY that one file.
⛔ CRITICAL: The incremental report is a STANDALONE report. Someone reading it without the old report must understand the complete security posture. Status annotations ([STILL PRESENT], [FIXED], [NEW CODE], etc.) are additions on top of complete content — not replacements for it.
4a. 0.1-architecture.md
-
Read
skeletons/skeleton-architecture.mdfirst — use as structural template -
Copy the old report's component structure as your starting template
-
Unchanged components: Regenerate description using the current code (not copy-paste from old report). Same ID, same conventions.
-
Modified components: Update description to reflect code changes. Add annotation:
[MODIFIED — security-relevant changes detected] -
New components: Add with annotation:
[NEW] -
Removed components: Add with annotation:
[REMOVED]and brief note -
Tech stack, deployment model: update if changed, otherwise carry forward
⛔ DEPLOYMENT CLASSIFICATION IS MANDATORY (even in incremental mode): The
0.1-architecture.mdMUST contain:**Deployment Classification:** \[VALUE]`line (e.g.,K8S_SERVICE,LOCALHOST_DESKTOP`)### Component Exposure Tablewith columns: Component, Listens On, Auth Required, Reachability, Min Prerequisite, Derived Tier If the baseline had these, carry them forward and update for new/modified components. If the baseline did NOT have these, derive them from code NOW — they are required for all subsequent steps. DO NOT proceed to Step 4b without these two elements in place.
-
Scenarios: keep old scenarios, add new ones for new functionality
-
All standard
0.1-architecture.mdrules fromoutput-formats.mdapply
4b. 1.1-threatmodel.mmd (DFD)
-
Read
skeletons/skeleton-dfd.mdandskeletons/skeleton-summary-dfd.mdfirst -
Start from the old DFD's logical layout
-
Same node IDs for carried-forward components (critical for ID stability)
-
New components: Add with distinctive styling — use
classDef newComponent fill:#d4edda,stroke:#28a745,stroke-width:3px -
Removed components: Show as dashed with gray fill — use
classDef removedComponent fill:#e9ecef,stroke:#6c757d,stroke-width:1px,stroke-dasharray:5 -
Same flow IDs for unchanged flows
-
New flows: New IDs continuing the sequence
-
All standard DFD rules from
diagram-conventions.mdapply (flowchart LR, color palette, etc.)⛔ POST-DFD GATE: After creating
1.1-threatmodel.mmd, count elements and boundaries. If elements > 15 OR boundaries > 4 → create1.2-threatmodel-summary.mmdusingskeleton-summary-dfd.mdNOW. Do NOT proceed to Step 4c until the decision is made.
4c. 1-threatmodel.md
- Read
skeletons/skeleton-threatmodel.mdfirst — use table structure - Element table: all old elements + new elements, with an added
Statuscolumn- Values:
Unchanged,Modified,New,Removed,Restructured
- Values:
- Flow table: all old flows + new flows, with
Statuscolumn - Boundary table: inherited boundaries + any new ones
- If
1.2-threatmodel-summary.mmdwas generated, include## Summary Viewsection with the summary diagram and mapping table - All standard table rules from
output-formats.mdapply
4d. 2-stride-analysis.md
- Read
skeletons/skeleton-stride-analysis.mdfirst — use Summary table and per-component structure
⛔ CRITICAL REMINDERS FOR INCREMENTAL STRIDE (these rules from orchestrator.md apply identically here):
- The "A" in STRIDE-A is ALWAYS "Abuse" (business logic abuse, workflow manipulation, feature misuse). NEVER use "Authorization" as the STRIDE-A category name. This applies to threat ID suffixes (T01.A), N/A justification labels, and all prose. Authorization issues fall under Elevation of Privilege (E), not the A category.
- The
## Summarytable MUST appear at the TOP of the file, immediately after## Exploitability Tiers, BEFORE any individual component sections. Use this EXACT structure at the top:
# STRIDE-A Threat Analysis
## Exploitability Tiers
| Tier | Label | Prerequisites | Assignment Rule |
|------|-------|---------------|----------------|
| **Tier 1** | Direct Exposure | `None` | Exploitable by unauthenticated external attacker with NO prior access. |
| **Tier 2** | Conditional Risk | Single prerequisite | Requires exactly ONE form of access. |
| **Tier 3** | Defense-in-Depth | Multiple prerequisites or infrastructure access | Requires significant prior breach or multiple combined prerequisites. |
## Summary
| Component | Link | S | T | R | I | D | E | A | Total | T1 | T2 | T3 | Risk |
|-----------|------|---|---|---|---|---|---|---|-------|----|----|----|------|
<!-- one row per component with numeric counts, then Totals row -->
---
## [First Component Name]
- STRIDE categories may produce 0, 1, 2, 3+ threats per component. Do NOT cap at 1 threat per category. Components with rich security surfaces should typically have 2-4 threats per relevant category. If every STRIDE cell in the Summary table is 0 or 1, the analysis is too shallow — go back and identify additional threat vectors. The Summary table columns reflect actual threat counts.
- ⛔ PREREQUISITE FLOOR CHECK (per threat): Before assigning a prerequisite to any threat, look up the component's
Min PrerequisiteandDerived Tierin the Component Exposure Table (0.1-architecture.md). The threat's prerequisite MUST be ≥ the component's floor. The threat's tier MUST be ≥ the component's derived tier. Use the canonical prerequisite→tier mapping fromanalysis-principles.md. Prerequisites MUST use only canonical values:None,Authenticated User,Privileged User,Internal Network,Local Process Access,Host/OS Access,Admin Credentials,Physical Access,{Component} Compromise. ⛔Application AccessandHost Accessare FORBIDDEN.
⛔ HEADING ANCHOR RULE (applies to ALL output files): ALL ## and ### headings in every output file must be PLAIN text — NO status tags ([Existing], [Fixed], [Partial], [New], [Removed], or any old-style tags) in heading text. Tags break markdown anchor links and pollute table-of-contents. Place status annotations on the FIRST LINE of the section/finding body instead:
- ✅
## KmsPluginProviderwith first line> **[New]** Component added in this release. - ✅
### FIND-01: Missing Auth Checkwith first line> **[Existing]** - ❌
## KmsPluginProvider [New](breaks#kmspluginprovideranchor) - ❌
### FIND-01: Missing Auth Check [Existing](pollutes heading)
This rule applies to: 0.1-architecture.md, 2-stride-analysis.md, 3-findings.md, 1-threatmodel.md.
For each component, the STRIDE analysis approach depends on its change status:
| Component Status | STRIDE Approach |
|-----------------|-----------------|
| Unchanged | Carry forward all threat entries from old report with [STILL PRESENT] annotation. Re-verify each threat's mitigation status against current code. |
| Modified | Re-analyze the component with access to the diff. For each old threat: determine if still_present, fixed, mitigated, or modified. Discover new threats from the code changes → classify as new_in_modified. |
| New | Full fresh STRIDE-A analysis (same as single-analysis mode). All threats classified as new_code. |
| Removed | Section header with note: "Component removed — all threats resolved with removed_with_component status." |
Threat ID continuity:
- Old threats keep their original IDs (e.g., T01.S, T02.T)
- New threats continue the sequence from the old report's highest threat number
- NEVER reassign or reuse an old threat ID
N/A categories (from §3.7 of PRD):
- Each component gets all 7 STRIDE-A categories addressed
- Non-applicable categories:
N/A — {1-sentence justification} - N/A entries do NOT count toward threat totals
Status annotation format in STRIDE tables:
Add a Change column to each threat table row with one of:
Existing— threat exists in current code, same as before (includes threats with minor detail changes)Fixed— vulnerability was remediated (cite the specific code change)New— threat from a new component, code change, or previously unidentifiedRemoved— component was removed
⛔ POST-STEP CHECK: After writing the Change column for ALL threats, verify:
- Every threat row has exactly one of: Existing, Fixed, New, Removed
- No old-style tags: Still Present, New (Code), New (Modified), Previously Unidentified
- Fixed threats cite the specific code change
4e. 3-findings.md
⛔ BEFORE WRITING ANY FINDING — Re-read skeletons/skeleton-findings.md NOW.
The skeleton defines the EXACT structure for each finding block, including the mandatory **Prerequisite basis:** line in the #### Evidence section. Every finding — whether [Existing], [New], [Fixed], or [Partial] — MUST follow this skeleton structure.
⛔ DEPLOYMENT CONTEXT GATE (FAIL-CLOSED) — applies to ALL findings (new and carried-forward):
Read 0.1-architecture.md Deployment Classification and Component Exposure Table.
If classification is LOCALHOST_DESKTOP or LOCALHOST_SERVICE:
- ZERO findings may have
Exploitation Prerequisites=None→ fix toLocal Process AccessorHost/OS Access - ZERO findings may be in
## Tier 1→ downgrade to T2/T3 - ZERO CVSS vectors may use
AV:Nunless component hasReachability = ExternalFor ALL classifications: - Each finding's prerequisite MUST be ≥ its component's
Min Prerequisitefrom the exposure table - Each finding's tier MUST be ≥ its component's
Derived Tier - EVERY finding's
#### Evidencesection MUST start with a**Prerequisite basis:**line citing the specific code/config that determines the prerequisite (e.g., "ClusterIP service, no Ingress — Internal Only per Exposure Table"). This applies to [Existing] findings too — re-derive from current code. - Prerequisites MUST use only canonical values. ⛔
Application AccessandHost Accessare FORBIDDEN.
For each old finding, verify against the current code:
| Situation | change_status | Action |
|-----------|---------------|--------|
| Code unchanged, vulnerability intact | still_present | Carry forward with > **[Existing]** on first line of body |
| Code changed to fix the vulnerability | fixed | Mark with > **[Fixed]**, cite the specific code change |
| Code changed partially | partially_mitigated | Mark with > **[Partial]**, explain what changed and what remains |
| Component removed entirely | removed_with_component | Mark with > **[Removed]** |
For new findings:
| Situation | change_status | Label |
|-----------|---------------|-------|
| New component, new vulnerability | new_code | > **[New]** |
| Existing component, vulnerability introduced by code change | new_in_modified | > **[New]** — cite the specific change |
| Existing component, vulnerability was in old code but missed | previously_unidentified | > **[New]** — verify against baseline worktree |
Finding ID continuity:
- Old findings keep their original IDs (FIND-01 through FIND-N)
- New findings continue the sequence: FIND-N+1, FIND-N+2, ...
- No gaps, no duplicates
- Fixed findings are retained but annotated — they are NOT removed from the report
- Document order: Findings are sorted by Tier (1→2→3), then by severity (Critical→Important→Moderate→Low), then by CVSS descending — same as standalone analysis. Because old IDs are preserved, the ID numbers may NOT be numerically ascending in the document. This is acceptable in incremental mode — ID stability for cross-report tracing takes precedence over sequential ordering. The
### FIND-XX:headings will appear in tier/severity order, not ID order.
Previously-unidentified verification procedure:
- Identify the finding's component and evidence files
- Read the same files at the baseline commit:
cat {BASELINE_WORKTREE}/{file_path} - If the vulnerability pattern exists in the old code →
previously_unidentified - If the vulnerability pattern does NOT exist in the old code →
new_in_modified
4f. threat-inventory.json
- Read
skeletons/skeleton-inventory.mdfirst — use exact field names and schema structure
Same schema as single analysis, with additional fields:
{
"schema_version": "1.1",
"incremental": true,
"baseline_report": "threat-model-20260309-174425",
"baseline_commit": "2dd84ab",
"target_commit": "abc1234",
"components": [
{
"id": "McpHost",
"change_status": "unchanged",
...existing fields...
}
],
"threats": [
{
"id": "T01.S",
"change_status": "still_present",
...existing fields...
}
],
"findings": [
{
"id": "FIND-01",
"change_status": "still_present",
...existing fields...
}
],
"metrics": {
...existing fields...,
"status_summary": {
"components": {
"unchanged": 15,
"modified": 2,
"new": 1,
"removed": 1,
"restructured": 0
},
"threats": {
"still_present": 80,
"fixed": 5,
"mitigated": 3,
"new_code": 10,
"new_in_modified": 4,
"previously_unidentified": 2,
"removed_with_component": 8
},
"findings": {
"still_present": 12,
"fixed": 2,
"partially_mitigated": 1,
"new_code": 3,
"new_in_modified": 2,
"previously_unidentified": 1,
"removed_with_component": 1
}
}
}
}
4g. 0-assessment.md
- Read
skeletons/skeleton-assessment.mdfirst — use section order and table structures
Standard assessment sections (all 7 mandatory) plus incremental-specific sections:
Standard sections (same as single analysis):
- Report Files
- Executive Summary (with
> **Note on threat counts:**blockquote) - Action Summary (with
### Quick Wins) - Analysis Context & Assumptions (with
### Needs Verificationand### Finding Overrides) - References Consulted
- Report Metadata
- Classif