Extending Cuckoo Framework


Extending Cuckoo Framework

As previously published in Automating Malware Analysis with Cuckoo [1]it was demonstrated how to install the Cuckoo sandbox malware analysis system and basic usage. In short this framework allows for automated analysis of malicious specimens within a controlled environment. In this article we will describe some of the advanced features, extending the platforms capabilities and demonstrate how to tie all this analysis into a single report.


Cuckoo Sandbox is an application that provides a virtual sandbox for the automatic analysis of malware specimens. Originally developed by Claudio Guarnieri for the Google Summer of Code, the project became so popular it is now a mainstay of the Honeynet Project, a leading international research institution with a special focus on malware. The platform allows for the automatic capture and advanced analysis of dangerous strains of malware in a contained environment [2]. If you haven’t installed this previously, or don’t have a working copy of Cuckoo please refer to the reference section to prepare your system [1].

Being a completely python developed framework, this platform is extremely powerful and flexible. It can be installed on almost any operating system and with its open-source roots it can be customized to fit any individual or organizational needs. These customizations come in the form of processing modules, signatures and reporting modules.

Processing Modules

Cuckoo’s processing modules are Python scripts that let you define custom ways to analyze the raw results generated by the sandbox and append some information to a global container that will be later used by the signatures and the reporting modules [3].

The currently available default processing modules are:

  1. AnalysisInfo(modules/processing/analysisinfo.py) - generates some basic information on the current analysis, such as timestamps, version of Cuckoo and so on.
  2. BehaviorAnalysis(modules/processing/behavior.py) - parses the raw behavioral logs and perform some initial transformations and interpretations, including the complete processes tracing, a behavioral summary and a process tree.
  3. Debug(modules/processing/debug.py) - includes errors and the analysis.log generated by the analyzer.
  4. Dropped(modules/processing/dropped.py) - includes information on the files dropped by the malware and dumped by Cuckoo.
  5. NetworkAnalysis(modules/processing/network.py) - parses the PCAP file and extract some network information, such as DNS traffic, domains, IPs, HTTP requests, IRC and SMTP traffic.
  6. StaticAnalysis(modules/processing/static.py) - performs some static analysis of PE32 files.
  7. Strings(modules/processing/static.py) - extracts strings from the analyzer binary.
  8. TargetInfo(modules/processing/targetinfo.py) - includes information on the analyzed file, such as hashes.
  9. VirusTotal(modules/processing/virustotal.py) - lookup VirusTotal.com for AntiVirus signatures of the analyzed file.


With Cuckoo you’re able to create some customized signatures that you can run against the analysis results in order to identify some predefined pattern that might represent a particular malicious behavior or an indicator you’re interested in. These signatures are very useful to give a context to the analyses: both because they simplify the interpretation of the results as well as for automatically identifying malwares of interest [4].

