Guide · Agent skill
How to use the UPX Malware Unpacker agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The UPX Malware Unpacker is an agent skill for analyzing suspicious Windows programs that have been compressed with the UPX packer, a technique malware authors use to hide their code. Once installed, an AI agent can identify the packer, attempt standard UPX decompression, repair tampered UPX headers, and describe how to unpack the sample manually in a debugger. This guide covers what the skill does, how to install it, how to ask for it in plain language, and the safety precautions you need before running anything.
UPX Malware Unpackermukul975/Anthropic-Cybersecurity-Skills · Apache-2.0 Download the skill Quick start
- 1Download and unzip the skill. Download the skill ZIP from this page and unzip it. Confirm the folder contains SKILL.md, scripts/agent.py and references/api-reference.md.
- 2Place the folder. Copy the folder into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder to limit it to that project. You can also upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
- 3Set up the isolated VM. Install UPX, Python 3.8+ with pefile, and the optional Detect It Easy inside an analysis VM with no network connectivity.
- 4Make a working copy. Copy the suspect sample to a separate working file so the original stays unchanged.
- 5Ask for the unpacking task. Describe the sample's symptoms, such as high entropy or minimal imports, and say you want the original code for Ghidra or IDA.
- 6Review the results. Check the packer identification, the decompression output and the validation report before loading the unpacked file into a disassembler.
What is an agent skill and what does this one do?
An agent skill is a folder containing instructions (a SKILL.md file) and optional scripts and reference files that an AI agent loads when a task matches the skill's description. This skill is for malware analysts and security students who receive packed Windows samples and need the original executable for reverse engineering.
The skill walks the agent through a workflow: identifying whether a sample is packed, trying UPX's built-in decompression, repairing modified UPX magic bytes or section names when that fails, and explaining how to unpack manually with a debugger and the Scylla plugin when automated methods cannot succeed. The goal is a recovered binary that can be loaded into Ghidra or IDA.
- Checks section entropy, section names and import count with pefile
- Runs standard UPX decompression and verbose output for debugging
- Repairs tampered UPX section names and magic bytes, then retries
- Describes manual OEP-finding and import repair with x64dbg/x32dbg and Scylla
- Validates the unpacked file's sections, imports and size ratio
Install the skill: download, unzip, and place it
Download the skill ZIP from this page and unzip it. For a personal install, place the folder in ~/.claude/skills/. To limit it to one project, place it in that project's .claude/skills/ folder. The folder should contain SKILL.md, scripts/agent.py and references/api-reference.md.
You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal install: ~/.claude/skills/analyzing-packed-malware-with-upx-unpacker/
- Project install: .claude/skills/analyzing-packed-malware-with-upx-unpacker/ inside your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Install the tools the skill needs
The skill relies on external tools. It does not install them for you. The source lists the following prerequisites. Install them inside your isolated analysis VM, not on your everyday machine.
Detect It Easy is optional but useful for packer identification. The UPX command-line tool is required for decompression. Python 3.8+ with the pefile library is needed for the header and validation scripts.
- UPX command-line tool (the source suggests apt install upx-ucl or download from https://upx.github.io/)
- Detect It Easy (DIE) for packer identification (optional)
- Python 3.8+ with the pefile library
- x64dbg or x32dbg for manual unpacking
- PE-bear or CFF Explorer for header inspection
- Scylla plugin for manual import repair
- An isolated analysis VM without network connectivity (recommended by the skill)
apt install upx-uclHow do you trigger the skill with a natural request?
You do not need special syntax. Agents load a skill when your request matches its description. The description mentions packed or high-entropy samples, minimal imports, LoadLibrary and GetProcAddress in the import table, and preparing binaries for Ghidra or IDA, so describe your situation in those terms.
Give the agent the file name and a clear goal, and state that the sample is in an isolated VM. Asking for the original code to load into Ghidra works well.
- "This suspect.exe has high entropy and only LoadLibrary and GetProcAddress in its imports. Identify the packer and unpack it for Ghidra."
- "Standard upx -d fails on suspect.exe, I think the UPX headers were modified. Repair them and retry."
- "Walk me through manually unpacking this UPX sample in x64dbg so I can dump it with Scylla."
- "Validate unpacked.exe and tell me whether the imports look resolved."
Run the workflow step by step
The skill's workflow follows a fixed order, so you can also follow it yourself. Start by identifying the packer, because the other steps depend on it. Only move to manual unpacking when automated decompression and header repair have failed.
The commands below are taken from the skill. Run them only on a sample inside an isolated VM.
- Step 1: identify the packer with diec, upx -t and the pefile section check
- Step 2: try upx -d suspect.exe -o unpacked.exe, adding -v for verbose output
- Step 3: if that fails, repair tampered magic bytes and section names, save suspect_fixed.exe, then retry
- Step 4: if automation fails entirely, unpack manually in x64dbg and dump with Scylla
- Step 5: validate unpacked.exe with pefile and compare file sizes
upx -d suspect.exe -o unpacked.exeSafety notes: scripts and network
This skill runs scripts (scripts/agent.py) and works on live malware samples. The source states that it uses no network, but the samples themselves are hostile. Treat every sample as if it could do harm if run.
The skill recommends an isolated analysis VM without network connectivity. Do not execute samples or the unpacked output on a normal or networked machine. The skill is also not meant for custom packers or VM-based protectors such as Themida or VMProtect, which it says are out of scope, and it is not meant for unpacking commercial software you have no rights to modify.
- Use an isolated VM with no network connectivity, and keep snapshots so you can revert
- Review scripts/agent.py before running anything
- Do not use on Themida, VMProtect or custom packers; the techniques will not work there
- Do not use for non-malware work such as unpacking commercial software without rights
Tips for better results
Give the agent the exact file names and the results of earlier checks, such as the upx -t output or the DIE report. The skill's decision points depend on those results. Keep the original sample unchanged and work on copies, since the scripts write new files such as suspect_fixed.exe and unpacked.exe.
If the imports after unpacking look incomplete, the skill's manual path with Scylla is the next step. Check the entropy of the unpacked sections as well, because high entropy in the unpacked output can mean it is still packed.
- Always state the sample is in an isolated VM
- Keep the original file and work on copies
- Share tool output (DIE, upx -t, pefile results) so the agent can choose the right step
- Ask for the reasoning at each decision point so you can verify it
What people use it for
- Recovering the original code of a UPX-packed Windows sample so it can be decompiled in Ghidra
- Repairing a sample whose UPX section names were changed so standard decompression works again
- Preparing a packed binary for IDA by unpacking it manually with x64dbg and Scylla
- Checking whether an unpacked file still has high entropy or unresolved imports
- Teaching how UPX stubs, entropy and import tables reveal packing
Frequently asked questions
Is the UPX Malware Unpacker skill free?
The skill is licensed under Apache-2.0, as stated on this page. The external tools it uses, such as UPX, Detect It Easy, pefile, x64dbg and Scylla, are separate projects with their own licences, which you should check before use.
What do I need installed to use this skill?
You need Python 3.8+ with the pefile library and the UPX command-line tool. Detect It Easy is optional for packer identification. For manual unpacking you also need x64dbg or x32dbg, PE-bear or CFF Explorer, and the Scylla plugin, plus an isolated analysis VM without network connectivity.
How do I install an agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
Why does upx -d fail on my sample?
The source says malware authors often modify UPX magic bytes or section names so automatic decompression fails with a 'not packed by UPX' style error. The skill's Step 3 repairs those headers and retries; if that still fails, manual unpacking in a debugger is the next option.
Can this skill unpack Themida or VMProtect?
No. The skill says VM-based protectors such as Themida and VMProtect, and custom packers, are out of scope, and the techniques will not work on them.
Is it safe to run on my own computer?
The skill is built for handling live malware and the source recommends an isolated VM without network connectivity. Do not run samples on a normal or networked machine. The skill itself uses no network, but the samples are hostile.
How does this compare with other unpacking tools?
This skill is one guided workflow built around UPX, pefile and debugger-based manual unpacking. The source does not compare it with other tools, so judge it by whether your sample is UPX-packed and whether you are working in an isolated lab.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits malware analysts, students and incident responders who work in an isolated VM and need the original code of a UPX-packed Windows sample for Ghidra or IDA. It is the wrong choice for Themida, VMProtect, custom packers or any task where you cannot keep samples isolated from a network.
Download the skill