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.

gemini-code-assist · 2026-05-25T12:54:59Z

+    if backend == BACKEND_GHIDRA:
+        return {}
+
    if input_format in STATIC_FORMATS:


Disabling extractor filters for the Ghidra backend prevents users from using --restrict-to-functions. Since Ghidra is a static analysis backend, it should support these filters. Merging this with the static format check allows filters to be applied correctly for Ghidra regardless of the input format detection.

Suggested change

if backend == BACKEND_GHIDRA:

return {}

if input_format in STATIC_FORMATS:

if input_format in STATIC_FORMATS or backend == BACKEND_GHIDRA:

@saniyafatima07 thoughts here? I'd expect the Ghidra backend to handle function restrictions set by the user. Is there a reason we're skipping them?

I agree, Mike. Since Ghidra is a static-analysis backend, it should support function restrictions too. I had a slight misinterpretation while implementing this logic. I’ll correct it.

@saniyafatima07 this still needs to be addressed.

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.

mike-hunhoff · 2026-05-28T15:33:23Z

Great work splitting up the code into helper functions to keep things concise.

mike-hunhoff · 2026-05-28T16:05:32Z

+    if backend == BACKEND_GHIDRA:
+        return {}
+
    if input_format in STATIC_FORMATS:


@saniyafatima07 thoughts here? I'd expect the Ghidra backend to handle function restrictions set by the user. Is there a reason we're skipping them?

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.

mike-hunhoff · 2026-06-04T22:24:11Z

+        exctype_str = str(exctype)
+        # Give a targeted message when the Ghidra project DB is locked.
+        if "LockException" in exctype_str or "ghidra.framework.store.LockException" in exctype_str:
+            print(
+                f"Unexpected exception raised: {exctype}.\n It looks like the Ghidra project database is locked. "
+                "Please close the project in the Ghidra GUI (or other process) and try again. For details, run in debug mode (-d/--debug).",
+                file=sys.stderr,
+            )


This is very specific to Ghidra, so please move it closer to the Ghidra-specific code related to opening an existing project. Let's add a new exception type under capa.exceptions called LockedProjectDatabaseError that gracefully handles this case, and propagates the message accordingly. We should also consider trimming down the message, e.g. "Ghidra project database is locked. Ensure all programs accessing <database_name>.gpr are closed before proceeding."

Also, please add a new return value for this case:

capa/capa/main.py

Lines 116 to 132 in 33701d6

E_MISSING_RULES = 10

E_MISSING_FILE = 11

E_INVALID_RULE = 12

E_CORRUPT_FILE = 13

E_FILE_LIMITATION = 14

E_INVALID_SIG = 15

E_INVALID_FILE_TYPE = 16

E_INVALID_FILE_ARCH = 17

E_INVALID_FILE_OS = 18

E_UNSUPPORTED_IDA_VERSION = 19

E_UNSUPPORTED_GHIDRA_VERSION = 20

E_MISSING_CAPE_STATIC_ANALYSIS = 21

E_MISSING_CAPE_DYNAMIC_ANALYSIS = 22

E_EMPTY_REPORT = 23

E_UNSUPPORTED_GHIDRA_EXECUTION_MODE = 24

E_INVALID_INPUT_FORMAT = 25

E_INVALID_FEATURE_EXTRACTOR = 26

@saniyafatima07 this code can be removed now?

mike-hunhoff · 2026-06-04T22:25:28Z

+    if backend == BACKEND_GHIDRA:
+        return {}
+
    if input_format in STATIC_FORMATS:


@saniyafatima07 this still needs to be addressed.

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!

mike-hunhoff · 2026-06-05T17:58:09Z

            except Exception:
+                if program is not None:
+                    program.release(consumer)
                project_cm.__exit__(None, None, None)
-                tmpdir.cleanup()
+                if tmpdir:
+                    tmpdir.cleanup()
                raise


This is critical to preventing an error or exception from holding the database lock, so let's bump the robustness just a bit by isolating each step in a nested try/except:

except Exception: if program is not None: try: program.release(consumer) except Exception: logger.warning("failed to release program handle", exc_info=True) try: project_cm.__exit__(None, None, None) except Exception: logger.warning("failed to close Ghidra project", exc_info=True) if tmpdir: try: tmpdir.cleanup() except Exception: pass raise

