dataflow-analysis

Dataflow Analysis

Perform intra-procedural dataflow analysis to track how data flows within functions.

When to use

• Track if a function parameter flows to a function call argument
• Track if a function call's output flows to another function call's argument
• Find taint propagation paths (e.g., user input reaching dangerous functions)
• Detect vulnerabilities like command injection, buffer overflows

Instructions

Using the VulHunt MCP tools, open the project (open_project) and run the following Lua query (query_project).

To perform dataflow analysis, use project:calls_matching{}:

local calls = project:calls_matching({
  to = <target_call>,
  where = function(caller)
    return caller:named("<function_name>") and caller:has_call(<target_call>)
  end,
  using = {
    -- Annotate caller parameters
    parameters = {var:named "first_param", _},
    -- Annotate callees
    callees = {
      ["malloc"] = {inputs = {var:named "size"}}, 
      ["strlen"] = {output = var:named "len", inputs = {_}},
      ["check_len"] = {inputs = {var:sanitised()}}
    }
  }
})

local results = {}

for _, c in ipairs(calls) do
  local entry = {
    caller_name = c.caller.name,
    call_address = c.call_address,
  }

  if c.inputs[1] and c.inputs[1].annotation then
    entry.arg1_annotation = c.inputs[1].annotation
    entry.arg1_source = c.inputs[1].origin.source_address
  end

  if c.inputs[2] and c.inputs[2].annotation then
    entry.arg2_annotation = c.inputs[2].annotation
    entry.arg2_source = c.inputs[2].origin.source_address
  end

  if c.output then
    entry.return_annotation = c.output.annotation
  end

  table.insert(results, entry)
end

return results

Possible values for <target_call>:

• A string, e.g. "system"
• An AddressValue
  • VulHunt APIs return addresses as AddressValue instances
  • Create one with AddressValue.new(<hex_addr>) (e.g., <hex_addr> = 0x1234)
• A regex, e.g. {matching = "<regex>", kind = "symbol"}
• A byte pattern, e.g. {matching = "41544155", kind = "bytes"}

Inputs and output are of type OperandInfo (see operand-info.md). Origins are of type OperandOrigin (see operand-origin.md).

Annotations

• var:named "x" - Tags a variable with the name "x". This tag follows the data through the function, allowing later checks on where it ends up (e.g., which function argument it flows into).
• _ - Placeholder for variables that don't need to be tracked.
• var:sanitised() - Stops taint propagation when a tainted variable flows through that function argument.

The annotation set in using appears in c.inputs[N].annotation in the results. For example, if annotated with var:named "cmd", then c.inputs[1].annotation == "cmd" indicates the first argument came from that tracked variable.

Examples

Function parameter -> Function argument

Example 1: Buffer overflow via memcpy

C code snippet:

void vulnerable_function(int len, char *path) {
  char buffer[256];
  memcpy(buffer, path, len);
}

Lua query:

local calls = project:calls_matching{
  to = "memcpy",
  using = {
    parameters = {var:named "len", var:named "path"}
  }
}

local findings = {}
for _, call in ipairs(calls) do
  local len_src = call.inputs[3]
  local data_src = call.inputs[2]

  if (len_src ~= nil and len_src.annotation == "len") or
     (data_src ~= nil and data_src.annotation == "path") then
    table.insert(findings, {
      caller_address = tostring(call.caller_address),
      call_address = tostring(call.call_address),
    })
  end
end

return findings

Example 2: Command injection via snprintf -> system

C code snippet:

void vulnerable_function(char *cmd) {
  char buffer[256];

  snprintf(buffer, sizeof(buffer), "sh -c %s", cmd);
  system(buffer);
}

Lua query:

local calls = project:calls_matching{
  to = "system",
  where = function(caller)
    return caller:has_call("snprintf")
  end,
  using = {
    callees = {snprintf = {inputs = {var:named "cmd", _, _}}}
  }
}

local findings = {}
for _, call in ipairs(calls) do
  local src = call.inputs[1]

  if src ~= nil and src.annotation == "cmd" then
    table.insert(findings, {
      caller_address = tostring(call.caller_address),
      call_address = tostring(call.call_address),
    })
  end
end

return findings

Use cases

Command injection

Shell commands built from format strings

Find calls to system() where the argument was built using snprintf():

local calls = project:calls_matching{
  to = "system",  -- system(cmd)
  where = function(caller)
    return caller:has_call("snprintf") -- snprintf(cmd, ...)
  end,
  using = {
    callees = {snprintf = {inputs = {var:named "cmd", _, _}}}
  }
}

local findings = {}
for _, call in ipairs(calls) do
  local src = call.inputs[1]

  if src ~= nil and src.annotation == "cmd" then
    table.insert(findings, {
      snprintf_address = tostring(src.origin.source_address),
      caller_name = tostring(call.caller.name),
      caller_address = tostring(call.caller_address),
      call_address = tostring(call.call_address),
    })
  end
end

return findings

NOTE: Only change the propagated value if the source changes.

Returns a JSON object containing:

• snprintf_address is the address of the call site to snprintf
• caller_address is the address of the function that makes the call
• call_address is the address of the call site to system (the code block address where the call is made)

References

• calls-matching-param.md - Input format for calls_matching
• calls-matching-table.md - Structure of the returned table from calls_matching
• regex-matcher.md - Regex matching utilities

URLs to additional documentation pages are available at https://vulhunt.re/llm.txt

Related Skills

• functions (/functions) - Use this skill to find target functions by name, address, or pattern before performing dataflow analysis
• call-sites (/call-sites) - To find where functions are called without tracking data flow, use this simpler skill instead
• decompiler (/decompiler) - View decompiled code to understand function logic before setting up complex dataflow annotations