updates capa_explorer.py, enabling the user to choose b/w having bookmarks & comments. #2029

Atlas-64 · 2024-03-14T10:14:56Z

Updates capa_explorer.py to let users choose between adding bookmarks/comments when the script is executed. Uses the Ghidra's askChoices API to do so.

closes issue: #1977

Checklist

No CHANGELOG update needed

No new tests needed

No documentation update needed

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

CHANGELOG updated or no update needed, thanks! 😄

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

mike-hunhoff · 2024-03-15T15:31:59Z

@Atlas-64 thank you for your contribution! Let's get the lint errors fixed before we review. Have you followed the capa development installation steps? Specifically, these steps outline how to use pre-commit resolve linting issues locally. Please let us know here if you have/had issues running pre-commit locally. Also, please add an entry to CHANGELOG.md with a short description of the PR.

Atlas-64 · 2024-03-17T13:08:39Z

hi @mike-hunhoff i did follow the steps to install my version of capa (in editable mode) and the dependencies and then continued to run the pre commit command to see if it passes the linting issues but i cant seem to pinpoint what do we do to import askChoices for use in capa_ghidra() which is why it seems that on the ruff hook it throws me the following error :

i have tried going through the api documentation and even trying to run it in a seperately defined function where all the user i/o would take place (referencing it self for invoking everytime it runs the script) ,But i keep encountering that specific wall .
i think after fixing the imlementation of the askchoices api everything should work well, i can make a change to the changelog and run further ghidra specific tests and post it in this PR
any help steering the solve in the right direction would be appreciated . Thanks in advance

mike-hunhoff · 2024-03-18T14:36:42Z

hi @mike-hunhoff i did follow the steps to install my version of capa (in editable mode) and the dependencies and then continued to run the pre commit command to see if it passes the linting issues but i cant seem to pinpoint what do we do to import askChoices for use in capa_ghidra() which is why it seems that on the ruff hook it throws me the following error : i have tried going through the api documentation and even trying to run it in a seperately defined function where all the user i/o would take place (referencing it self for invoking everytime it runs the script) ,But i keep encountering that specific wall . i think after fixing the imlementation of the askchoices api everything should work well, i can make a change to the changelog and run further ghidra specific tests and post it in this PR any help steering the solve in the right direction would be appreciated . Thanks in advance

Thank you for your thorough explanation! You're encountering a side effect of the way Ghidrathon adds Ghidra FlatProgramAPI methods (e.g. askChoices) to the Python built-in scope. Linting tools including ruff complain because there is no explicit definition or import statement mapping to the method. Our current solution is to force our linters to ignore this specific linting error by adding the comment # type: ignore [name-defined] # noqa: F821 at the end of affected lines, e.g. the add_bookmark helper function found in capa_explorer.py.

CHANGELOG updated or no update needed, thanks! 😄

mike-hunhoff

Great work @Atlas-64 ! I've left comments for you to review. Please post any questions here and re-request my review when you're ready.

capa/ghidra/capa_explorer.py

mike-hunhoff · 2024-03-19T15:40:09Z

capa/ghidra/capa_explorer.py

+    if user_choice == "bookmarks":
+        for item in parse_json(capa_data):
+            item.bookmark_functions()
+    elif user_choice == "comments":
+        for item in parse_json(capa_data):
+            item.label_matches()
+    elif user_choice == "both":
+        for item in parse_json(capa_data):
+            item.bookmark_functions()
+            item.label_matches()
+    else:
+        pass


This script modifies a Ghidra database by adding:

new namespace named "capa" and corresponding namespace entries

pre/plate-comments

function bookmarks

We want our changes here to enable users to select any number of these options when running this script. Presently, the label_matches method creates the "capa" namespace, corresponding namespace entries, and pre/plate-comments. We need to modify the label_matches method to account for the user's selection and I'd recommend passing new boolean arguments to the label_matches method to implement this. Creating a new "capa" namespace and corresponding namespace entries should be grouped as one option, likewise with setting pre/plate-comments.

@mike-hunhoff

So just to clarify for the adding comments based on the user input, we want to just have a boolean default and pass an argument based on what the user wants in the function call within the if-else statement.

and, if I understand right you'd like separate options for creating the 'capa' namespace and setting pre/plate comments, even though the namespace might be used for comments. Is that correct?

Can you elaborate on the reasoning behind separate options? Is it for user flexibility or maybe workflow reasons?

Taking a step back, it may be easier to understand the requested changes by reviewing the README's UI integration section.

capa_explorer.py does three things:

Add Ghidra top-level namespace named "capa" that is viewable in Ghidra's Symbol Tree window

Add pre/plate comments that are viewable in Ghidra's Disassembly Listing and Decompiler windows

Add bookmarks that are viewable in Ghidra's Bookmarks window

We'd like to give user's an option to choose which of these three things are executed based on their needs/workflow. For example, a user may be interested in options 1 and 3 while not wanting 100s of comments added to their Ghidra database by option 2.

…64/capa into comments-bookmarks-option

mike-hunhoff · 2024-03-25T14:59:08Z

capa/ghidra/capa_explorer.py

    for item in parse_json(capa_data):
-        item.bookmark_functions()
-        item.label_matches()
+        item.bookmark_functions(bookmarks)


Let's simply not call bookmark_functions here if bookmarks is False.

mike-hunhoff · 2024-03-25T15:04:02Z

