Enhance ghidra backend with existing project feature by saniyafatima07 · Pull Request #3087 · mandiant/capa

saniyafatima07 · 2026-05-25T12:53:24Z

This PR adds support for analyzing existing Ghidra projects directly using .gpr project input.

Users can now provide input in the format:

capa /path/to/project.gpr

For multi-program projects:

CAPA_GHIDRA_PROGRAM_PATH=/folder/program capa /path/to/project.gpr

Motivation & Context

Currently, the Ghidra backend always creates a temporary project and re-imports the binary. This:

increases analysis time
ignores previously analyzed projects and annotations
duplicates existing analysis work

This change enables reuse of existing analyzed Ghidra projects while keeping the implementation localized to the Ghidra backend with minimal architecture changes.

Implementation Details

Added automatic .gpr detection to select the Ghidra backend when a Ghidra project file is provided as input.
Added recursive Ghidra project file enumeration using domain_file.getPathname() to discover programs within the project.
Added automatic program selection for single-program projects.
Added CAPA_GHIDRA_PROGRAM_PATH support for selecting the target program in multi-program projects.
Added informative error handling that lists available project program paths when disambiguation is required.
Updated Ghidra loader flow to:
- open existing projects using create=False
- reuse already analyzed programs via consume_program
- skip temporary project creation/import flow for .gpr input
Default behavior remains unchanged for non-.gpr inputs.

Tests

Added tests for:

automatic Ghidra backend selection for .gpr input
skipping generic file extractor probing for Ghidra project input

Closes #3004

Checklist

CHANGELOG updated
Added few tests
Documentation updated
This submission includes AI-generated code and I have provided details in the description.

Parts of this implementation were assisted using AI tools (Github Copilot, ChatGPT).
AI was used for:

refining implementation approach
improving edge case handling

All code was reviewed, modified and tested manually before submission.

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

Code Review

This pull request introduces support for Ghidra projects (.gpr files) by adding utilities to navigate Ghidra project structures and updating the loader to handle project-based analysis. The changes include automatic backend detection for Ghidra projects and updated CLI logic to skip generic file extraction when a project is provided. Review feedback highlights the need for better terminal formatting in error messages, improved resource management to prevent program leaks during exceptions, and the enablement of function filters for the Ghidra backend.

CHANGELOG updated or no update needed, thanks! 😄

saniyafatima07 · 2026-05-25T13:42:29Z

@mike-hunhoff
I have tried implementing this feature with the new approach as per the discussion in #3066 .
Could you please review it?
Thank you for your time!

mike-hunhoff

Great work @saniyafatima07 ! I left comments for your review. I'll do some more thinking on how to best handle the .gpr tests in the meantime.

saniyafatima07 · 2026-05-28T18:26:38Z

Great work @saniyafatima07 ! I left comments for your review. I'll do some more thinking on how to best handle the .gpr tests in the meantime.

Thank you for the review Mike.
I will address all the comments.
Sure.

saniyafatima07 · 2026-06-01T14:35:41Z

@mike-hunhoff @larchchen @Maijin I have made all the requested changes.
Could you please review it?

mike-hunhoff

Thank you @saniyafatima07 ! I've left comments for your review.

saniyafatima07 · 2026-06-05T14:16:04Z

Thank you for the review @mike-hunhoff . I have addressed all the requested changes.

mike-hunhoff

Thanks @saniyafatima07 , I've left comments for your review!

saniyafatima07 · 2026-06-06T11:20:44Z

Done @mike-hunhoff .
Could you please review?

mike-hunhoff

Thanks @saniyafatima07 ! I've left additional comments for your review.

mike-hunhoff · 2026-06-22T20:43:28Z

Let's remove these for now. We can add in a more robust test for this specific feature if it becomes a problem in the future.

saniyafatima07 · 2026-06-23T20:25:14Z

Thank you for the review @mike-hunhoff . I have addressed all the requested changes.

mike-hunhoff

Thank you again for the changes @saniyafatima07 . I think we're almost there, I've left a few comments for your review. Also, please resolve all merge conflicts and close the corresonding .gpr capa-testfiles pull request before requesting another review.

mike-hunhoff · 2026-07-24T19:21:45Z

+                program, consumer = pyghidra.consume_program(project, program_path)

                # Analyze
                pyghidra.analyze(program, monitor)


I noticed that analyzing an existing .gpr project currently takes just as long as running capa on a raw binary file. pyghidra.analyze(program, monitor) is called unconditionally even when loading a .gpr project. This forces Ghidra to re-run auto-analysis on an already-analyzed binary. Skip calling pyghidra.analyze when opening .gpr files:

