Sustainable Sustworks - Tools for Internet Travel
Advanced Networking for Mactintosh Professionals
Search






 




IPNetSentry Command Syntax

The IPNetSentry Config file defines how IPNetSentry will defend your Macintosh. The default configuration file, which was placed in your Preferences folder during installation, provides excellent protection for most Macintosh users:

If you wish to make any changes to this file you can simply edit this file with any text editor (such as SimpleText). The commands understood by IPNetSentry are defined below (this document is also included with your IPNetSentry installation and should be located in the IPNetSentry folder).

After making any changes to the IPNetSentry Config document you will need to first turn off IPNetSentry then turn it back on in order to invoke the new configuration.

Contents

SET COMMANDS - used to set variables within the IPNetSentry FBA

#set\default_filter_time\number

sets the time in seconds that an aged filter is enforced after a trigger is hit

number is any numeric value

EXAMPLE:

Top



#set\notification_type\notification_method

sets the notification method after a trigger is hit. Logging always occurs for any trigger event.

Starting with IPNetSentry v1.0c3, you can designate multiple notification methods (on separate lines). Starting with IPNetSentry v1.0c5 you can also designate per trigger type notification. (see triggers below).

notification_method is one of the following options:

  • none
  • alert (displays an alert with trigger info)
  • browser (takes your browser to a page at Sustworks.com which gives you detailed info about the intrusion)
  • both (alert and browser. Browser is conditionally invoked IF you hold down the Shift key when you click OK to the alert button)
  • applescript (applescript is invoked when an intrusion is detected. AppleScript name is required - see below).
  • syslog (a syslog message is sent to a designated syslog server with a UDP message on port 514. Syslog server IP address or Domain Name is required - see below).

EXAMPLES:

Top



#set\applescript_name\name_of_applescript

sets the name of the AppleScript which is to be invoked when an intrusion occurs. AppleScript must be Run-Only application and reside in Preferences folder.

name_of_applescript is the name of your Run-Only AppleScript

EXAMPLE:

Top



#set\syslog_server\ip_address_or_name_of_syslog_server

sets the IP Address or the domain name of a designated Syslog server

ip_address_or_name_of_syslog_server is the IP Address or the name of the Syslog server

EXAMPLES:

Top



#set\logging_mode\mode_of_logging

sets the logging mode for IPNetSentry

mode_of_logging is one of the following options:

  • normal (just trigger events are logged)
  • detailed (a detailed log is kept, including startup, reset, and trigger events. The log is persistant and not overwritten when the IPNetSentry FBA restarts).
  • reset (same as detailed BUT the log is reset each time the IPNetSentry FBA restarts).

EXAMPLE:

Top



#set\filter_logging\filter_logging_mode

turns filter logging on or off. IPNetSentry can log packets which arrive and matching existing filter entries. A use for filter logging would be to watch if a remote intruder kept hitting your machine even after the intruder was blocked by IPNetSentry (with the 32 bit filter).

Filter logging is OFF by default (with no command entered in the IPNetSentry config file).

filter_logging_mode is one of the following options:

  • on (matching filter events are logged).
  • on no broadcast (matching filter events are logged, but NOT from broadcast datagrams (destination address is 255.255.255.255)).
  • off (matching filter events are not logged).

EXAMPLES:

Top



#set\firewall_logging_mode\mode_of_firewall_logging

sets the logging mode for IPNetSentry and Who's There Firewall Advisor

mode_of_firewall_logging is one of the following options:

  • normal (trigger events are logged. The log is persistant and not overwritten when the IPNetSentry FBA restarts).
  • reset (same as detailed BUT the log is reset each time the IPNetSentry FBA restarts).

EXAMPLE:

Top



#set\hex_dump_ip_header\on

sets the hex dump feature to on. When the hex dump feature is on, and a datagram arrives which matches a filter (or trigger), the entire datagram IP header is dumped in the log file in hexadecimal format (for manaul analysis). This feature is primarily used to identify datagrams which arrive but are not automatically recognized as being IPv4 datagrams of known protocols.

