{"id":13705897,"url":"https://github.com/kevoreilly/CAPEv2","last_synced_at":"2025-05-05T17:31:14.194Z","repository":{"id":37498499,"uuid":"215366713","full_name":"kevoreilly/CAPEv2","owner":"kevoreilly","description":"Malware Configuration And Payload Extraction","archived":false,"fork":false,"pushed_at":"2024-10-29T11:04:42.000Z","size":181408,"stargazers_count":1975,"open_issues_count":28,"forks_count":421,"subscribers_count":66,"default_branch":"master","last_synced_at":"2024-10-29T11:57:42.025Z","etag":null,"topics":["cape","configs","debugging-tools","malware","malware-analysis","malware-research","reverse-engineering","sandbox","unpacking"],"latest_commit_sha":null,"homepage":"https://capesandbox.com/analysis/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kevoreilly.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-10-15T18:16:09.000Z","updated_at":"2024-10-29T11:14:20.000Z","dependencies_parsed_at":"2023-12-25T22:22:16.083Z","dependency_job_id":"6ed634d1-d3f4-4317-a595-d97dc93ac6eb","html_url":"https://github.com/kevoreilly/CAPEv2","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevoreilly%2FCAPEv2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevoreilly%2FCAPEv2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevoreilly%2FCAPEv2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevoreilly%2FCAPEv2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kevoreilly","download_url":"https://codeload.github.com/kevoreilly/CAPEv2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224191823,"owners_count":17271137,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cape","configs","debugging-tools","malware","malware-analysis","malware-research","reverse-engineering","sandbox","unpacking"],"created_at":"2024-08-02T22:00:49.429Z","updated_at":"2024-11-13T13:31:05.587Z","avatar_url":"https://github.com/kevoreilly.png","language":"Python","readme":"## CAPE: Malware Configuration And Payload Extraction - [Documentation](https://capev2.readthedocs.io/en/latest/#)\n\n### CAPE is a malware sandbox.\nA sandbox is used to execute malicious files in an isolated environment\nwhilst instrumenting their dynamic behaviour and collecting forensic artefacts.\n\nCAPE was derived from Cuckoo v1 which features the following core capabilities\non the Windows platform:\n\n* Behavioral instrumentation based on API hooking\n* Capture of files created, modified and deleted during execution\n* Network traffic capture in PCAP format\n* Malware classification based on behavioral and network signatures\n* Screenshots of the desktop taken during the execution of the malware\n* Full memory dumps of the target system\n\nCAPE complements Cuckoo's traditional sandbox output with several key additions:\n\n* Automated dynamic malware unpacking\n* Malware classification based on YARA signatures of unpacked payloads\n* Static \u0026 dynamic malware configuration extraction\n* Automated debugger programmable via YARA signatures, allowing:\n    * Custom unpacking/config extractors\n    * Dynamic anti-sandbox countermeasures\n    * Instruction traces\n* Interactive desktop\n\nThere is a free demonstration instance online that anyone can use:\n\nhttps://capesandbox.com - For account activation reach to https://twitter.com/capesandbox\n\n### Some History\n\nCuckoo Sandbox started as a Google Summer of Code project in 2010 within\nThe Honeynet Project. It was originally designed and developed by Claudio\nGuarnieri, the first beta release was published in 2011. In January 2014,\nCuckoo v1.0 was released.\n\n2015 was a pivotal year, with a significant fork in Cuckoo's history.\nDevelopment of the original monitor and API hooking method was halted in the\nmain Cuckoo project. It was replaced by an [alternative monitor](https://github.com/cuckoosandbox/monitor)\nusing a ``restructuredText``-based signature format compiled via Linux toolchain,\ncreated by Jurriaan Bremer.\n\nAround the same time, a fork called [Cuckoo-modified](https://github.com/spender-sandbox/cuckoo-modified)\nwas created by Brad 'Spender' Spengler continuing development of the original\nmonitor with significant improvements including 64-bit support and importantly\nintroducing Microsoft's Visual Studio compiler.\n\nDuring that same year development of a dynamic command-line configuration and payload\nextraction tool called CAPE was begun at Context Information Security by Kevin O'Reilly.\nThe name was coined as an acronym of 'Config And Payload Extraction' and the original\nresearch focused on using API hooks provided by Microsoft's [Detours](https://github.com/microsoft/Detours)\nlibrary to capture unpacked malware payloads and configuration. However, it became\napparent that API hooks alone provide insufficient power and precision to allow for\nunpacking of payloads or configs from arbitrary malware.\n\nFor this reason research began into a novel debugger concept to allow malware to be\nprecisely controlled and instrumented whilst avoiding use of Microsoft debugging\ninterfaces, in order to be as stealthy as possible. This debugger was integrated\ninto the proof-of-concept Detours-based command-line tool, combining with API hooks\nand resulting in very powerful capabilities.\n\nWhen initial work showed that it would be possible to replace Microsoft Detours\nwith Cuckoo-modified's [API hooking engine](https://github.com/spender-sandbox/cuckoomon-modified),\nthe idea for CAPE Sandbox was born. With the addition of the debugger, automated unpacking,\nYARA-based classification and integrated config extraction, in September 2016 at 44con, CAPE Sandbox was\npublicly released for the first time: [CAPE](https://github.com/ctxis/CAPE) version 1.\n\nIn the summer of 2018 the project was fortunate to see the beginning of huge\ncontributions from Andriy 'doomedraven' Brukhovetskyy, a long-time Cuckoo\ncontributor. In 2019 he began the mammoth task of porting CAPE to Python 3\nand in October of that year [CAPEv2](https://github.com/kevoreilly/CAPEv2) was released.\n\nCAPE has been continuously developed and improved to keep pace with advancements\nin both malware and operating system capabilities. In 2021, the ability to program\nCAPE's debugger during detonation via dynamic YARA scans was added, allowing for\ndynamic bypasses to be created for anti-sandbox techniques. Windows 10 became the\ndefault operating system, and other significant additions include interactive desktop,\nAMSI (Anti-Malware Scan Interface) payload capture, 'syscall hooking' based on Microsoft\nNirvana and debugger-based direct/indirect syscall countermeasures.\n\n### Classification\n![image](https://github.com/kevoreilly/CAPEv2/assets/22219888/15b34a87-6b2a-49bd-a58a-d16d5fee438e)\n\nMalware can be classified in CAPE via three mechanisms:\n* YARA scans of unpacked payloads\n* Suricata scans of network captures\n* Behavioral signatures scanning API hook output\n\n### Config Extraction\n\n![image](https://github.com/kevoreilly/CAPEv2/assets/22219888/a44f2f8a-10df-47cc-9690-5ef08f04ea6b)\n\nParsing can be done using CAPE's own framework, alternatively the following frameworks are supported: [RATDecoders](https://github.com/kevthehermit/RATDecoders), [DC3-MWCP](https://github.com/Defense-Cyber-Crime-Center/DC3-MWCP), [MalDuck](https://github.com/CERT-Polska/malduck/tree/master/malduck/), or [MaCo](https://github.com/CybercentreCanada/maco)\n\n#### Special note about config parsing frameworks:\n* Due to the nature of malware, since it changes constantly when any new version is released, something might become broken!\n* 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.\n    * As a bonus, you can reuse your extractors in other projects.\n\n### Automated Unpacking\n![image](https://github.com/kevoreilly/CAPEv2/assets/22219888/090ce3fb-9dc8-4316-bc20-469c6fff725a)\n\nCAPE takes advantage of many malware techniques or behaviours to allow for unpacked payload capture:\n- Process injection\n    - Shellcode injection\n    - DLL injection\n    - Process Hollowing\n    - Process Doppelganging\n- Extraction or decompression of executable modules or shellcode in memory\n\nThese behaviours 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.\n\nIn 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.\n\nCAPE 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-derived packers dynamically via custom 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.\n\n![image](https://github.com/kevoreilly/CAPEv2/assets/22219888/daf702c8-a658-48fe-850a-d86f0a89dc82)\n\n![image](https://github.com/kevoreilly/CAPEv2/assets/22219888/76b2c800-1d96-4ea5-ae86-c261b3946424)\n\nThe `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`).\n\n### [Debugger](https://capev2.readthedocs.io/en/latest/usage/monitor.html)\nThe debugger has allowed CAPE to continue to evolve beyond its original capabilities, which now include dynamic anti-evasion bypasses. Since modern malware commonly tries to evade analysis within sandboxes, for example by using timing traps for virtualisation or API hook detection, CAPE allows dynamic countermeasures to be developed combining debugger actions within Yara signatures to detect evasive malware as it detonates, and perform control-flow manipulation to force the sample to detonate fully or skip evasive actions.\n\n![image](https://github.com/kevoreilly/CAPEv2/assets/22219888/801fb4d3-2569-44aa-b40e-d3d5cc7d8bb3)\n![image](https://github.com/kevoreilly/CAPEv2/assets/22219888/d76da82f-38b7-4cdf-ad9d-f16e8d2dfa66)\n\nQuick access to the debugger is made possible with the submission options `bp0` through `bp3` accepting RVA or VA values to set breakpoints, whereupon a short instruction trace will be output, governed by `count` and `depth` options (e.g. `bp0=0x1234,depth=1,count=100`).\n![image](https://github.com/kevoreilly/CAPEv2/assets/22219888/6aa3d31e-cd52-4549-997f-734fb755f10b)\n\nTo 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 RVA breakpoints to be set by API call (e.g. `base-on-api=NtReadFile,bp0=0x2345`).\n\n![image](https://github.com/kevoreilly/CAPEv2/assets/22219888/3acfbde2-68e1-479d-a829-0c9142fb1be7)\n\nOptions `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`). CAPE`s documentation contains further examples of such actions.\n\n### [capemon](https://github.com/kevoreilly/capemon)\nThe repository containing the code for the CAPE's monitor is distinct.\n\n### Updates summary [changelog](https://github.com/kevoreilly/CAPEv2/blob/master/changelog.md)\n\n### [Community contributions](https://github.com/CAPESandbox/community)\nThere is a community repository of signatures containing several hundred signatures developed 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.\n\nPlease 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.\n\nA huge thank you to @D00m3dR4v3n for single-handedly porting CAPE to Python 3.\n\n## Installation recommendations and scripts for optimal performance\n* Python3\n    * agent.py is tested with python (3.7.2|3.8) x86. __You should use x86 python version inside of the VM!__\n    * host tested with python3 version 3.7, 3.8, 3.10, but newer versions should work too\n\n* __Only rooter should be executed as root__, the rest as __cape__ user. Running as root will mess with permissions.\n1. Become familiar with the [documentation](https://capev2.readthedocs.io/en/latest/) and __do read ALL__ config files inside of `conf` folder!\n2. For best compabitility we strongly suggest installing on [Ubuntu 22.04 LTS](https://ubuntu.com/#download) and using Windows 10 21H2 as target.\n3. `kvm-qemu.sh` and `cape2.sh` __SHOULD BE__ executed from `tmux` session to prevent any OS problems if ``ssh`` connections breaks.\n4. [KVM](https://github.com/kevoreilly/CAPEv2/blob/master/installer/kvm-qemu.sh) is recommended as the hypervisor.\n * Replace `\u003cusername\u003e` with a real pattern.\n * You need to replace all `\u003cWOOT\u003e` inside!\n * Read it! You must understand what it does! It has configuration in header of the script.\n * `sudo ./kvm-qemu.sh all \u003cusername\u003e 2\u003e\u00261 | tee kvm-qemu.log`\n4. To install CAPE itself, [cape2.sh](https://github.com/kevoreilly/CAPEv2/blob/master/installer/cape2.sh) with all optimizations\n    * Read and understand what it does! This is not a silver bullet for all your problems! It has configuration in header of the script.\n    * `sudo ./cape2.sh base 2\u003e\u00261 | tee cape.log`\n5. After installing everything save both installation logs as gold!\n6. Configure CAPE by doing mods to config files inside `conf` folder.\n7. Restart all CAPE services to pick config changes and run CAPE properly!\n    * CAPE Services\n        * cape.service\n        * cape-processor.service\n        * cape-web.service\n        * cape-rooter.service\n        * To restart any service use `systemctl restart \u003cservice_name\u003e`\n        * To see service log use `journalctl -u \u003cservice_name\u003e`\n    * 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.\n5. Reboot and enjoy!\n\n\n* All scripts contain __help__ `-h`, but please check the scripts to __understand__ what they are doing.\n\n\n### How to create VMs with virt-manager see docs for configuration\n* [step by step](https://www.doomedraven.com/2020/04/how-to-create-virtual-machine-with-virt.html)\n\n## Virtual machine core dependency\n* [choco.bat](https://github.com/kevoreilly/CAPEv2/blob/master/installer/choco.bat)\n\n## How to update\n* CAPE: `git pull`\n* community: `python3 utils/community.py -waf` see `-h` before to ensure you understand\n\n## How to upgrade with a lot of custom small modifications that can't be public?\n\n#### With rebase\n```\ngit add --all\ngit commit -m '[STASH]'\ngit pull --rebase origin master\n# fix conflict (rebase) if needed\ngit reset HEAD~1\n```\n\n#### With merge\n```\n# make sure kevoreilly repo has been added as a remote (only needs to be done once)\ngit remote add kevoreilly https://github.com/kevoreilly/CAPEv2.git\n# make sure all your changes are commited on the branch which you will be merging\ngit commit -a -m '\u003cyour commit message goes here\u003e'\n# fetch changes from kevoreilly repo\ngit fetch kevoreilly\n# merge kevoreilly master branch into your current branch\ngit merge kevoreilly/master\n# fix merge conflicts if needed\n# push to your repo if desired\ngit push\n```\n\n### How to cite this work\nIf you use CAPEv2 in your work, please cite it as specified in the \"Cite this repository\" GitHub menu.\n\n### Special note about 3rd part dependencies:\n* They becoming a headache, specially those that using `pefile` as each pins version that they want.\n    * Our suggestion is clone/fork them, remove `pefile` dependency as you already have it installed. Volia no more pain.\n\n### Docs\n* [ReadTheDocs](https://capev2.readthedocs.io/en/latest/#)\n","funding_links":[],"categories":["Synopsis","IR Tools Collection","Tools","\u003ca id=\"tag-dev\" href=\"#tag-dev\"\u003eDev\u003c/a\u003e","Other Lists","Blue Team","Python"],"sub_categories":["Table of Contents","Sandboxing/Reversing Tools","\u003ca id=\"tag-dev.security\" href=\"#tag-dev.security\"\u003eSecurity\u003c/a\u003e","🧪 LAB","Malware Analysis"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevoreilly%2FCAPEv2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkevoreilly%2FCAPEv2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevoreilly%2FCAPEv2/lists"}