One small thing to mention, I replaced the try/except/pass(tmpdir) with contextlib.suppress(Exception) to satisfy Ruff's SIM105 rule.

mike-hunhoff · 2026-06-05T17:58:34Z

+        exctype_str = str(exctype)
+        # Give a targeted message when the Ghidra project DB is locked.
+        if "LockException" in exctype_str or "ghidra.framework.store.LockException" in exctype_str:
+            print(
+                f"Unexpected exception raised: {exctype}.\n It looks like the Ghidra project database is locked. "
+                "Please close the project in the Ghidra GUI (or other process) and try again. For details, run in debug mode (-d/--debug).",
+                file=sys.stderr,
+            )


@saniyafatima07 this code can be removed now?

mike-hunhoff · 2026-06-05T18:03:47Z

+def get_extractor_filters_from_cli(args, input_format, backend: Optional[str] = None) -> FilterConfig:
    if not hasattr(args, "restrict_to_processes") and not hasattr(args, "restrict_to_functions"):
        # no processes or function filters were installed in the args
        return {}

-    if input_format in STATIC_FORMATS:
+    if input_format in STATIC_FORMATS or backend == BACKEND_GHIDRA:


To avoid adding Ghidra specific checks in this function, can we simply add the given FORMAT_ to the list of STATIC_FORMATS, similar to how FORMAT_BINJA_DB is handled for Binary Ninja? If so, let's remove the Ghidra specific check and revert the backend method argument.

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

Done @mike-hunhoff .
Could you please review?

Enhance ghidra backend with existing project feature

0a6b2eb

github-actions Bot previously requested changes May 25, 2026

View reviewed changes

gemini-code-assist Bot reviewed May 25, 2026

View reviewed changes

saniyafatima07 added 3 commits May 25, 2026 18:25

Merge branch 'master' into ghidra-feature-new

e568c00

Update changelog with new feature

d67d97c

Fix errors

8a032cc

Update documentation

c8ffff2

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

saniyafatima07 added 2 commits May 26, 2026 20:10

Minor fix

0f06fd1

Merge branch 'master' into ghidra-feature-new

ad1cd4a

mike-hunhoff requested changes May 28, 2026

View reviewed changes

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

saniyafatima07 added 5 commits May 28, 2026 22:04

Merge branch 'master' into ghidra-feature-new

36ea4bc

Fix: Changelog and doc

d7060fa

Fix: Formatting issues

23058f4

Handle cleanup during exception

a4cf712

Add additional logs for lock exception handling

4e694c8

saniyafatima07 mentioned this pull request May 29, 2026

Enhance ghidra backend with existing project feature #3066

Closed

4 tasks

Fix: import assert_never error

a2a3fc2

mike-hunhoff requested changes Jun 4, 2026

View reviewed changes

saniyafatima07 added 2 commits June 5, 2026 18:41

Merge branch 'master' into ghidra-feature-new

d8233ac

Add exception and new return value

53eea29

mike-hunhoff requested changes Jun 5, 2026

View reviewed changes

Improve cleanup, add ghidra to static format

ae95ab9

	E_MISSING_RULES = 10
	E_MISSING_FILE = 11
	E_INVALID_RULE = 12
	E_CORRUPT_FILE = 13
	E_FILE_LIMITATION = 14
	E_INVALID_SIG = 15
	E_INVALID_FILE_TYPE = 16
	E_INVALID_FILE_ARCH = 17
	E_INVALID_FILE_OS = 18
	E_UNSUPPORTED_IDA_VERSION = 19
	E_UNSUPPORTED_GHIDRA_VERSION = 20
	E_MISSING_CAPE_STATIC_ANALYSIS = 21
	E_MISSING_CAPE_DYNAMIC_ANALYSIS = 22
	E_EMPTY_REPORT = 23
	E_UNSUPPORTED_GHIDRA_EXECUTION_MODE = 24
	E_INVALID_INPUT_FORMAT = 25
	E_INVALID_FEATURE_EXTRACTOR = 26

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!

gemini-code-assist Bot May 25, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

saniyafatima07 commented May 25, 2026

Uh oh!

mike-hunhoff left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

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!

mike-hunhoff Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

saniyafatima07 commented Jun 5, 2026

Uh oh!

mike-hunhoff left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

saniyafatima07 commented Jun 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

saniyafatima07 commented May 25, 2026 •

edited

Loading

mike-hunhoff Jun 4, 2026 •

edited

Loading