MCRIT IDA Plugin

July 15, 2026 · View on GitHub

Integration with MCRIT for MinHash-based code similarity analysis in IDA Pro.

MCRIT (MinHash-based Code Relationship & Investigation Toolkit) simplifies MinHash-based code similarity detection. This plugin seamlessly integrates MCRIT servers with IDA Pro for malware analysis and function identification.

✨ Features

Code Similarity - Compare functions/blocks against MCRIT.
Function Matching - Identify similar functions across binaries.
Label Management - Sync function labels with the server.
Interactive Widgets - Dedicated views for blocks, functions, and overview.
Integrated Settings - Native configuration via ida-settings.
HCLI Support - Easy installation and updates.

🚀 Installation

Option 1: HCLI

For new users, start with HCLI. The package to install is ida-hcli, and the command you will use afterward is hcli.

python -m pip install --upgrade ida-hcli
hcli --version

If mcrit-ida has already been indexed by the Hex-Rays plugin repository, install it directly:

hcli plugin search mcrit
hcli plugin install mcrit-ida

Useful follow-up commands:

hcli plugin status
hcli plugin upgrade mcrit-ida
hcli plugin uninstall mcrit-ida

If the plugin has not been indexed yet, or you want to test a local build first, package the plugin locally and install the ZIP:

python scripts/package_plugin.py --repo . --output ../mcrit-ida.zip
hcli plugin install ../mcrit-ida.zip

For headless shells or CI, pass settings explicitly so hcli does not try to open its interactive configuration prompt:

hcli plugin install ../mcrit-ida.zip \
  --config mcrit_server=https://mcrit.example.com/api/ \
  --config mcritweb_api_token=YOUR_TOKEN \
  --config mcritweb_username=analyst \
  --config mcrit_request_timeout=10

Option 2: Manual Installation Without HCLI

If you do not want to use HCLI at all, you can install the plugin manually:

Copy this repository, or extract a packaged release ZIP, into $IDAUSR/plugins/mcrit-ida/.
Ensure the plugin directory contains at least ida-plugin.json, ida_mcrit.py, config.py, helpers/, widgets/, and icons/.
Install the Python dependencies with the Python interpreter bundled with your IDA installation:

python -m pip install smda ida-settings>=3.3.0

Restart IDA Pro.

If your installation of IDA Pro is in an offline Windows VM, use the wheelhouse bundle from the release assets instead. After unpacking it, install from the local directory:

python -m pip install --no-index --find-links=. -r requirements.txt

⚙️ Configuration

Configuration is managed via ida-settings.

Configure with HCLI

If you installed via HCLI, inspect and update settings from the command line:

hcli plugin config mcrit-ida list
hcli plugin config mcrit-ida get mcrit_server
hcli plugin config mcrit-ida set mcrit_server https://mcrit.example.com/api/
hcli plugin config mcrit-ida set mcritweb_api_token YOUR_TOKEN
hcli plugin config mcrit-ida set mcrit_request_timeout 10

You can also export or import settings as JSON:

hcli plugin config mcrit-ida export
hcli plugin config mcrit-ida import "{\"mcrit_server\":\"https://mcrit.example.com/api/\",\"mcrit_request_timeout\":\"10\"}"

Configure with the GUI

Install ida-settings-editor and configure the plugin through Edit -> Plugins -> Plugin Settings Manager:

hcli plugin install ida-settings-editor

Configure Manually

If you are not using HCLI, the most practical manual override is a config_override.json placed next to config.py. A minimal example looks like this:

{
  "mcrit_server": "https://mcrit.example.com/api/",
  "mcritweb_api_token": "YOUR_TOKEN",
  "mcritweb_username": "analyst",
  "mcrit_request_timeout": "10"
}

You can also manage settings through $IDAUSR/ida-config.json if you already use ida-settings.

Connecting to Server

Configure the plugin to connect to your MCRIT instance:

Setting	Description	Example
`mcrit_server`	Server URL	`https://mcrit.example.com/api/`
`mcritweb_api_token`	API Token (for MCRITweb)	`eyJ0eXAi...`
`mcritweb_username`	Username (optional)	`analyst`
`sample_group_only`	Restrict matching queries to the server-side sample group	`false`

Note: For MCRITweb, the username is inferred automatically by setting the API token.

📖 Usage

Open Binary: Load a file in IDA Pro.
Open Widgets: View → Open subviews → MCRIT widgets.
Analyze: Right-click a function → MCRIT → Query function.
Matches: Review results in the Function Scope Widget.

🔧 Development

Project Structure

mcrit-plugin/
├── ida-plugin.json   # Plugin metadata
├── ida_mcrit.py      # Entry point
├── config.py         # Settings management
├── helpers/          # Utilities (incl. vendored pyperclip and pylev)
├── widgets/          # UI components
└── icons/            # Resources

