"Fossies" - the Fresh Open Source Software Archive

Member "portsentry-2.0b1/README.install" (8 Apr 2002, 17608 Bytes) of package /linux/privat/old/portsentry-2.0b1.tar.gz:

As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Psionic PortSentry - Port scan detection and active defense.
    2 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
    4 $Id: README.install,v 1.30 2002/04/08 17:24:14 crowland Exp crowland $
    6 E-Mail : sentrysupport@psionic.com
    7 Date   : 04-08-2002
    8 Version: 2.0b1
   10 Introduction
   11 =-=-=-=-=-=-
   13 This is the "long" install version. You should read this file if you want
   14 to understand everything going on and the method to the madness in the
   15 program logic. Skip to Install down below if you don't care about this.
   17 PortSentry is part of Psionic's TriSentry Suite of security products. If you like
   18 this tool you will really like our other products. Check our website at:
   20 http://www.psionic.com
   22 PortSentry has a number of options to detect port scans, when it finds one it
   23 can react in the following ways:
   25 	- A log indicating the incident is made via syslog()
   26 	- The target host is automatically dropped into /etc/hosts.deny
   27 	  for TCP Wrappers
   28 	- The local host is automatically re-configured to route all
   29 	  traffic to the target to a dead host to make the target system
   30 	  disappear.
   31 	- The local host is automatically re-configured to drop all
   32 	  packets from the target via a local packet filter.
   35 The purpose of this is to give an admin a heads up that their host is
   36 being probed. There are similar programs that do this already (klaxon,
   37 etc.) We have added a little twist to the whole idea (auto-blocking), plus
   38 extensive support for stealth scan detection.
   40 PortSentry 2.x has been re-written to use libpcap. The old "classic" modes
   41 that used bound ports to detect attacks has been removed. If you liked the
   42 "classic" modes, please use the 1.1 version of PortSentry.
   44 Install
   45 =-=-=-=
   47 Step ONE:
   49 Pull the portsentry_config.h file into your editor and make sure the
   50 following are to your liking:
   52 CONFIG_FILE - The path to the PortSentry configuration file.
   53 WRAPPER_HOSTS_DENY - The path and name of TCP wrapper hosts.deny file.
   54 SYSLOG_FACILITY - The syslog facility for PortSentry to use.
   55 SYSLOG_LEVEL - The syslog level to send messages.
   57 We suggest not changing any of these options unless you know what you
   58 are doing.
   60 NOTE: For advanced users, you may wish to change the SYSLOG_FACILITY from
   61 LOG_DAEMON to LOG_LOCAL0 (or one of the other LOCAL reporting facilities).
   62 This will allow you to edit the syslog.conf file and drop PortSentry
   63 messages direcly to its own file on the system for separate monitoring.
   66 they are required by the C compiler to pre-process the headers. If you delete
   67 the "#" signs you will get compile errors.
   69 THIRD NOTE: Read the SECOND NOTE again. We get a lot of questions from people who
   70 delete the "#" signs and then can't compile the program. Note that the
   71 portsentry_config.h will probably go away as the 2.x version exits beta.
   74 Step TWO:
   76 Next, pull in portsentry.conf into your editor and check/change the
   77 following options:
   79 INTERFACE - The interface name you want to monitor. Most people can leave
   80 this as "auto" and PortSentry will figure out the primary interface to monitor.
   81 Others though may have multiple interfaces and want to watch only one (i.e.
   82 a firewall external interface). In this case you can set the interface name
   83 manually. Don't include "/dev/eth0" to watch eth0, just put in the interface
   84 name "eth0", etc. in here. PortSentry can only watch one interface at a time
   85 so don't put in multiple names.
   87 INTERFACE_ADDRESS - PortSentry needs to know the IP Address of the Interface
   88 you are watching. This version does not figure this out automatically, but
   89 should in the near future. If you don't put in the address then PortSentry will
   90 not work properly. This is not a great solution for DHCP or dynamic IP users, but
   91 will be fixed as the beta matures. For now you'll have to do this manually for
   92 static IPs, or write a quick script to do it automatically for you on system
   93 startup.
   95 TCP_PORTS - A comma delimited string of TCP ports you want PortSentry to
   96 listen to. This string can NOT have any spaces in it. You can put in as
   97 many sockets as you want but the Berkely Packet Filter (BPF) length may get
   98 too big and cause problems. If this happens you'll see an error message in the
   99 log file and should shorten the sting length.
  101 UDP_PORTS - The same as above, except for UDP ports.
  103 IGNORE_FILE - The path to the file that contains IP addresses of hosts you
  104 want to always be ignored. This will be explained later.
  106 BLOCKED_FILE - The path to the file that contains the IP addresses of
  107 blocked hosts.
  109 RESOLVE_HOST - This option turns off DNS resolution for hosts. If you have a
  110 slow DNS server it may be more effective to turn off resolution. Also if you have
  111 this turned on an attacker could see the DNS requests coming back to them and know
  112 you are monitoring connections. Default is to leave this off.
  114 BLOCK_UDP - This option disables all automatic responses to UDP probes.
  115 Because UDP can be easily forged, it may allow an attacker to start a
  116 denial of service attack against the protected host, causing it to block
  117 all manner of hosts that should normally be left alone. Setting this option
  118 to "0" will disable all responses, although the connects are still logged.
  119 This option is mainly useful for Internet exposed hosts. For internal hosts
  120 you should leave this enabled. If someone internally is firing spoofed
  121 packets at you, then you have a much bigger problem than a denial of service.
  123 BLOCK_TCP - Same as above, but for TCP. For stealth scan detection modes the
  124 UDP warning applies as well:
  126 	An attacker can cause you to block hosts you don't want to
  127 	through packet forgery.
  129 Every few months we get someone who writes and tells us this obvious point.
  130 Yes, we know about packet forgery, denial of service, etc. We just don't
  131 consider it as big of a risk compared to a system compromise so we leave
  132 this option enabled for most hosts (except certain hosts prone to being
  133 beat up on [firewall]). Read README.stealth for a more in-depth answer
  134 to what you should do.
  136 KILL_ROUTE - This is the command to run to drop the offending route if
  137 an attack is detected. This is the *full path* to the route command
  138 along with the necessary parameters to make the command work. The macro
  139 $TARGET$ will be substituted with the attacking host IP and is
  140 REQUIRED in this option. Your gateway should be a *dead host* on the
  141 local subnet. On some systems though you can just put in the localhost
  142 address ( and this will probably work. All packets from the
  143 target host will get routed to this address so don't mess this up.
  144 More modern route commands will include a "-blackhole" or "-reject" flag.
  145 Check your man(1) pages and if your route command supports this feature
  146 you should use it (although we recommend using packet filtering
  147 instead, see below).
  149 Also be aware that can create what is known as an "asynchronous
  150 route" which basically means packets enter your host via one route
  151 and are sent out on another (dead) route. This works OK for full
  152 TCP connect requests, but for UDP and stealth scan modes it
  153 still allows packets to activate PortSentry and you may get a
  154 series of "already blocked" alarms by PortSentry. For UDP scans
  155 this method prevents ICMP messages from returning to the attacker
  156 so all ports appear open. However, if the attacker is performing
  157 an actual exploit with UDP the drop route method will not work.
  158 The asynchronous route allows the packet to hit the system and the
  159 attacker could perform a "blind" attack with UDP if they know what
  160 the responses are going to be.
  162 By far the best method is to use the local packet filter (such as Linux
  163 ipchains/iptables, BSD ipfw, etc). This is a much cleaner solution and is
  164 detailed in the config file. The macro $PORT$ will substitute the port
  165 that was connected to by the attacker, but this is NOT required for this
  166 option. The macro $MODE$ reports what mode the blocking occurred in
  167 (tcp, udp) but is also NOT required.
  169 KILL_HOSTS_DENY - This is the format of the string to drop into the
  170 hosts.deny file that TCP wrappers uses. Again the $TARGET$ macro is
  171 expanded out to be the IP of the attacker and is required. You can
  172 also drop in any TCP wrapper escape codes here as well (%h, twist,
  173 etc). The macro $PORT$ will substitute the port that was connected to
  174 by the attacker, but this is NOT required for this option. The macro
  175 $MODE$ reports what mode the blocking occurred in (tcp, udp) but is also
  176 NOT required.
  178 KILL_RUN_CMD - This is a command you want run *before* the route
  179 is dropped to the attacker. You can put in any program/script you want
  180 executed when an attack is detected. WE NEVER RECOMMEND PUTTING IN
  182 are port scanned the host doing the scanning has been compromised itself.
  183 Therefore, if you retaliate you are probably attacking an innocent(?)
  184 party. Also the goal of security is to make the person GO AWAY. You don't
  185 want to irritate them into making a personal vendetta against you.
  186 Remember, even a 13 year old can run a [insert favorite D.O.S. program
  187 here] attack against you from their Windows box to make your life
  188 miserable. As above, the $TARGET$, $PORT$, and $MODE$ macros are
  189 available to you but they are not required with this option as above.
  191 KILL_RUN_CMD_FIRST - Setting this to "0" makes the command above run
  192 before the route is dropped. Setting it to "1" makes the command run
  193 after the blocking has occurred.
  195 SCAN_TRIGGER - PortSentry has a state engine that will remember hosts
  196 that connected to it. Setting this value will tell PortSentry to allow X
  197 number of grace port hits before it reacts. This will detect both
  198 sequential and random port sweeps. The default is 0 which will react
  199 immediately. A setting of 1 or 2 will reduce false alarms, anything
  200 higher is probably too much as anything more than 3 hits to different
  201 ports is pretty suspicious behavior. Usually you can leave this at 0
  202 without any consequence.
  204 Step THREE:
  206 Pull the portsentry.ignore file into your editor and add in any host you
  207 want to have ignored if it connects to a tripwired port. This should always
  208 contain at least the localhost ( and the IP's of the local
  209 interfaces. We would *not* recommend putting in every machine IP on your
  210 network, but you can use a netmask to do this. Format for this is:
  212 <IP Address>/<Netmask Bits>
  216 etc.
  218 We don't recommend ignoring too much. It may be important for you to see
  219 who is connecting to you, even if it is a "friendly" machine. This can
  220 help you detect internal host compromises faster.
  222 To answer your paranoia, yes this does happen and we've heard of *several*
  223 cases of admins ignoring too much and getting hacked by their *own compromised
  224 machines*
  227 Step FOUR:
  229 Compile. Type make and pick your system type and allow it to build and install.
  230 The default directory is /usr/local/psionic/portsentry2. If you don't like
  231 this directory just edit the Makefile and make sure your portsentry.conf and
  232 portsentry_config.h files reflect the new path.
  234 Type make install after the build to have it copy files to your install
  235 directory.
  237 Step FIVE:
  239 Start up PortSentry. Two ways to do this after install:
  241 1) cd to the install directory (/usr/local/psionic/portsentry2, etc.) and 
  242 type:
  244 ./portsentry
  246 2) Run the command directly:
  248 /usr/local/psionic/portsentry2/portsentry
  251 Stealth TCP scan detection mode [BETA]
  253 PortSentry will use monitor all incoming packets. If an incoming
  254 packet is destined for a monitored port listed in TCP_PORTS it will react
  255 to block the host. This method will detect connect() scans, SYN/half-open
  256 scans, XMAS scan, FIN scans, NULL scans, etc. UDP/Stealth scan warnings apply
  257 (read: README.stealth).
  259 "Stealth" UDP scan detection mode [BETA]
  261 This operates the same as the TCP stealth mode above. UDP ports need to be
  262 listed and they are then monitored. This does not bind any sockets, and
  263 while not really "stealth" scan detection (doesn't usually apply to UDP),
  264 it operates in a similar manner (reacts to *any* UDP packet). UDP/Stealth
  265 scan warnings apply (read: README.stealth).
  267 ** Advanced Logic Mode ** - PortSentry is intelligent about how it monitors
  268 ports. For some protocols such as FTP the client actually opens up ports
  269 in the ephemeral range (1024-65535) and the server then connects *back* to
  270 you. This would normally cause the port scanner to activate. PortSentry though
  271 will look at the incoming connection and determine if it is destined for
  272 one of these "temporary" bindings. If it is, then the connection is
  273 ignored for that one time. As soon as the connection is torn down the
  274 window closes and full protection is back again. This is in fact a
  275 rudimentary stateful inspection engine. UDP/Stealth scan warnings apply
  276 (read: README.stealth).
  279 Test the install:
  281 Tail the local log and you should see several PortSentry initialization
  282 messages.
  284 A successful startup looks like this:
  286 Mar  5 21:16:00 nemesis portsentry[2286]: adminalert: Monitoring interface
  287 eth0 and address:
  288 Mar  5 21:16:00 nemesis portsentry[2286]: adminalert: Monitoring TCP ports:
  289 1,11,110,143,635,1080
  290 . . .
  291 Mar  5 21:16:00 nemesis portsentry[2286]: adminalert: PortSentry is initialized
  292 and monitoring.
  294 ************************************************************************
  295 ** The last line indicates the PortSentry is properly initialized, if **
  296 ** you don't see it then something failed. 			      **
  297 ************************************************************************
  299 Now you can go to another host and telnet to a booby-trapped port.
  304 Read the above again. We get a fair number of people who write something
  305 like this to us (a dramatization, but you get the idea):
  307 "hi, i installed port sentry on my web server installed on an isolated oil
  308 platform in the north atlantic that's only accessible by helicopter for one
  309 week out of the year. i then went to the only admin system on the entire
  310 planet that can connect to it and tested port sentry by telneting to a protected
  311 port. now it looks like port sentry worked because i can't get to my box but
  312 now i need to get to my box. can you help me?"
  314 Anyway...
  316 You should immediately see something like:
  318 Mar  5 21:17:39 packetmonkey portsentry[2286]: attackalert: Host
  319 has been blocked via wrappers with string: "ALL:"
  320 Mar  5 21:17:39 packetmonkey portsentry[2286]: attackalert: TCP SYN scan from
  321 host to TCP port: 143 from TCP port: 31337
  323 If you disconnect and try to telnet back again you should find that the
  324 target system is now unreachable. Congratulations you are now operational.
  326 If you are running Logcheck this will show up in the next pass and
  327 it should be screaming at you.
  329 If you do a netstat -rn you will see the suspect host pointed at the dead
  330 route you supplied (unless using a packet filter, which is what we
  331 recommend).
  333 Drop the PortSentry commands in a startup file and get back to work as
  334 you are done.
  336 How will it help?
  338 Here are some ideas:
  340 	- Run as a UDP service on port 69 to catch TFTP probes.
  341 	- Run as a UDP service on port 161,162 to catch SNMP probes.
  342 	- Run as a UDP service in the port range 32000-33000 to catch RPC
  343 	  probes.
  344 	- Run as a TCP service on port 143 to catch IMAP probes.
  345 	- Run as a TCP service on ports 11,15 to catch netstat/systat
  346 	  probes.
  347 	- etc.
  349 The fact is that PortSentry reacts quickly enough that a port scan of your
  350 host by an attacker will be stopped within one second after hitting any
  351 tripwired port.
  353 For any type of UDP scan it will prove highly irritating for the person
  354 trying to scan you as all the ports will likely appear "open." For TCP scans
  355 the attacker will simply get no response whatsoever.
  357 Safety
  358 =-=-=-
  360 If we missed anything in the program's safety considerations we would very
  361 much like to hear about it before you post it to BugTraq :).
  363 Messages
  364 =-=-=-=-
  366 To the best we could, all states/errors/successes and unknowns are written
  367 to the syslog. The following tags identify each one:
  369 adminalert: - Some message indicating the status of the PortSentry.
  370 securityalert: - A message indicating a security relevant event occurred.
  371 attackalert: - A host has tripped a sensor and an action was performed.
  374 Files
  375 =-=-=
  377 As it stands now, all hosts are dropped into the portsentry.blocked file
  378 when they are blocked as well as a portsentry.history file. The blocked file
  379 is erased each time PortSentry is restarted. The history file is simply
  380 appended to and can be used as a record of all hosts that have been blocked
  381 to date.
  383 After a period of time elapses you may wish to delete the local dead route
  384 to the offender and keep them in the hosts.deny file. This is solely your
  385 choice. If you wish to re-enable blocking should the offender return, just
  386 re-start PortSentry or delete the individual entry from the blocked file.
  388 If you need to restore the route to the blocked host on most systems you can
  389 simply delete the route like so:
  391 Linux:
  393 route del <ip_address> reject
  395 Others:
  397 route delete <ip_address> <dead_route>
  399 Or you can simply flush your packet filters.
  401 That's about it. We highly recommend you use Logcheck to keep an eye
  402 on things in the log files as well so you can detect other problems, and
  403 see what the PortSentry is saying to you. You can find this program at:
  405 http://www.psionic.com
  407 Thanks for reading this and write if you have any questions or comments.
  410 Thanks,
  413 -- Craig
  415 Psionic Technologies, Inc.
  416 sentrysupport@psionic.com