NAME
etterfilter NG-0.7.3 - Filter compiler for ettercap content filtering
engine
SYNOPSIS
etterfilter [OPTIONS] FILE
DESCRIPTION
The etterfilter utility is used to compile source filter files into
binary filter files that can be interpreted by the JIT interpreter in
the ettercap(8) filter engine. You have to compile your filter scripts
in order to use them in ettercap. All syntax/parse errors will be
checked at compile time, so you will be sure to produce a correct
binary filter for ettercap.
GENERAL OPTIONS
-o, --output <FILE>
you can specify the output file for a source filter file. By
default the output is filter.ef.
-t, --test <FILE>
you can analyze a compiled filter file with this option.
etterfilter will print in a human readable form all the
instructions contained in it. It is a sort of "disassembler" for
binary filter files.
-d, --debug
prints some debug messages during the compilation. Use it more
than once to increase the debug level ( etterfilter -ddd ... ).
-w, --suppress-warnings
Don’t exit on warnings. With this option the compiler will
compile the script even if it contains warnings.
STANDARD OPTIONS
-v, --version
Print the version and exit.
-h, --help
prints the help screen with a short summary of the available
options.
SCRIPTS SYNTAX
A script is a compound of instructions. It is executed
sequentially and you can make branches with the ’if’ statements.
’if’ and ’if/else’ statements are the only supported. No loops
are implemented. The syntax is almost like C code except that
you have to put ’if’ blocks into graph parentheses ’{’ ’}’, even
if they contain only one instruction.
NOTE: you have to put a space between the ’if’ and the ’(’. You
must not put the space between the function name and the ’(’.
Example:
if (conditions) { }
func(args...);
The conditions for an ’if’ statement can be either functions or
comparisons. Two or more conditions can be linked together with
logical operators like OR ’||’ and AND ’&&’.
Example:
if (tcp.src == 21 && search(DATA.data, "ettercap")) {
}
Pay attention to the operator precedence. You cannot use
parentheses to group conditions, so be careful with the order.
An AND at the beginning of a conditions block will exclude all
the other tests if it is evaluated as false. The parsing is
left-to-right, when an operator is found: if it is an AND and
the previous condition is false, all the statement is evaluated
as false; if it is an OR the parsing goes on even if the
condition is false.
Example:
if (ip.proto == UDP || ip.proto == TCP && tcp.src == 80) {
}
if (ip.proto == TCP && tcp.src == 80 || ip.proto == UDP) {
}
the former condition will match all udp or http traffic. The
latter is wrong, because if the packet is not tcp, the whole
condition block will be evaluated as false. If you want to make
complex conditions, the best way is to split them into nested
’if’ blocks.
Every instruction in a block must end with a semicolon ’;’.
Comparisons are implemented with the ’==’ operator and can be
used to compare numbers, strings or ip addresses. An ip address
MUST be enclosed within two single quotes (eg. ’192.168.0.7’).
You can also use the ’less than’ (’<’), ’greater than’ (’>’),
’less or equal’ (’<=’) and ’greater or equal’ (’>=’) operators.
The lvalue of a comparison must be an offset (see later)
Example:
if (DATA.data + 20 == "ettercap" && ip.ttl > 16) {
}
Assignments are implemented with the ’=’ operator and the lvalue
can be an offset (see later). The rvalue can be a string, an
integer or a hexadecimal value.
Example:
ip.ttl = 0xff;
DATA.data + 7 = "ettercap NG";
You can also use the ’inc’ and ’dec’ operations on the packet
fields. The operators used are ’+=’ and ’-=’. The rvalue can be
an integer or a hexadecimal value.
Example:
ip.ttl += 5;
OFFSET DEFINITION
An offset is identified by a virtual pointer. In short words, an
offset is a pointer to the packet buffer. The virtual pointer is
a tuple <L, O, S>, where L is the iso/osi level, O is the offset
in that level and S is the size of the virtual pointer. You can
make algebraic operations on a virtual pointer and the result is
still an offset. Specifying ’vp + n’ will result in a new
virtual pointer <L, O+n, S>. And this is perfectly legal, we
have changed the internal offset of that level.
Virtual pointers are in the form ’name.field.subfield’. For
example ’ip.ttl’ is the virtual pointer for the Time To Live
field in the IP header of a packet. It will be translated as
<L=3, O=9, S=1>. Indeed it is the 9th byte of level 3 and its
size is 1 byte. ’ip.ttl + 1’ is the same as ’ip.proto’ since the
10th byte of the IP header is the protocol encapsulated in the
IP packet.
The list of all supported virtual pointers is in the file
etterfilter.tbl. You can add your own virtual pointers by adding
a new table or modifying the existing ones. Refer to the
comments at the beginning of the file for the syntax of
etterfilter.tbl file.
SCRIPTS FUNCTIONS
search(where, what)
this function searches the string ’what’ in the buffer ’where’.
The buffer can be either DATA.data or DECODED.data. The former
is the payload at layer DATA (ontop TCP or UDP) as it is
transmitted on the wire, the latter is the payload
decoded/decrypted by dissectors.
So, if you want to search in an SSH connection, it is better to
use ’DECODED.data’ since ’data’ will be encrypted.
The string ’what’ can be binary. You have to escape it.
example:
search(DATA.data, "\x41\x42\x43")
regex(where, regex)
this function will return true if the ’regex’ has matched the
buffer ’where’. The considerations about ’DECODED.data’ and
’DATA.data’ mentioned for the function ’search’ are the same for
the regex function.
NOTE: regex can be used only against a string buffer.
example:
regex(DECODED.data, ".*login.*")
pcre_regex(where, pcre_regex ... )
this function will evaluate a perl compatible regular
expression. You can match against both DATA and DECODED, but if
your expression modifies the buffer, it makes sense to operate
only on DATA. The function accepts 2 or 3 parameters depending
on the operation you want. The two parameter form is used only
to match a pattern. The three parameter form means that you want
to make a substitution. In both cases, the second parameter is
the search string.
You can use $n in the replacement string. These placeholders are
referred to the groups created in the search string. (e.g.
pcre_regex(DATA.data, "^var1=([:digit:]*)&var2=([:digit:]*)",
"var1=$2&var2=$1") will swap the value of var1 and var2).
NOTE: The pcre support is optional in ettercap and will be
enabled only if you have the libpcre installed. The compiler
will warn you if you try to compile a filter that contains pcre
expressions but you don’t have libpcre. Use the -w option to
suppress the warning.
example:
pcre_regex(DATA.data, ".*foo$")
pcre_regex(DATA.data, "([^ ]*) bar ([^ ]*)", "foo $1 $2")
replace(what, with)
this function replaces the string ’what’ with the string ’with’.
They can be binary string and must be escaped. The replacement
is always performed in DATA.data since is the only payload which
gets forwarded. The ’DECODED.data’ buffer is used only
internally and never reaches the wire.
example:
replace("ethercap", "ettercap")
inject(what)
this function injects the content of the file ’what’ after the
packet being processed. It always injects in DATA.data. You can
use it to replace the entire packet with a fake one using the
drop() function right before the inject() command. In that case
the filtering engine will drop the current packet and inject the
fake one.
example:
inject("./fake_packet")
log(what, where)
this function dumps in the file ’where’ the buffer ’what’. No
information is stored about the packet, only the payload is
dumped. So you will see the stream in the file. If you want to
log packets in a more enhanced mode, you need to use the
ettercap -L option and analyze it with etterlog(8).
The file ’where’ must be writable to the user EC_UID (see
etter.conf(5)).
example:
log(DECODED.data, "/tmp/interesting.log")
msg(message)
this function displays a message to the user in the User
Messages window. It is useful to let the user know whether a
particular filter has been successful or not.
example:
msg("Packet filtered successfully")
drop() this function marks the packet "to be dropped". The packet will
not be forwarded to the real destination.
example:
drop()
kill() this function kills the connection that owns the matched packet.
If it is a TCP connection, a RST is sent to both sides of the
connection. If it is an UDP connection, an ICMP PORT UNREACHABLE
is sent to the source of the packet.
example:
kill()
exec(command)
this function executes a shell command. You have to provide the
full path to the command since it is executed without any
environment. There is no way to determine if the command was
successful or not. Furthermore, it is executed asynchronously
since it is forked by the main process.
example:
exec("/bin/cat /tmp/foo >> /tmp/bar")
exit() this function causes the filter engine to stop executing the
code. It is useful to stop the execution of the script on some
circumstance checked by an ’if’ statement.
example:
exit()
EXAMPLES
Here are some examples of using etterfilter.
etterfilter filter.ecf -o filter.ef
Compiles the source filter.ecf into a binary filter.ef
AUTHORS
Alberto Ornaghi (ALoR) <alor@users.sf.net>
Marco Valleri (NaGA) <naga@antifork.org>
SEE ALSO
etter.filter.examples
ettercap(8) etterlog(8) etter.conf(5) ettercap_curses(8)
ettercap_plugins(8)