Skip to content

Souvik-223/agent-skills-agentic-tools / .agents/skills/dfd-analysis

dfd-analysis

Verified

Deep DFD understanding from images and text. Multi-phase analysis protocol that extracts entities, maps data flows, contextualizes security boundaries, and produces structured DFD features JSON for threat modeling.

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

TriggerAction
User provides a DFD image/screenshotActivate Image Analysis Mode → read image-analysis.md
User provides structured system description (JSON)Activate Text Analysis Mode
User describes a system in natural languageActivate Text Analysis Mode (parse into structured input first)
User provides both image + textActivate Hybrid Mode (image as primary, text as supplement)
Need to validate/review existing DFD JSONActivate 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 TypeDetectionPreparation
ImageFile/URL with image extension, or vision inputRead image-analysis.md → extract visual elements
Structured JSONHas structured_input with users, systempurpose, keyfeatures etc.Parse directly
Natural LanguageFree-form text describing a systemConvert to structured input format first
HybridImage + any text/JSONParse 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)

RuleViolation ExampleCorrect Form
No direct entity↔data store flowsCustomer → User DatabaseCustomer → Login → User Database
No direct entity↔entity flowsStripe → CustomerStripe → Process Payment → Customer
Every flow passes through a processProduct DB → CustomerProduct DB → Search Products → Customer
Include return flowsOne-way onlyAdd 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 TypeMatches 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:

ZoneContainsNesting
Internet ZoneExternal usersChildren: per-user-type networks
DMZPublic-facing processes—
Application ZoneBusiness logic processes—
Data ZoneDatabases, file storage—
External Services ZoneThird-party entities—
PCI ZonePayment processes (if card data)—
Admin ZoneAdmin 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 TypeResolution Strategy
Orphan ProcessMatch 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 EntityMatch to process that needs that entity type. User-type → user-facing processes. Service-type → integration processes.
Orphan Data StoreMatch 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

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

Anti-Patterns

❌ Don't✅ Do
Skip orphan resolutionAlways run Phase 5
Connect entities directly to data storesRoute through processes
Use generic names ("Database 1")Use descriptive names ("Product Database")
Guess at unclear image elementsFlag uncertainty, ask user
Copy input verbatim without normalizationCapitalize, normalize third-party names
Add unnecessary data storesDerive only from processes
Omit return flowsInclude bidirectional flows for request/response
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall