cheerleader 0.2.0__py3-none-any.whl

cheerleader/__init__.py

@@ -0,0 +1,44 @@
+"""disasm — binary inspector (Mach-O, ELF)."""
+
+import argparse
+import sys
+
+from cheerleader.tui.app import APP_TITLE
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog=APP_TITLE,
+        description="Binary inspector TUI",
+    )
+    parser.add_argument("binary", help="path to the binary to inspect")
+    parser.add_argument(
+        "--hex",
+        action="store_true",
+        default=False,
+        help="open in hex editor mode (raw file hex dump only)",
+    )
+    parser.add_argument(
+        "--env",
+        default=".env",
+        metavar="FILE",
+        help="path to .env file for AI agent config (default: .env)",
+    )
+    args = parser.parse_args()
+
+    try:
+        open(args.binary, "rb").close()
+    except OSError as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+    from cheerleader.formats import detect_format
+
+    fmt = detect_format(args.binary)
+    if fmt == "unknown":
+        print("Warning: unrecognised binary format — continuing anyway")
+
+    from cheerleader.tui import DisasmApp
+
+    app = DisasmApp(args.binary, env_file=args.env, hex_mode=args.hex)
+    app.run()

cheerleader/agent/__init__.py

@@ -0,0 +1,9 @@
+# disassembly agent
+
+from .agent import CheerleaderAIAgent
+from .agent_settings import load_environment_variables as load_agent_settings
+
+__all__ = [
+    "load_agent_settings",
+    "CheerleaderAIAgent",
+]

cheerleader/agent/agent.py

@@ -0,0 +1,81 @@
+# disassembly agent
+
+from typing import Any
+from pathlib import Path
+from deepagents import create_deep_agent
+from langchain.chat_models import init_chat_model, BaseChatModel
+from langchain_core.messages import HumanMessage
+from langgraph.graph.state import CompiledStateGraph
+
+# the agent class
+class CheerleaderAIAgent(object):
+    def __init__(self, config: dict[str, Any]):
+        self.provider: str = config.get("provider")
+        self.llm_model: str = config.get("llm_model")
+        self.base_url: str = config.get("base_url")
+        self.api_key: str = config.get("api_key")
+        self.system_prompt: str = config.get("system_prompt")
+        self.skills_path: Path = Path(config.get("skills_path"))
+
+        # at the beginning, connection is empty
+        self.llm_connector: BaseChatModel = None
+        self.agent: CompiledStateGraph = None
+        try:
+            self.llm_connector: BaseChatModel = self._create_model_connector()
+            self.agent: CompiledStateGraph = self._create_agent()
+        except Exception as e:
+            raise e from e
+
+    # create a connection to a custom supported endpoint
+    # specify model name and apikey
+    def _create_model_connector(self) -> BaseChatModel:
+        try:
+            return init_chat_model(
+                model=self.llm_model,
+                model_provider=self.provider,
+                api_key=self.api_key if self.api_key != "" else "sk-unprotected",
+                base_url=self.base_url,
+            )
+        except Exception:
+            import logging
+
+            msg = f"Failed to initialize chat model: provider={self.provider}, base_url={self.base_url}, model={self.llm_model}"
+
+            logging.critical(msg)
+            raise Exception(msg)
+
+    # create reverser agent with langchain deepagent library
+    def _create_agent(self) -> CompiledStateGraph:
+        try:
+            # resolve skills path
+            if not self.skills_path.exists():
+                raise Exception(f"Skills dir {self.skills_path.absolute()} not found")
+
+            # check connector
+            if self.llm_connector is None:
+                raise Exception(f"Connector for model {self.llm_model}, using URL {self.base_url} is not available.")
+        
+            # create a filesystem backend to load skills from
+            from deepagents.backends.filesystem import FilesystemBackend
+            fs_backend = FilesystemBackend(root_dir=self.skills_path.absolute().parent)
+
+            # create the agent object
+            return create_deep_agent(
+                model=self.llm_connector,
+                backend=fs_backend,
+                system_prompt=self.system_prompt,
+                skills=[self.skills_path.name]
+            )
+        except Exception:
+            import logging
+            msg = f"Failed to initialize Agent: model={self.llm_model}"
+
+            logging.critical(msg)
+            raise Exception(msg)
+
+    # main method
+    def invoke(self, user_prompt: str):
+        payload = {
+            "messages": [HumanMessage(content=user_prompt)]
+        }
+        return self.agent.invoke(payload)

cheerleader/agent/agent_settings.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python
+"""
+Resolved agent configuration: ``.env`` overrides defaults from ``src.config``.
+
+Load order: ``python-dotenv`` reads the project ``.env`` into ``os.environ``;
+each setting prefers a non-empty environment value, otherwise the value from
+``src.config``.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+# import required modules
+try:
+    from dotenv import load_dotenv
+    from cheerleader.util.utils import _str_setting
+except ImportError:
+    raise ImportError("python-dotenv is required to use this module")
+
+# load the environment variables
+def load_environment_variables(envfile: str) -> dict[str, Any]:
+    e_file = Path(envfile)
+    if not e_file.exists():
+        raise FileNotFoundError(f"Environment file {e_file} not found")
+    load_dotenv(e_file)  # load the environment variables
+    return _get_settings_from_environment()
+
+
+# get the settings
+def _get_settings_from_environment():
+    settings = {
+        "provider": _str_setting("LLM_PROVIDER", "openai"),
+        "llm_model": _str_setting("LLM_MODEL", "gpt-4o-mini"),
+        "base_url": _str_setting("BASE_URL", "https://api.openai.com/v1"),
+        "api_key": _str_setting("API_KEY", "your-api-key-here"),
+        "skills_path": _str_setting("SKILLS_PATH", "./skills"),
+        "system_prompt": _str_setting("SYSTEM_PROMPT", "you are an expert in reverse engineering"),
+    }
+    return settings
+
+
+# export the settings
+__all__ = [
+    "load_environment_variables",
+]

cheerleader/formats/__init__.py

@@ -0,0 +1,45 @@
+"""Binary format detection and parser dispatcher."""
+
+from __future__ import annotations
+
+import struct
+
+from cheerleader.libs.types import BinaryInfo
+
+_MACHO_MAGICS = frozenset({
+    0xFEEDFACE, 0xCEFAEDFE,   # 32-bit LE/BE
+    0xFEEDFACF, 0xCFFAEDFE,   # 64-bit LE/BE
+    0xCAFEBABE, 0xBEBAFECA,   # fat LE/BE
+})
+
+
+def detect_format(path: str) -> str:
+    """Return "macho", "elf", or "unknown" by reading the first 4 bytes."""
+    try:
+        with open(path, "rb") as f:
+            raw = f.read(4)
+    except OSError:
+        return "unknown"
+    if len(raw) < 4:
+        return "unknown"
+    if raw[:4] == b'\x7fELF':
+        return "elf"
+    le_val = struct.unpack_from("<I", raw)[0]
+    if le_val in _MACHO_MAGICS:
+        return "macho"
+    be_val = struct.unpack_from(">I", raw)[0]
+    if be_val in _MACHO_MAGICS:
+        return "macho"
+    return "unknown"
+
+
+def parse(path: str, **kwargs) -> BinaryInfo:
+    """Detect format and dispatch to the appropriate parser."""
+    fmt = detect_format(path)
+    if fmt == "macho":
+        from cheerleader.formats.macho import parse as _macho_parse
+        return _macho_parse(path, **kwargs)
+    if fmt == "elf":
+        from cheerleader.formats.elf import parse as _elf_parse
+        return _elf_parse(path, **kwargs)
+    return BinaryInfo(path=path, error="Unrecognised file format")

cheerleader/formats/base.py

@@ -0,0 +1,11 @@
+"""Abstract parser protocol for binary formats."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from cheerleader.libs.types import BinaryInfo
+
+
+class FormatParser(Protocol):
+    def parse(self, path: str, **kwargs) -> BinaryInfo: ...