Data Flow Mapping

Trace how data moves through the application from input to storage to output. Identify trust boundary crossings, encryption/decryption points, serialization steps, and data transformation operations. Produces annotated data flow maps with security observations at each transition.

Supported Flags

Read ../../shared/schemas/flags.md for the full flag specification.

| Flag | Data Flow Behavior | |------|--------------------| | --scope | Default full. Data flow mapping requires broad visibility. Narrow scopes trace only flows touching scoped files. | | --depth quick | Entry points and data stores only, no intermediate tracing. | | --depth standard | Trace major data paths from input through processing to storage/output. | | --depth deep | Full taint analysis: every transformation, validation, and boundary crossing. | | --depth expert | Deep + annotate with threat categories, identify covert channels, DREAD scoring on flow weaknesses. | | --format | Default text. Use md for Mermaid diagrams, json for structured flow graph. |

Workflow

Step 1: Determine Scope

1. Parse --scope flag. Default to full for comprehensive flow mapping.
2. Resolve to a concrete file list.
3. Prioritize: HTTP handlers, database access layers, external service clients, message queue producers/consumers, file I/O operations, cache layers, serialization/deserialization code, encryption modules.

Step 2: Identify Data Sources (Origins)

Catalog every point where data enters the system:

| Source Type | What to Look For | |-------------|-----------------| | HTTP requests | Request body, query params, headers, cookies, path params, uploaded files | | Database reads | Queries returning user data, config data, or cached content | | External APIs | Responses from third-party services, webhook payloads | | Message queues | Consumed messages from Kafka, RabbitMQ, SQS, etc. | | File system | File reads, config loading, uploaded file processing | | Environment | Environment variables, secrets managers, config services | | User sessions | Session data, cached user state |

Step 3: Identify Data Sinks (Destinations)

Catalog every point where data exits or is persisted:

| Sink Type | What to Look For | |-----------|-----------------| | Database writes | INSERT, UPDATE, ORM save/create operations | | HTTP responses | Response body, headers, cookies set | | External APIs | Requests to third-party services | | Message queues | Published messages | | File system | File writes, log files, exported data | | Logs | Application logs, audit logs, error tracking | | Browser | Rendered HTML, JavaScript context, DOM injection points | | Email/SMS | Outbound notification content |

Step 4: Trace Data Paths

For each source, trace data through the codebase to its sinks:

1. Follow the variable: Track the request parameter/input through function calls, assignments, and returns.
2. Map transformations: Record every operation applied to the data:
   • Validation (type checks, regex, allowlists)
   • Sanitization (HTML escaping, SQL parameterization, encoding)
   • Encryption/Decryption (note algorithm and key source)
   • Serialization/Deserialization (JSON parse, protobuf, pickle)
   • Aggregation (data combined with other sources)
   • Redaction (fields stripped or masked)
3. Mark trust boundaries: Note when data crosses between:
   • External network to application
   • Application to database
   • Application to external service
   • Frontend to backend
   • Service to service (in microservices)
   • User space to privileged operations

Step 5: Annotate Security Properties

At each node in the data flow, annotate:

| Property | Values | |----------|--------| | Encrypted | In transit (TLS), at rest (AES/etc.), both, neither | | Validated | Yes (with method), no, partial | | Sanitized | Yes (with method), no | | Logged | Yes (check for sensitive data in logs), no | | Access controlled | Auth required, role checked, none | | PII/Sensitive | Contains PII, financial, health, credentials, or other sensitive data |

Step 6: Identify Flow Weaknesses

Flag security concerns at data flow transitions:

1. Missing validation: Data crosses a trust boundary without validation.
2. Missing encryption: Sensitive data transmitted or stored without encryption.
3. Sensitive data in logs: PII, credentials, or tokens written to log sinks.
4. Deserialization of untrusted data: pickle.loads, JSON.parse on unvalidated external input without schema validation, ObjectInputStream on network data.
5. Trust boundary violations: Internal-only data exposed to external sinks.
6. Missing sanitization before output: Data from untrusted source rendered in HTML, SQL, or shell command without appropriate encoding.
7. Data retention issues: Sensitive data persisted longer than necessary or without deletion mechanisms.
8. Implicit trust: Data from one service consumed by another without re-validation.

Step 7: Generate Flow Diagrams

Produce Mermaid data flow diagrams:

graph LR
    subgraph External
        User[User Browser]
        ExtAPI[Payment API]
    end
    subgraph Application
        API[API Handler]
        Valid[Validator]
        Logic[Business Logic]
        Encrypt[Encryption Layer]
    end
    subgraph Storage
        DB[(Database)]
        Cache[(Redis Cache)]
    end

    User -->|HTTPS, JSON body| API
    API -->|raw input| Valid
    Valid -->|validated data| Logic
    Logic -->|PII: encrypted| Encrypt
    Encrypt -->|ciphertext| DB
    Logic -->|session token| Cache
    Logic -->|payment request, TLS| ExtAPI

Annotate edges with: protocol, encryption status, data sensitivity level.

Step 8: Report

Output the data flow map with security annotations and any findings.

Output Format

This skill produces a data flow map plus findings for flow weaknesses.

Finding ID prefix: FLOW (e.g., FLOW-001).

## Data Flow Analysis

### Summary
- Data sources identified: N
- Data sinks identified: N
- Trust boundary crossings: N
- Unvalidated crossings: N
- Sensitive data flows: N

### Data Flow Diagram
[Mermaid diagram]

### Flow Inventory

| # | Source | Path | Sink | Sensitivity | Encrypted | Validated | Issue |
|---|--------|------|------|-------------|-----------|-----------|-------|
| 1 | POST /api/login | -> auth.verify -> db.query | users table | Credentials | TLS only | Yes | None |
| 2 | POST /api/upload | -> fileHandler -> fs.write | /uploads/ | User files | No | No | FLOW-001 |

### Trust Boundary Crossings
[Table of all boundary crossings with security annotations]

### Findings
[Standard findings for flow weaknesses]

Findings follow ../../shared/schemas/findings.md with:

• metadata.tool: "data-flows"
• references.cwe: CWE-319 (Cleartext Transmission), CWE-312 (Cleartext Storage), CWE-532 (Info Exposure Through Log), CWE-502 (Deserialization of Untrusted Data)

Pragmatism Notes

• Not every data path needs encryption. Public data served over HTTPS is fine.
• Internal service-to-service calls over a trusted network or service mesh are lower priority than internet-facing flows.
• Focus on sensitive data flows first: credentials, PII, financial data, health data.
• Log redaction is important but severity depends on log access controls.
• At --depth quick, a high-level source-to-sink map is more useful than exhaustive intermediate tracing.