Skip to content

move function-name feature matching to insn scope #3125

Open

Description

@mike-hunhoff

function-name features presently match at file scope which prevents detection like "function A calls function-name C then function-name D". Changing function-name features to match at the insn scope would also align with api matching.

Activity

  1. williballenthin commented on Jul 14, 2026

    @williballenthin
    Collaborator

    today we coerce recognized called names into api features. for example, when flirt matches, we use the recovered name as an api feature. is this sufficient for you?

    i thought that maybe we already emit function-name at function scope to indicate the name of the current function, so we could say "strcpy that calls GetProcAddress" but our documentation doesn't mention it.

    can you walk through your idea a little more?

  2. mike-hunhoff commented on Jul 15, 2026

    @mike-hunhoff
    CollaboratorAuthor

    For context, I submitted this issue on behalf of another. Their goal is to isolate functions in large binaries where the binaries contain mostly statically linked code. e.g., function A downloads a payload and decrypts it, where the decryption function is statically linked and therefore, AFAIK, can only be matched using the function-name feature, if extracted. However, since function-name features are file scoped, capa does not currently support this goal.

    today we coerce recognized called names into api features.

    Can you explain this more? Is this something handled by capa core? Or is it the responsibility of the extractors to emit both api and function-name features for recovered names? e.g., the BinExport feature extractor only emits function-name features:

    if vertex.HasField("mangled_name"):
    yield FunctionName(vertex.mangled_name), fh.address

  3. abhinav-phi commented on Jul 15, 2026

    @abhinav-phi
  4. williballenthin commented on Jul 15, 2026

    @williballenthin
    Collaborator

    can you explain it more

    yield API(name), ih.address

    here we take the recognized name of a callee, such as via FLIRT, and emit it as an API feature.

  5. williballenthin commented on Jul 15, 2026

    @williballenthin
    Collaborator

    e.g., the BinExport feature extractor only emits function-name features

    ah, this is just what i was looking for! note that this feature is emitted at function scope. it is meant to convey: "we believe the name of this function is 'foo'". it is not meant to indicate one function calls another - that is the API feature.

    (we need to update the capa rules doc to explain this case, and clarify this consideration).

  6. williballenthin commented on Jul 15, 2026

    @williballenthin
    Collaborator

    Is this something handled by capa core? Or is it the responsibility of the extractors to emit both api and function-name features for recovered names?

    It's the responsibility of the extractor to emit API features if it knows the name of callees. capa core doesn't do any magic to map callee names or interpret the call graph.

  7. mike-hunhoff commented on Jul 16, 2026

    @mike-hunhoff
    CollaboratorAuthor

    can you explain it more

    capa/capa/features/extractors/ida/insn.py

    Line 135 in 30f9378

    yield API(name), ih.address
    here we take the recognized name of a callee, such as via FLIRT, and emit it as an API feature.

    Hmmm so it looks like the IDA feature extractor is already emitting function-name features at the instruction scope

    for altname in capa.features.extractors.ida.helpers.get_function_alternative_names(target_func.start_ea):
    yield FunctionName(altname), ih.address
    yield API(altname), ih.address

  8. mike-hunhoff commented on Jul 16, 2026

    @mike-hunhoff
    CollaboratorAuthor

    e.g., the BinExport feature extractor only emits function-name features

    ah, this is just what i was looking for! note that this feature is emitted at function scope. it is meant to convey: "we believe the name of this function is 'foo'". it is not meant to indicate one function calls another - that is the API feature.

    (we need to update the capa rules doc to explain this case, and clarify this consideration).

    Agreed, we need to update the documentation to convey the intention of function-name features and how they differ from api features. We'll then likely need to update the extractors to follow what is documented.

  9. williballenthin commented on Jul 16, 2026

    @williballenthin
    Collaborator

    Hmmm so it looks like the IDA feature extractor is already emitting function-name features at the instruction scope

    hm yeah that seems like a bug. maybe a copy paste issue?

  10. williballenthin commented on Jul 16, 2026

    @williballenthin
    Collaborator

    @mike-hunhoff do you think API features let you do what you want? or do we still need to extend the behavior in another way?

  11. mike-hunhoff commented on Jul 24, 2026

    @mike-hunhoff
    CollaboratorAuthor

    @williballenthin yes, API features would satisfy this requirement.

    Here is my understanding of next steps (let me know if I'm missing anything):

    • Review extractors to ensure API features are emitted for recovered function names (FLIRT, meta, etc.) at instruction scope
    • Review extractors to ensure function name features are emitted only at >= function scope
    • Update function name / API feature documentation to highlight intention/difference
  12. williballenthin commented on Jul 24, 2026

    @williballenthin
    Collaborator
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions