tenrec

<p align="center"> <img alt="logo" src="https://raw.githubusercontent.com/axelmierczuk/tenrec/refs/heads/main/tenrec/documentation/static/_media/icon.svg" width="30%" height="30%"> </p> # Tenrec [](https://pypi.org/project/tenrec/) [](https://pypi.org/project/tenrec/) [](https://img.shields.io/pypi/l/tenrec) A headless, extendable, multi-session MCP framework for IDA Pro, built with [ida-domain](https://ida-domain.docs.hex-rays.com/) and FastMCP. ## Features - **Headless**: No GUI required, powered by ida-domain - **Multi-session**: Analyze multiple binaries simultaneously - **Extensible**: Custom plugin support via entry points - **Auto-docs**: Generate documentation from plugins ### Built-in Plugins | Plugin | Description | |--------|-------------| | Functions | Analyze functions, boundaries, pseudocode | | Xrefs | Data and code cross-references | | Names | Symbol naming and demangling | | Comments | Code comments (regular, repeatable) | | Strings | String literal search/analysis | | Segments | Memory segment queries | | Bytes | Binary data read/patch | | Types | Type information and structures | | Entries | Entry points and exports | For complete plugin documentation, see [tenrec docs](https://axelmierczuk.github.io/tenrec/#/). > [!NOTE] > Community plugins: [tenrec-plugins](https://github.com/axelmierczuk/tenrec-plugins) ## Demo Solving Flare-On 9 Challenge 4 (darn mice) with a single prompt using tenrec and Claude Code: > Use tenrec to open a session and reverse the binary. Focus on getting a high-level understanding by finding entry points and tracing execution flow. Rename variables and functions as you work. The xref plugin can help. Look for a flag in email format. https://github.com/user-attachments/assets/3eb442dd-9b7a-44a6-836b-b73f99f4c2f3 Challenge write-up: [04-darn-mice.pdf](https://services.google.com/fh/files/misc/04-darn-mice.pdf) | Binary: [fareedfauzi/Flare-On-Challenges](https://github.com/fareedfauzi/Flare-On-Challenges) ## Installation ### Prerequisites - Python 3.10+ - IDA Pro 9.1+ ### Install ```bash uv tool install tenrec ``` Verify installation: ```bash uv tool list # Should show tenrec which tenrec # Should show path to executable ``` ### Set IDA Directory ```bash # macOS export IDADIR="/Applications/IDA Professional 9.1.app/Contents/MacOS" # Linux export IDADIR="/opt/idapro" # Windows (PowerShell, as Administrator) setx IDADIR "C:\Program Files\IDA Pro" /M ``` ## Quick Start ### 1. Install MCP Client ```bash tenrec install ``` Select your MCP client from the list (Claude Code, Cursor, Windsurf, etc.). ### 2. Run Server ```bash tenrec run ``` The server runs with stdio transport by default. Use `--transport sse` for SSE. ### 3. Plugin Management ```bash # Add plugin tenrec plugins add --plugin "package-name" tenrec plugins add --plugin "/path/to/plugin" tenrec plugins add --plugin "git+https://github.com/user/repo" # List plugins tenrec plugins list # Remove plugin tenrec plugins remove --dist plugin_name ``` ### 4. Generate Documentation ```bash tenrec docs -p tenrec/plugins/plugins ``` ## Documentation | Guide | Description | |-------|-------------| | [Plugin Development](agent_docs/plugin-development.md) | Creating custom plugins | | [CLI Reference](agent_docs/cli-reference.md) | Complete command reference | | [Architecture](agent_docs/architecture.md) | System design | | [Testing](agent_docs/testing.md) | Testing patterns | | [Integrations](agent_docs/integrations.md) | MCP client setup (including Codex) | | [Contributing](agent_docs/contributing.md) | Development setup and guidelines | | [Roadmap](agent_docs/roadmap.md) | Future plans | ## Creating Plugins ```python from tenrec.plugins.models import PluginBase, Instructions, operation class MyPlugin(PluginBase): """Plugin description.""" name = "my_plugin" # Must be snake_case version = "1.0.0" # Must be semver instructions = Instructions( purpose="What this plugin does", interaction_style=["How to use effectively"], examples=["my_plugin_operation()"], anti_examples=["What NOT to do"], ) @operation() def my_operation(self) -> dict: """Operation docstring for LLM guidance.""" # Access IDA via self.database return {"result": "value"} ``` Package with entry point in `pyproject.toml`: ```toml [project.entry-points."tenrec.plugins"] my_plugin = "my_package:MyPlugin" ``` See [Plugin Development Guide](agent_docs/plugin-development.md) for complete documentation. ## Known Issues - Windows support is in progress. See [Issue #9](https://github.com/axelmierczuk/tenrec/issues/9). ## Contributing See [Contributing Guide](agent_docs/contributing.md) for development setup and guidelines. ## License MIT