reverse-engineering-assistant 2.9.1__tar.gz → 2.9.2__tar.gz

{reverse_engineering_assistant-2.9.1 → reverse_engineering_assistant-2.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: reverse-engineering-assistant
-Version: 2.9.1
+Version: 2.9.2
 Summary: An AI assistant for reverse engineering tasks
 Author: サイバーカイダ (cyberkaida)
 Classifier: License :: OSI Approved :: Apache Software License
@@ -11,6 +11,7 @@ Description-Content-Type: text/markdown
 Requires-Dist: langchain
 Requires-Dist: langchain-core
 Requires-Dist: langchain-openai
+Requires-Dist: langchain-community
 Requires-Dist: prompt_toolkit
 Requires-Dist: sentence_transformers
 Requires-Dist: PyYAML
@@ -18,6 +19,7 @@ Requires-Dist: pydantic
 Requires-Dist: rich
 Requires-Dist: grpcio
 Requires-Dist: protobuf
+Requires-Dist: flask
 
 # ReVA - Reverse Engineering Assistant
 
@@ -46,13 +48,14 @@ information from the tools, but when there is no information it can still respon
 questions from its training.
 
 You can ask questions like:
+- What are the interesting strings in this program?
 - Does this program use encryption? Write a markdown report on the encryption and where it is used.
 - Draw a class diagram using plantuml syntax.
 - Start from main, examine the program in detail. Rename variables as you go and provide a summary of the program.
 - Explain the purpose of the `__mod_init` segment.
 - What does `mmap` return?
 - What does the function at address 0x80000 do?
-- This is a CTF problem. Start at main, examine the program in detail and write a pwntools script to get the flag.
+- This is a CTF problem. Write a pwntools script to get the flag.
 
 An important part of reverse engineering is the process. Many other tools simply ask a single question of the LLM,
 this means it is difficult to determine _why_ a thing happened. In ReVa we break all actions down into small parts
@@ -68,33 +71,40 @@ Built in support is provided for:
 - [OpenAI](https://platform.openai.com/overview) for online inference and easy setup (Needs an OpenAI API key)
 - [Ollama](https://ollama.ai) and any model it supports for local on-device inference or connecting to a self hosted remote inference server.
 
+See [Configuration](#configuration) for more information about settings for the providers.
+
 Adding additional inference servers is easy if it is supported by langchain.
 
 ## Configuration
 
-> This is currently being moved to the Ghidra GUI
-> See Edit -> Tool Options -> ReVa in the Codebrowser Tool
+Configuration for ReVa is in the CodeBrowser Tool options.
+Open a program and go to Edit -> Tool Options -> ReVa.
+
+There are options for:
+- Selecting a provider (OpenAI or Ollama, others coming soon!)
+- Enabling "Follow", this will move the Ghidra view to the location of
+things ReVa is examining or changing.
+- Enabling "Auto-allow", ReVa will log her actions for the user to accept
+in the "ReVa Actions Log" window.
+
+There are sections for the providers.
+
+### OpenAI
 
-Configuration for the reverse engineering assistant is stored at
-`~/.config/reverse-engineering-assistant/config.yaml`. If this
-is not present on first start, a default configuration using
-OpenAI for inference and the `OPENAI_API_TOKEN` environment
-variable will be used.
+By default, the OpenAI key is loaded from the environment variable `OPENAI_API_KEY`. You can also set your key inside Ghidra. Setting the key back to the `OPENAI_API_KEY` value will clear the key from the Ghidra configuration and load it from the environment.
 
-The most important setting is the `type` top level setting.
-This controls what inference service you use. These are the
-same as the configuration keys, for example to use Ollama,
-set type to `ollama` and configure the settings in the `ollama:`
-section.
+You can also select the model. By default `gpt-4o` is selected. This model works best with the tools and the prompt provided by ReVa.
 
-The configuration also contains the prompts used for the models.
-If you use Ollama or OpenAI these will be processed to fit the
-model specific prompt pattern (placing the system prompt in the
-correct tags, etc).
+`gpt-4` also works well, but is slow and needs more prompting by the user to explore a binary.
 
-For `llama-cpp` and `text-generation-webui` these may need to be
-configured for your specific model. For this reason Ollama is
-preferred for self hosting.
+### Ollama
+
+Ollama is a local inference server. The default server is set to localhost, with the default Ollama port. You can change this to a remote server if you want to perform inference on a remote machine. This is useful for organisations that self host.
+
+You can also select a model. The model must alread be loaded on the server. Good performance has been seen with:
+- `mixtral`
+- `llama3`
+- `phi`
 
 ## Workflow
 
@@ -112,24 +122,41 @@ If you have more than one Ghidra open, you can select the right one with
 `reva-chat --project ${project-name}`, if it is not set, `reva-chat` will
 ask you which project you want to connect to.
 
-## Installation
+## Protocol Build
 
-First install the python component, I like to use `pipx`. It is best to make
-sure that `reva-server` and `reva-chat` are on your path.
-The Ghidra extension will need to start `reva-server`, and you will need to
-run `reva-chat`.
+To communicate between `reva-server` and the extension, [gRPC](https://grpc.io) is used. You can read more about that (here)[./DEVELOPER.md]. Building the source files from those protocol definitions is driven from the [Makefile](/Makefile). To build the protocol source code files, run this command in the project's root:
 
-To install the particular extension for your disassembler see:
-- [Ghidra Support](#ghidra-support)
+```sh
+make protocol
+```
 
-The chat can be started with:
+## Python Project (reva-server and reva-chat) Installation
+
+First install the python component, I like to use `pipx`. Install it with something like:
 
 ```sh
-reva-chat
+pip install pipx
 ```
 
-> You can also configure the path to `reva-server` in `Edit -> Tool Options -> ReVa`
-> if it is not on your path. But you really should put it on your path!
+In the `reverse-engineering-assistant` folder, run:
+
+```sh
+pipx install .
+```
+
+After installing the python project, pipx may warn you that you need to add a folder to your PATH environment variable. Make sure that the folder (now containing `reva-server` and `reva-chat`) are in your PATH variable. pipx can do it for you with this command:
+
+```sh
+pipx ensurepath
+```
+
+The extension will need to start `reva-server`, and you will need to run `reva-chat`. In case you do not want to add them to your PATH, see the [Configuration](#configuration) section for how to set the path to the executables.
+
+Once the `reva-server` has been started by the extension the chat can be started with:
+
+```sh
+reva-chat
+```
 
 # Ghidra Support
 
@@ -139,12 +166,16 @@ reva-chat
 
 Follow the instructions in the [ghidra-assistant](ghidra-assistant/README.md) plugin.
 
-After installation, enable the `ReVaPlugin` extension in the CodeBrowser tool (Open a file and click: File -> Configure -> Miscellaneous).
+After installation, enable the `ReVa Plugin` extension in the CodeBrowser tool (Open a file and click: File -> Configure -> Miscellaneous).
 
 If you want ReVa enabled by default, click File -> Save Tool to save the configuration.
 
 If everything is working correctly you will see a ReVa menu on your menu bar.
 
+## Configuration
+
+You can modify the plugin configuration in `Edit -> Tool Options -> ReVa`.
+
 ## Undo
 
 Whenever ReVa performs an action it will create an undo point for each action. If ReVa renames 5 variables, this will be
@@ -152,9 +183,17 @@ one undo.
 
 ## Menus
 
-> These are being added in the next release
+ReVa adds an option to the CodeBrowser Tool's Window menu.
+Select Window -> ReVa Action Log to open the ReVa Action Log window.
+
+This window shows actions ReVa has performed and would like to perform.
+You can accept or reject a change by double clicking the ✅ or ❌ icon. You can also go to the location the action will be performed by double clicking the address.
+
+If you reject an action, ReVa will be told and she will move on.
+
+You can also enable "Auto-allow" in the ReVa options. This will automatically accept all actions ReVa wants to perform.
 
-ReVa adds some elements to the Ghidra UI. You can either ask ReVa to do something in the chat window,
+ReVa also adds some elements to the Ghidra UI. You can either ask ReVa to do something in the chat window,
 "Examine the variable usage in `main` in detail, rename the variables with more descriptive names.",
 or use the menu system.
 

{reverse_engineering_assistant-2.9.1 → reverse_engineering_assistant-2.9.2}/README.md

@@ -25,13 +25,14 @@ information from the tools, but when there is no information it can still respon
 questions from its training.
 
 You can ask questions like:
+- What are the interesting strings in this program?
 - Does this program use encryption? Write a markdown report on the encryption and where it is used.
 - Draw a class diagram using plantuml syntax.
 - Start from main, examine the program in detail. Rename variables as you go and provide a summary of the program.
 - Explain the purpose of the `__mod_init` segment.
 - What does `mmap` return?
 - What does the function at address 0x80000 do?
-- This is a CTF problem. Start at main, examine the program in detail and write a pwntools script to get the flag.
+- This is a CTF problem. Write a pwntools script to get the flag.
 
 An important part of reverse engineering is the process. Many other tools simply ask a single question of the LLM,
 this means it is difficult to determine _why_ a thing happened. In ReVa we break all actions down into small parts
@@ -47,33 +48,40 @@ Built in support is provided for:
 - [OpenAI](https://platform.openai.com/overview) for online inference and easy setup (Needs an OpenAI API key)
 - [Ollama](https://ollama.ai) and any model it supports for local on-device inference or connecting to a self hosted remote inference server.
 
+See [Configuration](#configuration) for more information about settings for the providers.
+
 Adding additional inference servers is easy if it is supported by langchain.
 
 ## Configuration
 
-> This is currently being moved to the Ghidra GUI
-> See Edit -> Tool Options -> ReVa in the Codebrowser Tool
+Configuration for ReVa is in the CodeBrowser Tool options.
+Open a program and go to Edit -> Tool Options -> ReVa.
+
+There are options for:
+- Selecting a provider (OpenAI or Ollama, others coming soon!)
+- Enabling "Follow", this will move the Ghidra view to the location of
+things ReVa is examining or changing.
+- Enabling "Auto-allow", ReVa will log her actions for the user to accept
+in the "ReVa Actions Log" window.
+
+There are sections for the providers.
+
+### OpenAI
 
-Configuration for the reverse engineering assistant is stored at
-`~/.config/reverse-engineering-assistant/config.yaml`. If this
-is not present on first start, a default configuration using
-OpenAI for inference and the `OPENAI_API_TOKEN` environment
-variable will be used.
+By default, the OpenAI key is loaded from the environment variable `OPENAI_API_KEY`. You can also set your key inside Ghidra. Setting the key back to the `OPENAI_API_KEY` value will clear the key from the Ghidra configuration and load it from the environment.
 
-The most important setting is the `type` top level setting.
-This controls what inference service you use. These are the
-same as the configuration keys, for example to use Ollama,
-set type to `ollama` and configure the settings in the `ollama:`
-section.
+You can also select the model. By default `gpt-4o` is selected. This model works best with the tools and the prompt provided by ReVa.
 
-The configuration also contains the prompts used for the models.
-If you use Ollama or OpenAI these will be processed to fit the
-model specific prompt pattern (placing the system prompt in the
-correct tags, etc).
+`gpt-4` also works well, but is slow and needs more prompting by the user to explore a binary.
 
-For `llama-cpp` and `text-generation-webui` these may need to be
-configured for your specific model. For this reason Ollama is
-preferred for self hosting.
+### Ollama
+
+Ollama is a local inference server. The default server is set to localhost, with the default Ollama port. You can change this to a remote server if you want to perform inference on a remote machine. This is useful for organisations that self host.
+
+You can also select a model. The model must alread be loaded on the server. Good performance has been seen with:
+- `mixtral`
+- `llama3`
+- `phi`
 
 ## Workflow
 
@@ -91,24 +99,41 @@ If you have more than one Ghidra open, you can select the right one with
 `reva-chat --project ${project-name}`, if it is not set, `reva-chat` will
 ask you which project you want to connect to.
 
-## Installation
+## Protocol Build
 
-First install the python component, I like to use `pipx`. It is best to make
-sure that `reva-server` and `reva-chat` are on your path.
-The Ghidra extension will need to start `reva-server`, and you will need to
-run `reva-chat`.
+To communicate between `reva-server` and the extension, [gRPC](https://grpc.io) is used. You can read more about that (here)[./DEVELOPER.md]. Building the source files from those protocol definitions is driven from the [Makefile](/Makefile). To build the protocol source code files, run this command in the project's root:
 
-To install the particular extension for your disassembler see:
-- [Ghidra Support](#ghidra-support)
+```sh
+make protocol
+```
 
-The chat can be started with:
+## Python Project (reva-server and reva-chat) Installation
+
+First install the python component, I like to use `pipx`. Install it with something like:
 
 ```sh
-reva-chat
+pip install pipx
 ```
 
-> You can also configure the path to `reva-server` in `Edit -> Tool Options -> ReVa`
-> if it is not on your path. But you really should put it on your path!
+In the `reverse-engineering-assistant` folder, run:
+
+```sh
+pipx install .
+```
+
+After installing the python project, pipx may warn you that you need to add a folder to your PATH environment variable. Make sure that the folder (now containing `reva-server` and `reva-chat`) are in your PATH variable. pipx can do it for you with this command:
+
+```sh
+pipx ensurepath
+```
+
+The extension will need to start `reva-server`, and you will need to run `reva-chat`. In case you do not want to add them to your PATH, see the [Configuration](#configuration) section for how to set the path to the executables.
+
+Once the `reva-server` has been started by the extension the chat can be started with:
+
+```sh
+reva-chat
+```
 
 # Ghidra Support
 
@@ -118,12 +143,16 @@ reva-chat
 
 Follow the instructions in the [ghidra-assistant](ghidra-assistant/README.md) plugin.
 
-After installation, enable the `ReVaPlugin` extension in the CodeBrowser tool (Open a file and click: File -> Configure -> Miscellaneous).
+After installation, enable the `ReVa Plugin` extension in the CodeBrowser tool (Open a file and click: File -> Configure -> Miscellaneous).
 
 If you want ReVa enabled by default, click File -> Save Tool to save the configuration.
 
 If everything is working correctly you will see a ReVa menu on your menu bar.
 
+## Configuration
+
+You can modify the plugin configuration in `Edit -> Tool Options -> ReVa`.
+
 ## Undo
 
 Whenever ReVa performs an action it will create an undo point for each action. If ReVa renames 5 variables, this will be
@@ -131,9 +160,17 @@ one undo.
 
 ## Menus
 
-> These are being added in the next release
+ReVa adds an option to the CodeBrowser Tool's Window menu.
+Select Window -> ReVa Action Log to open the ReVa Action Log window.
+
+This window shows actions ReVa has performed and would like to perform.
+You can accept or reject a change by double clicking the ✅ or ❌ icon. You can also go to the location the action will be performed by double clicking the address.
+
+If you reject an action, ReVa will be told and she will move on.
+
+You can also enable "Auto-allow" in the ReVa options. This will automatically accept all actions ReVa wants to perform.
 
-ReVa adds some elements to the Ghidra UI. You can either ask ReVa to do something in the chat window,
+ReVa also adds some elements to the Ghidra UI. You can either ask ReVa to do something in the chat window,
 "Examine the variable usage in `main` in detail, rename the variables with more descriptive names.",
 or use the menu system.
 

{reverse_engineering_assistant-2.9.1 → reverse_engineering_assistant-2.9.2}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "reverse-engineering-assistant"
 readme = "README.md"
-version = "2.9.1"
+version = "2.9.2"
 authors = [
     {name="サイバーカイダ (cyberkaida)"},
 ]
@@ -20,6 +20,7 @@ dependencies = [
     "langchain",
     "langchain-core",
     "langchain-openai",
+    "langchain-community",
     "prompt_toolkit",
     "sentence_transformers",
     "PyYAML",
@@ -27,8 +28,9 @@ dependencies = [
     "rich",
     "grpcio",
     "protobuf",
+    "flask",
 ]
 
 [project.scripts]
 reva-server = "reverse_engineering_assistant.assistant_api_server:main"
-reva-chat = "reverse_engineering_assistant.chat_client:main"
+reva-chat = "reverse_engineering_assistant.chat_client:main"

{reverse_engineering_assistant-2.9.1 → reverse_engineering_assistant-2.9.2}/reverse_engineering_assistant/api_server_tools/llm_tools.py

@@ -3,7 +3,7 @@
 from ast import Call
 import queue
 import threading
-from typing import Callable
+from typing import Callable, Dict, Optional
 from venv import logger
 
 from ..protocol.RevaChat_pb2_grpc import RevaChatServiceServicer
@@ -18,6 +18,9 @@ module_logger = logging.getLogger("reva-server")
 from langchain_core.callbacks.base import BaseCallbackHandler
 from langchain_core.agents import AgentAction, AgentFinish
 
+from langchain_core.language_models.base import BaseLanguageModel
+from langchain_core.language_models.chat_models import BaseChatModel
+
 class RevaActionCollector(BaseCallbackHandler):
     """
     A callback handler for logging agent actions in the reverse engineering assistant.
@@ -57,10 +60,17 @@ class RevaActionCollector(BaseCallbackHandler):
 
 class RevaChat(RevaChatServiceServicer):
     logger = logging.getLogger("reva-server.RevaChat")
+    llm: BaseLanguageModel | BaseChatModel
+
+    def __init__(self, llm: BaseLanguageModel | BaseChatModel) -> None:
+        self.llm = llm
 
     def chat(self, request, context):
         self.logger.info(f"Received request: {request}")
-        assistant = ReverseEngineeringAssistant(request.project, langchain_callbacks=[RevaActionCollector(callback)])
+        assistant = ReverseEngineeringAssistant(
+            request.project,
+            model=self.llm
+        )
         self.logger.info(f"Assistant: {assistant}")
         llm_response = assistant.query(request.message)
         self.logger.info(f"LLM Response: {llm_response}")
@@ -83,7 +93,11 @@ class RevaChat(RevaChatServiceServicer):
             response.thought = message
             response_queue.put(response)
 
-        assistant = ReverseEngineeringAssistant(request.project, langchain_callbacks=[RevaActionCollector(callback)])
+        assistant = ReverseEngineeringAssistant(
+            request.project,
+            model=self.llm,
+            langchain_callbacks=[RevaActionCollector(callback)]
+        )
         self.logger.info(f"Assistant: {assistant}")
 
         def run_query(query: str):
@@ -106,6 +120,40 @@ class RevaChat(RevaChatServiceServicer):
         t.join()
 
     def chatStream(self, request_iterator, context):
-        # TODO: This needs to be re-written to use the new callback system
-        # let's grab a reference to our assistant
-        raise NotImplementedError("chatStream is not implemented yet")
+        assistant: Optional[ReverseEngineeringAssistant] = None
+        response_queue: queue.Queue = queue.Queue()
+
+        def callback(message: str):
+            # Called for intermediate thoughts
+            response = RevaChatMessageResponse()
+            response.thought = message
+            response_queue.put(response)
+
+        for request in request_iterator:
+            if not assistant:
+                assistant = ReverseEngineeringAssistant(
+                    request.project,
+                    model=self.llm,
+                    langchain_callbacks=[RevaActionCollector(callback)]
+                )
+            self.logger.info(f"Received request: {request}")
+            def run_query(query: str):
+                assert assistant is not None
+                self.logger.info(f"Asking assistant: {query}")
+                llm_response = assistant.query(query)
+                self.logger.info(f"LLM Response: {llm_response}")
+                response = RevaChatMessageResponse()
+                response.message = llm_response
+                response_queue.put(response)
+
+            t = threading.Thread(target=run_query, args=[request.message])
+            t.start()
+
+            done = False
+            while not done:
+                response = response_queue.get()
+                # We stop when we get a message and not thoughts
+                if response.message and not response.thought:
+                    done = True
+                yield response
+            t.join()