Local Build & Install

To install a development version from source:

# 1. Clone
git clone https://github.com/danielplohmann/mcrit-plugin.git
cd mcrit-plugin

# 2. Package
python scripts/package_plugin.py --repo . --output ../mcrit-ida.zip

# 3. Install
hcli plugin install ../mcrit-ida.zip

Validation

Run the local checks before publishing:

python scripts/verify_metadata_sync.py --repo .
python scripts/verify_settings_sync.py --repo .
python scripts/run_quality_checks.py --repo .
python scripts/package_plugin.py --repo . --output dist/mcrit-ida.zip
hcli plugin lint .
hcli plugin lint dist/mcrit-ida.zip

Release Workflow

This plugin publishes a dedicated plugin ZIP as the HCLI package artifact.

git tag v1.1.6
git push origin v1.1.6

The tag-driven release workflow validates metadata, builds mcrit-ida-<version>.zip, lints both the repo and the ZIP with hcli, and then creates the GitHub release with the plugin archive attached. The offline dependency workflow runs after the release is published and attaches the optional wheelhouse bundles.

Version History

v1.1.8 (2026-07-15)

Isolated MCRIT4IDA loggers by configuring them with their own handler instead of relying on IDA's shared root logger.
Stopped bundled minimcrit modules from calling logging.basicConfig() at import time.
Added a regression test for the case where another IDA plugin has already configured the root logger.

v1.1.7 (2026-05-11)

Better guarding of remote metadata
Extensive testing for config parsing and McritClient communication
Expose sample-group-only matching setting

v1.1.6 (2026-03-23)

Updated HCLI-facing plugin metadata for release packaging, including the 1.1.6 version, IDA 9.0+ minimum, repository URL, and request-timeout setting.
Added repo-local packaging and validation scripts for metadata sync, settings sync, Ruff checks, and minimal plugin ZIP creation.
Added validation/release GitHub Actions to lint both the repo and packaged ZIP, publish mcrit-ida-<version>.zip, and attach offline dependency bundles to published releases.
Switched the offline dependency workflow to run from published releases so wheelhouse bundles attach to the canonical release instead of tag pushes alone.
Expanded the README with first-time HCLI setup, local ZIP installs, headless configuration examples, and manual installation steps without HCLI.

v1.1.5 (2026-02-27)

Added configurable MCRIT request timeouts via mcrit_request_timeout and aligned numeric setting defaults with the plugin settings metadata.
Refactored McritClient HTTP calls through shared request helpers and added centralized timeout support via setTimeout().
Moved the initial server connection check off the UI thread and improved startup status reporting.
Added architecture-aware SMDA backend selection with logging and fallback handling during IDB-to-SMDA conversion.
Hardened McritInterface connection error handling and UI-thread dispatch for background updates.
Guarded remote metadata lookups and empty/missing response data in BlockMatchWidget, FunctionMatchWidget, and SampleInfoWidget to avoid crashes when server state is incomplete.
Added safety checks before applying labels in FunctionOverviewWidget when no label column is configured or no labels have been fetched.
Fixed job dialog preselection when the selected row index is 0.
Removed the custom graph close action from SmdaGraphViewer to avoid the AttributeError path there.
Cleaned up vendored pyperclip compatibility handling for newer Python versions and removed stray debug/formatting issues from the batch.

v1.1.4 (2026-01-30)

added Github action to build dependency packages to facilitate installation in offline environments.
Removed the mcrit package dependency by internalizing McritClient and required DTOs.
Restored plugin hotkey handler and added a close action to the graph context menu.
Improved resilience for missing or empty match data and guarded SMDA import paths.
Hardened UI flows around function labels and form handling.
Dev/CI: Added Ruff config + GitHub Action and reformatted the codebase.

v1.1.3 (2026-01-28)

Significantly improved usablity of FunctionOverviewWidget by being able to deconflict multiple candidate labels.

v1.1.2 (2026-01-19)

Optionally use SMDA as backend analysis engine (consistency towards MCRIT server), even when in IDA Pro.

v1.1.1 (2026-01-15)

Now coloring results in BlockMatch (by frequency) and FunctionMatch (by score) widgets
Can now display offsets of matched functions in FunctionMatchWidget

v1.1.0 (2025-12-30)

Full HCLI Plugin Manager support.
Migrated configuration to ida-settings.
Code quality improvements.
Strict HCLI compliance.

v1.0.0 (2025-12-22)

Initial standalone release.
IDA 9.2 (PySide6) compatibility.

📄 License

GPL-3.0. See LICENSE for details.

👤 Author

Daniel Plohmann (@danielplohmann)
Rony (@r0ny123)