add-function-scope-call-chain-matching-across-call-graph

[akshat4703]

Summary

Add support for call-chain rules that allow capa to detect behaviors
spread across multiple functions.

This PR introduces a new feature type that enables rules to match ordered
sequences of APIs across function boundaries using the program call graph.
This allows capa to detect multi-stage behaviors that are implemented across
several functions.

Example rule syntax:

features:

• call-chain:
  • api: CryptDecrypt
  • api: connect
  • api: CreateProcessA

Motivation

Many malware capabilities are implemented across multiple functions.
For example, one function may decrypt data, another establish a network
connection, and a third execute a command. Individually these functions
may not trigger meaningful rules, but together they represent a clear
malicious capability.

This change enables capa rules to express such multi-function behavior
using ordered API sequences derived from the function call graph.

Implementation

This PR introduces the following changes:

Call-chain feature support

• Added a new CallChain feature type.
• Implemented a corresponding engine statement to evaluate ordered API sequences.

Call graph construction

• Built a function call graph during static analysis.
• Caller → callee relationships are extracted and stored for use in capability matching.

Call-chain resolution pipeline

The static capabilities pipeline is extended to:

1. Precompute function features
2. Build a function call graph
3. Resolve call-chain sequences across reachable functions
4. Inject resolved call-chain features into function feature sets
5. Run function-scope rule matching

This allows call-chain features to integrate naturally with existing
function-scope matching logic.

Rule Syntax

Example rule:

features:

• call-chain:
  • api: CryptDecrypt
  • api: connect
  • api: CreateProcessA

This rule matches when the ordered API sequence appears across
reachable functions in the call graph.

Files Changed

Core changes:

• capa/features/extractors/function.py (new)
• capa/features/common.py
• capa/engine.py
• capa/rules/init.py
• capa/capabilities/static.py

Tests:

• tests/test_call_chain.py (new)
• tests/test_engine.py
• tests/test_rules.py

Validation

Executed the following test suite:

PYTHONPATH=. ./venv/bin/pytest -q
tests/test_engine.py
tests/test_rules.py
tests/test_call_chain.py
tests/test_capabilities.py

Result:

67 passed

Notes

The implementation integrates with the existing capa rule engine and
feature extraction pipeline without modifying existing rule behavior.

This change enables richer behavioral detection by allowing rules to
capture multi-function workflows present in real-world malware.

[github-actions]

Please add bug fixes, new features, breaking changes and anything else you think is worthwhile mentioning to the master (unreleased) section of CHANGELOG.md. If no CHANGELOG update is needed add the following to the PR description: [x] No CHANGELOG update needed

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances capa's capability to identify complex malicious behaviors by introducing "call-chain" rules. These rules allow analysts to define and detect sequences of API calls that occur across different functions within a program, leveraging the function call graph. This enables the detection of multi-stage attacks or sophisticated malware techniques that would be difficult to capture with single-function rules, thereby improving the accuracy and depth of threat intelligence.

Highlights

• Introduced Call-Chain Rules: Added support for a new "call-chain" feature type, enabling rules to detect ordered sequences of API calls across multiple functions using the program's call graph.
• Call Graph Construction: Implemented functionality to build a function call graph during static analysis, capturing caller-callee relationships.
• Extended Static Capabilities Pipeline: Modified the analysis pipeline to precompute function features, construct the call graph, resolve call-chain sequences, and inject these as features for function-scope rule matching.
• New Engine Statement and Feature Type: Implemented a "CallChain" engine statement and a corresponding "CallChain" feature type to represent and evaluate these multi-function behaviors.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• capa/capabilities/static.py
  • Updated imports to include Iterator, capa.engine, Feature, and function_extractor.
  • Refactored CodeCapabilities to store raw function_features instead of function_matches.
  • Introduced iter_call_chain_feature_sequences to extract call-chain definitions from rules.
  • Modified find_static_capabilities to collect function features, build a call graph, resolve call-chain features, and then apply function-scope rules.
• capa/engine.py
  • Added CallChain class, a new Statement type for matching ordered feature sequences across function calls.
• capa/features/common.py
  • Expanded Feature's value type to support tuples, accommodating call-chain sequences.
  • Improved Feature comparison (lt) with a fallback for features without freeze support.
  • Defined a new CallChain feature type to encapsulate ordered sequences of other features.
• capa/features/extractors/function.py
  • Added new file to manage function-level feature extraction related to call graphs.
  • Implemented build_function_call_graph to construct a call graph from function features.
  • Provided find_call_chain_starts to locate functions initiating a specific call chain.
  • Developed add_call_chain_features to inject resolved call-chain features into function feature sets.
• capa/rules/init.py
  • Registered CallChain as a valid feature within the FUNCTION scope.
  • Extended rule parsing logic to support the call-chain keyword, including validation for its structure and content.
  • Assigned a high scoring priority to CallChain features for rule indexing.
• tests/test_call_chain.py
  • Added new file containing tests for the call-chain functionality.
  • Included MockCallChainExtractor to simulate a program's call graph and API calls.
  • Verified that a call-chain rule correctly identifies a sequence of API calls across mocked functions.
• tests/test_engine.py
  • Updated imports to include CallChain engine statement and CallChain feature.
  • Added a test case to confirm the correct evaluation of the CallChain engine statement.
• tests/test_rules.py
  • Added a test to ensure call-chain rules are correctly parsed from YAML definitions.

Activity

• The author executed a comprehensive test suite including test_engine.py, test_rules.py, test_call_chain.py, and test_capabilities.py, with all 67 tests passing.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

CHANGELOG updated or no update needed, thanks! 😄

[gemini-code-assist]

Code Review

This pull request introduces support for call-chain rules to detect behaviors spanning multiple functions. The implementation is well-structured, involving a two-pass analysis for static capabilities, a new CallChain feature and statement type, and logic for building a call graph and resolving call chains. The changes are accompanied by good tests. I've found one critical issue related to a merge conflict marker and one suggestion for improving type hints for better maintainability.

[williballenthin]

we're not going to consider major features like this without prior planning and research.