1ETTERFILTER(8) System Manager's Manual ETTERFILTER(8)
2
6 etterfilter NG-0.7.3 - Filter compiler for ettercap content filtering
7 engine
8
11 etterfilter [OPTIONS] FILE
12
16 The etterfilter utility is used to compile source filter files into
17 binary filter files that can be interpreted by the JIT interpreter in
18 the ettercap(8) filter engine. You have to compile your filter scripts
19 in order to use them in ettercap. All syntax/parse errors will be
20 checked at compile time, so you will be sure to produce a correct
21 binary filter for ettercap.
22 GENERAL OPTIONS
25 -o, --output <FILE>
27 you can specify the output file for a source filter file. By
28 default the output is filter.ef.
29 -t, --test <FILE>
32 you can analyze a compiled filter file with this option. etter‐
33 filter will print in a human readable form all the instructions
34 contained in it. It is a sort of "disassembler" for binary fil‐
35 ter files.
36 -d, --debug
39 prints some debug messages during the compilation. Use it more
40 than once to increase the debug level ( etterfilter -ddd ... ).
41 -w, --suppress-warnings
44 Don't exit on warnings. With this option the compiler will com‐
45 pile the script even if it contains warnings.
46 STANDARD OPTIONS
49 -v, --version
51 Print the version and exit.
52 -h, --help
55 prints the help screen with a short summary of the available
56 options.
57 SCRIPTS SYNTAX
62 A script is a compound of instructions. It is executed sequen‐
63 tially and you can make branches with the 'if' statements. 'if'
64 and 'if/else' statements are the only supported. No loops are
65 implemented. The syntax is almost like C code except that you
66 have to put 'if' blocks into graph parentheses '{' '}', even if
67 they contain only one instruction.
68 NOTE: you have to put a space between the 'if' and the '('. You
70 must not put the space between the function name and the '('.
71 Example:
73 if (conditions) { }
74 func(args...);
75 The conditions for an 'if' statement can be either functions or
78 comparisons. Two or more conditions can be linked together with
79 logical operators like OR '||' and AND '&&'.
80 Example:
82 if (tcp.src == 21 && search(DATA.data, "ettercap")) {
83 }
84 Pay attention to the operator precedence. You cannot use paren‐
86 theses to group conditions, so be careful with the order. An AND
87 at the beginning of a conditions block will exclude all the
88 other tests if it is evaluated as false. The parsing is left-to-
89 right, when an operator is found: if it is an AND and the previ‐
90 ous condition is false, all the statement is evaluated as false;
91 if it is an OR the parsing goes on even if the condition is
92 false.
93 Example:
95 if (ip.proto == UDP || ip.proto == TCP && tcp.src == 80) {
96 }
97 if (ip.proto == TCP && tcp.src == 80 || ip.proto == UDP) {
99 }
100 the former condition will match all udp or http traffic. The
102 latter is wrong, because if the packet is not tcp, the whole
103 condition block will be evaluated as false. If you want to make
104 complex conditions, the best way is to split them into nested
105 'if' blocks.
106 Every instruction in a block must end with a semicolon ';'.
109 Comparisons are implemented with the '==' operator and can be
111 used to compare numbers, strings or ip addresses. An ip address
112 MUST be enclosed within two single quotes (eg. '192.168.0.7').
113 You can also use the 'less than' ('<'), 'greater than' ('>'),
114 'less or equal' ('<=') and 'greater or equal' ('>=') operators.
115 The lvalue of a comparison must be an offset (see later)
116 Example:
118 if (DATA.data + 20 == "ettercap" && ip.ttl > 16) {
119 }
120 Assignments are implemented with the '=' operator and the lvalue
122 can be an offset (see later). The rvalue can be a string, an
123 integer or a hexadecimal value.
124 Example:
126 ip.ttl = 0xff;
127 DATA.data + 7 = "ettercap NG";
128 You can also use the 'inc' and 'dec' operations on the packet
130 fields. The operators used are '+=' and '-='. The rvalue can be
131 an integer or a hexadecimal value.
132 Example:
134 ip.ttl += 5;
135 OFFSET DEFINITION
139 An offset is identified by a virtual pointer. In short words, an
140 offset is a pointer to the packet buffer. The virtual pointer is
141 a tuple <L, O, S>, where L is the iso/osi level, O is the offset
142 in that level and S is the size of the virtual pointer. You can
143 make algebraic operations on a virtual pointer and the result is
144 still an offset. Specifying 'vp + n' will result in a new vir‐
145 tual pointer <L, O+n, S>. And this is perfectly legal, we have
146 changed the internal offset of that level.
147 Virtual pointers are in the form 'name.field.subfield'. For
149 example 'ip.ttl' is the virtual pointer for the Time To Live
150 field in the IP header of a packet. It will be translated as
151 <L=3, O=9, S=1>. Indeed it is the 9th byte of level 3 and its
152 size is 1 byte. 'ip.ttl + 1' is the same as 'ip.proto' since the
153 10th byte of the IP header is the protocol encapsulated in the
154 IP packet.
155 The list of all supported virtual pointers is in the file etter‐
157 filter.tbl. You can add your own virtual pointers by adding a
158 new table or modifying the existing ones. Refer to the comments
159 at the beginning of the file for the syntax of etterfilter.tbl
160 file.
161 SCRIPTS FUNCTIONS
165 search(where, what)
167 this function searches the string 'what' in the buffer 'where'.
168 The buffer can be either DATA.data or DECODED.data. The former
169 is the payload at layer DATA (ontop TCP or UDP) as it is trans‐
170 mitted on the wire, the latter is the payload decoded/decrypted
171 by dissectors.
172 So, if you want to search in an SSH connection, it is better to
173 use 'DECODED.data' since 'data' will be encrypted.
174 The string 'what' can be binary. You have to escape it.
175 example:
177 search(DATA.data, "\x41\x42\x43")
178 regex(where, regex)
182 this function will return true if the 'regex' has matched the
183 buffer 'where'. The considerations about 'DECODED.data' and
184 'DATA.data' mentioned for the function 'search' are the same for
185 the regex function.
186 NOTE: regex can be used only against a string buffer.
188 example:
190 regex(DECODED.data, ".*login.*")
191 pcre_regex(where, pcre_regex ... )
195 this function will evaluate a perl compatible regular expres‐
196 sion. You can match against both DATA and DECODED, but if your
197 expression modifies the buffer, it makes sense to operate only
198 on DATA. The function accepts 2 or 3 parameters depending on the
199 operation you want. The two parameter form is used only to match
200 a pattern. The three parameter form means that you want to make
201 a substitution. In both cases, the second parameter is the
202 search string.
203 You can use $n in the replacement string. These placeholders are
204 referred to the groups created in the search string. (e.g.
205 pcre_regex(DATA.data, "^var1=([:digit:]*)&var2=([:digit:]*)",
206 "var1=$2&var2=$1") will swap the value of var1 and var2).
207 NOTE: The pcre support is optional in ettercap and will be
208 enabled only if you have the libpcre installed. The compiler
209 will warn you if you try to compile a filter that contains pcre
210 expressions but you don't have libpcre. Use the -w option to
211 suppress the warning.
212 example:
214 pcre_regex(DATA.data, ".*foo$")
215 pcre_regex(DATA.data, "([^ ]*) bar ([^ ]*)", "foo $1 $2")
216 replace(what, with)
220 this function replaces the string 'what' with the string 'with'.
221 They can be binary string and must be escaped. The replacement
222 is always performed in DATA.data since is the only payload which
223 gets forwarded. The 'DECODED.data' buffer is used only inter‐
224 nally and never reaches the wire.
225 example:
227 replace("ethercap", "ettercap")
228 inject(what)
232 this function injects the content of the file 'what' after the
233 packet being processed. It always injects in DATA.data. You can
234 use it to replace the entire packet with a fake one using the
235 drop() function right before the inject() command. In that case
236 the filtering engine will drop the current packet and inject the
237 fake one.
238 example:
240 inject("./fake_packet")
241 log(what, where)
245 this function dumps in the file 'where' the buffer 'what'. No
246 information is stored about the packet, only the payload is
247 dumped. So you will see the stream in the file. If you want to
248 log packets in a more enhanced mode, you need to use the etter‐
249 cap -L option and analyze it with etterlog(8).
250 The file 'where' must be writable to the user EC_UID (see
251 etter.conf(5)).
252 example:
254 log(DECODED.data, "/tmp/interesting.log")
255 msg(message)
259 this function displays a message to the user in the User Mes‐
260 sages window. It is useful to let the user know whether a par‐
261 ticular filter has been successful or not.
262 example:
264 msg("Packet filtered successfully")
265 drop() this function marks the packet "to be dropped". The packet will
269 not be forwarded to the real destination.
270 example:
272 drop()
273 kill() this function kills the connection that owns the matched packet.
277 If it is a TCP connection, a RST is sent to both sides of the
278 connection. If it is an UDP connection, an ICMP PORT UNREACHABLE
279 is sent to the source of the packet.
280 example:
282 kill()
283 exec(command)
287 this function executes a shell command. You have to provide the
288 full path to the command since it is executed without any envi‐
289 ronment. There is no way to determine if the command was suc‐
290 cessful or not. Furthermore, it is executed asynchronously since
291 it is forked by the main process.
292 example:
294 exec("/bin/cat /tmp/foo >> /tmp/bar")
295 exit() this function causes the filter engine to stop executing the
299 code. It is useful to stop the execution of the script on some
300 circumstance checked by an 'if' statement.
301 example:
303 exit()
304
309 Here are some examples of using etterfilter.
310 etterfilter filter.ecf -o filter.ef
312 Compiles the source filter.ecf into a binary filter.ef
314
319 Alberto Ornaghi (ALoR) <alor@users.sf.net>
320 Marco Valleri (NaGA) <naga@antifork.org>
321
326 etter.filter.examples
327 ettercap(8) etterlog(8) etter.conf(5) ettercap_curses(8) ettercap_plug‐
328 ins(8)
329ettercap NG-0.7.3 ETTERFILTER(8)