This is all based off the official documentation and self exploration.

Ahh! This is a necro post from previous blog dump.

Structure

./agent = The networking agent to communicate with guest VM's
./analyzer = Files used to analyze the guest VM (analysis packages)
./build = Build files made by Cuckoo
./conf = Files for configuration
./data = Data files used by web interface and analysis (things like file signatures)
./db = Databases
./docs = Documentation. Also found online.
./lib = Library files used by cuckoo core and such
./log = Cuckoo core log files
./modules = modules used to customize and make all the functionality in cuckoo sandbox

  • auxiliary - other, things like tcpdumping
  • machinery - guest VM specific things
  • processing - the actual analysis stuff, like networking and memory accesses
  • signatures - seems to check or file signatures to label things properly
  • reporting - used for reporting of the data gathered

./storage = analysis logs and malware binaries
./utils = some useful utilities to help, mainly web.py and submit.py
./web = stuff used by web.py to make the web interface

Useful information for analysis

Local analysis
submit.py --timeout <SPECIFY ANALYSIS TIMEOUT>  
          --machine <SPECIFY THE IDENTIFIER OF A MACHINE YOU WANT TO USE>
          --memory (enable to take memory dump of analysis machine)
          --pattern <PATTERN OF FILES TO SUBMIT>
          --unique (enable to only submit new samples, ignore dupes)

If you specify a directory as path, all the files contained in it will be submitted for analysis.

cuckoo.py --clean # to clean up analysis results and current scheduled tasks  

Information for customization

Auxiliary Modules

https://cuckoo.readthedocs.org/en/latest/customization/auxiliary/
Aux modules define procedures that are executed in parallel with each analysis process. The default one is starting tcpdump before the start of each malware analysis. This can be expanded into something interesting like checking if a file was edited during the malware execution.

Analysis Packages

The default analysis package for Windows is at ./analyzer/windows/packages/exe.py.

It essentially runs a dll or exe on the VM, injects it using the API Hook DLL (./analyzer/windows/dlls/cuckoomon.dll). It then checks if the option to do a memory dump is set or not. The interesting part for me is the API hooking which is done using the Cuckoo Monitor. More on this will probably come in another post.

def execute(self, path, args):  
        dll = self.options.get("dll")
        ...
        p = Process()
        if not p.execute(path=path, args=args, suspended=suspended):
            raise CuckooPackageError("Unable to execute the initial process, "
                                     "analysis aborted.")
        ...                            
        p.inject(dll)
        ...
        return p.pid

    def finish(self):
        if self.options.get("procmemdump"):
            ...
        return True

Cuckoo has capability to edit a few interesting events:

  • start() - Executed at the start of analysis
  • check() - Executed every 1 second while malware is running
  • execute() - Called to do the actual execution of the malware
  • finish() - Executed at the end of the analysis

Official documentation: https://cuckoo.readthedocs.org/en/latest/customization/packages/

Processing Modules

The processing modules are used to create the "global container" which contains all the data recorded during the malware analysis. After an analysis is completed, Cuckoo will invoke all the processing modules available in the ./modules/processing/ directory. They can be enabled/disabled in ./conf/processing.conf.

Every module is initialized and executed and the data returned is appended to a data structure known as the "global container", which is a big simple Python dictionary.

Official documentation: https://cuckoo.readthedocs.org/en/latest/customization/processing/

The currently available default processing modules are:

  • AnalysisInfo (modules/processing/analysisinfo.py) - generates some basic information on the current analysis, such as timestamps, version of Cuckoo and so on.
  • 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.
  • Debug (modules/processing/debug.py) - includes errors and the analysis.log generated by the analyzer.
  • Dropped (modules/processing/dropped.py) - includes information on the files dropped by the malware and dumped by Cuckoo.
  • Memory (modules/processing/memory.py) - executes Volatility on a full memory dump.
  • NetworkAnalysis (modules/processing/network.py) - parses the PCAP file and extracts some network information, such as DNS traffic, domains, IPs, HTTP requests, IRC and SMTP traffic.
  • ProcMemory (modules/processing/procmemory.py) - performs analysis of process memory dump. Note: the module is able to process user defined Yara rules from data/yara/memory/index_memory.yar. Just edit this file to add your Yara rules.
  • StaticAnalysis (modules/processing/static.py) - performs some static analysis of PE32 files.
  • Strings (modules/processing/strings.py) - extracts strings from the analyzed binary.
  • TargetInfo (modules/processing/targetinfo.py) - includes information on the analyzed file, such as hashes.
  • VirusTotal (modules/processing/virustotal.py) - searches on VirusTotal.com for antivirus signatures of the analyzed file. Note: the file is not uploaded on VirusTotal.com, if the file was not previously uploaded on the website no results will be retrieved.

Signatures

Signatures are a great way to add custom analysis of the global container. Some examples off the documentation:

  • Identify a particular malware family you’re interested in by isolating some unique behaviors (like file names or mutexes).
  • Spot interesting modifications the malware performs on the system, such as installation of device drivers.
  • Identify particular malware categories, such as Banking Trojans or Ransomware by isolating typical actions commonly performed by those.

A use case I'm interested in would be creating a signature to identify cryptography occurring during analysis. Processing and analysis modules can be used to generate the data necessary for signature modules to scan for.

Reporting Modules

Reporting modules are used to parse the "global container". The global container is passed to each of the reporting modules available who make it accessible and consumable in different formats. It seems you can use reporting modules for more than just parsing the global container into a different format. Reporting modules can be expanded into signature detection modules, e.g. looking for use of Microsoft's CryptoAPI's CryptEncrypt

Official documentation: https://cuckoo.readthedocs.org/en/latest/customization/reporting/