Data Flows

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.

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:

Step 3: Identify Data Sinks (Destinations)

Catalog every point where data exits or is persisted:

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:

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.