mike-hunhoff · 2026-07-24T19:25:11Z



-def get_sample_path_from_cli(args, backend: str) -> Optional[Path]:
+def get_sample_path_from_cli(args, input_format, backend) -> Optional[Path]:


Can we remove input_format and check backend instead?

Or is there something else that can be done to avoid changing the arguments?

mike-hunhoff · 2026-07-24T19:25:21Z



-def get_os_from_cli(args, backend) -> str:
+def get_os_from_cli(args, input_format, backend) -> str:


Can we remove input_format and check backend instead?

Or is there something else that can be done to avoid changing the arguments?

github-actions Bot previously requested changes May 25, 2026

View reviewed changes

gemini-code-assist Bot reviewed May 25, 2026

View reviewed changes

Comment thread capa/ghidra/helpers.py

Comment thread capa/ghidra/helpers.py

Comment thread capa/loader.py

Comment thread capa/loader.py

Comment thread capa/main.py Outdated

saniyafatima07 marked this pull request as ready for review May 25, 2026 13:42

saniyafatima07 mentioned this pull request May 26, 2026

Add sample.gpr mandiant/capa-testfiles#312

Open

mike-hunhoff requested changes May 28, 2026

View reviewed changes

Comment thread capa/ghidra/helpers.py

Comment thread capa/loader.py

Comment thread capa/loader.py

Comment thread capa/main.py Outdated

Comment thread doc/usage.md Outdated

Comment thread CHANGELOG.md Outdated

Comment thread capa/ghidra/helpers.py Outdated

mike-hunhoff requested a review from a team May 28, 2026 16:27

saniyafatima07 mentioned this pull request May 29, 2026

Enhance ghidra backend with existing project feature #3066

Closed

4 tasks

mike-hunhoff requested changes Jun 4, 2026

View reviewed changes

Comment thread capa/main.py Outdated

Comment thread capa/main.py Outdated

mike-hunhoff requested changes Jun 5, 2026

View reviewed changes

Comment thread capa/loader.py

Comment thread capa/main.py Outdated

Comment thread capa/main.py Outdated

mike-hunhoff requested changes Jun 22, 2026

View reviewed changes

saniyafatima07 added 13 commits June 24, 2026 01:03

Enhance ghidra backend with existing project feature

6669204

Update changelog with new feature

b388cb1

Fix errors

1525906

Update documentation

957b854

Minor fix

45fbf0b

Fix: Changelog and doc

9338532

Fix: Formatting issues

c58bb2b

Handle cleanup during exception

9f7ee5a

Add additional logs for lock exception handling

58f211f

Fix: import assert_never error

c4b5ab5

Add exception and new return value

b8622c9

Improve cleanup, add ghidra to static format

ef70aa8

Address comments

4ba5dd7

saniyafatima07 force-pushed the ghidra-feature-new branch from 031ed53 to 4ba5dd7 Compare June 23, 2026 19:37

Update tests data submodule

5ee451b

mike-hunhoff requested changes Jul 24, 2026

View reviewed changes



		def get_sample_path_from_cli(args, backend: str) -> Optional[Path]:
		def get_sample_path_from_cli(args, input_format, backend) -> Optional[Path]:



		def get_os_from_cli(args, backend) -> str:
		def get_os_from_cli(args, input_format, backend) -> str:

Uh oh!

Conversation

saniyafatima07 commented May 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation & Context

Implementation Details

Tests

Checklist

Uh oh!

github-actions Bot left a comment

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

saniyafatima07 commented May 25, 2026

Uh oh!

mike-hunhoff left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

saniyafatima07 commented May 28, 2026

Uh oh!

saniyafatima07 commented Jun 1, 2026

Uh oh!

mike-hunhoff left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

saniyafatima07 commented Jun 5, 2026

Uh oh!

mike-hunhoff left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

saniyafatima07 commented Jun 6, 2026

Uh oh!

mike-hunhoff left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mike-hunhoff Jun 22, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

saniyafatima07 commented Jun 23, 2026

Uh oh!

mike-hunhoff left a comment

Choose a reason for hiding this comment

Uh oh!

mike-hunhoff Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

mike-hunhoff Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

mike-hunhoff Jul 24, 2026

Choose a reason for hiding this comment

Uh oh!

mike-hunhoff Jul 24, 2026

saniyafatima07 commented May 25, 2026 •

edited

Loading