+ "longdescription": "# Shellcode IDE — Binary Ninja Plugin\n\nA Qt-based Binary Ninja plugin that helps you compose, analyze, optimize, validate, and export shellcode across architectures that Binary Ninja supports. It combines Binary Ninja’s assembler/disassembler with a user-friendly GUI for rapid iteration and safe validation of shellcode for reverse engineering, CTFs, and security research.\n\n- Audience: reverse engineers, CTF players, exploit developers, security researchers\n- Status: early development; core assemble/disassemble and UI scaffolding targeted first\n\n---\n\n## Highlights\n\n- Two-way conversion: raw bytes/hex ⇆ assembly text\n- Assemble for any Binary Ninja architecture/platform\n- Multiple output formats: inline `\\x..`, raw hex, C stub, Python stub, Zig stub, Rust stub, Go stub\n- Live metadata: byte length, instruction count, null count, endianness, arch\n- Configurable bad-pattern detection (e.g., `00`, `0a`, `ff`, sequences, regex)\n- Peephole optimizations with preview/confirm (e.g., `push 0` → `xor reg, reg; push reg`, `mov rax, imm8` when safe)\n- Validation rules: no variables/labels, no absolute addresses/relocations, no nulls (unless allowed)\n- Binary Ninja integration: menu + toolbar + dockable/floating Qt window with shortcuts\n\n---\n\n## Screenshots\n\n(Coming soon)\n- Main window with Input/Output panes and live stats\n- Validation tab with clickable issues and fix suggestions\n\n---\n\n## Requirements\n\n- Binary Ninja (licensed), with Python API available\n- Python 3.8+ (match your Binary Ninja build)\n- Qt via PySide2 (Binary Ninja typically bundles PySide2; no manual install required)\n- Optional: Capstone/Keystone for fallback dis/assembly (used only if configured)\n\n---\n\n## Installation\n\nYou can install as a user plugin. Typical plugin directories:\n\n- macOS: `~/Library/Application Support/Binary Ninja/plugins`\n- Linux: `~/.binaryninja/plugins`\n- Windows: `%APPDATA%\\Binary Ninja\\plugins`\n\nManual install:\n\n1. Close Binary Ninja.\n2. Copy or clone this repository into your plugins directory as `Shellcode-IDE`.\n - Example (macOS/Linux):\n - `cd \"~/Library/Application Support/Binary Ninja/plugins\"` (macOS) or `cd ~/.binaryninja/plugins` (Linux)\n - `git clone https://github.com/<you>/Shellcode-IDE.git Shellcode-IDE`\n3. Start Binary Ninja. The plugin registers a Tools menu entry and a toolbar icon.\n\nIf you’re reading this inside `.../Binary Ninja/plugins/Shellcode-IDE`, you’re set. Restart Binary Ninja to load the plugin, or use “Reload Plugins” if available.\n\n---\n\n## Launching\n\n- Menu: `Tools → Shellcode IDE`\n- Toolbar: Shellcode IDE icon\n- Docking: Opens as a dockable/floating Qt window\n\n---\n\n## Quick Start\n\n- Disassemble bytes/hex → assembly\n 1. Open Shellcode IDE.\n 2. Select target `Architecture`/`Platform` (defaults to active view when available).\n 3. Paste hex/bytes into the “Hex/Bytes” tab (supports whitespace, `0x` prefixes, and `\\x..` forms).\n 4. Click “Disassemble”. View assembly in the output panel and stats in the status bar.\n 5. Export via the “Formats” tab (copy or save to file).\n\n- Assemble assembly → shellcode\n 1. Switch to the “Assembly” tab and enter one instruction per line.\n 2. Click “Assemble”. Errors (if any) show inline with line/column info.\n 3. Review live stats, run “Optimize” (optional), “Validate”, and export in your preferred format.\n\n---\n\n## Features\n\n- Input/Output\n - Input tabs: “Hex/Bytes”, “Assembly”, with syntax highlighting and paste detection\n - Output tabs: “Disassembly / Assembly Output”, “Formats”, “Validation”, “History”\n - Status bar: arch/platform, length, null count, bad-pattern count, optimization status\n\n- Assemblers & Disassemblers\n - Uses Binary Ninja API: `Architecture.assemble()` and instruction text utilities\n - Disassembly can work in-memory from raw bytes; follows branches best-effort\n - Architecture and platform are user-selectable and default to the active view\n\n- Export Formats\n - Inline: `\"\\x90\\x90\\x48...\"`\n - Hex: `90 90 48 ...` or `0x90,0x90,...` (selectable)\n - C: minimal runnable C stub (mmap + function pointer)\n - Python: minimal runnable Python stub (mmap + ctypes)\n - Zig: minimal runnable Zig stub (page-alloc + mprotect + function pointer)\n - Rust: minimal runnable Rust stub (mmap + function pointer)\n - Go: minimal runnable Go stub (cgo + mmap + function pointer)\n - Configurable templates: variable names, include length, trailing comma, line wrapping\n\n- Bad-Pattern Detection\n - Patterns as hex bytes (`00`, `0a`, `ff`), byte sequences (`00 00 00`), or regex over hex text\n - Matches list with offsets; click to highlight bytes/assembly\n - Status badge for match count\n\n- Validation Rules\n - No variables/labels or assembler directives that produce relocations\n - No absolute addresses (e.g., `mov rax, 0x7fff...`, `[0xADDR]`)\n - No relocations/unresolved symbols from the assembler\n - No null bytes by default; user can allow via patterns\n\n- Peephole Optimizations (opt-in)\n - `push 0` → `xor reg, reg; push reg` (arch-aware)\n - `mov rax, IMM` → `mov al, IMM` when `IMM` fits and safe\n - Preview changes; accept/reject per transform\n - Safety checks ensure no forbidden bytes/semantics changes; warn on uncertainty\n\n- History & Snippets\n - Save/load named snippets per architecture\n - Persist settings and patterns per user\n\n---\n\n## UI Overview\n\n- Top toolbar: New, Open, Save, Copy, Assemble, Disassemble, Optimize (toggle), Validate\n- Left pane: Input tabs (Hex/Bytes, Assembly)\n- Right pane: Output (Disassembly/Assembly), Formats, Validation, History\n- Bottom status bar: arch/platform, length, nulls, bad-patterns, optimization state\n\n---\n\n## Keyboard Shortcuts (default)\n\n- `Ctrl/Cmd + Enter`: Assemble current Assembly tab\n- `Shift + Enter`: Disassemble Hex/Bytes input\n- `Ctrl/Cmd + B`: Toggle Optimize preview\n- `Ctrl/Cmd + E`: Validate\n- `Ctrl/Cmd + C`: Copy current format block\n\n(Shortcuts are subject to change; configurable in a later milestone.)\n\n---\n\n## Safety & Ethics\n\n- The plugin never executes shellcode. It assembles/disassembles and analyzes bytes only.\n- Use shellcode exclusively on systems you own or have explicit permission to test.\n\n---\n\n## Configuration & Storage\n\n- Bad patterns, export templates, and user snippets are stored in a plugin-specific config under Binary Ninja’s user data directory (platform-specific).\n- A future update will add UI to import/export settings and custom transforms.\n\n---\n\n## Development\n\n- Tech stack: Python 3.8+, Binary Ninja Python API, PySide2\n- Recommended workspace layout:\n\n```\nShellcode-IDE/\n shellcode_ide/\n __init__.py # plugin entrypoint (BN actions, dock widget)\n ui/ # Qt .ui files and wrappers\n backends/\n bn_adapter.py # BN assembly/disassembly wrappers\n optimize.py # peephole passes\n validator.py # validation checks\n formatters/ # export formatters\n tests/ # unit tests and sample shellcodes\n README.md # this file\n LICENSE # MIT recommended\n```\n\n### Running & Reloading\n\n- Start Binary Ninja; the plugin registers automatically.\n- To iterate on UI/logic: edit files, then restart BN or use “Reload Plugins”.\n- Logs and errors: open Binary Ninja’s Log and Python Console to view tracebacks and debug prints.\n\n### Testing\n\n- Tests cover assemble/disassemble round-trips, optimization rules, and validators.\n- From the repo root (with BN’s Python available on PATH or `PYTHONPATH`), run:\n - `python -m pytest -q`\n- Some tests may require the Binary Ninja API; those will be skipped if the API is unavailable in the current interpreter.\n\n### Coding Style\n\n- Prefer small, composable modules with clear responsibilities\n- Keep GUI code thin; push logic to backends\n- Add docstrings where behavior isn’t obvious; avoid over-commenting obvious code\n\n---\n\n## Roadmap\n\n- M1 — Core assemble/disassemble: basic GUI, assemble/disassemble, formats, length\n- M2 — Validation & bad-patterns: validation pipeline, pattern editor UI\n- M3 — Optimize passes: two sample peepholes, preview+apply UX\n- M4 — Extensibility: snippets, custom transforms, export templates\n- M5 — Polish & tests: full unit tests, docs, sample snippets, CI\n\n---\n\n## Troubleshooting\n\n- “Assemble” fails or produces errors\n - Confirm the selected Architecture/Platform matches your intent\n - Check Binary Ninja version and that its Python environment is used\n - Inspect the Log/Python Console for detailed assembler diagnostics\n\n- Disassembly stops mid-stream\n - The bytes may not decode fully for the selected architecture; verify input and arch mode (e.g., 32-bit vs 64-bit)\n\n- UI issues (blank window or missing Qt)\n - Binary Ninja bundles Qt/PySide2; ensure you’re not shadowing it with another Qt install\n - Restart Binary Ninja and check the Log for exceptions\n\n- Validation flags “relocations”\n - Remove labels/symbols/absolute addresses from assembly; ensure position-independent constructs\n\n---\n\n## FAQ\n\n- Does the plugin execute shellcode?\n - No. It never runs user-provided bytes; it only assembles/disassembles and analyzes.\n\n- Can I add my own optimizations?\n - Planned: a small JSON/DSL for custom peepholes with safety checks.\n\n- Which architectures are supported?\n - Any architecture that Binary Ninja supports and exposes via its Python API on your installation.\n\n---\n\n## Contributing\n\nContributions are welcome! Please open issues for bugs/ideas and submit focused PRs.\n\n- Keep changes minimal and scoped to the task\n- Match the existing code style and structure\n- Include tests for new logic where practical\n\n---\n\n## License\n\nMIT (recommended). See `LICENSE` once added to the repository.\n\n---\n\n## Acknowledgments\n\n- Binary Ninja team and community for the APIs and plugin ecosystem\n- Inspiration from common shellcode workflows and CTF tooling\n",
0 commit comments