Ginspect HOWTO
1.1 What is Ginspect?
1.2 Why did you write it?
1.3 How did you write it?
2.1 Understanding INSPECT
2.2 Examples
3.1 About TCPDUMP
3.2 TCPDUMP filter expressions
4.1 Using Ginspect
4.2 fw monitor example
4.3 TCPDUMP example
5 Warranty, License and credits
5.1 Warranty and License
5.2 Credits
Ginspect is a PHP script that runs on a webserver and generates
INSPECT filter code or a TCPDUMP filter expression from your input.
INSPECT is the language used by Checkpoint
in their FireWall1 products. It is used to validate packets as they pass
through the firewall.
Ginspect's main use is the fw
monitor command, a build in packet logger (aka sniffer) with specific
firewall functionality.
The fw monitor command's primary use is troubleshooting.
It is not officially documented (to my knowledge) and not very user friendly.
In order to do packet logging on the firewall, one must write INSPECT
code to specify what needs to be logged. This can be daunting when you want
something more specific then logging everything. Furthermore, INSPECT
is picky when it comes to how you write the code. Phoneboy once wrote
in a post to the firewall1-gurus (in those days it was called the firewall1-wizards) mailinglist:
As with all things INSPECT, it may or may not work for you with your
version nor may it work in a future build of FireWall-1.
I've tried to eliminate INSPECT's mood swings by producing 'raw' code,
but more about that later.
Ginspect allows you to specify certain parameters and generates the necessary
INSPECT for you, hoping to improve your troubleshooting efforts.
A recent addition to Ginspect is the ability to generate a TCPDUMP filter expression.
TCPDUMP is a general purpose packet logging tool that runs on a wide variety of platforms.
By default, TCPDUMP logs all packets, but you can narrow your options by passing it a filter expression.
Ginspect can generate such a filter expression for you.
fw monitor is a troubleshooting command, thus, you're only using it when you're in trouble. Since firewalls are not likely something that can be easily missed in your network, chances are management is breathing down your neck while you struggle to resolve the problems. At times like these, nobody should be losing time trying to get the INSPECT syntax right in order to do some efficient packet logging. I found myself in this situation once and I decided to do something about it, so here we are.
The INSPECT syntax is documented in the Checkpoint FireWall1 reference guide. The fw monitor command is documented in a Checkpoint Powerpoint presentation, that I got from my Checkpoint reseller. I worked from those documents. To my knowledge, the Checkpoint slideshow about fw monitor is not available on their website, but I included it here for you to download.
Download the Powerpoint presentation - fwmonitor.ppt (281088 bytes)
Download the Openoffice presentation - fwmonitor.sxi (130924 bytes)
If you can't read those formats, you can browse the presentation online.
For a more in-depth tutorial of INSPECT, please consult the Checkpoint FireWall1 reference guide.
IP reference diagram:
There are 8 bits in a byte. With INSPECT you can read the value of these bytes. The way this works is like this:
[start_byte:number_of_bytes(length)]
Thus if we know that the protocol ID is in the 9th byte, and it spans
a single byte, we can read it as follows:
[9:1]
The protocol ID for TCP is 6, so to filter out TCP, we'd use:
[9:1]=6
fw monitor only logs packets that are accepted by the firewall, so to make sure this works, we need to accept the packets and terminate our code with a ; (INSPECT uses C style syntax). Here is our first working example:
[9:1]=6, accept;
This will log all TCP packets going through the firewall.
If we want to log all TCP packets going through the firewall and
originating form (let's say) 10.20.30.40 we use this code:
([9:1]=6) and ([12:4]=10.20.30.40), accept;
As you can see in the IP reference diagram, the source IP address starts
at the 12th byte and spans 4 bytes. That's why we use [12:4]=10.20.30.40.
Following these simple rules, we generate INSPECT
Remark: You may find that the generated inspect code doesn't look
like the examples. That is because I had unstable results when reading
several bytes in one go. So instead of using [12:4]=10.20.30.40 the generated
code uses ([12:1]=10 and [13:1]=20 and [14:1]=30 and [15:1]=40) It's the
same thing, but it seems to be a lot more reliable this way. This 'byte-splitting'
is also done for portnumbers.
When generating 'readable' code, we define certain things
to make the code more readable. For example:
#define src [12:4]
Would allow us to use the following code:
src=12.2.3.4 , accept;
However, it seems that this is not as reliable as using 'raw' code (in
my experience). You can try it out for yourself, but your mileage may
vary. I'd be interested to find out how well it works for your setup.
If you just want it to work, use 'raw' code.
TCPDUMP prints out the headers of packets on a network interface that match the boolean expression.
It can also be run with the -w flag, which causes it to save the packet data to a file for later analysis, and/or with the -r flag, which causes it to read from a saved packet file rather than to read packets from a network interface.
In all cases, only packets that match the filter expression will be processed by tcpdump.
TCPDUMP was originally written by Van Jacobson, Craig Leres and Steven McCanne, all of the Lawrence Berkeley National Laboratory, University of California, Berkeley, CA and it is currently being maintained by tcpdump.org.
3.1 TCPDUMP filter Expressions
TCPDUMP will only process packets that match the filter expression. Such a filter expression can be passed on the command line, or read from a file using the -F filename parameter. For more detailed info on TCPDUMP and filter expressions, please consult the TCPDUMP man page, either on a unix system via the man command or online at tcpdump.org.
Ginspect now consists of one single form. This is different from previous versions
when there was a basic and an advanced version of the form. Since Ginspect version 0.3, only the advanced form is available.
Let's walk you through the different fields and options.
- Specify a source IP address in dotted quad format.
- Choose a netmask for the given source address.
- Specify a destination IP address in dotted quad format
- Choose a netmask for the given destination address.
- Please note that you do not have to provide IP addresses here. A blanco IP address field (either source, destination or both) is interpreted as 'Any'.
- Select one or more predefined protocols from the list.
- Please note that this is a multiple selection list, hold down to Ctrl key on your keyboard to select multiple entries.
- As an alternative to (5), select the 'Custom Port' radio button, enter your custom port number and choose a protocol from the list.
- Make sure to check the 'Include reply packets' checkbox if you want to monitor data in both directions. When in doubt, check this checkbox.
- Typically in Checkpoint, you log 'connections' originating from A to B. Here you must include reply packets to monitor a network conversation since we work at the packet level.
- Choose the output format you prefer:
- Generate 'raw' INSPECT code: Generate INSPECT code that 'just works'. When in doubt, choose this.
- Generate 'readable' INSPECT code: Generate INSPECT code that is easy to read, but less reliable.
- Generate 'readable' INSPECT code with definition headers: Generate INSPECT code that is easy to read and add headers to improve reliability.
- Generate a TCPDUMP expression: Generate a TCPDUMP filter expression. See TCPDUMP Basics
- Click submit to generate the code or reset to bring the form to it's initial state.
To use this code in the fw monitor command, you can either paste the generated code on the command line:
fw monitor -e "(([9:1]=6) and ([23:1]=80 or ([22:1]=1 and [23:1]=187) or [21:1]=80 or ([20:1]=1 and [21:1]=187)))
and
((([12:1]=1 and [13:1]=2 and [14:1]=3 and [15:1]=4) and ([16:1]=192 and [17:1]=168 and [18:1]=1)) or (([16:1]=1 and [17:1]=2 and [18:1]=3 and [19:1]=4) and ([12:1]=192 and [13:1]=168 and [14:1]=1))), accept; "
Or (and I think this is more useful) you can save it in a file and pass it to fw monitor with the -f parameter:
fw monitor -f a:\inspect.txt
This first example includes a file called 'inspect.txt' that is located
on a floppy drive (Windows platform).
fw monitor -f /inspect.txt
This second example includes the
same file located in the root of a Unix-like operating system (For Checkpoint,
that would be Solaris, IPSO or Secure Platform).
Please note that there are more options to the fw
monitor command. Consult either the Checkpoint presentation mentioned
above or 'How
can I run a Packet Sniffer on the FireWall?', one of the FireWall-1
FAQ's at Phoneboy's excellent site.
To use this code in the tcpdump command, you can either paste the generated code on the command line:
tcpdump '(host 1.2.3.4 and net 192.168.1) and ((tcp port 80 or port 443))'
Or (and I think this is more useful) you can save it in a file (in our example: /tcpdump.expression) and pass it to tcpdump with the -F parameter:
tcpdump -F /tcpdump.expression
Note: In most cases you shouls specify that interface the tcpdump should listen on. Since firewalls typically have multiple interfaces, make sure to select the correct interface. For more information, check the tcpdump man page.
5 Warranty, License and Credits
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Guido Messemaeckers of Comsol (now Noxs [www.noxs.be]) provided me with the Checkpoint fw monitor presentation. Dameon Welch-Abernathy (aka Phoneboy) [www.phoneboy.com] reviewed the first version and gave me a lot of good pointers. (Enough to start over from scratch I might add ;-) )
You can reach me at the following email address:
![Joost [at] decock [dot] org](lib/images/iemeejl.png)
Note that this is an image (for obvious anti-spam reasons) so you'll have
to type it manually into your mail client. For better privacy, feel free
to use encryption. You can get my public key here: joost.asc
- 1024 bit PGP Public Key
If you have any remarks, suggestions, bugs, feature request or
improvements, please let me know.
If you find this code useful in any way, I'd be happy to here from you.
Motivation is a powerful thing.
Joost De Cock