IP Header format is specified in RFC 791 and is summarized as follows:

 0                   1                   2                   3   
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |Version|  IHL  |Type of Service|          Total Length         |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |         Identification        |Flags|      Fragment Offset    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Time to Live |    Protocol   |         Header Checksum       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                       Source Address                          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Destination Address                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Options                    |    Padding    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                     
EXAMPLE:  
Top              



#set\public_port_name\port_name

sets the default port on which IPNetSentry aged filters will be invoked. This is important for IPNetRouter users who are sharing a PPP connection since the public port (PPP) is not the primary interface.

Normally this command does not have to be used.

port_name is any valid port name on your machine

EXAMPLES:

Top



#set\excluded_subnet\the_excluded_subnet

sets a subnet which will be excluded from invoking triggers (even if a machine on this subnet hits a trigger). This command would be useful if

  • you do not want client machines on your private IPNetRouter subnet to cause unnecessary triggers.
  • there is a remote machine (e.g. office) with a static IP address for which you always want to give access to your home machine. You do not want this office machine to accidently hit a trigger on the home machine, thereby banning this remote machine from any access.

You can exclude up to 5 different subnets (use this command multiple times). The_excluded_subnet is an IP address and mask suffix which specifies the subnet

EXAMPLES:




#set\max_log_size\max_size_in_KBytes

sets the maximum log size. When IPNetSentry starts, it checks the current size of the log file (IPNetSentry.log and IPNetSentry_FA.log). If either file size exceeds the size set with this command, you are alerted to this fact. The default log size is 1000 KBytes (if this command is not used).

This command does not have to be used.

max_size_in_KBytes is the maximum log size in KBytes

EXAMPLE:

Top



#set\denial_of_service_interval\dos_measured_interval

sets the time in seconds that a denial of service type attack will be measured. Used in conjunction with the denial_of_service_events parameter. (see below)

This command does not have to be used.

dos_measured_interval is the time in seconds that a Denial of Service type attack will be measured.

EXAMPLE:

Top



#set\denial_of_service_events\number_of_dos_events

sets the number of events which determines a denial of service type attack. Used in conjunction with the denial_of_service_interval parameter.

This command does not have to be used.

dos_measured_interval is the time in seconds that a Denial of Service type attack will be measured

EXAMPLE:

A Denial of Service (DoS) type attack is essentially a remote machine (or machines) bombarding your machine with so many incoming datagrams that no other valid traffic can pass.

How IPNetSentry detects a DoS attack: Once a filter is invoked by a trigger (or manually configured), IPNetSentry will receive a message when an incoming datagram matches a filter. As an intruder continues to hit your machine with datagrams, even though they are prevented from accessing your machine, IPNetSentry silently counts the number of packets received. If the number of incoming packets from a remote IP address exceeds the specified denial of service events in the specified interval (denial of service interval) then you are notified of a possible Denial of Service attack. Further logging of these filter events is also prevented (for this single remote IP address). This prevents a DoS attacker from filling your log file with filter entries.

Example calculation of possible DoS attack parameters:

DoS parameters depend on your Internet connection speed (incoming). It takes more datagrams per second to flood a cable or DSL modem connection than it does to flood a 56K analog modem connection.

Cable modem example:

Assume our cable modem download speed is 768 kb/s (kilobits/second). 768 kb/s x 1 Byte/8 bits = 96 KB/s

96 KB/s x 1000 Bytes/1 KB x 1 datagram/1500 Bytes = 64 datagrams/s

(1500 bytes is the typical Maximum Transmission Unit size for a cable/DSL/ADSL modem)

This tells us that we could set our parameters for 64 denial of service events (datagrams) every 1 second. But 1 second is a little too short of a period to accurately get a measurement. 10 seconds would be a much better period over which to measure and truly give us solid indication of a DoS type attack. This would equate to:

64 datagrams/1 sec = 640 datagrams/10 secs

Rounding down (to make our DoS trigger a bit more sensitive than the theoretical maximum), we get:

