For malware dynamic malware analysis, I am using Automated Malware Analysis - Cuckoo Sandbox. Now I wan to add new modules for analysis on malware. I have studied cuckoo sandbox's development documentation. But currently I am unable to add my custom script for static analysis on malware/samples. Python scripts available here.
Can anyone guide me how can I add more modules / analysis script inside cuckoo sandbox processing module. If their is any article available on net please share it.
Thanks
A Cuckoo Sandbox is a tool that is used to launch malware in a secure and isolated environment, the idea is the sandbox fools the malware into thinking it has infected a genuine host.
cuckoo as it defaults to ~/. cuckoo . All configuration files as you know them can be found in the $CWD/conf directory. I.e., $CWD/conf/cuckoo.
According the documentation:
The analysis packages are a core component of Cuckoo Sandbox. They consist in structured Python classes which, when executed in the guest machines, describe how Cuckoo’s analyzer component should conduct the analysis.
So, an analysis package is responsible of perform the needed actions to process the file.
Examples (On windows guests)
"C:\\WINDOWS\\system32\\rundll32.exe"
So, you write an Analisys Package to tell cuckoo how to open or execute a file. A Processing Module to process the file and extract the information for the report (Reporting Modules).
If you want to perform static analysis, you don't need to write an Analisis Package but a Processing Module. If you want to add new behavioural analysis you need to implement both.
This answer is about writting processing modules, since your question is about static analysis.
I use the documentation last version. In the docs I found many things that was helpful, others things (like how to display the module report in the html interface) I discovered my self in a test-and-error process and hacking the code.
In order to be a processing module, your script has to meet some requirements. Below, you will see which are these requirements and how to put them together to get a processing module.
After an analysis is completed, Cuckoo will invoke all the processing modules available in the modules/processing/ directory. Every module will then be initialized and executed and the data returned will be appended in a data structure that we’ll call global container. This container is simply just a big Python dictionary that contains all the abstracted results produced by all the modules sorted by their defined keys.
The resulting data of your processing module will be added to the global container, this way other modules (E.g report modules) can access to that information.
A basic processing module (lets call it simple_module) could look like this:
# simple_module.py
from lib.cuckoo.common.abstracts import Processing
class SimpleModule(Processing): # A class inheriting Processing.
def run(self): # A run() function
self.key = "simple_info" # The name that will have the returned data in the global container.
data = "This is the data returned by simple_module."
return data # A set of data (list, dictionary or string etc.) that will be appended to the global container.
# under the key secified in `self.key`.
There are several module categories, if you look at cuckoo's directory hierarchy you will find a directory called modules
and
inside some directories:
signature
means).The directory you have to care about is: processing. There you will put your new module.
Add a seccion like the following to the conf/processing.conf
file:
[simple_module]
enabled = yes
After the analysis raw results have been processed and abstracted by the processing modules and the global container is generated (ref. Processing Modules), 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.
Yes!! We need other module in order to be able to see the output of the new processing module. The easiest way is to log the result to a file:
You can visit the Reporting Modules documentation an you will find an example like this:
Lets implement a report for our processing module, simple_module:
# simple_report.py
import os
from lib.cuckoo.common.abstracts import Report
from lib.cuckoo.common.exceptions import CuckooReportError
class SimpleReport(Report):
def run(self, results): # IMPORTANT!! Here the parameter result will be the Global Container we saw before
try:
report = open(os.path.join(self.reports_path, "simple_report.txt"), "w")
report.write(results["simple_info"]) # We add our information to the Global Container under the key: simple_info
# now we are querying that info to write it down to a file.
report.close()
except (TypeError, IOError) as e:
raise CuckooReportError("Failed to make a simple report, :(")
Also you will need to enable this reporting module:
Every module should also have a dedicated section in the file conf/reporting.conf, for example if you create a module module/reporting/foobar.py you will have to append the following section to conf/reporting.conf
[simple_report]
enabled = on
Now wen you run a new analysis, you will be able to find a file called "simple_report.txt" in the storage/analyses/<analysis-number>/reports
folder.
Well ... thats a little more complex. If you take a look at the file modules/reporting/reporthtml.py
you will find a class ReportHtml
that at some point has code like this:
try:
tpl = env.get_template("report.html") # Ahhhh, so cuckoo is using a template for this.
html = tpl.render({"results": results}) # Look, the template receives the Global Container (this dude again!!!, it must be a VIP).
except Exception as e:
raise CuckooReportError("Failed to generate HTML report: %s" % e)
try:
with codecs.open(os.path.join(self.reports_path, "report.html"), "w", encoding="utf-8") as report:
report.write(html)
except (TypeError, IOError) as e:
raise CuckooReportError("Failed to write HTML report: %s" % e)
The templates are in web/templates/analysis
there you can find report.html
. Reading that file you will note two important code blocks:
Code for tabs:
<ul class="nav nav-tabs">
<li class="active"><a href="#overview" data-toggle="tab">Quick Overview</a></li>
<li><a href="#static" data-toggle="tab">Static Analysis</a></li>
{% if analysis.behavior.processes %}<li><a href="#behavior" data-toggle="tab" id="graph_hook">Behavioral Analysis</a></li>{% endif %}
<li><a href="#network" data-toggle="tab">Network Analysis</a></li>
<li><a href="#dropped" data-toggle="tab">Dropped Files</a></li>
{% if analysis.procmemory %}<li><a href="#procmemory" data-toggle="tab">Process Memory</a></li>{% endif %}
{% if analysis.memory %}<li><a href="#memory" data-toggle="tab">Memory Analysis</a></li>{% endif %}
<li><a href="#admin" data-toggle="tab">Admin</a></li>
</ul>
And code for content (some code was omitted for brevity):
<div class="tab-content">
<div class="tab-pane fade in active" id="overview">
{% include "analysis/overview/index.html" %}
</div>
<div class="tab-pane fade" id="static">
{% include "analysis/static/index.html" %}
</div>
{% if analysis.behavior.processes %}
<div class="tab-pane fade" id="behavior">
{% include "analysis/behavior/index.html" %}
</div>
{% endif %}
...
...
</div>
Ok, it is obvious, we need to add our template, lets proceed:
1- Create a file, web/templates/analysis/simple_module/index.html
{{analysis.simple_info}}
In the above line analysis
points to the root of the dictionary Global Results. And simple info is the key added to such dictionary by our process module, simple_module.
This will replace {{analysis.simple_info}}
with the value we set to that key in the Global Conatiner. See also The Django template language: for Python programmers.
2- Update web/templates/analysis/report.html
to include your templates
Add the line
<li class="active"><a href="#simple_module" data-toggle="tab">Simple Module</a></li>
to the tabs section. And the following lines to the content section:
<div class="tab-pane fade" id="simple_module">
{% include "analysis/simple_module/index.html" %}
</div>
And... Hocus Pocus ...
Is important to note that if you only want to display the result in the html format, you don't have to implemet a report module, just create the corresponding templates and use the respective variables.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With