/package-ida-plugin

name: package-ida-plugin
description: Package IDA Pro plugins for the IDA Plugin Manager and plugins.hex-rays.com repository

Packaging IDA Pro Plugins

This skill helps package IDA Pro plugins for distribution via the IDA Plugin Manager and the plugins.hex-rays.com repository. It covers creating and updating the `ida-plugin.json` manifest, packaging archives, and publishing via GitHub Releases.

Overview

The IDA Plugin Manager is a self-service ecosystem for discovering, installing, and sharing IDA plugins:

• **Discovery**: A daily indexer scans GitHub for repositories containing `ida-plugin.json`
• **Repository**: Published at [plugins.hex-rays.com](https://plugins.hex-rays.com/) and [github.com/HexRaysSA/plugin-repository](https://github.com/HexRaysSA/plugin-repository)
• **Client**: HCLI command-line tool (`hcli plugin install <name>`)
• **Compatibility**: IDA Pro 9.0+ (full support)

Critical: Understanding Plugin Root Directory

**The `ida-plugin.json` file defines the root of the plugin.** When a plugin is installed, only the directory containing `ida-plugin.json` (and its subdirectories) is copied to `$IDAUSR/plugins/`. Nothing outside this directory is included.

Assessing Directory Structure Compatibility

Before packaging, verify that your plugin's structure is self-contained:

# GOOD: All plugin code is in the same directory as ida-plugin.json
my-repo/
├── ida-plugin.json        # Plugin root
├── my_plugin.py           # Entry point - INCLUDED
├── my_plugin_lib/         # Supporting code - INCLUDED
│   └── helpers.py
├── README.md              # Plugin README - INCLUDED (shown on web)
└── assets/
    └── logo.png           # Logo - INCLUDED

# BAD: Plugin code outside the ida-plugin.json directory
my-repo/
├── plugin/
│   └── ida-plugin.json    # Plugin root is here
├── src/                   # NOT INCLUDED - outside plugin root!
│   └── my_plugin.py       # This file won't be installed!
└── README.md              # NOT INCLUDED - wrong directory!

Compatibility Checklist

When assessing an existing plugin, verify:

1. [ ] **Entry point location**: Is `entryPoint` in the same directory as `ida-plugin.json`? 2. [ ] **All imports resolvable**: Are all Python imports within the plugin root or in `pythonDependencies`? 3. [ ] **No parent directory references**: Does the code use `../` to access files outside the plugin root? 4. [ ] **Assets included**: Are logos, data files, or resources inside the plugin root? 5. [ ] **README placement**: Is `README.md` in the plugin root (not repo root) for web display?

Common Restructuring Patterns

**Pattern 1: Plugin in subdirectory**

If your plugin code is in a subdirectory like `src/` or `plugin/`, move `ida-plugin.json` into that directory:

# Before                          # After
my-repo/                          my-repo/
├── ida-plugin.json               └── src/
└── src/                              ├── ida-plugin.json  # Moved here
    └── my_plugin.py                  ├── my_plugin.py
                                      └── README.md        # Add for web

**Pattern 2: Monorepo with IDA plugin**

For projects where IDA plugin is one component (e.g., capa), place `ida-plugin.json` at the plugin code's location:

capa/
├── capa/
│   ├── ida/
│   │   └── plugin/
│   │       ├── ida-plugin.json   # Plugin root
│   │       ├── capa_explorer.py  # Entry point
│   │       └── README.md         # Plugin-specific docs
│   └── main.py                   # Not included in IDA plugin
└── README.md                     # Repo README - not the plugin README

README in Plugin Root

Place a `README.md` file in the same directory as `ida-plugin.json` to have it displayed on the [plugins.hex-rays.com](https://plugins.hex-rays.com/) web interface. This is separate from your repository's root README:

my-plugin/
├── ida-plugin.json
├── my_plugin.py
└── README.md              # This README appears on plugins.hex-rays.com

The plugin README should focus on:

• What the plugin does
• How to use it within IDA
• Configuration options (if using settings)
• Screenshots or examples

It does **not** need installation instructions (the Plugin Manager handles that).

The ida-plugin.json Manifest

Every plugin requires an `ida-plugin.json` file in its root directory. This is the **only required file** beyond the plugin code itself. Paths in the metadata file are relative to the metadata file, because the metadata file defines the root of the plugin, even if its nested within a ZIP archive.

Complete Schema

{
  "IDAMetadataDescriptorVersion": 1,
  "plugin": {
    "name": "my-plugin",
    "version": "1.0.0",
    "entryPoint": "my_plugin.py",
    "description": "A one-line description of what this plugin does",
    "license": "MIT",
    "urls": {
      "repository": "https://github.com/org/my-plugin",
      "homepage": "https://example.com/my-plugin"
    },
    "authors": [
      {"name": "Author Name", "email": "author@example.com"}
    ],
    "maintainers": [
      {"name": "Maintainer Name", "email": "maintainer@example.com"}
    ],
    "idaVersions": ["9.0", "9.1", "9.2"],
    "platforms": ["windows-x86_64", "linux-x86_64", "macos-x86_64", "macos-aarch64"],
    "categories": ["malware-analysis"],
    "keywords": ["analysis", "automation"],
    "pythonDependencies": ["requests>=2.0", "pydantic>=2"],
    "logoPath": "assets/logo.png",
    "settings": []
  }
}

Required Fields

| Field | Type | Description | |-------|------|-------------| | `IDAMetadataDescriptorVersion` | `1` | Always set to `1` | | `plugin.name` | string | Unique identifier. ASCII letters, digits, underscores, hyphens only. No leading/trailing `_` or `-`. Used to derive the IDA namespace: `__plugins__my_plugin` | | `plugin.version` | string | Semantic version `x.y.z` format. No leading `v` | | `plugin.entryPoint` | string | Entry point filename (e.g., `my_plugin.py`) or bare name for native plugins | | `plugi