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 · 24000

are in External.

  • Two runs on the same code MUST produce the same number of boundaries (±1). A difference of ≥2 boundaries is WRONG.
  • NEVER create boundaries based on code layers (Presentation/Business/Data) — boundaries represent DEPLOYMENT trust boundaries, not code architecture

Boundary count locking:

  • After identifying boundaries, LOCK the count. Two runs on the same code MUST produce the same number of boundaries (±1 acceptable if one run identifies an edge boundary the other doesn't)
  • A 4-boundary vs 7-boundary difference on the same code is WRONG and indicates the naming rules were not followed

Additional naming rules:

  • The SAME component must get the SAME id regardless of which LLM model runs the analysis or how many times it runs
  • External actors (Operator, AzureDataStudio, etc.) are ALWAYS included — never drop them
  • Datastores representing distinct storage (files, database) are ALWAYS separate components — never merge them
  • Lock the component list before Step 2. Use these exact IDs in ALL subsequent files (architecture, DFD, STRIDE, findings, JSON)
  • If two classes exist as separate files (e.g., ResponsesAPIService.cs and LLMService.cs), they are TWO components even if they seem related

⛔ DATA FLOW COMPLETENESS (MANDATORY — ensures consistent flow enumeration across runs): Data flows MUST be enumerated exhaustively. Two independent analyses of the same codebase MUST produce the same set of flows. To achieve this:

⛔ RETURN FLOW MODELING RULE (addresses 24% variance in flow counts):

  • DO NOT model separate return flows. A request-response pair is ONE bidirectional flow (use <--> in Mermaid).
  • Example: DF01: Operator <--> TUI (one flow for input and output)
  • Example: DF03: MCPHost <--> HealthAgent (one flow for delegation and result)
  • DO model separate flows ONLY when the two directions use different protocols or semantics (e.g., HTTP request vs WebSocket push-back).
  • Why: When runs independently decide whether to create 1 flow or 2 flows per interaction, the flow count varies by 20-30%. This rule eliminates that variance.
  • Flow count formula: # flows ≈ # unique component-to-component interactions. If component A talks to component B, that is 1 flow, not 2.

Flow completeness checklist (use <--> bidirectional flows per the return flow rule above):

  1. Ingress/reverse proxy flows: DF_EndUser_to_NginxIngress (bidirectional <-->), DF_NginxIngress_to_Backend (bidirectional <-->). Each is ONE flow, not two.
  2. Database/datastore flows: DF_Service_to_Redis (bidirectional <-->). ONE flow per service-datastore pair.
  3. Auth provider flows: DF_Service_to_AzureAD (bidirectional <-->). ONE flow per service-auth pair.
  4. Admin access flows: DF_Operator_to_Service (bidirectional <-->). ONE per admin interaction.
  5. Flow count locking: After enumerating flows, LOCK the count. Two runs on the same code MUST produce the same number of flows (±3 acceptable). A difference of >5 flows indicates incomplete enumeration.

⛔ EXTERNAL ENTITY INCLUSION RULES (addresses variance in which externals are modeled):

  • ALWAYS include AzureAD (or EntraID) as an external entity if the code acquires tokens from Azure AD / Microsoft Entra ID (look for ChainedTokenCredential, ManagedIdentityCredential, AzureCliCredential, MSAL, or any OAuth2/OIDC flow).
  • ALWAYS include the infrastructure target (e.g., OnPremInfra, HCICluster) as an external entity if the code sends commands to external infrastructure via PowerShell, REST, or WMI.
  • ALWAYS include AzureOpenAI (or equivalent LLM endpoint) if the code calls a cloud LLM API.
  • ALWAYS include Operator as an external actor for CLI/TUI tools, admin tools, or operator consoles.
  • Rule of thumb: If the code has a client class or config for a service, that service is an external entity.

⛔ TMT CATEGORY RULES (addresses category inconsistency across runs):

  • Tool servers that expose APIs callable by agents → SE.P.TMCore.WebSvc (NOT SE.P.TMCore.NetApp)
  • Network-level services that handle connections/sockets → SE.P.TMCore.NetApp
  • Services that execute OS commands (PowerShell, bash) → SE.P.TMCore.OSProcess
  • Services that store data to disk (SessionStore, FileLogger) → SE.DS.TMCore.FS (classify as Data Store, NOT Process)
  • Rule: If a class's primary purpose is persisting data, it is a Data Store. If it does computation or orchestration, it is a Process. Never switch between runs.

⛔ DFD DIRECTION (MANDATORY — addresses layout variance):

  • ALL DFDs MUST use flowchart LR (left-to-right). NEVER use flowchart TB.
  • ALL summary DFDs MUST also use flowchart LR.
  • This is immutable — do not change based on aesthetics or diagram shape.

Acronym rules for PascalCase:

  • Preserve well-known acronyms as ALL-CAPS: API, NFS, LLM, SQL, HCI, AD, UI, DB
  • Examples: IngestionAPI (not IngestionApi), NFSServer (not NfsServer), AzureAD (not AzureAd), VectorDBAPI (not VectorDbApi)
  • Single-word technologies keep standard casing: Redis, Milvus, PostgreSQL, Nginx

Common technology naming (use EXACTLY these IDs for well-known infrastructure):

  • Redis cache/state: Redis (never DaprStateStore, RedisCache, StateStore)
  • Milvus vector DB: Milvus (never MilvusVectorDb, VectorDB)
  • NGINX ingress: NginxIngress (never IngressNginx)
  • Azure AD/Entra: AzureAD (never AzureAd, EntraID)
  • PostgreSQL: PostgreSQL (never PostgresDb, Postgres)
  • User/Operator: Operator for admin users, EndUser for end users
  • Azure OpenAI: AzureOpenAI (never OpenAIService, LLMEndpoint)
  • NFS: NFSServer (never NfsServer, FileShare)
  • If two LLM models are separate deployments, keep them separate (never merge MistralLLM + PhiLLM into LocalLlm)

BUT: for application-specific classes, use the EXACT class name from the code, NOT a technology label:

  • ResponsesAPIService.cs → ResponsesAPIService (NOT OpenAIService — the class IS named ResponsesAPIService)
  • TaskProcessor.cs → TaskProcessor (NOT LocalLLM — the class IS named TaskProcessor)
  • SessionStore.cs → SessionStore (NOT StatePersistence — the class IS named SessionStore) Component granularity rules (CRITICAL for stability):
  • Model components at the technology/service level, not the script/file level
  • A Docker container running Kusto is KustoContainer — NOT decomposed into KustoService + IngestLogs + KustoDataDirectory
  • A Moby Docker engine is MobyDockerEngine — NOT InstallMoby (the installer script is evidence, not the component)
  • An installer for a tool is SetupInstaller — NOT renamed to InstallAzureEdgeDiagnosticTool (script filename)
  • Rule: if a component has one primary function (e.g., "run Kusto queries"), model it as ONE component regardless of how many scripts/files implement it
  • Scripts are EVIDENCE for components, not components themselves
  • Keep the same granularity across runs — never split a single component into sub-components or merge sub-components between runs

⛔ COMPONENT ID FORMAT (MANDATORY — addresses casing variance):

  • ALL component IDs MUST be PascalCase. NEVER use kebab-case, snake_case, or camelCase.
  • Examples: HealthAgent (not health-agent), AzureAD (not azure-ad), MCPHost (not mcp-host)
  • This applies to ALL artifacts: 0.1-architecture.md, 1-threatmodel.md, DFD mermaid, STRIDE, findings, JSON.

⛔ STRIDE SCOPE RULE (addresses external entity analysis variance):

  • STRIDE analysis in 2-stride-analysis.md MUST include sections for ALL elements in the Element Table EXCEPT external actors (Operator, EndUser).
  • External services (AzureOpenAI, AzureAD, OnPremInfra) DO get STRIDE sections — they are attack surfaces from YOUR system's perspective.
  • External actors (human users) do NOT get STRIDE sections — they are threat SOURCES, not targets.
  • This means: if you have 20 elements total and 1 is an external actor, you write 19 STRIDE sections.

⛔ STRIDE DEPTH CONSISTENCY (addresses threat count variance):

  • Each component MUST get ALL 7 STRIDE-A categories analyzed (S, T, R, I, D, E, A).
  • Each STRIDE category MUST be explicitly addressed per component: either with one or more concrete threats, OR with an explicit N/A — {1-sentence justification} row explaining why that category does not apply to this specific component.
  • A category may produce 0, 1, 2, 3, or more threats — the count depends on the component's actual attack surface. Do NOT cap at 1 threat per category. Components with rich security surfaces (API services, auth managers, command executors, LLM clients) should typically have 2-4 threats per relevant STRIDE category. Only simple components (static config, read-only data stores) should have mostly 0-1.
  • Expected distribution: For a 15-component system: ~30% of STRIDE cells should be 0 (with N/A), ~40% should be 1, ~25% should be 2, ~5% should be 3+. If ALL cells are 0 or 1 (binary pattern) → the analysis is too shallow. Go back and identify additional threat vectors.
  • N/A entries do NOT count toward threat totals in the Summary table. Only concrete threat rows count.
  • The Summary table S/T/R/I/D/E/A columns show the COUNT of concrete threats per category (0 is valid if N/A was justified).
  • This ensures comprehensive coverage while producing accurate, non-inflated threat counts.
  1. Write architecture overview (0.1-architecture.md)

    • Read skeletons/skeleton-architecture.md first — copy skeleton structure, fill [FILL] placeholders
    • System purpose, key components, top scenarios, tech stack, deployment
    • Use the exact component IDs locked in Step 1 — do not rename or merge components
    • Reference: output-formats.md for template, diagram-conventions.md for architecture diagram styles
  2. Inventory security infrastructure

    • Identify security-enabling components before flagging gaps
    • Reference: analysis-principles.md Security Infrastructure Inventory table
  3. Produce threat model DFD (1.1-threatmodel.mmd, 1.2-threatmodel-summary.mmd, 1-threatmodel.md)

    • Read skeletons/skeleton-dfd.md, skeletons/skeleton-summary-dfd.md, and skeletons/skeleton-threatmodel.md first
    • Reference: diagram-conventions.md for DFD styles, tmt-element-taxonomy.md for element classification
    • ⚠️ BEFORE FINALIZING: Run the Pre-Render Checklist from diagram-conventions.md

    ⛔ POST-DFD GATE — Run IMMEDIATELY after creating 1.1-threatmodel.mmd:

    1. Count elements (nodes with ((...)), [(...), ["..."]) in 1.1-threatmodel.mmd
    2. Count boundaries (subgraph lines)
    3. If elements > 15 OR boundaries > 4: → You MUST create 1.2-threatmodel-summary.mmd using skeleton-summary-dfd.md NOW → Do NOT proceed to 1-threatmodel.md until the summary file exists
    4. If threshold NOT met → skip summary, proceed to 1-threatmodel.md
    5. Create 1-threatmodel.md (include Summary View section if summary was generated)
  4. Enumerate threats per element and flow using STRIDE-A (2-stride-analysis.md)

    • Read skeletons/skeleton-stride-analysis.md first — use Summary table and per-component structure
    • Reference: analysis-principles.md for tier definitions, output-formats.md for STRIDE template
    • ⛔ PREREQUISITE FLOOR CHECK (per threat): Before assigning a prerequisite to any threat, look up the component's Min Prerequisite and Derived Tier in 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 (i.e., if component is T2, no threat can be T1). Use the canonical prerequisite→tier mapping from analysis-principles.md.
  5. For each threat: cite files/functions/endpoints, propose mitigations, provide verification steps

  6. Verify findings — confirm each finding against actual configuration before documenting

    • Reference: analysis-principles.md Finding Validation Checklist

7b. Technology sweep — Run the Technology-Specific Security Checklist from analysis-principles.md

  • For every technology found in the repo (Redis, Milvus, PostgreSQL, Docker, K8s, ML models, LLMs, NFS, CI/CD, etc.), verify you have at least one finding or explicit mitigation
  • This step catches gaps that component-level STRIDE misses (e.g., database auth defaults, container hardening, key management)
  • Add any missing findings before proceeding to Step 8
  1. Compile findings (3-findings.md)

    • Reference: output-formats.md for findings template and Related Threats link format
    • Reference: skeletons/skeleton-findings.md — read this skeleton, copy VERBATIM, fill in [FILL] placeholders for each finding

    ⛔ PRE-WRITE GATE — Verify before calling create_file for 3-findings.md:

    1. Finding IDs: ### FIND-01:, ### FIND-02: — sequential, FIND- prefix (NOT F01 or F-01)
    2. CVSS prefix: every vector starts with CVSS:4.0/ (NOT bare AV:N/AC:L/...)
    3. Related Threats: each threat ID is a separate hyperlink [TNN.X](2-stride-analysis.md#anchor) (NOT plain text)
    4. Sub-sections: #### Description, #### Evidence, #### Remediation, #### Verification (NOT Recommendation)
    5. Sort: within each tier → Critical → Important → Moderate → Low → higher CVSS first
    6. All 10 mandatory attribute rows present per finding
    7. Deployment context gate (FAIL-CLOSED): 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 to Local Process Access (T2) or Host/OS Access (T3)
      • ZERO findings may be in ## Tier 1 → downgrade to T2/T3 based on prerequisite
      • ZERO CVSS vectors may use AV:N unless the specific component has Reachability = External in the Component Exposure Table → fix to AV:L For ALL deployment classifications:
      • For EACH finding, look up its Component in the exposure table. The finding's prerequisite MUST be ≥ the component's Min Prerequisite. The finding's tier MUST be ≥ the component's Derived Tier.
      • 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 Access and Host Access are FORBIDDEN. If ANY violation exists → DO NOT WRITE THE FILE. Fix all violations first.

    ⛔ Fail-fast gate: Immediately after writing, run the Inline Quick-Checks for 3-findings.md from verification-checklist.md. Fix before proceeding.

    ⛔ MANDATORY: All 3 tier sections must be present. Even if a tier has zero findings, include the heading with a note:

    • ## Tier 1 — Direct Exposure (No Prerequisites) → *No Tier 1 findings identified for this repository.*
    • This ensures structural consistency for comparison matching and validation.

    ⛔ COVERAGE VERIFICATION FEEDBACK LOOP (MANDATORY): After writing the Threat Coverage Verification table at the end of 3-findings.md:

    1. Scan the table you just wrote. Count how many threats have status ✅ Covered vs 🔄 Mitigated by Platform vs ⚠️ Needs Review vs ⚠️ Accepted Risk.
    2. If ANY threat has ⚠️ Accepted Risk → FAIL. The tool cannot accept risks. Go back and create a finding for each one.
    3. If Platform ratio > 20% → SUSPECT. Re-examine each 🔄 Mitigated by Platform entry: is the mitigation truly from an EXTERNAL system managed by a DIFFERENT team? If the mitigation is the repo's own code (auth middleware, file permissions, TLS config, localhost binding), reclassify as Open and create a finding.
    4. If ANY Open threat in 2-stride-analysis.md has NO corresponding finding → create a finding NOW. Use the threat's description as the finding title, the mitigation column as the remediation guidance, and assign severity based on STRIDE category.
    5. Update 3-findings.md with the newly created findings. Renumber sequentially. Update the Coverage table to show ✅ Covered for each.
    6. This loop is the ENTIRE POINT of the Coverage table — it's not documentation, it's a self-check that forces complete coverage. If you write the table and don't act on gaps, you've wasted the effort.

8b. Generate threat inventory (threat-inventory.json)

  • Read skeletons/skeleton-inventory.md first — use exact field names and schema structure
  • After writing all markdown reports, compile a structured JSON inventory of all components, boundaries, data flows, threats, and findings - Use canonical PascalCase IDs for components (derived from class/file names) and keep display labels separate
  • Use canonical flow IDs: DF_{Source}_to_{Target} - Include identity keys on every threat and finding for future matching - Include deterministic identity fields for component and boundary matching across runs:
    • Component: aliases, boundary_kind, fingerprint
    • Boundary: kind, aliases, contains_fingerprint - Build fingerprint from stable evidence (source files, endpoint neighbors, protocols, type) — never from prose wording - Normalize synonyms to the same canonical component ID (example: SupportAgent and SupportabilityAgent → SupportabilityAgent) and store alternate names in aliases - Sort arrays deterministically before writing JSON:
    • components by id
    • boundaries by id
    • flows by id
    • threats by id then identity_key.component_id
    • findings by id then identity_key.component_id
  • Extract metrics (totals, per-tier counts, per-STRIDE-category counts)
  • Include git metadata (commit SHA, branch, date) and analysis metadata (model, timestamps)
  • Reference: output-formats.md for the threat-inventory.json schema
  • This file is NOT linked in 0-assessment.md but is always present in the output folder

⛔ PRE-WRITE SIZE CHECK (MANDATORY — before calling create_file for JSON): Before writing threat-inventory.json, count the data you plan to include:

  • Count total threats from 2-stride-analysis.md (grep ^\| T\d+\.)
  • Count total findings from 3-findings.md (grep ### FIND-)
  • Count total components from 0.1-architecture.md
  • If threats > 50 OR findings > 15: DO NOT use a single create_file call. Instead, use one of: (a) delegate to sub-agent, (b) Python extraction script, (c) chunked write strategy.
  • If threats ≤ 50 AND findings ≤ 15: single create_file is acceptable, but keep entries minimal (1-sentence description/mitigation fields).

⛔ POST-WRITE VALIDATION (MANDATORY — JSON Array Completeness): After writing threat-inventory.json, immediately verify:

  • threats.length == metrics.total_threats — if mismatch, the threats array was truncated during generation. Rebuild by re-reading 2-stride-analysis.md and extracting every threat row.
  • findings.length == metrics.total_findings — if mismatch, rebuild from 3-findings.md.
  • components.length == metrics.total_components — if mismatch, rebuild from architecture/element tables.

⛔ CROSS-FILE THREAT COUNT VERIFICATION (MANDATORY — catches dropped threats): The JSON threats.length can match metrics.total_threats but BOTH can be wrong if threats were dropped during JSON generation. To catch this:

  • Count threat rows in 2-stride-analysis.md: grep for ^\| T\d+\. and count unique threat IDs
  • Compare this count to threats.length in the JSON
  • If the markdown has MORE threats than the JSON → the JSON dropped threats. Rebuild the JSON by re-extracting ALL threats from 2-stride-analysis.md.
  • This is the #2 quality issue observed in testing (after truncation). Large repos (114+ threats) frequently have 1-3 threats dropped when sub-agents write the JSON from memory instead of re-reading the STRIDE file.

⛔ FIELD NAME COMPLIANCE GATE (MANDATORY — run immediately after array check): Read the first component and first threat from the JSON just written and verify these EXACT field names:

  • components[0] has key "display" (NOT "display_name", NOT "name") → if wrong, find-replace ALL occurrences

  • threats[0] has key "stride_category" (NOT "category") → if wrong, find-replace ALL occurrences

  • threats[0].identity_key has key "component_id" (threat→component link must be INSIDE identity_key, NOT a top-level component_id field on the threat) → if wrong, restructure

  • threats[0] has BOTH "title" (short name, e.g., "Information Disclosure — Redis unencrypted traffic") AND "description" (longer prose). If only description exists without title, create title from the first sentence of description. If name or threat_name exists instead of title, find-replace to title

  • Why this matters: Downstream tooling depends on these exact field names. Wrong names cause zero-value heatmaps, broken component matching, and empty display labels in comparison reports.

  • If ANY field name is wrong: fix it NOW with find-replace on the JSON file before proceeding. Do NOT leave it for verification.

  • This is the #1 quality issue observed in testing. Large repos (20+ components, 80+ threats) frequently have truncated JSON arrays because the model runs out of output tokens. If ANY array is truncated, you MUST rebuild it before proceeding. Do NOT finalize with mismatched counts.

⛔ HARD GATE — TRUNCATION RECOVERY (MANDATORY): If post-write validation detects ANY array mismatch:

  1. DELETE the truncated threat-inventory.json immediately
  2. DO NOT attempt to patch the truncated file — partial JSON is unreliable
  3. Regenerate using one of these strategies (in preference order): a. Delegate to a sub-agent — hand the sub-agent the output folder path and instruct it to read 2-stride-analysis.md and 3-findings.md, then write threat-inventory.json. The sub-agent has a fresh context window. b. Python extraction script — write a Python script that reads the markdown files, extracts threats/findings via regex, and writes the JSON. Run the script via terminal. c. Chunked write — use the Large Repo Strategy below.
  4. Re-validate after regeneration — if still mismatched, repeat with the next strategy
  5. NEVER proceed to Step 9 (assessment) or Step 10 (verification) with mismatched counts

⛔ LARGE REPO STRATEGY (MANDATORY for repos with >60 threats): For repos producing more than ~60 threats, the JSON file can exceed output token limits if generated in one pass. Use this chunked approach:

  1. Write metadata + components + boundaries + flows + metrics first — these are small arrays
  2. Append threats in batches — write threats array with ~20 threats per append operation. Use replace_string_in_file to add batches to the existing file rather than writing the entire JSON in one create_file call.
  3. Append findings — similarly batch if >15 findings
  4. Final validation — read the completed file and verify all array lengths match metrics

Alternative approach: If chunked writing is not feasible, keep each threat/finding entry minimal:

  • description field: max 1 sentence (not full prose paragraphs)
  • mitigation field: