1PSAD(8)                     System Manager's Manual                    PSAD(8)
2
3
4

NAME

6       psad - The Port Scan Attack Detector
7

SYNOPSIS

9       psad [options]
10

DESCRIPTION

12       psad  makes use of iptables log messages to detect, alert, and (option‐
13       ally) block port scans and other suspect traffic.  For TCP  scans  psad
14       analyzes  TCP  flags  to determine the scan type (syn, fin, xmas, etc.)
15       and corresponding command line options that could be supplied  to  nmap
16       to generate such a scan.  In addition, psad makes use of many TCP, UDP,
17       and ICMP signatures contained within the Snort intrusion detection sys‐
18       tem  (see  http://www.snort.org/)  to detect suspicious network traffic
19       such as probes for common  backdoors,  DDoS  tools,  OS  fingerprinting
20       attempts,  and  more.   By  default psad also provides alerts for snort
21       rules that are detected directly by iptables through the use of a rule‐
22       set  generated  by  fwsnort (http://www.cipherdyne.org/fwsnort/).  This
23       enables psad to send alerts for application layer attacks.   psad  fea‐
24       tures  a  set  of  highly configurable danger thresholds (with sensible
25       defaults provided) that allow the administrator to define what  consti‐
26       tutes  a port scan or other suspect traffic.  Email alerts sent by psad
27       contain the scanning ip, number of packets sent to each port, any  TCP,
28       UDP, or ICMP signatures that have been matched (e.g. "NMAP XMAS scan"),
29       the scanned port range, the current danger level (from 1 to 5), reverse
30       dns info, and whois information.  psad also makes use of various packet
31       header fields associated with TCP SYN packets to passively  fingerprint
32       remote operating systems (in a manner similar to the p0f fingerprinter)
33       from which scans originate.  This requires the use  of  the  --log-tcp-
34       options  argument  for  iptables  logging  rules; if this option is not
35       used, psad will fall back to a fingerprinting method that makes use  of
36       packet length, TTL and TOS values, IP ID, and TCP window sizes.
37
38       psad  reads all iptables log data by default from the /var/log/messages
39       file.  By parsing firewall log messages, psad  is  provided  with  data
40       that represents packets that have been logged (and possibly dropped) by
41       the running iptables policy.  In this sense, psad is  supplied  with  a
42       pure  data  stream  that exclusively contains packets that the firewall
43       has deemed unfit to enter the network.  psad consists of three daemons:
44       psad,  kmsgsd,  and psadwatchd.  psad is responsible for processing all
45       packets that have been logged by the firewall and applying  the  signa‐
46       ture  logic  in order to determine what type of scan has been leveraged
47       against the machine and/or network.  kmsgsd (deprecated) reads all mes‐
48       sages  that  have been written to the /var/lib/psad/psadfifo named pipe
49       and writes any message that matches a particular regular expression (or
50       string)   to   /var/log/psad/fwdata.    kmsgsd  is  only  used  if  the
51       ENABLE_SYSLOG_FILE variable is disabled in psad.conf.  psadwatchd is  a
52       software watchdog that will restart any of the other two daemons should
53       a daemon die for any reason.
54

OPTIONS

56       -A, --Analyze-msgs
57              Analyze an iptables logfile for scans and exit.  This will  gen‐
58              erate  email  alerts just as a normal running psad process would
59              have for all logged  scans.   By  default  the  psad  data  file
60              /var/log/psad/fwdata  is  parsed for old scans, but any file can
61              be specified through the use of the --messages-file command line
62              option.   For  example  it might be useful to point psad at your
63              /var/log/messages file.
64
65       --analysis-fields <search fields>
66              In --Analyze mode restrict analysis  to  iptables  log  messages
67              that  have  specific  values  for  particular  fields.  Examples
68              include "SRC:1.2.3.4", "DST:10.0.0.0/24, and "TTL:64", and  mul‐
69              tiple  fields  are  supported  as  a  comma-separated  list like
70              "SRC:1.2.3.4, LEN:44, DST:10.0.0.0/24".
71
72       -i, --interface <interface>
73              Specify the interface that psad will examine  for  iptables  log
74              messages.   This interface will be the IN= interface for packets
75              that are logged in the INPUT and FORWARD chains,  and  the  OUT=
76              interface for packets logged in the OUTPUT chain.
77
78       --sig-update
79              Instruct  psad to download the latest set of modified Snort sig‐
80              natures from http://www.cipherdyne.org/psad/signatures  so  that
81              psad  can  take  advantage  of  signature  updates  before a new
82              release is made.
83
84       -O, --Override-config <file>
85              Override config variable values that are normally read from  the
86              /etc/psad/psad.conf  file  with  values from the specified file.
87              Multiple override config files can be given as a comma separated
88              list.
89
90       -D, --Dump-conf
91              Dump the current psad config to STDOUT and exit.  Various pieces
92              of information such as the home network, alert email  addresses,
93              and  DShield user id are removed from the resulting output so it
94              is safe to send to others.
95
96       -F, --Flush
97              Remove any auto-generated firewall block rules if psad was  con‐
98              figured   to   automatically   respond   to   scans   (see   the
99              ENABLE_AUTO_IDS variable in psad.conf).
100
101       -S, --Status
102              Display the status of any psad processes that may or not be run‐
103              ning.   The  status  output  contains a listing of the number of
104              packets that have been processed by  psad,  along  with  all  IP
105              addresses  and corresponding danger levels that have scanned the
106              network.
107
108       --status-ip <ip>
109              Display status information associated with ip such as the proto‐
110              col  packet  counters  as  well as the last 10 packets logged by
111              iptables.
112
113       --status-dl <dl>
114              Display status information only for scans that  have  reached  a
115              danger level of at least dl
116
117       --status-summary
118              Instruct  psad to omit detailed IP information from --Status and
119              --Analyze modes.
120
121       -m, --messages-file <file>
122              This option is used to specify the file that will be  parsed  in
123              analysis mode (see the --Analyze-msgs option).  The default path
124              is the psad data file /var/log/psad/fwdata.
125
126       --CSV  Instruct  psad  to  parse   iptables   log   messages   out   of
127              /var/log/messages (by default, but this path can be changed with
128              the -m option), and print the packet fields on STDOUT in  comma-
129              separate value format.  This is useful for graphing iptables log
130              data    with     AfterGlow     (see     http://afterglow.source
131              forge.net/index.html).
132
133       --stdin
134              Acquire  iptables  log  data  from  STDIN instead of the default
135              /var/log/messages file.
136
137       --CSV-fields <tokens>
138              Instruct psad to only include a specific  set  of  iptables  log
139              message  fields  within the CSV output.  AfterGlow accepts up to
140              three fields for its graph data, so the  most  common  usage  of
141              this  option is "src dst dp" to print the source and destination
142              IP addresses, and the destination port number.
143
144       -K, --Kill
145              Kill the current psad process along with psadwatchd and  kmsgsd.
146              This  provides  a  quick and easy way to kill all psad processes
147              without having to look in the process table  or  appeal  to  the
148              psad-init script.
149
150       -R, --Restart
151              Restart  the currently running psad processes.  This option will
152              preserve the command line options  that  were  supplied  to  the
153              original psad process.
154
155       -U, --USR1
156              Send a running psad process a USR1 signal.  This will cause psad
157              to  dump  the  contents  of  the  %Scan   hash   to   the   file
158              "/var/log/psad/scan_hash.$$"  where  "$$"  represents the pid of
159              the psad process.  This is mostly useful for debugging purposes,
160              but  it  also  allows  the  administrator to peer into the %Scan
161              hash, which is the primary data structure  used  to  store  scan
162              data within system memory.
163
164       -H, --HUP
165              Send  all running psad daemons a HUP signal.  This will instruct
166              the daemons to  re-read  their  respective  configuration  files
167              without causing scan data to be lost in the process.
168
169       -B, --Benchmark
170              Run psad in benchmark mode.  By default benchmark mode will sim‐
171              ulate a scan of 10,000 packets (see the  --packets  option)  and
172              then  report  the  elapsed time.  This is useful to see how fast
173              psad can process packets on a specific machine.
174
175       -p, --packets <packets>
176              Specify the number of packets to analyze in  --Analyze  mode  or
177              use  in  --Benchmark  mode.   The  default  is 10,000 packets in
178              --Benchmark mode, and unlimited in --Analyze mode.
179
180       -d, --debug
181              Run psad in debugging mode.   This  will  automatically  prevent
182              psad  from  running  as a daemon, and will print the contents of
183              the %Scan hash and a few  other  things  on  STDOUT  at  crucial
184              points as psad executes.
185
186
187       -c, --config <configuration-file>
188              By  default  all of the psad makes use of the configuration file
189              /etc/psad/psad.conf for  almost  all  configuration  parameters.
190              psad can be made to override this path by specifying a different
191              file on the command line with the --config option.
192
193       --signatures <signatures-file>
194              The iptables firewalling code included within  the  linux  2.4.x
195              kernel  series has the ability to distinguish and log any of the
196              TCP flags present within TCP packets that traverse the  firewall
197              interfaces.  psad makes use of this logging capability to detect
198              several  types  of   TCP   scan   signatures   included   within
199              /etc/psad/signatures.   The  signatures were originally included
200              within the snort intrusion detection system.  New signatures can
201              be included and modifications to existing signatures can be made
202              to the signature file and psad  will  import  the  changes  upon
203              receiving a HUP signal (see the --HUP command line option) with‐
204              out having to restart the psad process.  psad also detects  many
205              UDP  and  ICMP  signatures  that were originally included within
206              snort.
207
208       -e, --email-analysis
209              Send alert emails when run in --Analyze-msgs mode.  Depending on
210              the  size  of  the  iptables logfile, using the --email-analysis
211              option could extend the runtime of psad by  quite  a  bit  since
212              normally  both DNS and whois lookups will be issued against each
213              scanning IP address.  As usual these  lookups  can  be  disabled
214              with the --no-rdns and --no-whois options respectively.
215
216       -w, --whois-analysis
217              By  default  psad  does  not issue whois lookups when running in
218              --Analyze-msgs mode.  The --whois-analysis option will  override
219              this  behavior  (when run in analysis mode) and instruct psad to
220              issue whois lookups against IP addresses  from  which  scans  or
221              other suspect traffic has originated.
222
223       --analysis-auto-block
224              Enable  auto-blocking  responses  when running in --Analyze-msgs
225              mode.  This is mostly useful only for the psad test  suite  when
226              auto-blocking responses are tested and verified.
227
228       --snort-type <type>
229              Restrict  the  type  of snort sids to type.  Allowed types match
230              the file names given to snort rules files such as "ddos", "back‐
231              door", and "web-attacks".
232
233       --snort-rdir <snort-rules-directory>
234              Manually  specify  the directory where the snort rules files are
235              located.  The default is /etc/psad/snort_rules.
236
237       --passive-os-sigs <passive-os-sigs-file>
238              Manually specify the path to the passive operating  system  fin‐
239              gerprinting signatures file.  The default is /etc/psad/posf.
240
241       --auto-dl <auto-dl-file>
242              Occasionally  certain  IP  addresses  are  repeat  offenders and
243              should automatically be given a higher danger level  than  would
244              normally  be  assigned.   Additionally,  some  IP  addresses can
245              always be ignored depending on your network  configuration  (the
246              loopback interface 127.0.0.1 might be a good candidate for exam‐
247              ple).  /etc/psad/auto_dl provides an interface for psad to auto‐
248              matically  increase/decrease/ignore  scanning  IP danger levels.
249              Modifications can be made to auto_dl (installed  by  default  in
250              /etc/psad)  and  psad  will  import  them  with  'psad -H' or by
251              restarting the psad process.
252
253       --fw-search <fw_search-file>
254              By default all of the psad makes use of the firewall search con‐
255              figuration  file  /etc/psad/fw_search.conf  for  firewall search
256              mode and search strings.  psad can be made to override this path
257              by  specifying  a  different  file  on the command line with the
258              --fw-search option.
259
260       --fw-list-auto
261              List all rules in iptables chains that are used by psad in auto-
262              blocking mode.
263
264       --fw-analyze
265              Analyze  the  local  iptables ruleset, send any alerts if errors
266              are discovered, and then exit.
267
268       --fw-del-chains
269              By default, if ENABLE_AUTO_IDS is  set  to  "Y"  psad  will  not
270              delete    the    auto-generated   iptables   chains   (see   the
271              IPT_AUTO_CHAIN keywords in psad.conf) if the --Flush  option  is
272              given.   The  --fw-del-chains option overrides this behavior and
273              deletes the auto-blocking chains from a running  iptables  fire‐
274              wall.
275
276       --fw-dump
277              Instruct  psad  to dump the contents of the iptables policy that
278              is running on the local system.  All IP  addresses  are  removed
279              from  the  resulting  output,  so it is safe to post to the psad
280              list, or communicate to others.  This option is most often  used
281              with --Dump-conf.
282
283       --fw-block-ip <ip>
284              Specify an IP address or network to add to the iptables controls
285              that are auto-generated by psad.  This allows psad to manage the
286              rule timeouts.
287
288       --fw-rm-block-ip <ip>
289              Specify  an  IP  address  or network to remove from the iptables
290              controls that are auto-generated by psad.
291
292       --fw-file <policy-file>
293              Analyze  the  iptables  ruleset  contained  within   policy-file
294              instead of the ruleset currently loaded on the local system.
295
296       --CSV-regex <regex>
297              Instruct  psad  to only print CSV data that matches the supplied
298              regex.  This regex is used to match against each of  the  entire
299              iptables log messages.
300
301       --CSV-neg-regex <regex>
302              Instruct  psad  to  only  print CSV data that does not match the
303              supplied regex.  This regex is used to negatively match  against
304              each of the entire iptables log messages.
305
306       --CSV-uniq-lines
307              Instruct psad to only print unique CSV data.  That is, each line
308              printed in --CSV mode will be unique.
309
310       --CSV-max-lines <num>
311              Limit the number of CSV-formatted lines that psad  generates  on
312              STDOUT.   This is useful to allow AfterGlow graphs to be created
313              that are not too cluttered.
314
315       --CSV-start-line <num>
316              Specify the beginning line number to start parsing  out  of  the
317              iptables log file in --CSV output mode.  This is useful for when
318              the log file is extremely large, and you want to begin parsing a
319              specific place within the file.  The default is begin parsing at
320              the beginning of the file.
321
322       --CSV-end-line <num>
323              Specify the ending line number to stop parsing the iptables  log
324              file in --CSV output mode.  This is useful for when the log file
325              is extremely large, and you do not  want  psad  to  process  the
326              entire thing.
327
328       --gnuplot
329              Enter  into Gnuplot mode whereby psad parses an iptables logfile
330              and creates .gnu and .dat files that are suitable  for  graphing
331              with Gnuplot.  The various --CSV command line arguments apply to
332              plotting iptables log with Gnuplot.
333
334       --gnuplot-template <file>
335              Use a template file for all Gnuplot graphing directives (this is
336              usually a .gnu file by convention).  Normally psad builds all of
337              the graphing directives based on various --gnuplot command  line
338              arguments, but the --gnuplot-template switch allows you to over‐
339              ride this behavior.
340
341       --gnuplot-file-prefix <file>
342              Specify a prefix for the .gnu, .dat, and  .png  files  that  are
343              generated  in --gnuplot mode.  So, when visualizing attacks cap‐
344              tured in an iptables logfile (let's say you  are  interested  in
345              port  scans),  you could use this option to have psad create the
346              two files portscan.dat, portscan.gnu, and Gnuplot will create an
347              additional  file  portscan.png  when  the  portscan.gnu  file is
348              loaded.
349
350       --gnuplot-x-label <label>
351              Set the label associated with the x-axis.
352
353       --gnuplot-x-range <range>
354              Set the x-axis range.
355
356       --gnuplot-y-label <label>
357              Set the label associated with the y-axis.
358
359       --gnuplot-y-range <range>
360              Set the y-axis range.
361
362       --gnuplot-z-label <label>
363              Set the label associated with the z-axis (only  if  --gnuplot-3D
364              is used).
365
366       --gnuplot-z-range <range>
367              Set the z-axis range. (only if --gnuplot-3D is used).
368
369       --gnuplot-3D
370              Generate  a  Gnuplot  splot graph.  This produces a three-dimen‐
371              sional graph.
372
373       --gnuplot-view
374              Set the viewing angle when graphing data in --gnuplot-3D mode.
375
376       --gnuplot-title <title>
377              Set the graph title for the Gnuplot graph.
378
379       -I, --Interval <seconds>
380              Specify the interval (in seconds) that psad should use to  check
381              whether  or  not packets have been logged by the firewall.  psad
382              will use the default of 15 seconds unless a different  value  is
383              specified.
384
385       -l, --log-server
386              This option should be used if psad is being executed on a syslog
387              logging server.  Running psad on a logging server requires  that
388              check_firewall_rules()  and auto_psad_response() not be executed
389              since the firewall is probably not being run locally.
390
391       -V, --Version
392              Print the psad version and exit.
393
394       --no-daemon
395              Do not run psad as a daemon.   This  option  will  display  scan
396              alerts on STDOUT instead of emailing them out.
397
398       --no-ipt-errors
399              Occasionally    iptables   messages   written   by   syslog   to
400              /var/log/messages seem to not conform  to  the  normal  firewall
401              logging  format  if the kernel ring buffer used by klogd becomes
402              full.  psad will write these message to /var/log/psad/errs/fwer‐
403              rorlog by default.  Passing the --no-ipt-errors option will make
404              psad ignore all such erroneous firewall messages.
405
406       --no-whois
407              By default psad will issue a whois query  against  any  IP  from
408              which  a  scan has originated, but this can be disabled with the
409              --no-whois command line argument.
410
411       --no-fwcheck
412              psad performs a rudimentary check of the firewall  ruleset  that
413              exists  on  the  machine  on which psad is deployed to determine
414              whether or not the firewall has a compatible configuration (i.e.
415              iptables has been configured to log packets).  Passing the --no-
416              fwcheck or --log-server options will disable this check.
417
418       --no-auto-dl
419              Disable auto danger level assignments.  This  will  instruct  to
420              not   import   any  IP  addresses  or  networks  from  the  file
421              /etc/psad/auto_dl.
422
423       --no-snort-sids
424              Disable snort sid processing mode.  This will instruct  psad  to
425              not  import snort rules (for snort SID matching in a policy gen‐
426              erated by fwsnort ).
427
428       --no-signatures
429              Disable psad signature processing.  Note that this  is  indepen‐
430              dent  of  snort  SID  matching in iptables messages generated by
431              fwsnort and also from the ICMP type/code validation routines.
432
433       --no-icmp-types
434              Disable ICMP type and code field validation.
435
436       --no-passive-os
437              By default psad will attempt to passively (i.e. without  sending
438              any  packets) fingerprint the remote operating system from which
439              a scan originates.  Passing the --no-passive-os option will dis‐
440              able this feature.
441
442       --no-rdns
443              psad  normally attempts to find the name associated with a scan‐
444              ning IP address, but this feature can be disabled with the --no-
445              rdns command line argument.
446
447       --no-kmsgsd
448              Disable  startup  of  kmsgsd.   This  option  is most useful for
449              debugging with individual iptables messages so that new messages
450              are not appended to the /var/log/psad/fwdata file.
451
452       --no-netstat
453              By default for iptables firewalls psad will determine whether or
454              not your machine is listening on a port for which a  TCP  signa‐
455              ture  has  been  matched.  Specifying --no-netstat disables this
456              feature.
457
458       -h, --help
459              Print a page of usage information for psad and exit.
460

FILES

462       /etc/psad/psad.conf
463              The main psad configuration file  which  contains  configuration
464              variables mentioned in the section below.
465
466       /etc/psad/fw_search.conf
467              Used  to  configure  the strategy both psad and kmsgsd employ to
468              parse iptables messages.  Using configuration  directive  within
469              this file, psad can be configured to parse all iptables messages
470              or only those that match specific log prefix  strings  (see  the
471              --log-prefix option to iptables).
472
473       /etc/psad/signatures
474              Contains  the  signatures  psad uses to recognize nasty traffic.
475              The signatures are written in a manner similar to the *lib  sig‐
476              nature files used in the snort IDS.
477
478       /etc/psad/icmp_types
479              Contains all valid ICMP types and corresponding codes as defined
480              by RFC 792.  By default,  ICMP  packets  are  validated  against
481              these  values  and  an alert will be generated if a non-matching
482              ICMP packet is logged by iptables.
483
484       /etc/psad/snort_rules/*.rules
485              Snort rules files that are consulted by default unless the --no-
486              snort-sids command line argument is given.
487
488       /etc/psad/auto_dl
489              Contains a listing of any IP addresses that should be assigned a
490              danger level based on any traffic that is logged  by  the  fire‐
491              wall.  The syntax is "<IP address> <danger level>" where <danger
492              level> is an integer from 0 to 5, with 0 meaning to  ignore  all
493              traffic from <IP address>, and 5 is to assign the highest danger
494              level to <IP address>.
495
496       /etc/psad/posf
497              Contains a listing of all passive operating system  fingerprint‐
498              ing  signatures.   These signatures include packet lengths, ttl,
499              tos, IP ID, and TCP window size values that are specific to var‐
500              ious operating systems.
501

PSAD CONFIGURATION VARIABLES

503       This  section describes what each of the more important psad configura‐
504       tion variables do and how they can be tuned to meet your  needs.   Most
505       of   the   variables   are  located  in  the  psad  configuration  file
506       /etc/psad/psad.conf but the FW_SEARCH_ALL and  FW_MSG_SEARCH  variables
507       are  located  in  the  file /etc/psad/fw_search.conf.  Each variable is
508       assigned sensible defaults for most network  architectures  during  the
509       install process.  More information on psad config keywords may be found
510       at: http://www.cipherdyne.org/psad/config.html
511
512       EMAIL_ADDRESSES
513              Contains a comma-separated list  of  email  addresses  to  which
514              email alerts will be sent.  The default is "root@localhost".
515
516       HOSTNAME
517              Defines  the  hostname  of the machine on which psad is running.
518              This will be used in the email alerts generated by psad.
519
520       HOME_NET
521              Define the internal network(s) that are connected to  the  local
522              system.   This  will  be  used in the signature matching code to
523              determine whether traffic matches snort rules, which  invariably
524              contain a source and destination network.  Multiple networks are
525              supported as a comma separated list, and each network should  be
526              specified  in  CIDR notation.  Normally the network(s) contained
527              in the HOME_NET variable should be  directly  connected  to  the
528              machine that is running psad.
529
530       IMPORT_OLD_SCANS
531              Preserve  scan  data  across  restarts  of  psad  or even across
532              reboots of the machine.  This is accomplished by  importing  the
533              data  contained  in  the  filesystem cache psad writes to during
534              normal operation back into  memory  as  psad  is  started.   The
535              filesystem   cache   data  in  contained  within  the  directory
536              /var/log/psad.
537
538       FW_SEARCH_ALL
539              Defines the search mode psad uses to  parse  iptables  messages.
540              By  default FW_SEARCH_ALL is set to "Y" since normally most peo‐
541              ple want all iptables log messages to be parsed for scan  activ‐
542              ity.   However,  if  FW_SEARCH_ALL is set to "N", psad will only
543              parse those iptables log  messages  that  match  certain  search
544              strings  that  appear  in  iptables  logs  with the --log-prefix
545              option.  This is useful for restricting psad to only operate  on
546              specific  iptables  chains  or  rules.  The strings that will be
547              searched for are defined with the  FW_MSG_SEARCH  variable  (see
548              below).   The  FW_SEARCH_ALL  variable  is  defined  in the file
549              /etc/psad/fw_search.conf since it is referenced by both psad and
550              kmsgsd.
551
552       FW_MSG_SEARCH
553              Defines a set of search strings that psad uses to identify ipta‐
554              bles messages that should be parsed for  scan  activity.   These
555              search  strings should match the log prefix strings specified in
556              the iptables ruleset  with  the  --log-prefix  option,  and  the
557              default  value for FW_MSG_SEARCH is "DROP".  Note that psad nor‐
558              mally parses all iptables messages,  and  so  the  FW_MSG_SEARCH
559              variable  is  only needed if FW_SEARCH_ALL (see above) is set to
560              "N".  The FW_MSG_SEARCH variable is referenced by both psad  and
561              kmsgsd so it lives in the file /etc/psad/fw_search.conf.
562
563       SYSLOG_DAEMON
564              Define  the  specific  syslog  daemon that psad should interface
565              with.  Psad supports three syslog daemons:  syslogd,  syslog-ng,
566              and metalog.  The default value of SYSLOG_DAEMON is syslogd.
567
568       IGNORE_PORTS
569              Specify a list of port ranges and/or individual ports and corre‐
570              sponding protocols that psad should complete  ignore.   This  is
571              particularly  useful for ignore ports that are used as a part of
572              a  port  knocking  scheme  (such  as  fwknop  http://www.cipher
573              dyne.org/fwknop/) for network authentication since such log mes‐
574              sages generated by the knock sequence may  otherwise  be  inter‐
575              preted  as  a  scan.   Multiple  ports and/or port ranges may be
576              specified   as   a   comma-separated   list,   e.g.     "tcp/22,
577              tcp/61000-61356, udp/53".
578
579       ENABLE_PERSISTENCE
580              If  "Y",  psad  will  keep  all scans in memory and not let them
581              timeout.   This  can  help  discover  stealthy  scans  where  an
582              attacker tries to slip beneath IDS thresholds by only scanning a
583              few ports over a long period of time.  ENABLE_PERSISTENCE is set
584              to "Y" by default.
585
586       SCAN_TIMEOUT
587              If ENABLE_PERSISTENCE is "N" then psad will use the value set by
588              SCAN_TIMEOUT to remove packets from the scan threshold  calcula‐
589              tion.  The default is 3600 seconds (1 hour).
590
591       DANGER_LEVEL{1,2,3,4,5}
592              psad uses a scoring system to keep track of the severity a scans
593              reaches (represented as a "danger level") over time.   The  DAN‐
594              GER_LEVEL{n} variables define the number of packets that must be
595              dropped by the firewall before psad will assign  the  respective
596              danger  level to the scan.  A scan may also be assigned a danger
597              level if the scan matches a particular  signature  contained  in
598              the signatures file.  There are five possible danger levels with
599              one being the lowest and five the highest.  Note there are  sev‐
600              eral  factors  that  can  influence how danger levels are calcu‐
601              lated: whether or not a  scan  matches  a  signature  listed  in
602              /etc/psad/signatures,  the  value  of  PORT_RANGE_SCAN_THRESHOLD
603              (see below), whether or not a scan comes  from  an  IP  that  is
604              listed in the /etc/psad/auto_dl file, and finally whether or not
605              scans are allowed  to  timeout  as  determined  by  SCAN_TIMEOUT
606              above.   If  a signature is matched or the scanning IP is listed
607              in /etc/psad/auto_dl, then the  corresponding  danger  level  is
608              automatically assigned to the scan.
609
610       PORT_RANGE_SCAN_THRESHOLD
611              Defines  the  minimum difference between the lowest port and the
612              highest port scanned before an alert is sent (the default  is  1
613              which  means that at least two ports must be scanned to generate
614              an alert).  For example, suppose an ip repeatedly scans a single
615              port  for  which  there  is  no special signature in signatures.
616              Then if PORT_RANGE_SCAN_THRESHOLD=1, psad  will  never  send  an
617              alert for this "scan" no matter how many packets are sent to the
618              port (i.e.  no matter what the value of DANGER_LEVEL1 is).   The
619              reason  for the default of 1 is that a "scan" usually means that
620              at least two ports are probed, but if you want psad to be  extra
621              paranoid  you  can  set  PORT_RANGE_SCAN_THRESHOLD=0 to alert on
622              scans to single ports (as long as the  number  of  packets  also
623              exceeds DANGER_LEVEL1).
624
625       SHOW_ALL_SIGNATURES
626              If  "Y", psad will display all signatures detected from a single
627              scanning IP since a scan was first detected instead of just dis‐
628              playing  newly-detected  signatures.  SHOW_ALL_SIGNATURES is set
629              to "N" by default.   All  signatures  are  listed  in  the  file
630              /etc/psad/signatures.
631
632       SNORT_SID_STR
633              Defines  the  string kmsgsd will search for in iptables log mes‐
634              sages that are generated by iptables rules  designed  to  detect
635              snort    rules.     The   default   is   "SID".    See   fwsnort
636              (http://www.cipherdyne.org/fwsnort/).
637
638       ENABLE_DSHIELD_ALERTS
639              Enable dshield alerting mode.  This will send a  parsed  version
640              of  iptables  log messages to dshield.org which is a (free) dis‐
641              tributed intrusion detection service.  For more information, see
642              http://www.dshield.org/
643
644       IGNORE_CONNTRACK_BUG_PKTS
645              If  "Y",  all TCP packets that have the ACK or RST flag bits set
646              will be ignored by psad since usually we see such packets  being
647              blocked  as  a  result  of the iptables connection tracking bug.
648              Note there are no signatures that make use of the RST  flag  and
649              very few that use ACK flag.
650
651       ALERT_ALL
652              If  "Y", send email for all new bad packets instead of just when
653              a danger level increases.  ALERT_ALL is set to "Y" by default.
654
655       PSAD_EMAIL_LIMIT
656              Defines the maximum number of emails that will  be  sent  for  a
657              single  scanning  IP  (default  is 50).  This variable gives you
658              some protection from psad sending  countless  alerts  if  an  IP
659              scans  your  machine constantly.  psad will send a special alert
660              if an IP has exceeded the email limit.  If  PSAD_EMAIL_LIMIT  is
661              set  to  zero,  then  psad  will ignore the limit and send alert
662              emails indefinitely for any scanning ip.
663
664       EMAIL_ALERT_DANGER_LEVEL
665              Defines the danger level a scan must reach before any  alert  is
666              sent.  This variable is set to 1 by default.
667
668       ENABLE_AUTO_IDS
669              psad has the capability of dynamically blocking all traffic from
670              an IP that has reached a  (configurable)  danger  level  through
671              modification  of  iptables  or  tcpwrapper rulesets.  IMPORTANT:
672              This feature is disabled by default since it is possible for  an
673              attacker  to  spoof  packets  from  a well known (web)site in an
674              effort to make it look as  though  the  site  is  scanning  your
675              machine, and then psad will consequently block all access to it.
676              Also, psad works by parsing firewall messages  for  packets  the
677              firewall  has  already  dropped, so the "scans" are unsuccessful
678              anyway.  However, some administrators prefer to take  this  risk
679              anyway  reasoning  that  they  can always review which sites are
680              being blocked and manually remove the block  if  necessary  (see
681              the --Flush option).  Your mileage will vary.
682
683       AUTO_IDS_DANGER_LEVEL
684              Defines  the  danger  level  a  scan must reach before psad will
685              automatically block the IP (ENABLE_AUTO_IDS must be set to "Y").
686

EXAMPLES

688       The following examples illustrate the command line arguments that could
689       be supplied to psad in a few situations:
690
691       Signature  checking, passive OS fingerprinting, and automatic IP danger
692       level assignments are enabled by default without having to specify  any
693       command line arguments (best for most situations):
694
695       # psad
696
697       Same as above, but this time we use the init script to start psad:
698
699       # /etc/init.d/psad start
700
701       Use  psad  as a forensics tool to analyze an old iptables logfile (psad
702       defaults to analyzing the /var/log/messages file if the  -m  option  is
703       not specified):
704
705       # psad -A -m <iptables logfile>
706
707       Run  psad  in forensics mode, but limit its operations to a specific IP
708       address "10.1.1.1":
709
710       # psad -A -m <iptables logfile> --analysis-fields src:10.1.1.1
711
712       Generate graphs of scan data using AfterGlow:
713
714       # psad --CSV --CSV-fields src dst dp --CSV-max 1000 -m  <iptables  log‐
715       file>  |  perl  afterglow.pl -c color.properties | neato -Tgif -o ipta‐
716       bles_graph.gif
717
718       The psad.conf, signatures,  and  auto_dl  files  are  normally  located
719       within  the  /etc/psad/ directory, but the paths to each of these files
720       can be changed:
721
722       # psad -c <config file> -s <signatures file> -a <auto ips file>
723
724       Disable the firewall check and the local port lookup subroutines;  most
725       useful if psad is deployed on a syslog logging server:
726
727       # psad --log-server --no-netstat
728
729       Disable  reverse  dns  and whois lookups of scanning IP addresses; most
730       useful if speed of psad is the main concern:
731
732       # psad --no-rdns --no-whois
733

DEPENDENCIES

735       psad requires that iptables is configured with a "drop and log"  policy
736       for  any  traffic that is not explicitly allowed through.  This is con‐
737       sistent with a secure network configuration since all traffic that  has
738       not  been explicitly allowed should be blocked by the firewall ruleset.
739       By default, psad attempts to determine whether or not the firewall  has
740       been  configured  in  this  way.  This feature can be disabled with the
741       --no-fwcheck or --log-server options.  The --log-server option is  use‐
742       ful if psad is running on a syslog logging server that is separate from
743       the firewall.  For more information on  compatible  iptables  rulesets,
744       see the FW_EXAMPLE_RULES file that is bundled with the psad source dis‐
745       tribution.
746
747       psad by default parses the /var/log/messages file for all iptables  log
748       data.
749

DIAGNOSTICS

751       The --debug option can be used to display crucial information about the
752       psad data structures on STDOUT as a scan generates  firewall  log  mes‐
753       sages.  --debug disables daemon mode execution.
754
755       Another  more  effective way to peer into the runtime execution of psad
756       is to send (as root) a USR1 signal to the psad process which will cause
757       psad    to    dump    the    contents    of    the    %Scan   hash   to
758       /var/log/psad/scan_hash.$$ where $$ represents  the  pid  of  the  psad
759       process.
760

SEE ALSO

762       iptables(8),  kmsgsd(8),  psadwatchd(8), fwsnort(8), snort(8), nmap(1),
763       p0f(1), gnuplot(1)
764

AUTHOR

766       Michael Rash <mbr@cipherdyne.org>
767

CONTRIBUTORS

769       Many people who are active in the open source community  have  contrib‐
770       uted  to  psad.   See  the  CREDITS  file in the psad sources, or visit
771       http://www.cipherdyne.org/psad/docs/contributors.html   to   view   the
772       online list of contributors.
773

BUGS

775       Send  bug  reports  to mbr@cipherdyne.org.  Suggestions and/or comments
776       are always welcome as well.
777
778       For iptables firewalls as  of  Linux  kernel  version  2.4.26,  if  the
779       ip_conntrack  module  is  loaded  (or compiled into the kernel) and the
780       firewall has been configured to keep state of connections, occasionally
781       packets  that are supposed to be part of normal TCP traffic will not be
782       correctly identified due to a bug in the firewall  state  timeouts  and
783       hence dropped.  Such packets will then be interpreted as a scan by psad
784       even though they are not part of any malicious activity.   Fortunately,
785       an  interim  fix  for  this  problem  is  to simply extend the TCP_CON‐
786       NTRACK_CLOSE_WAIT  timeout  value  in  linux/net/ipv4/netfilter/ip_con‐
787       ntrack_proto_tcp.c  from  60  seconds to 2 minutes, and a set of kernel
788       patches is included within the patches/ directory in the  psad  sources
789       to  change  this.  (Requires a kernel recompile of course; see the Ker‐
790       nel-HOWTO.)  Also, by default the IGNORE_CONNTRACK_BUG_PKTS variable is
791       set  to  "Y"  in  psad.conf which causes psad to ignore all TCP packets
792       that have the ACK bit set unless the packets match  a  specific  signa‐
793       ture.
794

DISTRIBUTION

796       psad is distributed under the GNU General Public License (GPL), and the
797       latest version may be downloaded from: http://www.cipherdyne.org/ Snort
798       is a registered trademark of Sourcefire, Inc.
799
800
801
802Linux                             March 2009                           PSAD(8)
Impressum