1
.\" etterfilter -- filter compiler for ettercap filter files
3
.\" This program is free software; you can redistribute it and/or modify
4
.\" it under the terms of the GNU General Public License as published by
5
.\" the Free Software Foundation; either version 2 of the License, or
6
.\" (at your option) any later version.
8
.\" This program is distributed in the hope that it will be useful,
9
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
10
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11
.\" GNU General Public License for more details.
13
.\" You should have received a copy of the GNU General Public License
14
.\" along with this program; if not, write to the Free Software
15
.\" Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
17
.\" $Id: etterfilter.8.in,v 1.22 2005/01/04 14:35:43 alor Exp $
23
.TH ETTERFILTER "8" "" "ettercap @VERSION@"
25
.B etterfilter @VERSION@ \- Filter compiler for ettercap content filtering engine
29
[\fIOPTIONS\fR] \fIFILE\fR
33
The etterfilter utility is used to compile source filter files into binary
34
filter files that can be interpreted by the JIT interpreter in the ettercap(8)
35
filter engine. You have to compile your filter scripts in order to use them in
36
ettercap. All syntax/parse errors will be checked at compile time, so you
37
will be sure to produce a correct binary filter for ettercap.
42
\fB\-o\fR, \fB\-\-output <FILE>\fR
43
you can specify the output file for a source filter file. By default the output
47
\fB\-t\fR, \fB\-\-test <FILE>\fR
48
you can analyze a compiled filter file with this option. etterfilter will print
49
in a human readable form all the instructions contained in it. It is a sort of
50
"disassembler" for binary filter files.
53
\fB\-d\fR, \fB\-\-debug\fR
54
prints some debug messages during the compilation. Use it more than once to
55
increase the debug level ( etterfilter -ddd ... ).
58
\fB\-w\fR, \fB\-\-suppress-warnings\fR
59
Don't exit on warnings. With this option the compiler will compile the script
60
even if it contains warnings.
65
\fB\-v\fR, \fB\-\-version\fR
66
Print the version and exit.
69
\fB\-h\fR, \fB\-\-help\fR
70
prints the help screen with a short summary of the available options.
76
A script is a compound of instructions. It is executed sequentially and you can
77
make branches with the 'if' statements. 'if' and 'if/else' statements are the only
78
supported. No loops are implemented. The syntax is almost like C code
79
except that you have to put 'if' blocks into graph parentheses '{' '}', even if they
80
contain only one instruction.
82
NOTE: you have to put a space between the 'if' and the '('. You must not put the
83
space between the function name and the '('.
92
The conditions for an 'if' statement can be either functions or comparisons.
93
Two or more conditions can be linked together with logical operators like
98
if (tcp.src == 21 && search(DATA.data, "ettercap")) {
102
Pay attention to the operator precedence.
103
You cannot use parentheses to group conditions, so be careful with the order. An
104
AND at the beginning of a conditions block will exclude all the other tests if
105
it is evaluated as false. The parsing is left-to-right, when an operator is
106
found: if it is an AND and the previous condition is false, all the statement
107
is evaluated as false; if it is an OR the parsing goes on even if the condition
112
if (ip.proto == UDP || ip.proto == TCP && tcp.src == 80) {
116
if (ip.proto == TCP && tcp.src == 80 || ip.proto == UDP) {
120
the former condition will match all udp or http traffic. The latter is wrong,
121
because if the packet is not tcp, the whole condition block will be evaluated as false.
122
If you want to make complex conditions, the best way is to split them into nested 'if'
126
Every instruction in a block must end with a semicolon ';'.
128
Comparisons are implemented with the '==' operator and can be used to compare
129
numbers, strings or ip addresses. An ip address MUST be enclosed within two single
130
quotes (eg. '192.168.0.7'). You can also use the 'less than' ('<'), 'greater than'
131
('>'), 'less or equal' ('<=') and 'greater or equal' ('>=') operators.
132
The lvalue of a comparison must be an offset (see later)
136
if (DATA.data + 20 == "ettercap" && ip.ttl > 16) {
140
Assignments are implemented with the '=' operator and the lvalue can be an
141
offset (see later). The rvalue can be a string, an integer or a hexadecimal
148
DATA.data + 7 = "ettercap NG";
150
You can also use the 'inc' and 'dec' operations on the packet fields. The operators
151
used are '+=' and '-='. The rvalue can be an integer or a hexadecimal value.
160
An offset is identified by a virtual pointer. In short words, an offset is a
161
pointer to the packet buffer. The virtual pointer is a tuple <L, O, S>, where
162
L is the iso/osi level, O is the offset in that level and S is the size of the virtual pointer.
163
You can make algebraic operations on a virtual pointer and the result is still an
164
offset. Specifying 'vp + n' will result in a new virtual pointer <L, O+n, S>.
165
And this is perfectly legal, we have changed the internal offset of that
168
Virtual pointers are in the form 'name.field.subfield'. For example 'ip.ttl' is
169
the virtual pointer for the Time To Live field in the IP header of a packet. It
170
will be translated as <L=3, O=9, S=1>. Indeed it is the 9th byte of level 3 and
171
its size is 1 byte. 'ip.ttl + 1' is the same as 'ip.proto' since the 10th byte
172
of the IP header is the protocol encapsulated in the IP packet.
174
The list of all supported virtual pointers is in the file etterfilter.tbl. You
175
can add your own virtual pointers by adding a new table or modifying the
176
existing ones. Refer to the comments at the beginning of the file for the
177
syntax of etterfilter.tbl file.
183
.B search(\fIwhere\fR, \fIwhat\fR)
184
this function searches the string 'what' in the buffer 'where'. The buffer
185
can be either DATA.data or DECODED.data. The former is the payload at layer
186
DATA (ontop TCP or UDP) as it is transmitted on the wire, the latter is the
187
payload decoded/decrypted by dissectors.
189
So, if you want to search in an SSH connection, it is better to use 'DECODED.data'
190
since 'data' will be encrypted.
192
The string 'what' can be binary. You have to escape it.
196
search(DATA.data, "\\x41\\x42\\x43")
200
.B regex(\fIwhere\fR, \fIregex\fR)
201
this function will return true if the 'regex' has matched the buffer 'where'.
202
The considerations about 'DECODED.data' and 'DATA.data' mentioned for the function 'search'
203
are the same for the regex function.
205
NOTE: regex can be used only against a string buffer.
209
regex(DECODED.data, ".*login.*")
213
.B pcre_regex(\fIwhere\fR, \fIpcre_regex\fR ... )
214
this function will evaluate a perl compatible regular expression. You can match
215
against both DATA and DECODED, but if your expression modifies the buffer, it
216
makes sense to operate only on DATA. The function accepts 2 or 3 parameters
217
depending on the operation you want. The two parameter form is used only to
218
match a pattern. The three parameter form means that you want to make a
219
substitution. In both cases, the second parameter is the search string.
221
You can use $n in the replacement string. These
222
placeholders are referred to the groups created in the search string. (e.g.
223
pcre_regex(DATA.data, "^var1=([:digit:]*)&var2=([:digit:]*)", "var1=$2&var2=$1")
224
will swap the value of var1 and var2).
226
NOTE: The pcre support is optional in ettercap and will be enabled only if you
227
have the libpcre installed.
228
The compiler will warn you if you try to compile a filter that contains
229
pcre expressions but you don't have libpcre. Use the -w option to suppress the
234
pcre_regex(DATA.data, ".*foo$")
236
pcre_regex(DATA.data, "([^ ]*) bar ([^ ]*)", "foo $1 $2")
240
.B replace(\fIwhat\fR, \fIwith\fR)
241
this function replaces the string 'what' with the string 'with'. They can be
242
binary string and must be escaped. The replacement is always performed in
243
DATA.data since is the only payload which gets forwarded. The 'DECODED.data' buffer
244
is used only internally and never reaches the wire.
248
replace("ethercap", "ettercap")
252
.B inject(\fIwhat\fR)
253
this function injects the content of the file 'what' after the packet being
254
processed. It always injects in DATA.data. You can use it to replace the entire
255
packet with a fake one using the drop() function right before the inject() command.
256
In that case the filtering engine will drop the current packet and inject the
261
inject("./fake_packet")
265
.B log(\fIwhat\fR, \fIwhere\fR)
266
this function dumps in the file 'where' the buffer 'what'. No information is
267
stored about the packet, only the payload is dumped. So you will see the stream
268
in the file. If you want to log packets in a more enhanced mode, you need to
269
use the ettercap -L option and analyze it with etterlog(8).
271
The file 'where' must be writable to the user EC_UID (see etter.conf(5)).
275
log(DECODED.data, "/tmp/interesting.log")
279
.B msg(\fImessage\fR)
280
this function displays a message to the user in the User Messages window. It is
281
useful to let the user know whether a particular filter has been successful or not.
285
msg("Packet filtered successfully")
290
this function marks the packet "to be dropped". The packet will not be
291
forwarded to the real destination.
300
this function kills the connection that owns the matched packet. If it is a TCP
301
connection, a RST is sent to both sides of the connection. If it is an UDP
302
connection, an ICMP PORT UNREACHABLE is sent to the source of the packet.
310
.B exec(\fIcommand\fR)
311
this function executes a shell command. You have to provide the full path to
312
the command since it is executed without any environment. There is no way to
313
determine if the command was successful or not. Furthermore, it is executed
314
asynchronously since it is forked by the main process.
318
exec("/bin/cat /tmp/foo >> /tmp/bar")
323
this function causes the filter engine to stop executing the code. It is useful
324
to stop the execution of the script on some circumstance checked by an 'if' statement.
333
Here are some examples of using etterfilter.
335
.B etterfilter filter.ecf -o filter.ef
337
Compiles the source filter.ecf into a binary filter.ef
342
Alberto Ornaghi (ALoR) <alor@users.sf.net>
344
Marco Valleri (NaGA) <naga@antifork.org>
349
.I "etter.filter.examples"
354
.I "ettercap_curses(8)"
355
.I "ettercap_plugins(8)"
added
removed
.pc/0004-man-page-tweaks.patch/man/etterfilter.8.in
