Skip to main content
v2026.11,986 entries · CC-BY 4.0

CAPE Sandbox: Install, Submit and Read Malware Analysis Results

CAPE Sandbox runs malware in an isolated VM and extracts payloads and configs. Install, submit, read results and fix common faults, from the official docs.

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:

  1. Make the virtualisation script executable with sudo chmod a+x kvm-qemu.sh, then run sudo ./kvm-qemu.sh all USERNAME | tee kvm-qemu.log and 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.
  2. Make the CAPE script executable with sudo chmod a+x cape2.sh. Run ./cape2.sh -h to see its options, then sudo ./cape2.sh base cape | tee cape.log (or all) 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().

  1. Switch to the cape user and change to the CAPE directory, as in the installation steps above.
  2. Submit a file: poetry run python utils/submit.py /path/to/binary. To submit a URL instead, use --url http://www.example.com.
  3. 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-timeout and --clock "01-24-2001 14:41:20", which uses the %m-%d-%Y %H:%M:%S format.
  4. Pass package-specific settings with --options, written as comma-separated name=value pairs. For example, --package exe --options arguments=--dosomething /path/to/binary.exe runs the sample as an executable with an argument.
  5. 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.

CAPE Sandbox analysis folder: items and when they exist
ItemLocationWhat it holdsCondition
analysis.confstorage/analyses/ID/Internal analysis configurationInternal use
analysis.logstorage/analyses/ID/Log of the analysis runWritten for each analysis
dump.pcapstorage/analyses/ID/Network capture in PCAP formatDepends on PCAP generation working
memory.dmpstorage/analyses/ID/Full memory dump after the analysisOnly if memory dumping is enabled (--memory)
files/storage/analyses/ID/Dumped filesWritten for each analysis
logs/storage/analyses/ID/Raw monitor logsWritten for each analysis
shots/storage/analyses/ID/ScreenshotsWritten for each analysis
report.htmlstorage/analyses/ID/reports/HTML reportReporting output
report.jsonstorage/analyses/ID/reports/JSON reportReporting output
report.maec-4.0.1.xmlstorage/analyses/ID/reports/MAEC 4.0.1 XML reportReporting output
report.metadata.xmlstorage/analyses/ID/reports/Metadata XML reportReporting output

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about CAPE Sandbox: Install, Submit and Read Malware Analysis Results

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →