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  configures syslog to write all kern.info messages to a named pipe
39       /var/lib/psad/psadfifo and then reads all messages out of the pipe that
40       are  matched  by  a string designed to catch any packets that have been
41       logged (and possibly dropped) by the firewall.  In  this  way  psad  is
42       supplied with a pure data stream that exclusively contains packets that
43       the firewall has deemed unfit to enter the network.  psad  consists  of
44       three  daemons:  psad, kmsgsd, and psadwatchd.  psad is responsible for
45       processing all packets that have been logged by the firewall and apply‐
46       ing  the  signature  logic  in order to determine what type of scan has
47       been leveraged against the machine and/or network.   kmsgsd  reads  all
48       messages  that  have  been  written to the /var/lib/psad/psadfifo named
49       pipe and writes any message that matches a particular  regular  expres‐
50       sion  (or  string)  to  /var/log/psad/fwdata.  psadwatchd is a software
51       watchdog that will restart any of the other two daemons should a daemon
52       die for any reason.
53

OPTIONS

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

FILES

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

PSAD CONFIGURATION VARIABLES

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

EXAMPLES

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

DEPENDENCIES

718       psad requires that iptables is configured with a "drop and log"  policy
719       for  any  traffic that is not explicitly allowed through.  This is con‐
720       sistent with a secure network configuration since all traffic that  has
721       not  been explicitly allowed should be blocked by the firewall ruleset.
722       By default, psad attempts to determine whether or not the firewall  has
723       been  configured  in  this  way.  This feature can be disabled with the
724       --no-fwcheck or --log-server options.  The --log-server option is  use‐
725       ful if psad is running on a syslog logging server that is separate from
726       the firewall.  For more information on  compatible  iptables  rulesets,
727       see the FW_EXAMPLE_RULES file that is bundled with the psad source dis‐
728       tribution.
729
730       psad also requires that syslog be configured  to  write  all  kern.info
731       messages to the named pipe /var/lib/psad/psadfifo.  A simple
732
733              echo -e 'kern.info |/var/lib/psad/psadfifo' >> /etc/syslog.conf
734
735       will  do.   Remember  also  to restart syslog after the changes to this
736       file.
737

DIAGNOSTICS

739       The --debug option can be used to display crucial information about the
740       psad  data  structures  on STDOUT as a scan generates firewall log mes‐
741       sages.  --debug disables daemon mode execution.
742
743       Another more effective way to peer into the runtime execution  of  psad
744       is to send (as root) a USR1 signal to the psad process which will cause
745       psad   to   dump    the    contents    of    the    %Scan    hash    to
746       /var/log/psad/scan_hash.$$  where  $$  represents  the  pid of the psad
747       process.
748

SEE ALSO

750       iptables(8), kmsgsd(8), psadwatchd(8), fwsnort(8),  snort(8),  nmap(1),
751       p0f(1), gnuplot(1)
752

AUTHOR

754       Michael Rash <mbr@cipherdyne.org>
755

CONTRIBUTORS

757       Many  people  who are active in the open source community have contrib‐
758       uted to psad.  See the CREDITS file  in  the  psad  sources,  or  visit
759       http://www.cipherdyne.org/psad/docs/contributors.html   to   view   the
760       online list of contributors.
761

BUGS

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

DISTRIBUTION

784       psad is distributed under the GNU General Public License (GPL), and the
785       latest version may be downloaded from: http://www.cipherdyne.org/ Snort
786       is a registered trademark of Sourcefire, Inc.
787
788
789
790Linux                             March 2009                           PSAD(8)
Impressum