AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

threat-model-analyst

Full STRIDE-A threat model analysis and incremental update skill for repositories and systems. Supports two modes: (1) Single analysis — full STRIDE-A threat model of a repository, producing architecture overviews, DFD diagrams, STRIDE-A analysis, prioritized findings, and executive assessments. (2) Incremental analysis — takes a previous threat model report as baseline, compares the codebase at the latest (or a given commit), and produces an updated report with change tracking (new, resolved, still-present threats), STRIDE heatmap, findings diff, and an embedded HTML comparison. Only activate when the user explicitly requests a threat model analysis, incremental update, or invokes /threat-model-analyst directly.

Original source
github
License
MIT
Pinned revision
5269f7ea2d6c3a9bfda5ed878b6726cf509121fd

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read github--threat-model-analyst at revision 5269f7ea2d6c3a9bfda5ed878b6726cf509121fd, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 17

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: read skeletons/skeleton-architecture.md
  • Before 1.1-threatmodel.mmd: read skeletons/skeleton-dfd.md
  • Before 1-threatmodel.md: read skeletons/skeleton-threatmodel.md
  • Before 2-stride-analysis.md: read skeletons/skeleton-stride-analysis.md
  • Before 3-findings.md: read skeletons/skeleton-findings.md
  • Before 0-assessment.md: read skeletons/skeleton-assessment.md
  • Before threat-inventory.json: read skeletons/skeleton-inventory.md
  • Before incremental-comparison.html: read skeletons/skeleton-incremental-html.md Phase 3 (verification): Delegate to a sub-agent and include verification-checklist.md in 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:

  1. Organize findings by Exploitability Tier (Tier 1/2/3), never by severity level
  2. Split each component's STRIDE table into Tier 1, Tier 2, Tier 3 sub-sections
  3. Include Exploitability Tier and Remediation Effort on every finding — both are MANDATORY
  4. 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).
  5. .md files: start with # Heading on line 1. The create_file tool writes raw content — no code fences
  6. .mmd files: start with %%{init: on line 1. Raw Mermaid source, no fences
  7. Section MUST be titled exactly ## Action Summary. Include ### Quick Wins subsection with Tier 1 low-effort findings table
  8. K8s sidecars: annotate host container with <br/>+ Sidecar — never create separate sidecar nodes (see diagram-conventions.md Rule 1)
  9. Intra-pod localhost flows are implicit — do NOT draw them in diagrams
  10. Action Summary IS the recommendations — no separate ### Key Recommendations section
  11. Include > **Note on threat counts:** blockquote in Executive Summary
  12. Every finding MUST have CVSS 4.0 (score AND full vector string), CWE (with hyperlink), and OWASP (:2025 suffix)
  13. OWASP suffix is always :2025 (e.g., A01:2025 – Broken Access Control)
  14. Include Threat Coverage Verification table at end of 3-findings.md mapping every threat → finding
  15. Every component in 0.1-architecture.md MUST appear in 2-stride-analysis.md
  16. First 3 scenarios in 0.1-architecture.md MUST have Mermaid sequence diagrams
  17. 0-assessment.md MUST include ## Analysis Context & Assumptions with ### Needs Verification and ### Finding Overrides tables
  18. ### Quick Wins subsection is REQUIRED under Action Summary (include heading with note if none)
  19. ALL 7 sections in 0-assessment.md are MANDATORY: Report Files, Executive Summary, Action Summary, Analysis Context & Assumptions, References Consulted, Report Metadata, Classification Reference
  20. Deployment Classification is BINDING. In 0.1-architecture.md, set Deployment Classification and fill the Component Exposure Table. If classification is LOCALHOST_DESKTOP or LOCALHOST_SERVICE: zero T1 findings, zero Prerequisites = None, zero AV:N for non-listener components. See analysis-principles.md Deployment Context table.
  21. Finding IDs MUST be sequential top-to-bottom: FIND-01, FIND-02, FIND-03... Renumber after sorting
  22. CWE MUST include hyperlink: [CWE-306](https://cwe.mitre.org/data/definitions/306.html): Missing Authentication
  23. 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
  24. CVSS AV:L or PR:H → finding CANNOT be Tier 1. Downgrade to T2/T3. See CVSS-to-Tier Consistency Check in analysis-principles.md
  25. Use only Low/Medium/High effort labels. NEVER generate time estimates, sprint phases, or scheduling. See Prohibited Content in output-formats.md
  26. 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)
  27. Report Metadata: include ALL fields from output-formats.md template — Model, Analysis Started, Analysis Completed, Duration. Run Get-Date -Format "yyyy-MM-dd HH:mm:ss" -AsUTC at Step 1 and before writing 0-assessment.md
  28. ## Summary table in 2-stride-analysis.md MUST appear at the TOP, immediately after ## Exploitability Tiers, BEFORE individual component sections
  29. 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)
  30. 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
  31. Summary DFD: after creating 1.1-threatmodel.mmd, run the POST-DFD GATE in Step 4. The gate and skeleton-summary-dfd.md control whether 1.2-threatmodel-summary.mmd is generated.
  32. Report Files table in 0-assessment.md: list 0-assessment.md (this document) as the FIRST row, followed by 0.1-architecture.md, 1-threatmodel.md, etc. Use the exact template from output-formats.md
  33. threat-inventory.json MUST be generated for every analysis run (Step 8b). This file enables future comparisons. See output-formats.md for schema.
  34. NEVER delete, modify, or remove any existing threat-model-* or threat-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:

  1. Literal skeletons in skeletons/skeleton-*.md — exact section/table headers and attribute rows
  2. Mandatory Rules in orchestrator.md (this list)
  3. 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

  1. Record start time & gather context

    • Run Get-Date -Format "yyyy-MM-dd HH:mm:ss" -AsUTC and store as START_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.md for 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.md for values). Record in 0.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):

    1. Primary class name — Use the EXACT class name from the source code. Do NOT abbreviate, expand, or rephrase it.
      • TaskProcessor.cs → TaskProcessor (NOT TaskServer, NOT TaskService)
      • SessionStore.cs → SessionStore (NOT FileSessionStore, NOT SessionService)
      • TerminalUserInterface.cs → TerminalUserInterface (NOT TerminalUI)
      • PowerShellCommandExecutor.cs → PowerShellCommandExecutor (NOT PowerShellExecutor)
      • ResponsesAPIService.cs → ResponsesAPIService (NOT LLMService — that's a DIFFERENT class)
      • MCPHost.cs → MCPHost (NOT OrchestrationHost)
    2. Primary script name → Import-Images.ps1 → ImportImages
    3. Primary config/manifest name → Dockerfile → DockerContainer, values.yaml → HelmChart
    4. Directory name (if component spans multiple files) → src/ParquetParsing/ → ParquetParser
    5. Technology name (for external services/datastores) → "Azure OpenAI" → AzureOpenAI, "Redis" → Redis
    6. 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.name in deployment YAML → use that as the component ID (PascalCase normalized)
    • Example: metadata.name: devportal in templates/knowledge/devportal-deployment.yml → component ID is DevPortal
    • Example: metadata.name: phi-model in templates/knowledge/phi-deployment.yml → component ID is PhiModel
    • Why: Helm templates frequently get reorganized (e.g., moved from templates/ to templates/knowledge/) but the Kubernetes workload name stays the same. Using the workload name ensures the component ID survives directory reorganizations.
    • source_files MUST include the deployment YAML path AND the application source code path (e.g., both helmchart/myapp/templates/knowledge/devportal-deployment.yml AND developer-portal/src/)
    • source_directories MUST 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.json for Azure OpenAI connection config, helmchart/values.yaml for 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., NOT OpenAIClient). 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_keys and dependencies fields 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: TerminalUI for TerminalUserInterface, PSExecutor for PowerShellCommandExecutor
    • NEVER substitute a synonym: TaskServer for TaskProcessor, LLMService for ResponsesAPIService
    • NEVER merge two separate classes into one component: ResponsesAPIService and LLMService are 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 WindowsRegistry component
    • NEVER rename between runs: if you called it TaskProcessor in run 1, it MUST be TaskProcessor in 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 list
    

    This 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 aliases array, not as separate components
    • Example: If CredentialManager orchestrates credential lookup and uses AzureCredentialProvider internally, CredentialManager is the component and AzureCredentialProvider is an alias
    • Example: Do NOT include both SessionStore and SessionFiles — SessionStore is the class, SessionFiles is 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, the fingerprint fields source_directories, class_names, and namespace serve 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 id field. Therefore:
    • source_directories MUST be populated for every process-type component (never empty [])
    • class_names MUST include at least the primary class name
    • namespace MUST 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:

    1. It crosses a trust boundary OR handles security-sensitive data (credentials, user input, network I/O, file I/O, process execution)
    2. 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)
    3. 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, Tier suffixes)
    • 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
    • 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 requests
      • DataStorage — Databases and persistent storage (Redis, Milvus, PostgreSQL, NFS) — these have different access controls, persistence, and backup policies
      • MLModels — ML model servers running on GPU nodes — these have different compute resources, attack surfaces (adversarial inputs), and scaling characteristics
      • Agentic — Agent runtime/manager services if present
      • The outer K8sCluster contains 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, ServiceBoundary are 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.
    • Example: An application where TerminalUserInterface, MCPHost, HealthAgent, ResponsesAPIService all run in the same process → they are ALL in Application. External services like AzureOpenAI