Written and maintained by CASRAI Editorial Board
Published
On this page
CAPE Sandbox is an open-source malware analysis sandbox whose name stands for Malware Configuration And Payload Extraction: it runs a suspicious file in an isolated virtual machine, records what the file does, and automatically unpacks and extracts the payloads and configuration data that malware hides at runtime. It is a fork of Cuckoo Sandbox, and its project page is github.com/kevoreilly/CAPEv2.
What CAPE Sandbox is used for in research
The CAPEv2 README describes CAPE as a sandbox that executes malicious files in an isolated environment while instrumenting their behaviour and collecting forensic artefacts. For research, that makes it a repeatable way to turn a sample into structured evidence: API-call behaviour, dropped files, network capture in PCAP form, screenshots and memory dumps, all stored per analysis. Studies of malware families, comparisons of how families unpack, and threat-intelligence work that needs configuration data (command-and-control addresses, keys) from many samples all depend on that kind of repeatable capture. For the wider method, see our guide to malware analysis.
Its distinguishing feature is the extraction pipeline. The README lists what CAPE adds to the Cuckoo design: automated dynamic unpacking, YARA classification of the unpacked payloads (see YARA rules), static and dynamic configuration extraction, and a programmable debugger. It also lists an interactive desktop, AMSI payload capture and syscall hooking. Configuration parsers can come from the CAPE framework itself, RATDecoders, DC3-MWCP, MalDuck or MaCo, and the project keeps its parsers in the CAPESandbox/CAPE-parsers repository and community signatures in CAPESandbox/community.
Where CAPE came from
According to the README, the project is derived from Cuckoo v1. Kevin O’Reilly began it in 2015 at Context Information Security, and Andriy Brukhovetskyy (known as doomedraven) ported it to Python 3; CAPEv2 was released in October 2019. If you are choosing between the two, our Cuckoo Sandbox guide covers the parent project.
CAPE versus its Cuckoo origins
| Capability | Inherited from Cuckoo | Added by CAPE |
|---|---|---|
| API-hook behaviour monitoring | Yes | Extended with syscall hooking |
| File capture, PCAP, screenshots, memory dumps, signatures | Yes | No change stated in the README |
| Unpacking of payloads | No | Automated dynamic unpacking |
| Classification of unpacked payloads | No | YARA classification |
| Malware configuration extraction | No | Static and dynamic extraction |
| Analyst tooling | No | Programmable debugger, interactive desktop, AMSI payload capture |
This comparison follows the README’s own lists of inherited and added features; the README is the source for each row.
Install or access
The official source is the CAPEv2 repository and its documentation at capev2.readthedocs.io. The README states the host requirements: Python 3 on the host (tested with 3.10 and 3.12), Ubuntu 24.04 LTS recommended, KVM recommended as the virtualisation layer, and a Windows 10 or Windows 11 23H2 guest recommended as the analysis target. The guest agent, agent.py, was tested on x86 Python 3.7.2 and 3.8. A public demonstration instance exists at capesandbox.com.
The host installation page describes two installer scripts, run in this order:
- Make the virtualisation script executable with
sudo chmod a+x kvm-qemu.sh, then runsudo ./kvm-qemu.sh all USERNAME | tee kvm-qemu.logand reboot. Before running it, replace the WOOT placeholders in the script with hardware identifier patterns; the documentation suggests random four-character strings for a lab. - Make the CAPE script executable with
sudo chmod a+x cape2.sh. Run./cape2.sh -hto see its options, thensudo ./cape2.sh base cape | tee cape.log(orall) and reboot.
The installer sets up four services: cape, cape-processor, cape-web and cape-rooter. Python dependencies are managed with Poetry from /opt/CAPEv2/: run poetry install, list environments with poetry env list, and run CAPE as the cape user with sudo -u cape poetry run python3 cuckoo.py. Optional packages install with sudo -u cape poetry run pip install -r extra/optional_dependencies.txt, and sudo su - cape -c /bin/bash gives you a shell as the cape user.
The documentation is explicit about two rules: “We advise against modifying or updating any package installed by the script”, and only the install scripts and utilities such as rooter.py are run with sudo. CAPE uses rolling updates, so the documentation tells you to pull the repository regularly. For research that needs to be reproduced, record the commit you ran, because a later pull changes the analysis code.
Preparing the Windows guest
The guest-preparation chapter of the documentation covers creating the VM, installing Python and additional software, installing the agent, configuring the network, and saving a snapshot. Its agent page states that the agent must run with elevated privileges, and that agent.py comes from the agent/ directory of the CAPE repository. The agent starts an HTTP server on port 8000; you can confirm it is reachable from the host with curl VM_IP:8000, and the page asks you to test this before saving the snapshot. On Windows the file can be renamed agent.pyw to suppress the console window. Before Windows 10 the file goes in the all-users startup folder (open shell:common startup from the Run dialog); on Windows 10 and later, a scheduled task set to “Run with highest privileges” starts it at logon, and the page warns against the StartUp folder there because the agent would lack the required privileges.
Step-by-step task: submit a sample and collect the result
The submission documentation runs the command-line utility as the cape user from the CAPE directory. Other routes exist: the web interface, the REST API, a distributed CAPE setup, and Python calls to add_path() or add_url().
- Switch to the cape user and change to the CAPE directory, as in the installation steps above.
- Submit a file:
poetry run python utils/submit.py /path/to/binary. To submit a URL instead, use--url http://www.example.com. - Add the options the study needs. The documented ones include
--priority 5,--timeout 60,--machine cape1,--platform windows,--memory(take a full memory dump after the analysis),--enforce-timeoutand--clock "01-24-2001 14:41:20", which uses the %m-%d-%Y %H:%M:%S format. - Pass package-specific settings with
--options, written as comma-separated name=value pairs. For example,--package exe --options arguments=--dosomething /path/to/binary.exeruns the sample as an executable with an argument. - Wait for processing to finish, then open the results folder described below.
Dump options
The most CAPE-specific part of a submission is the set of dump and unpacking options passed through --options. The documentation lists these names: procdump, procmemdump, import-reconstruction (documented as slow), dump-limit (default 10), dump-on-api, dump-config-region, dump-crypto and dump-keys, amsidump, jit-dumps, tlsdump, regdump, store_memdump, and unpacker, where 1 selects passive and 2 selects active unpacking. The remaining injection, extraction, compression and combo settings are documented alongside them. Choose options per research question and write them into your method notes, since they change which artefacts exist afterwards.
Output and how to read it
Each analysis writes to storage/analyses/ID/. The data table below maps every item the results documentation lists. In practice, begin with reports/report.json for machine-readable analysis, or report.html for a readable view, check analysis.log for what the run itself reported, and open files/ for payloads CAPE dumped. The web interface, which pulls from a MongoDB or ElasticSearch database, lets you browse reports and search across all analyses; it needs the matching reporting module enabled in reporting.conf. Where results are used as evidence in a study, pair them with technique mapping such as the MITRE adversary-technique framework rather than relying on raw logs alone.
Troubleshooting
Where to start
Read CAPE’s own logs in /opt/CAPEv2/log/; the current one is cuckoo.log and older logs rotate daily. For virtual-machine problems, read the libvirt logs with sudo journalctl -u virtqemud -r. Then try to reproduce the failure by hand, for example by starting the VM in Virtual Machine Manager, to learn which layer is failing.
No internet connection in the guest
Check, in order: that the network configuration steps were followed (and the per-analysis routing and CAPE Rooter chapters read); that dirtyline in routing.conf names the interface carrying the host’s internet connection (for example eno1) rather than a virtual one such as virbr1; that agent.py runs with elevated privileges in the guest; that the correct static IP is set in kvm.conf; and that the correct interface is set in auxiliary.conf.
No PCAP generated
Confirm the pcap group exists and the cape user belongs to it, set the tcpdump path (find it with whereis tcpdump) in auxiliary.conf, and confirm the cape user can execute it. If it still fails, give the binary the group and capabilities the page shows: sudo chgrp pcap /usr/bin/tcpdump and sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/tcpdump.
Services or packages misbehaving
The installer creates four services (cape, cape-processor, cape-web, cape-rooter), so these are the first things to check when analyses are not processed. The documentation advises against modifying packages the installer put in place, and poetry env list shows the Poetry environments available to the cape user.
Free alternatives
CAPE’s closest relative is its parent, Cuckoo Sandbox, which our guide describes as open source under the GNU General Public License v3. That guide also compares other open-source options in a table, and its Free alternatives section is the place to start if CAPE’s setup (KVM, Windows guest, services) is more than a study needs. For the process that sandbox output feeds, see malware analysis.
Frequently asked questions
What does CAPE stand for?
Malware Configuration And Payload Extraction, per the CAPEv2 README.
Is CAPE the same as Cuckoo Sandbox?
No. CAPE is derived from Cuckoo v1 and keeps its behaviour-monitoring design, but adds automated unpacking, YARA classification of payloads and configuration extraction.
Which operating system does CAPE run on?
The README recommends Ubuntu 24.04 LTS for the host, with Python 3 (tested on 3.10 and 3.12) and KVM, and a Windows 10 or Windows 11 23H2 guest.
Where are the results stored?
In storage/analyses/ID/ on the host, with reports in its reports/ subfolder.
Sources
- CAPEv2 README, github.com/kevoreilly/CAPEv2, read 2026-11-14.
- CAPE host installation, capev2.readthedocs.io/en/latest/installation/host/installation.html, read 2026-11-14.
- CAPE guest agent, capev2.readthedocs.io/en/latest/installation/guest/agent.html, read 2026-11-14.
- CAPE guest troubleshooting, capev2.readthedocs.io/en/latest/installation/guest/troubleshooting.html, read 2026-11-14.
- CAPE submission, capev2.readthedocs.io/en/latest/usage/submit.html, read 2026-11-14.
- CAPE analysis results, capev2.readthedocs.io/en/latest/usage/results.html, read 2026-11-14.
- CAPE web interface, capev2.readthedocs.io/en/latest/usage/web.html, read 2026-11-14.
Data: CAPE Sandbox analysis folder: items and when they exist
Compiled from the CAPE v2 results documentation and README: each item stored under storage/analyses/ID/ and its reports/ subfolder, what it holds and whether it is always written or depends on an option.
| Item | Location | What it holds | Condition |
|---|---|---|---|
| analysis.conf | storage/analyses/ID/ | Internal analysis configuration | Internal use |
| analysis.log | storage/analyses/ID/ | Log of the analysis run | Written for each analysis |
| dump.pcap | storage/analyses/ID/ | Network capture in PCAP format | Depends on PCAP generation working |
| memory.dmp | storage/analyses/ID/ | Full memory dump after the analysis | Only if memory dumping is enabled (--memory) |
| files/ | storage/analyses/ID/ | Dumped files | Written for each analysis |
| logs/ | storage/analyses/ID/ | Raw monitor logs | Written for each analysis |
| shots/ | storage/analyses/ID/ | Screenshots | Written for each analysis |
| report.html | storage/analyses/ID/reports/ | HTML report | Reporting output |
| report.json | storage/analyses/ID/reports/ | JSON report | Reporting output |
| report.maec-4.0.1.xml | storage/analyses/ID/reports/ | MAEC 4.0.1 XML report | Reporting output |
| report.metadata.xml | storage/analyses/ID/reports/ | Metadata XML report | Reporting output |
Sources
- CAPE v2 documentation: analysis results (accessed 2026-11-14)
- CAPE v2 documentation: submitting an analysis (accessed 2026-11-14)
- CAPEv2 README (accessed 2026-11-14)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







