CAPEv2 - Malware Configuration And Payload Extraction

项目说明

CAPE: Malware Configuration And Payload Extraction - Documentation

CAPE is a malware sandbox.

A sandbox is used to execute malicious files in an isolated en
whilst instrumenting their dynamic behaviour and collecting forensic artefacts.

CAPE was derived from Cuckoo v1 which features the following core capabilities
on the Windows platform:

* Beha instrumentation based on API hooking
* Capture of files created, modified and deleted during execution
* Network traffic capture in PCAP format
* Malware classification based on beha and 网络 signatures
* Screenshots of the desktop taken during the execution of the malware
* Full memory dumps of the target system

CAPE complements Cuckoo's traditional sandbox output with several key additions:

* Automated dynamic malware unpacking
* Malware classification based on YARA signatures of unpacked payloads
* Static & dynamic malware configuration extraction
* Automated debugger programmable via YARA signatures, allowing:
* Custom unpacking/config extractors
* Dynamic anti-sandbox countermeasures
* Instruction traces
* Interacti

There is a free demonstration instance online that anyone can use:

- For account acti reach to

Some History

Cuckoo Sandbox started as a Google Summer of 代码 project in 2010 within
The Honeynet Project. It was originally designed and de by Claudio
Guarnieri, the first beta release was published in 2011. In January 2014,
Cuckoo v1.0 was released.

2015 was a pivotal year, with a significant fork in Cuckoo's history.
De of the original monitor and API hooking method was halted in the
main Cuckoo project. It was replaced by an alternati
using a `restructuredText-based signature format compiled toolchain,
created by Jurriaan Bremer.

Around the same time, a fork called Cuckoo-modified
was created by Brad 'Spender' Spengler continuing de of the original
monitor with significant impro including 64-bit support and importantly
introducing Microsoft's Studio compiler.

During that same year de of a dynamic command-line configuration and payload
extraction tool called CAPE was begun at Context Information Security by Kevin O'Reilly.
The name was coined as an acronym of 'Config And Payload Extraction' and the original
research focused on using API hooks provided by Microsoft's Detours
library to capture unpacked malware payloads and configuration. However, it became
apparent that API hooks alone provide insufficient power and precision to allow for
unpacking of payloads or configs from arbitrary malware.

For this reason research began into a no concept to allow malware to be
precisely controlled and instrumented whilst a use of Microsoft debugging
interfaces, in order to be as stealthy as possible. This debugger was integrated
into the proof-of-concept Detours-based command-line tool, combining with API hooks
and resulting in very powerful capabilities.

When initial work showed that it would be possible to replace Microsoft Detours
with Cuckoo-modified's API hooking engine,
the idea for CAPE Sandbox was born. With the addition of the debugger, automated unpacking,
YARA-based classification and integrated config extraction, in September 2016 at 44con, CAPE Sandbox was
publicly released for the first time: CAPE 1.

In the summer of 2018 the project was fortunate to see the beginning of huge
contributions from Andriy 'doomedraven' Brukho, a long-time Cuckoo
contributor. In 2019 he began the mammoth task of porting CAPE to Python 3
and in October of that year CAPEv2 was released.

CAPE has been continuously de and improved to keep pace with ad
in both malware and operating system capabilities. In 2021, the ability to program
CAPE's debugger during detonation YARA scans was added, allowing for
dynamic bypasses to be created for anti-sandbox techniques. Windows 10 became the
default operating system, and other significant additions include interacti,
AMSI (Anti-Malware Scan Interface) payload capture, 'syscall hooking' based on Microsoft
Nirvana and debugger-based direct/indirect syscall countermeasures.

In 2024 enzok created CAPEsolo, an interacti desktop of CAPE,
using wxPython for the graphical interface, as well as introducing 64-bit guest Python compatibility.
In 2026, support for added for all Windows 10 and Windows 11 23H2.

Classification

!image

Malware can be classified in CAPE mechanisms:
* YARA scans of unpacked payloads
* Suricata scans of network captures
* Beha signatures scanning API hook output

Config Extraction

!image

Parsing can be done using CAPE's own framework, alternatively the following frameworks are supported: RATDecoders, DC3-MWCP, MalDuck, or MaCo

#### CAPE-parsers

CAPE's core and community configuration parsers are maintained in the separate
CAPE-parsers repository and installed
as the CAPE-parsers dependency. Submit additions and fixes to those parsers
there; its README describes the expected configuration fields.

#### Special note about config parsing frameworks:
* Due to the nature of malware, since it changes constantly when any new is released, something might become broken!
* We suggest using CAPE's framework which is simply pure Python with entry point def extract_config(data): that will be called by cape_utils.py and 0 complications.
* As a bonus, you can reuse your extractors in other projects.

Automated Unpacking

!image

CAPE takes ad of many malware techniques or beha to allow for unpacked payload capture:

Process injection

- Shellcode injection
- DLL injection
- Process Hollowing
- Process Doppelganging

Extraction or decompression of executable modules or shellcode in memory

These beha will result in the capture of payloads being injected, extracted, or decompressed for further analysis. In addition CAPE automatically creates a process dump for each process, or, in the case of a DLL, the DLL's module image in memory. This is useful for samples packed with simple packers, where often the module image dump is fully unpacked.

In addition to CAPE's default 'passive' unpacking mechanisms, it is possible to enable 'active' unpacking which uses breakpoints to detect writing to newly allocated or protected memory regions, in order to capture unpacked payloads as early as possible prior to execution. This is enabled via web submission tickbox or by specifying option unpacker=2 and is left off by default as it may impact detonation quality.

CAPE can be programmed via YARA signature to unpack specific packers. For example, UPX-type packers are very common and, although in CAPE these result in unpacked payloads being passively captured, the default capture is made after the unpacked payload has begun executing. Therefore by detecting UPX-deri dynamically YARA signature and setting a breakpoint on the final packer instruction, it is possible to capture the payload at its original entry point (OEP) before it has begun executing.

!image

!image

The dump-on-api option allows a module to be dumped when it calls a specific API function that can be specified in the web interface (e.g. dump-on-api=DnsQuery_A).

Debugger

The debugger has allowed CAPE to continue to evol its original capabilities, which now include dynamic anti-e bypasses. Since modern malware commonly tries to evade analysis within sandboxes, for example by using timing traps for or API hook detection, CAPE allows dynamic countermeasures to be de combining debugger actions within Yara signatures to detect e malware as it detonates, and perform control-flow manipulation to force the sample to detonate fully or skip e actions.

!image
!image

Quick access to the debugger is made possible with the submission options bp0 through bp3 accepting RVA or to set breakpoints, whereupon a short instruction trace will be output, go by count and depth options (e.g. bp0=0x1234,depth=1,count=100).
!image

To set a breakpoint at the module entry point, ep is used instead of an address (e.g. bp0=ep). Alternatively break-on-return allows for a breakpoint on the return address of a hooked API (e.g. break-on-return=NtGetContextThread). An optional base-on-api parameter allows the image base for R to be set by API call (e.g. base-on-api=NtReadFile,bp0=0x2345).

!image

Options action0 - action3 allow actions to be performed when breakpoints are hit, such as dumping memory regions (e.g. action0=dumpebx) or changing the execution control flow (e.g. action1=skip). CAPEs documentation contains further examples of such actions.

capemon

The repository containing the 代码 for the CAPE's monitor is distinct.

Updates summary changelog

Community contributions

There is a community repository of signatures containing several hundred signatures de by the CAPE community. All new community feature should be pushed to that repo. Later they can be moved to core if devs are able and willing to maintain them.

Please contribute to this project by helping create new signatures, parsers, or bypasses for further malware families. There are many in the works currently, so watch this space.

A huge thank you to for single-handedly porting CAPE to Python 3.

Installation recommendations and scripts for optimal performance

* Python3
* agent.py is tested with python (3.7.2|3.8) x86. __You should use x86 python inside of the VM!__
* host tested with python3 3.10, 3.12, but newer should work too

* __Only rooter should be executed as root__, the rest as __cape__ user. Running as root will mess with permissions.
1. Become familiar with the documentation and __do read ALL__ config files inside of conf folder!
2. For best compabitility we strongly suggest installing on Ubuntu 24.04 LTS and using Windows 10 or Windows 11 23H2 as target.
3. k.sh and cape2.sh __SHOULD BE__ executed from tmux session to prevent any OS problems if `ssh connections breaks.
4. KVM is recommended as the hypervisor.
* Replace <username> with a real pattern.
* You need to replace all <WOOT> inside!
* Read it! You must understand what it does! It has configuration in header of the script.
* sudo ./k.sh all <username> 2>&1 | tee k.log
4. To install CAPE itself, cape2.sh with all optimizations
* Read and understand what it does! This is not a sil for all your problems! It has configuration in header of the script.
* sudo ./cape2.sh base 2>&1 | tee cape.log
5. After installing e save both installation logs as gold!
6. Configure CAPE by doing mods to config files inside conf folder.
7. Restart all CAPE services to pick config changes and run CAPE properly!
* CAPE Services
* cape.service
* cape-processor.service
* cape-web.service
* cape-rooter.service
* To restart any service use systemctl restart <ser>
* To see service log use journalctl -u <ser>
* To debug any problem, stop the relevant service and run the command that runs that service by hand to see more logs. Check -h for the help menu. Running the service in debug mode (-d) can help as well.
5. Reboot and enjoy!

* All scripts contain __help__ -h, but please check the scripts to __understand__ what they are doing.

How to create VMs with see docs for configuration

* step by step

machine core dependency

* choco.bat

How to update

* CAPE: git pull
* community: python3 utils/community.py -waf see -h before to ensure you understand

How to upgrade with a lot of custom small modifications that can't be public?

#### With rebase

#### With merge

How to cite this work

If you use CAPEv2 in your work, please cite it as specified in the "Cite this repository" GitHub menu.

Special note about 3rd part dependencies:

* They becoming a headache, specially those that using pefile as each pins that they want.
* Our suggestion is clone/fork them, remove pefile` dependency as you already have it installed. Volia no more pain.

Docs

* ReadTheDocs
* DeepWiki - AI generated, some might be wrong but generally pretty accurate.

项目信息

开发语言：Python

Star 数：3552

技术要点

该项目属于黑客技术方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Malware Configuration And Payload Extraction展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。