DFD Analysis Skill

Purpose: Enable models to deeply understand Data Flow Diagrams from images, text descriptions, or structured input — then produce a detailed, validated DFD features JSON optimized for threat modeling and diagram rendering.

---

When to Use

Trigger	Action
User provides a DFD image/screenshot	Activate Image Analysis Mode → read image-analysis.md
User provides structured system description (JSON)	Activate Text Analysis Mode
User describes a system in natural language	Activate Text Analysis Mode (parse into structured input first)
User provides both image + text	Activate Hybrid Mode (image as primary, text as supplement)
Need to validate/review existing DFD JSON	Activate Validation Mode (Phase 5 only)

---

5-Phase Analysis Protocol

Every DFD analysis follows these phases sequentially. No phase may be skipped.

Phase 1 — Input Classification

Determine input type and prepare for analysis.

Input Type	Detection	Preparation
Image	File/URL with image extension, or vision input	Read image-analysis.md → extract visual elements
Structured JSON	Has structured_input with users, systempurpose, keyfeatures etc.	Parse directly
Natural Language	Free-form text describing a system	Convert to structured input format first
Hybrid	Image + any text/JSON	Parse image first, merge with text data

For natural language → structured input conversion:

Extract these fields from the description:

• users — Who interacts with the system?
• systempurpose — What does the system do?
• keyfeatures — What are the main capabilities?
• hostingenvironment — Where is it deployed?
• sensitivedata — What sensitive/PII data exists?
• thirdpartyservices — What external services are used?
• accessmethods — How do users access it?
• datastores — What data stores exist?
• cybercontrols — What security controls exist?
• assets — What valuable data needs protection? (optional)
• threat_actors — What threat actors are relevant? (optional)

---

Phase 2 — Entity Extraction

Extract the three core DFD element types. Refer to json-schema.md for naming rules.

2a. External Entities

• Sources: users + thirdpartyservices fields
• Rules:
  • Capitalize properly: customers → Customers
  • Normalize third-party names: google login → Google SSO, stripe payment → Stripe
  • Include all user types AND external service providers

2b. Processes

• Source: keyfeatures field
• Rules:
  • Each feature becomes a process, capitalize each word
  • For payment services: add Process Payment only if no explicit checkout/pay feature
  • Keep process names action-oriented: Login, Search Products, Checkout And Pay

2c. Data Stores

• Derived from: processes (NOT directly from input)
• Naming rules:
  • Manage [Entity] → [Entity] Database
  • Manage [Entity]s → [Entity] Database (singular)
  • Special: Manage Blog Posts → Blog Database
  • Logical derivation: Search Products → Product Database
• Exclusions:
  • No User Database if SSO handles auth externally
  • No Payment Database if payments handled by third-party

---

Phase 3 — Flow Mapping

Map all data flows following strict Source → Process → Target pattern.

Hard Rules (NEVER violate)

Rule	Violation Example	Correct Form
No direct entity↔data store flows	Customer → User Database	Customer → Login → User Database
No direct entity↔entity flows	Stripe → Customer	Stripe → Process Payment → Customer
Every flow passes through a process	Product DB → Customer	Product DB → Search Products → Customer
Include return flows	One-way only	Add reverse flow (query results, confirmations)

Entity-to-Process Matching

Use these mappings to connect external entities to processes. See json-schema.md for the complete mapping table.

External Entity Type	Matches Processes Containing
Payment (Stripe, PayPal, Razorpay)	payment, pay, checkout, transaction, billing
Search (Elastic, Algolia)	search, browse, find, query, discover
Auth (Google SSO, Auth0, Okta)	login, auth, sign, authenticate
AI (OpenAI, Claude, Gemini)	generate, analyze, predict, recommend, chat
Communication (Twilio, SendGrid)	notify, message, email, sms, alert
Maps (Google Maps, Mapbox)	map, location, track, navigate, delivery
Storage (S3, Azure Blob)	upload, download, store, backup

Authentication Flows