#set\denial_of_service_interval\10
#set\denial_of_service_events\600

 

56K Analog modem example:

Assume our analog modem download speed is 44 kb/s (kilobits/second). 44 kb/s x 1 Byte/8 bits = 5.5 KB/s

5.5 KB/s x 1000 Bytes/1 KB x 1 datagram/500 Bytes = 11 datagrams/s

(500 bytes is the typical Maximum Transmission Unit size for an analog modem).

This tells us that we could set our parameters for 11 denial of service events (datagrams) every 1 second. But 1 second is a little too short of a period to accurately get a measurement. 10 seconds would be a much better period over which to measure and truly give us solid indication of a DoS type attack. This would equate to:

11 datagrams/1 sec = 110 datagrams/10 secs

Rounding down (to make our DoS trigger a bit more sensitive than the theoretical maximum), we get:

#set\denial_of_service_interval\10
#set\denial_of_service_events\100

Top

 



#set\payload_inspection\protocol\port\log_block\offset
\inspection_string\notification_string\notification_method
\age_time\tcp_disconnect

sets a payload inspection type trigger. This command is mainly used to detect worms and other viruses (e.g. Code Red Worm). It does this by examing the payload portion of a datagram for a specific character pattern (through the first 64 bytes of a datagram).

This command does not have to be used.

protoocol: tcp, udp, gre, etc.

port: 1 -65535

log_block: on or off. Setting this tells IPNetSentry if it should continue logging incoming blocked packets (after the payload inspection criteria is met). On will continue to logged blocked packets from the intruding IP address. Off will not continue to logged blocked packets from the intruding IP address.

offset: how many 4 byte units (words) from the beginning of the packet datagram the inspection routine should start looking for the special character pattern. The beginning of the packet datagram starts at the beginning of the packet header. The payload (actual data) begins at offset 6 (24 bytes from the start of the datagram). The offset is used to increase the performance of the inspection routine (no need to search the IP header for the character pattern).

NEW (3/28/02): this parameter can also be specified as a "word offset:byte length" parameter. This gives you more control over the start and length of the datagram scan, and will search the datagram further down the packet. For example, "10:128" will start the search at word offset 10 (40 bytes) and for 128 bytes after this offset. This syntax is often needed to detect various hack attempts at servers, such as the File Maker Pro hacker access intrusion. See the example below for a payload inspection command which detects this access and blocks it.

inspection_string: the character pattern which is being sought. When found (within the first 64 bytes of the datagram), the inspection criteria is met and a filter is invoked against the source IP address.

notification_string: the string which will appear in the notification alert, log, apple event, etc. when the inspection routine detects a match.

notification_method: one of the following options:

  • none
  • alert (displays an alert with trigger info)
  • browser (takes your browser to a page at Sustworks.com which gives you detailed info about the intrusion)
  • both (alert and browser. Browser is conditionally invoked IF you hold down the Shift key when you click OK to the alert button)
  • applescript (applescript is invoked when an intrusion is detected. AppleScript name is required - see below).
  • syslog (a syslog message is sent to a designated syslog server with a UDP message on port 514. Syslog server IP address or Domain Name is required - see below).

When no notifcation_method is specified in the command, the default notification method is used.

age_time: sets the age time of a filter which is invoked when the payload inspection criteria is met. If no age time is specified, the default filter time is used.

tcp_disconnect: when set to "1", a tcp connection will be actively disconnected. Some worms leave connections up (such as the Code Red worm). In this case the disconnect flag would be set to 1 so that IPNetSentry can actively disconnect the TCP connection after installing the block filter.

Other worms (such a Nimda) immediately abort the TCP connection as soon as they have established the TCP connection with a server. In this case you want to set the tcp_disconnect flag to 0 (no active disconnect) because the Nimda infected machine would have already aborted the connection.

EXAMPLE:

The above example is the payload inspection command used to detect the Code Red Worm.

EXAMPLE:

The above are the payload inspection commands used to detect the Nimda Worm.

EXAMPLE:

