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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: reverse-engineering-assistant
-Version: 2.9.1
+Version: 2.9.4
 Summary: An AI assistant for reverse engineering tasks
 Author: サイバーカイダ (cyberkaida)
 Classifier: License :: OSI Approved :: Apache Software License
@@ -11,6 +11,9 @@ Description-Content-Type: text/markdown
 Requires-Dist: langchain
 Requires-Dist: langchain-core
 Requires-Dist: langchain-openai
+Requires-Dist: langchain-community
+Requires-Dist: langchain-experimental
+Requires-Dist: langgraph
 Requires-Dist: prompt_toolkit
 Requires-Dist: sentence_transformers
 Requires-Dist: PyYAML
@@ -18,6 +21,7 @@ Requires-Dist: pydantic
 Requires-Dist: rich
 Requires-Dist: grpcio
 Requires-Dist: protobuf
+Requires-Dist: flask
 
 # ReVA - Reverse Engineering Assistant
 
@@ -46,13 +50,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 +73,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 +124,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 +168,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 +185,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.4}/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.4}/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.4"
 authors = [
     {name="サイバーカイダ (cyberkaida)"},
 ]
@@ -20,6 +20,9 @@ dependencies = [
     "langchain",
     "langchain-core",
     "langchain-openai",
+    "langchain-community",
+    "langchain-experimental",
+    "langgraph",
     "prompt_toolkit",
     "sentence_transformers",
     "PyYAML",
@@ -27,8 +30,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.4/reverse_engineering_assistant/api_server_tools/__init__.py

@@ -0,0 +1,91 @@
+
+
+from typing import List
+from reverse_engineering_assistant.reva_exceptions import RevaToolException
+from reverse_engineering_assistant.tool import AssistantProject
+from reverse_engineering_assistant.assistant import RevaTool
+from reverse_engineering_assistant.model import RevaModel
+from reverse_engineering_assistant.api_server_tools.connection import get_channel
+from typing import Optional, Tuple
+import logging
+
+
+class RevaMessageHandler(object):
+    handles_type = None
+
+_global_message_handlers: List[RevaMessageHandler] = []
+
+__all__ = ['register_message_handler']
+
+def register_message_handler(cls: RevaMessageHandler):
+    _global_message_handlers.append(cls)
+    return cls
+
+
+class RevaRemoteTool(RevaTool):
+    logger: logging.Logger
+
+    def __init__(self, project: AssistantProject, llm: RevaModel) -> None:
+        self.logger = logging.getLogger(f"reverse_engineering_assistant.RevaRemoteTool.{self.__class__.__name__}")
+        self.logger.addHandler(logging.FileHandler(project.project_path / "reva.log"))
+        super().__init__(project, llm)
+
+    @property
+    def channel(self):
+        return get_channel()
+
+    def resolve_to_address_and_symbol(self, thing: str) -> Tuple[str, Optional[str]]:
+        """
+        Resolve a string to an address and symbol.
+        If it is an address it can be a namespaced address or a plain hex address.
+
+        This helps reduce hallucinations and catch issues with symbols and namespaces early.
+
+        Returns a tuple of (address, symbol).
+        """
+        self.logger.debug(f"Resolving {thing} to address and symbol")
+        assert thing is not None
+        address: Optional[str] = None
+        symbol: Optional[str] = None
+        try:
+            # This is a plain address in the main namespace
+            address = hex(int(thing, 16))
+            self.logger.debug(f"Resolved {thing} to address: {address}")
+        except ValueError:
+            # This could also be a Ghidra namespaced address, so let's check that too!
+            if "::" in thing:
+                last_part = thing.split("::")[-1]
+                try:
+                    hex(int(last_part, 16))
+                    # If the last part of the address is a hex number, then we can assume it is an address
+                    address = thing
+                except ValueError:
+                    # Otherwise, it is a symbol
+                    symbol = thing
+            else:
+                # This is a symbol
+                symbol = thing
+
+        # We can check if it is a symbol
+        from ..protocol import RevaGetSymbols_pb2_grpc, RevaGetSymbols_pb2
+        stub = RevaGetSymbols_pb2_grpc.RevaToolSymbolServiceStub(self.channel)
+        request = RevaGetSymbols_pb2.RevaSymbolRequest()
+        if address:
+            request.address = address
+        if symbol:
+            request.name = symbol
+
+        self.logger.debug(f"Getting symbol for {thing} request: {request}")
+        response = stub.GetSymbol(request)
+        self.logger.debug(f"Got symbol for {thing} response: {response}")
+
+        if response.name:
+            symbol = response.name
+        if response.address:
+            address = response.address
+
+        if address is None and symbol is None:
+            raise RevaToolException(message=f"Could not resolve {thing} to an address or symbol. Double check your symbol or address is correct.")
+        self.logger.debug(f"Resolved {thing} to address: {address}, symbol: {symbol}")
+        assert address is not None
+        return address, symbol

{reverse_engineering_assistant-2.9.1 → reverse_engineering_assistant-2.9.4}/reverse_engineering_assistant/api_server_tools/connection.py

@@ -11,6 +11,9 @@ from functools import cache
 _channel: Optional[Channel] = None
 @cache
 def get_channel() -> Channel:
+    """
+    Get the global gRPC channel to the extension.
+    """
     global _channel
     if not _channel:
         raise ValueError("Channel not set")

reverse_engineering_assistant-2.9.4/reverse_engineering_assistant/api_server_tools/llm_tools.py

@@ -0,0 +1,134 @@
+
+
+from ast import Call
+import queue
+import threading
+from typing import Callable, Dict, Optional
+from uuid import uuid4
+from venv import logger
+
+from ..protocol.RevaChat_pb2_grpc import RevaChatServiceServicer
+from ..protocol.RevaChat_pb2 import RevaChatMessageResponse
+
+from functools import cache
+from ..assistant import ReverseEngineeringAssistant
+
+import logging
+module_logger = logging.getLogger("reva-server")
+
+from langchain_core.callbacks.base import BaseCallbackHandler
+from langchain_core.agents import AgentAction, AgentFinish
+
+from reverse_engineering_assistant.model import RevaModel
+from reverse_engineering_assistant.model import get_llm_ollama, get_llm_openai
+
+class RevaChat(RevaChatServiceServicer):
+    logger = logging.getLogger("reva-server.RevaChat")
+
+    def _model_from_request(self, request) -> RevaModel:
+        """
+        Given a request, return the model associated with the request.
+        """
+        if request.ollama.model:
+            return get_llm_ollama(base_url=request.ollama.url, model=request.ollama.model)
+        if request.openai.model:
+            return get_llm_openai(model=request.openai.model, api_key=request.openai.token)
+        raise ValueError("No model specified in request. Please file a bug.")
+
+    def chat(self, request, context):
+        self.logger.info(f"Received request: {request}")
+        assistant = ReverseEngineeringAssistant(
+            request.project,
+            model=self._model_from_request(request)
+        )
+        self.logger.info(f"Assistant: {assistant}")
+        llm_response = assistant.query(request.message)
+        self.logger.info(f"LLM Response: {llm_response}")
+        response = RevaChatMessageResponse()
+        response.message = llm_response
+        return response
+
+    def chatResponseStream(self, request, context):
+        """
+        Given a request, return a stream of responses including
+        thoughts and a final message from the LLM.
+        """
+        self.logger.info(f"Received request: {request}")
+
+        response_queue: queue.Queue = queue.Queue()
+
+        def callback(message: str):
+            # Called for intermediate thoughts
+            response = RevaChatMessageResponse()
+            response.thought = message
+            response_queue.put(response)
+
+        assistant = ReverseEngineeringAssistant(
+            request.project,
+            model=self._model_from_request(request),
+            logging_callbacks=[callback],
+        )
+        self.logger.info(f"Assistant: {assistant}")
+
+        def run_query(query: str):
+            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()
+
+    def chatStream(self, request_iterator, context):
+        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._model_from_request(request),
+                    logging_callbacks=[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()
+
+    def shutdown(self, request, context):
+        self.logger.warning("Shutting down")
+        import sys
+        sys.exit(0)

reverse_engineering_assistant-2.9.4/reverse_engineering_assistant/api_server_tools/re_tool_box/__init__.py

@@ -0,0 +1,6 @@
+"""
+To make sure your tool is loaded, you should import it here.
+`assistant_api_server.py` imports everything from `re_tools.py`,
+and `re_tools.py` imports everything from here.
+"""
+