• SSO: User → Login → SSO Provider + SSO Provider → Login → User
• Include callback flows where applicable

Flow Numbering

• Sequential: 1., 2., 3....
• Use arrow symbol: →
• Format: "1. Source → Process → Target"

---

Phase 4 — Security Contextualization

Build the security layer on top of the functional DFD.

4a. Trust Boundaries

Hierarchical zones with nesting support. Standard zones:

Zone	Contains	Nesting
Internet Zone	External users	Children: per-user-type networks
DMZ	Public-facing processes	—
Application Zone	Business logic processes	—
Data Zone	Databases, file storage	—
External Services Zone	Third-party entities	—
PCI Zone	Payment processes (if card data)	—
Admin Zone	Admin processes	—

Determine boundaries based on: deployment environment, data sensitivity, data flow patterns.

4b. Assets

Identify valuable data that needs protection.

• Priority: Use input assets if provided; otherwise derive from sensitivedata + processes/data stores
• IDs: A01, A02, A03...
• Sensitivity: high | medium | low
• Common assets: User Credentials, Payment Data, Personal Information, Health Records, Business Data, API Keys/Secrets

4c. Security Controls

Categorize from cybercontrols input.

• IDs: C01, C02, C03...
• Types: authentication | authorization | encryption_transit | encryption_rest | monitoring | network | access_control
• Associate with relevant nodes (processes) and edges (flow numbers)
• See json-schema.md for type-to-control mapping

4d. Threat Actors

• Priority: Use input threat_actors if provided; otherwise infer from system type + assets
• IDs: T01, T02, T03...
• Categories: external | insider | third_party | automated
• Associate with target assets (by ID) and entry points (external entities)

---

Phase 5 — Validation & Orphan Resolution

This phase is mandatory. Do NOT skip.

Step 1: Orphan Detection

Scan all external entities, processes, and data stores. Any that don't appear in ANY data flow → orphan list.

Step 2: Orphan Resolution

Apply these rules systematically:

Orphan Type	Resolution Strategy
Orphan Process	Match to entity whose ROLE relates to the function. Inventory → Store Managers/Vendors. Payment → Payment entities. Admin → Admins. Then connect to appropriate data store.
Orphan External Entity	Match to process that needs that entity type. User-type → user-facing processes. Service-type → integration processes.
Orphan Data Store	Match to process that would read/write that data. User DB → Login. Order DB → Checkout. Product DB → Search/Inventory.

After adding orphan flows: number them sequentially after the last existing flow.

Step 3: Cross-Validation Checklist

• Every external entity appears in at least one flow
• Every process appears in at least one flow
• Every data store appears in at least one flow
• No direct entity↔data store flows exist
• No direct entity↔entity flows exist
• All flows follow Source → Process → Target pattern
• Return flows exist for query/response patterns
• Trust boundary components match actual entity/process/store names exactly
• All asset associatedNodes reference real node names
• All control associatedEdges reference real flow numbers
• All threat actor entryPoints reference real external entities
• All threat actor targetAssets reference real asset IDs
• IDs are sequential with no gaps (A01-A0N, C01-C0N, T01-T0N)

---

Output

Produce a single JSON object matching the schema in json-schema.md.

Format rules:

• No markdown code fences in output
• Proper capitalization on all names
• Empty arrays [] for categories with no items
• No placeholder text
• Arrow symbol → in data flows

---

Supplementary Files

File	When to Read
image-analysis.md	When input contains a DFD image or screenshot
json-schema.md	Always — contains the output schema, all mapping rules, and naming conventions
examples.md	When you need reference input→output pairs

---

Anti-Patterns

❌ Don't	✅ Do
Skip orphan resolution	Always run Phase 5
Connect entities directly to data stores	Route through processes
Use generic names ("Database 1")	Use descriptive names ("Product Database")
Guess at unclear image elements	Flag uncertainty, ask user
Copy input verbatim without normalization	Capitalize, normalize third-party names
Add unnecessary data stores	Derive only from processes
Omit return flows	Include bidirectional flows for request/response