An open repository exists for individual contributors to upload custom signatures to enhance the platform, located on Github (https://github.com/cuckoobox/community). Cuckoo provides a mechanism to download new updates submitted to this repository through a script located in “/opt/cuckoo/utils”.

This script has a couple of arguments of importance is the “-a -f and -w” which indicate to download everything, force install, and rewrite existing files respectably.


 Figure 1 – community.py update script

Writing custom signatures is also supported. This is demonstrated perfectly by Xavier who wrote a blog post indicating how to cross-reference if your malware specimen was communicating with known malwaredomain.com url [5].

To install any custom signature make sure to copy/create your signature in the “/opt/cuckoo/modules/signatures” directory. Any new signature won’t be loaded until the application framework is reloaded.


Another powerful feature of Cuckoo is the ability to utilize the Yara framework. YARA is a tool aimed at helping malware researchers to identify and classify malware samples. With YARA you can create descriptions of malware families based on textual or binary patterns contained on samples of those families. Each description consists of a set of strings and a Boolean expression, which determines its logic [6].

Large communities of malware researchers are consistently creating signatures to combat and identify malware stands. As an open source framework you have the ability to create your own signatures. A great starting resource for finding yara signatures is deependresearch.org [7]. This site contains numerous links to research into this platform. Another good site includes AlianVault [8] who created a yara signature to detect any activity from malware communicating with APT1 domains, previously identified by Mandiant [9].

When downloading or creating new yara signatures you want to ensure they are located in the following directory: “/opt/cuckoo/data/yara”.


Figure 2 – yara signatures

Reporting Modules

After the analysis raw results have been processed and abstracted by the processing modules and the global container is generated, it is passed over by Cuckoo to all the reporting modules available, which will make some use of it and will make it accessible and consumable in different formats [10].

[membership level="1,2,3,4,5,6,7,8"]

Using Cuckoo

With all the additional custom and/or downloaded processing modules, signatures and reporting modules installed let’s launch cuckoo and analyze some malware. At the root of your install directory you have a python script named “cuckoo.py” this is the framework application launcher. The application provides a couple arguments, of which I primarily use –d to invoke “debug messages”. This is useful to display additional messages from the framework and indicate if errors are received from any additions to the platform.

Untitled Figure 3 – cuckoo.py arguments

Once finished loading you will notice “INFO: Waiting for analysis tasks…” if you don’t see this message you have to revert to the documentation and correct any error received before continuing. Once completed, you’re ready to submit malware.

Submitting malware is achievable by executing a python script located in “/opt/cuckoo/util/” named submit.py

In it’s basic format the following examples are used for submit malware specimens, advanced features can be found in the official documentation [11]:

submit a local binary:
$ ./utils/submit.py /path/to/binary

submit an URL:
$ ./utils/submit.py --url http://www.example.com

Luckily for me I received a malware specimen from an email message to test. If you don’t have a specimen file head over to malwaredomains.com and utilize a malicious URL

After submission, your virtual machine will boot-up and star the analysis process. During this time various windows may appear within the VM – please DO NOT INTERACT with the VM, allow the process to complete.


Figure 4 – submitting malware to cuckoo

Once the process is completed the virtual machine will close and your terminal prompt will indicate that the post analysis is started. This is where your signatures will be utilized and compared against the malware analysis and written to your report.

Untitled Figure 4 – cuckoo post processing, report generation

Once the post analysis is completed a report will be generated in the director “opt/cuckoo/storage/analysis/#/reports/” where the # is substituted for the taskID. Each malware specimen submitted is incremental.

Upon opening the report you will notice towards the top the Yara results, and matched signatures (if any) as well as any additional analysis obtained


Figure 5 – cuckoo report results

Also contained within this directory are the binary files dropped, memory dump screenshots, log files and network communication traffic dump for offline analysis.


Malware analysis is a time consuming process. It takes a highly skilled individual to dedicate the time and resources to accurately re-create the timeline, attack vectors, and impact to computing resources. Utilizing a framework outlined above could aid in the discovery of advanced malware and allow faster remediation to protect corporate assets.


Cuckoo framework configured on your host machine – host machine

Virtual machine available and configured for testing – guest machine

Malware specimen and/or access to malware domains

What you need to know

    1. How to use *nix based operating systems, including installing and configuring applications

    2. How to operate virtual box or any other virtual platform

    3. General Windows system administration

    4. Fundamental understanding of TCP/IP communication

Authors Bio

Christopher Ashby, Principle IT Security Analyst at GLOBALFOUNDRIES, has more than 15 years of proven experience participating in a broad range of corporate initiatives including architecting, engineering, and operating information-security solutions in direct support of business objectives. In his most current role he serves alongside a team of engineers responsible for the security of a large global organization. For specific information on the author or to contact him please visit his LinkedIn profile [http://www.linkedin.com/in/ashbyca]


[1] Pentester’s Development Kit – PenTest Regular 05/2013 - https://pentestmag.com/pentesters-development-kit-pentest-regular-052013/

[2] About Cuckoo - http://www.cuckoosandbox.org/about.html

[3] Cuckoo Processing Modules - http://docs.cuckoosandbox.org/en/latest/customization/processing/

[4] Cuckoo Signatures - http://docs.cuckoosandbox.org/en/latest/customization/signatures/

[5] Creating Customer Cuckoo Signatures –


[6] Yara - http://code.google.com/p/yara-project/

[7] Deependresearch -


[8] AlianVault Yara Signatures - http://www.alienvault.com/open-threat-exchange/blog/yara-rules-for-apt1-comment-crew-malware-arsenal

[9] Mandiant APT1 Report - https://www.mandiant.com/blog/mandiant-exposes-apt1-chinas-cyber-espionage-units-releases-3000-indicators/

[10] Cuckoo Reporting Modules - http://docs.cuckoosandbox.org/en/latest/customization/reporting/

[11] Cuckoo Submit Documentation - https://cuckoo.readthedocs.org/en/latest/usage/submit/index.html?highlight=submit


To Read the Full article please login or register with a FREE account.

March 12, 2015
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments

© HAKIN9 MEDIA SP. Z O.O. SP. K. 2013