package-ida-plugin

What this skill does

# 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

```json
{
  "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": "[email protected]"}
    ],
    "maintainers": [
      {"name": "Maintainer Name", "email": "[email protected]"}
    ],
    "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 |
| `plugin.urls.repository` | string | GitHub URL: `https://github.com/org/project` |
| `plugin.authors` OR `plugin.maintainers` | array | At least one contact with `email` field required |

### Optional Fields

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `plugin.description` | string | none | One-line description shown in search results |
| `plugin.license` | string | none | License identifier (e.g., `MIT`, `Apache-2.0`, `GPL-3.0`) |
| `plugin.urls.homepage` | string | none | Homepage URL if different from repository |
| `plugin.idaVersions` | array or string | all versions | Supported IDA versions. Can be explicit list `["9.0", "9.1"]` or spec `">=7.4"` |
| `plugin.platforms` | array | all platforms | Supported platforms: `windows-x86_64`, `linux-x86_64`, `macos-x86_64`, `macos-aarch64` |
| `plugin.categories` | array | `[]` | See Categories section below |
| `plugin.keywords` | array | `[]` | Search terms for discoverability |
| `plugin.pythonDependencies` | array or `"inline"` | `[]` | PyPI packages. Use `"inline"` for PEP 723 metadata |
| `plugin.logoPath` | string | none | Relative path to logo image (16:9 aspect ratio recommended) |
| `plugin.settings` | array | `[]` | Plugin configuration options. See Settings section |

### Valid Categories

```
disassembly-and-processor-modules
file-parsers-and-loaders
decompilation
debugging-and-tracing
deobfuscation
collaboration-and-productivity
integration-with-third-parties-interoperability
api-scripting-and-automation
ui-ux-and-visualization
malware-analysis
vulnerability-research-and-exploit-development
other
```

### Valid IDA Versions

Current/supported: `9.2`, `9.1`, `9.0sp1`, `9.0`,  ...

Use a version specifier like `">=9.0"` to match multiple versions automatically.

## Packaging Pure Python Plugins

For simple Python plugins, the directory structure is minimal:

```
my-plugin/
├── ida-plugin.json
├── README.md             # Displayed on plugins.hex-rays.com
├── my_plugin.py          # entryPoint
└── my_plugin_lib/        # optional supporting modules
    ├── __init__.py
    └── helpers.py
```

### Minimal Exa