capa/ghidra/capa_explorer.py

@@ -137,84 +137,114 @@ def set_pre_comment(self, ghidra_addr, sub_type, description):
        else:
            return

-    def label_matches(self):
+    def label_matches(self, namespace=False, comments=False):


Let's split this into two functions, create_capa_namespace and create_capa_comments, that are only called if the corresponding bool values retrieved from the user are True.

mike-hunhoff · 2024-03-25T15:05:00Z

capa/ghidra/capa_explorer.py

-        item.bookmark_functions()
-        item.label_matches()
+        item.bookmark_functions(bookmarks)
+        item.label_matches(namespace, comments)


See my comment above about splitting this function in two.

…64/capa into comments-bookmarks-option

Atlas-64 · 2024-04-12T06:30:05Z

@mike-hunhoff sorry for the absence have been busy with school, I think I will try running the changed version and see if its working alright, and then move on to actually running the tests against it . Will post screenshots here of the results

adding options for choosing b/w bookmarks & comments

fe2a208

github-actions bot previously requested changes Mar 14, 2024

View reviewed changes

Atlas-64 added 3 commits March 14, 2024 15:55

trying to fix the lint issue

07fc637

trying to fix the lint issue

94c9ada

trying to fix the lint issue

e57ad9b

github-actions bot previously requested changes Mar 15, 2024

View reviewed changes

adding short description to Changelog

1ffa18c

Atlas-64 force-pushed the comments-bookmarks-option branch from 4afe1cc to 1ffa18c Compare March 19, 2024 12:57

Atlas-64 added 2 commits March 19, 2024 18:30

adding comment to bypass ruff hook

0491470

saved black hook formatting

e90b303

mike-hunhoff requested changes Mar 19, 2024

View reviewed changes

Atlas-64 changed the title ~~updates capa_explorer.py, enabling the user to choose b/w having bookmarks & comments or neither.~~ updates capa_explorer.py, enabling the user to choose b/w having bookmarks & comments. Mar 21, 2024

Atlas-64 added 5 commits March 21, 2024 23:43

Merge branch 'master' into comments-bookmarks-option

9e2984c

seperating namespace and comment functionality within label_matches

e7d67c1

Merge branch 'comments-bookmarks-option' of https://github.com/Atlas-…

b7c5267

…64/capa into comments-bookmarks-option

fixing flake8 linter violation

8cff831

Merge branch 'master' into comments-bookmarks-option

c71e1bf

Atlas-64 requested a review from mike-hunhoff March 24, 2024 11:43

mike-hunhoff requested changes Mar 25, 2024

View reviewed changes

Atlas-64 added 3 commits March 27, 2024 23:18

defining seperate namespace & comments functions

869c3bd

Merge branch 'comments-bookmarks-option' of https://github.com/Atlas-…

acee34e

…64/capa into comments-bookmarks-option

Merge branch 'master' into comments-bookmarks-option

f26a806

Atlas-64 requested a review from mike-hunhoff March 28, 2024 20:32

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

updates capa_explorer.py, enabling the user to choose b/w having bookmarks & comments. #2029

updates capa_explorer.py, enabling the user to choose b/w having bookmarks & comments. #2029

Atlas-64 commented Mar 14, 2024 •

edited

github-actions bot left a comment

github-actions bot left a comment

mike-hunhoff commented Mar 15, 2024 •

edited

Atlas-64 commented Mar 17, 2024

mike-hunhoff commented Mar 18, 2024 •

edited

mike-hunhoff left a comment

mike-hunhoff Mar 19, 2024

Atlas-64 Mar 21, 2024 •

edited

mike-hunhoff Mar 21, 2024

mike-hunhoff Mar 25, 2024

mike-hunhoff Mar 25, 2024 •

edited

mike-hunhoff Mar 25, 2024

Atlas-64 commented Apr 12, 2024 •

edited

updates capa_explorer.py, enabling the user to choose b/w having bookmarks & comments. #2029

Are you sure you want to change the base?

updates capa_explorer.py, enabling the user to choose b/w having bookmarks & comments. #2029

Conversation

Atlas-64 commented Mar 14, 2024 • edited

Checklist

github-actions bot left a comment

Choose a reason for hiding this comment

github-actions bot left a comment

Choose a reason for hiding this comment

mike-hunhoff commented Mar 15, 2024 • edited

Atlas-64 commented Mar 17, 2024

mike-hunhoff commented Mar 18, 2024 • edited

mike-hunhoff left a comment

Choose a reason for hiding this comment

mike-hunhoff Mar 19, 2024

Choose a reason for hiding this comment

Atlas-64 Mar 21, 2024 • edited

Choose a reason for hiding this comment

mike-hunhoff Mar 21, 2024

Choose a reason for hiding this comment

mike-hunhoff Mar 25, 2024

Choose a reason for hiding this comment

mike-hunhoff Mar 25, 2024 • edited

Choose a reason for hiding this comment

mike-hunhoff Mar 25, 2024

Choose a reason for hiding this comment

Atlas-64 commented Apr 12, 2024 • edited

Atlas-64 commented Mar 14, 2024 •

edited

mike-hunhoff commented Mar 15, 2024 •

edited

mike-hunhoff commented Mar 18, 2024 •

edited

Atlas-64 Mar 21, 2024 •

edited

mike-hunhoff Mar 25, 2024 •

edited

Atlas-64 commented Apr 12, 2024 •

edited