The above example is the payload inspection command used to detect and block the File Maker Pro hacker access intrusion.

Top



#set\saved_aged_filter_file_interval\interval_time

interval_time is the time in seconds that the aged filter table should be checked to see if any changes should be saved to disk

When a filter is added or removed from the Aged Filter table, a signal is set which tells IPNetSentry that the Aged Filter table has changed, and that this table should be saved to disk. Before, this saving operation occurred at for every change (i.e. event driven). We have now made the saving of the Aged Filter table to be interval driven.

IF you set the in to -1, saving of the Aged Filter table is completely disabled. This may be desireable when using IPNetSentry in extremely high-speed network environments.

IF, you do not specify this command in the IPNetSentry Config file, the default value of 0 is used, essentially making this saving operation event driven (the previous method).

This command does not have to be used and is completely optional.

The example below will check the aged filter table for changes every 60 seconds, and if changes are flagged, the revised aged filter table will be saved to disk.

EXAMPLE:

Top



#set\log_file_interval\-1

turns off logging to disk. This may be desireable when using IPNetSentry in extremely high-speed network environments.

This command does not have to be used and is completely optional.

EXAMPLE:

Top



#set\max_aged_filter_table_size\table_size

table_size is a value between 1 to 1900

We have increased the filter table size to 2000 entries, 1900 of which are available to be used by IPNetSentry. This not only involved a change in the IPNetSentry.PPC FBA extension, but also in the OTModl$Proxy module.

The default Aged Filter table size is 150 entries. This command does not have to be used and is completely optional.

Even though IPNetSentry now has the capacity to hold up to 1900 Aged Filter entries, we offer you the flexibility of specifying how large this table can really get. This is done with the following command:

EXAMPLE:

Top


TRIGGER COMMANDS - used to set the triggers within the IPNetSentry FBA

+trigger\protocol\port\service\optional_notification

invokes a trigger for a specified protocol and port. The protocol and port define a service, for which you can give it a name. You can set up to 60 different triggers in a single configuration.

protocol is TCP, UDP or ICMP

port is any port between 1-65535. For ICMP the port is the Type

service is the service name defined by the protocol and port (type)

optional_notification is a specific notification action desired for this specific trigger. This optional setting overrides the default trigger notification mechanism specified in the #set/notification_type command.

EXAMPLES:

Top

FILTER COMMANDS - used to set static filters within the IPNetSentry FBA

+filter\port\direction\action\protocol\ack\source_net
\source_ports\destination_net\destination_ports

invokes a static filter within the IPNetSentry FBA. This is mostly used to permit specified remote machines access to your machine. Setting up static filters can be complex. If you do decide to build your own filters, please understand each of the parameters above.

port is the port on which the filter will be applied. Normally you would designate this as "Default_Interface", although any other valid port name could be used.

direction is either Rcv or Snd. For IPNetSentry this field is normally set to Rcv.

action is Pass, Block, Trigger, or Log

protocol can be TCP, UDP, ICMP, GRE or * (* is a wildcard for all protocols).

ack is a TCP acknowledge flag and can be set to 1, 0, or *. Normally this is set to *

source_net is the source network address and mask suffix for the filter (filtering on the condition "which IP address or network did packets originated").

source_ports are the source ports for the filter (filtering on the condition "from which ports did packets originate").

destination_net is the destination network address and mask suffix for the filter (filtering on the condition "for which IP address or network are packets destined").

destination_ports are the destination ports for the filter (filtering on the condition "for which ports are the packets destined").

When configuring IPNetSentry for exclusive access, you actually have to configure two separate filters. The first filter (lowermost) blocks all incoming packets for a specific service. The second filter (uppermost) passes all incoming packets from a specified source network.

EXAMPLES:

Permitting access to your machine for Apple Filesharing over TCP/IP from a specific remote machine at IP address 24.123.58.62:

IF you had another remote machine that you wished to give access to this same service, then you only need to add another Pass filter (since the Block filter would already be in place):

Log all incoming ICMP datagrams:

Log all outgoing HTTP datagrams

Top