Flow Trace

Flow Trace Skill

Purpose

Trace data flow from source (user input) to sink (dangerous function) across multiple files. Outputs structured flow_edges for visualization and documentation.

When to Use

• After finding a potential vulnerability, trace the full path
• Understanding how user input reaches a dangerous sink
• Documenting the attack path for a finding
• Verifying if a source can actually reach a sink

Input Requirements

Provide either:

1. Starting point: Source file and function/variable
2. Ending point: Sink file and function
3. Both: For verifying connectivity

Output Format

Output flow edges in this structure:

flow_edges:
  - from_file: "src/routes/api.rs"
    from_line: 45
    from_symbol: "request.params['id']"
    to_file: "src/routes/api.rs"
    to_line: 48
    to_symbol: "get_user(id)"
    kind: taint
    notes: "User input passed to function"

  - from_file: "src/routes/api.rs"
    from_line: 48
    from_symbol: "get_user(id)"
    to_file: "src/db/users.rs"
    to_line: 23
    to_symbol: "User::find(id)"
    kind: dataflow
    notes: "Function call crosses file boundary"

  - from_file: "src/db/users.rs"
    from_line: 23
    from_symbol: "User::find(id)"
    to_file: "src/db/users.rs"
    to_line: 25
    to_symbol: "db.query(format!(...))"
    kind: taint
    notes: "SINK: Unsanitized input in SQL query"

Flow Edge Types

Tracing Process

1. Identify Source

Common sources:
- HTTP request parameters, body, headers
- File uploads (filename, content)
- Database values (stored attacks)
- Environment variables
- WebSocket messages
- Command line arguments

2. Follow Transformations

Track through:
- Variable assignments: let x = source
- Function parameters: foo(source)
- Return values: return process(source)
- Object properties: obj.field = source
- Array operations: arr.push(source)

3. Cross File Boundaries

Look for:
- Function calls to other modules
- Imports/requires
- Class inheritance
- Trait implementations
- Interface method calls

4. Identify Sinks

Dangerous sinks by type:
- SQL: db.query(), db.execute(), raw SQL
- Command: system(), exec(), spawn()
- XSS: innerHTML, document.write()
- File: open(), readFile(), writeFile()
- SSRF: http.get(url), fetch(url)

Example Trace

Starting Point

File: src/api/users.rs:15
Symbol: request.query("id")

Trace Output

flow_edges:
  - from_file: "src/api/users.rs"
    from_line: 15
    from_symbol: "request.query('id')"
    to_file: "src/api/users.rs"
    to_line: 16
    to_symbol: "id"
    kind: taint
    notes: "Query param extracted"

  - from_file: "src/api/users.rs"
    from_line: 16
    from_symbol: "id"
    to_file: "src/api/users.rs"
    to_line: 18
    to_symbol: "UserService::get(id)"
    kind: dataflow
    notes: "Passed to service layer"

  - from_file: "src/api/users.rs"
    from_line: 18
    from_symbol: "UserService::get(id)"
    to_file: "src/services/user.rs"
    to_line: 42
    to_symbol: "UserRepository::find(id)"
    kind: dataflow
    notes: "Service delegates to repository"

  - from_file: "src/services/user.rs"
    from_line: 42
    from_symbol: "UserRepository::find(id)"
    to_file: "src/db/repository.rs"
    to_line: 78
    to_symbol: "db.execute(query)"
    kind: taint
    notes: "SINK: SQL execution"

summary: "User input from query param flows through 4 hops to SQL sink"
sink_type: "SQL Injection"
sanitization_found: false

Summary Format

After tracing, provide:

summary: "<source> -> ... (<N> hops) -> <sink>"
sink_type: "SQL Injection|Command Injection|XSS|Path Traversal|SSRF|..."
sanitization_found: true|false
sanitization_notes: "Input validated at step 2 with regex"

Tips for Effective Tracing

1. Start broad, narrow down: First identify all call sites, then trace specific paths
2. Watch for sanitization: Note if/where input is validated or escaped
3. Track transformations: URL decode, base64, JSON parse can bypass filters
4. Check error paths: Error handlers often have different (weaker) validation
5. Follow async flows: Callbacks, promises, async/await can obscure data flow

KYCo Integration

After tracing a vulnerability path, register the finding and flow edges:

1. Check Active Project

kyco project list

2. Create Finding with Taint Path

kyco finding create \
  --title "SQL Injection via user ID parameter" \
  --project PROJECT_ID \
  --severity high \
  --cwe CWE-89 \
  --attack-scenario "User input flows from request.params['id'] through 4 hops to db.query() without sanitization"

3. Import SARIF/Semgrep Results (if available)

# Import from security scanner output
kyco finding import semgrep-results.json --project PROJECT_ID

# Auto-detect format
kyco finding import scan-results.sarif --project PROJECT_ID

4. View Flow in Kanban

The KYCo GUI Kanban board visualizes flow traces. Open with:

kyco gui

Then click on a finding to see the SOURCE → intermediate → SINK flow graph.