1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
.. _cuckoo-module:
#############
Cuckoo module
#############
The Cuckoo module enables you to create YARA rules based on behavioral
information generated by `Cuckoo sandbox <https://cuckoosandbox.org/>`_.
While scanning a PE file with YARA, you can pass additional information about
its behavior to the ``cuckoo`` module and create rules based not only on what
it *contains*, but also on what it *does*.
.. important::
This module is not built into YARA by default, to learn how to include it
refer to :ref:`compiling-yara`. Good news for Windows users: this module
is already included in the official Windows binaries.
Suppose that you're interested in executable files sending a HTTP request to
http://someone.doingevil.com. In previous versions of YARA you had to settle
with:
.. code-block:: yara
rule evil_doer
{
strings:
$evil_domain = "http://someone.doingevil.com"
condition:
$evil_domain
}
The problem with this rule is that the domain name could be contained in the
file for perfectly valid reasons not related with sending HTTP requests to
http://someone.doingevil.com. Furthermore, the malicious executable could
contain the domain name ciphered or obfuscated, in which case your rule
would be completely useless.
But now with the ``cuckoo`` module you can take the behavior report generated
for the executable file by your Cuckoo sandbox, pass it alongside the
executable file to YARA, and write a rule like this:
.. code-block:: yara
import "cuckoo"
rule evil_doer
{
condition:
cuckoo.network.http_request(/http:\/\/someone\.doingevil\.com/)
}
Of course you can mix your behavior-related conditions with good old
string-based conditions:
.. code-block:: yara
import "cuckoo"
rule evil_doer
{
strings:
$some_string = { 01 02 03 04 05 06 }
condition:
$some_string and
cuckoo.network.http_request(/http:\/\/someone\.doingevil\.com/)
}
But how do we pass the behavior information to the ``cuckoo`` module? Well, in
the case of the command-line tool you must use the ``-x`` option in this way::
$yara -x cuckoo=behavior_report_file rules_file pe_file
``behavior_report_file`` is the path to a file containing the behavior file
generated by the Cuckoo sandbox in JSON format.
If you are using ``yara-python`` then you must pass the behavior report in the
``modules_data`` argument for the ``match`` method:
.. code-block:: python
import yara
rules = yara.compile('./rules_file')
report_file = open('./behavior_report_file')
report_data = report_file.read()
rules.match(pe_file, modules_data={'cuckoo': bytes(report_data)})
Reference
---------
.. default-domain:: c
.. type:: network
.. function:: http_request(regexp)
Function returning true if the program sent a HTTP request to a URL
matching the provided regular expression.
*Example: cuckoo.network.http_request(/evil\\.com/)*
.. function:: http_get(regexp)
Similar to :func:`http_request`, but only takes into account GET
requests.
.. function:: http_post(regexp)
Similar to :func:`http_request`, but only takes into account POST
requests.
.. function:: http_user_agent(regexp)
Function returning true if the program sent a HTTP request with a
user agent matching the provided regular expression.
*Example: cuckoo.network.http_user_agent(/MSIE 6\\.0/)*
.. function:: dns_lookup(regexp)
Function returning true if the program sent a domain name resolution
request for a domain matching the provided regular expression.
*Example: cuckoo.network.dns_lookup(/evil\\.com/)*
.. function:: host(regexp)
Function returning true if the program contacted an IP address
matching the provided regular expression.
*Example: cuckoo.network.host(/192\\.168\\.1\\.1/)*
.. function:: tcp(regexp, port)
Function returning true if the program contacted an IP address
matching the provided regular expression, over TCP on the provided
port number.
*Example: cuckoo.network.tcp(/192\\.168\\.1\\.1/, 443)*
.. function:: udp(regexp, port)
Function returning true if the program contacted an IP address
matching the provided regular expression, over UDP on the provided
port number.
*Example: cuckoo.network.udp(/192\\.168\\.1\\.1/, 53)*
.. type:: registry
.. function:: key_access(regexp)
Function returning true if the program accessed a registry entry
matching the provided regular expression.
*Example: cuckoo.registry.key_access(/\\\\Software\\\\Microsoft\\\\Windows\\\\CurrentVersion\\\\Run/)*
.. type:: filesystem
.. function:: file_access(regexp)
Function returning true if the program accessed a file matching the
provided regular expression.
*Example: cuckoo.filesystem.file_access(/autoexec\\.bat/)*
.. type:: sync
.. function:: mutex(regexp)
Function returning true if the program opens or creates a mutex matching
the provided regular expression.
*Example: cuckoo.sync.mutex(/EvilMutexName/)*
|
