SNORT(8)						 SNORT(8)


NAME
       Snort - open source network intrusion detection system

SYNOPSIS
       snort [-abCdDeINopqsvVxX?] [-A alert-mode ] [-c rules-file
       ] [-F bpf-file ] [-g grpname ] [-h home-net ]  [-i  inter-
       face ] [-l log-dir ] [-L bin-log-file ] [-M smb-hosts-file
       ] [-n packet-count ] [-r tcpdump-file  ]	 [-S  n=v  ]  [-t
       chroot_directory ] [-u usrname ] expression

DESCRIPTION
       Snort  is  an open source network intrusion detection sys-
       tem, capable of performing real-time traffic analysis  and
       packet  logging	on  IP networks.  It can perform protocol
       analysis, content searching/matching and can  be	 used  to
       detect  a  variety  of  attacks and probes, such as buffer
       overflows, stealth port scans, CGI attacks, SMB probes, OS
       fingerprinting  attempts,  and  much  more.   Snort uses a
       flexible rules language to describe traffic that it should
       collect	or  pass, as well as a detection engine that uti-
       lizes a modular plugin architecture.   Snort  also  has	a
       modular	 real-time   alerting  capability,  incorporating
       alerting and logging plugins  for  syslog,  a  ASCII  text
       files,  UNIX sockets, WinPopup messages to Windows clients
       using Samba's smbclient,	 database  (Mysql/PostgreSQL/Ora-
       cle/ODBC) or XML.

       Snort  has  three  primary  uses.   It  can  be	used as a
       straight packet sniffer like tcpdump(1), a  packet  logger
       (useful	for network traffic debugging, etc), or as a full
       blown network intrusion detection system.

       Snort logs packets  in  tcpdump(1)  binary  format,  to	a
       database or in Snort's decoded ASCII format to a hierarchy
       of logging directories that are	named  based  on  the  IP
       address of the "foreign" host.

OPTIONS
       -A alert-mode
	      Alert  using the specified alert-mode.  Valid alert
	      modes include fast, full, none, and  unsock.   Fast
	      writes alerts to the default "alert" file in a sin-
	      gle-line, syslog style alert message.  Full  writes
	      the alert to the "alert" file with the full decoded
	      header as well as the alert  message.   None  turns
	      off  alerting.  Unsock is an experimental mode that
	      sends the alert information out over a UNIX  socket
	      to another process that attaches to that socket.

       -a     Display ARP packets when decoding packets.

       -b     Log  packets in a tcpdump(1) formatted file.    All
	      packets are logged in their native binary state  to
	      a	 tcpdump  formatted log file named with the snort



			   January 2001				1





SNORT(8)						 SNORT(8)


	      start  timestamp	and  "snort.log".   This   option
	      results in much faster operation of the program
	       since  it doesn't have to spend time in the packet
	      binary->text converters.	Snort can keep up  pretty
	      well with 100Mbps networks in "-b" mode.	To choose
	      an alternate name for the binary log file, use  the
	      "-L" switch.

       -c config-file
	      Use the rules located in file config-file.

       -C     Print  the  character  data from the packet payload
	      only (no hex).

       -d     Dump the application  layer  data	 when  displaying
	      packets in verbose or packet logging mode.

       -D     Run  Snort  in  daemon  mode.   Alerts  are sent to
	      /var/log/snort/alert unless otherwise specified.

       -e     Display/log the link layer packet headers.

       -F bpf-file
	      Read BPF filters from bpf-file.  This is handy  for
	      people  running  Snort  as  a SHADOW replacement or
	      with a love of super complex BPF filters.	 See  the
	      "expressions"  section  of  this	man page for more
	      info on writing BPF fileters.

       -g <grpname>
	      Change the GID Snort runs under to <grpname>  after
	      initialization.	This  switch allows Snort to drop
	      root priveleges after it's initialization phase has
	      completed as a security measure.

       -h home-net
	      Set  the "home network" to home-net.  The format of
	      this address variable is a network  prefix  plus	a
	      CIDR  block,  such  as  192.168.1.0/24.	Once this
	      variable is set, all decoded packet logging will be
	      done  relative  to  the home network address space.
	      This is useful because of the way that  Snort  for-
	      mats  its	 ASCII	log data.  With this value set to
	      the local	 network,  all	decoded	 output	 will  be
	      logged  into decode directories with the address of
	      the foreign computer as the directory  name,  which
	      is very useful during traffic analysis.

       -i interface
	      Sniff packets on interface.

       -I     Print out the receiving interface name in alerts.

       -l log-dir
	      Set  the	output logging directory to log-dir.  All
	      plain text alerts and  packet  logs  go  into  this
	      directory.   If  this  option is not specified, the
	      default logging directory is set to /var/log/snort.

       -L binary-log-file
	      Set  the filename of the binary log file to binary-
	      log-file.	 If this switch is not used, the  default
	      name  is	a timestamp for the time that the file is
	      created plus "snort.log".

       -M smb-hosts-file
	      Send WinPopup messages to the list of  workstations
	      contained	 in  the  smb-hosts-file  .   This option
	      requires Samba to be resident and in  the	 path  of
	      the machine running Snort.  The workstation file is
	      simple: each line of the file contains the SMB name
	      of the box to send the message to.

       -n packet-count
	      Process packet-count packets and exit.

       -N     Turn  off packet logging.	 The program still gener-
	      ates alerts normally.

       -o     Change the order in which the rules are applied  to
	      packets.	 Instead of being applied in the standard
	      Alert->Pass->Log order, this  will  apply	 them  in
	      Pass->Alert->Log order.

       -O     Obfuscate	 the  IP  addresses  when in ASCII packet
	      dump mode.  This switch changes  the  IP	addresses
	      that   get   printed  to	the  screen/log	 file  to
	      "xxx.xxx.xxx.xxx".  If the homenet  address  switch
	      is  set (-h), only addresses on the homenet will be
	      obfuscated while non- homenet IPs will be left vis-
	      ible.   Perfect  for posting to your favorite secu-
	      rity mailing list!

       -p     Turn off promiscuous mode sniffing.

       -q      Quiet operation. Don't display banner and initial-
	      ization information.

       -r tcpdump-file
	       Read   the  tcpdump-formatted  file  tcpdump-file.
	      This will cause Snort to read and process the  file
	      fed to it.  This is useful if, for instance, you've
	      got a bunch of SHADOW files that you want	 to  pro-
	      cess  for content, or even if you've got a bunch of
	      reassembled packet fragments which have been  writ-
	      ten into a tcpdump formatted file.

       -s     Send  alert  messages  to	 syslog.  On linux boxen,
	      they will appear in /var/log/secure,  /var/log/mes-
	      sages on many other platforms.

       -S n=v Set variable name "n" to value "v".  This is useful
	      for setting the value of a defined variable name in
	      a	 Snort	rules  file  to	 a command line specified
	      value.  For instance,  if	 you  define  a	 HOME_NET
	      variable name inside of a Snort rules file, you can
	      set this value from it's predefined  value  at  the
	      command line.

       -t chroot
	      Changes Snort's root directory to chroot after ini-
	      tialization.  Please note that all log/alert  file-
	      names  are  relative  to	the  chroot  directory if
	      chroot is used.

       -u uname
	      Change the UID Snort runs under to uname after ini-
	      tialization.

       -v     Be  verbose.   Prints  packets  out to the console.
	      There is one big problem with  verbose  mode:  it's
	      slow.   If you are doing IDS work with Snort, don't
	      use the -v switch, you WILL drop packets.

       -V     Show the version number and exit.

       -X     Dump the raw  packet  data  starting  at	the  link
	      layer.  This switch overrides the -d switch.

       -?     Show the program usage statement and exit.

	expression
	      selects  which  packets  will  be	 dumped.   If  no
	      expression is given, all packets on the net will be
	      dumped.	Otherwise, only packets for which expres-
	      sion is `true' will be dumped.

	      The expression consists of one or more  primitives.
	      Primitives  usually  consist of an id (name or num-
	      ber) preceded by one or more qualifiers.	There are
	      three different kinds of qualifier:

	      type   qualifiers	 say  what  kind  of thing the id
		     name or number refers  to.	  Possible  types
		     are  host,	 net and port.	E.g., `host foo',
		     `net 128.3', `port 20'.  If there is no type
		     qualifier, host is assumed.

	      dir    qualifiers	 specify  a  particular	 transfer
		     direction	to  and/or  from  id.	 Possible
		     directions	 are src, dst, src or dst and src
		     and dst.  E.g., `src foo', `dst net  128.3',
		     `src  or dst port ftp-data'.  If there is no
		     dir qualifier, src or dst is  assumed.   For
		     `null' link layers (i.e. point to point pro-
		     tocols such as slip) the  inbound	and  out-
		     bound  qualifiers	can  be used to specify a
		     desired direction.

	      proto  qualifiers restrict the match to a	 particu-
		     lar  protocol.   Possible protos are: ether,
		     fddi,  ip,	 arp,  rarp,  decnet,  lat,  sca,
		     moprc, mopdl, tcp and udp.	 E.g., `ether src
		     foo', `arp net 128.3', `tcp  port	21'.   If
		     there  is	no proto qualifier, all protocols
		     consistent with the type are assumed.  E.g.,
		     `src  foo'	 means	`(ip  or arp or rarp) src
		     foo' (except the latter is	 not  legal  syn-
		     tax),  `net  bar' means `(ip or arp or rarp)
		     net bar' and `port 53' means `(tcp	 or  udp)
		     port 53'.

	      [`fddi'  is  actually  an	 alias	for  `ether'; the
	      parser treats them  identically  as  meaning  ``the
	      data  link  level	 used  on  the	specified network
	      interface.''  FDDI  headers  contain  Ethernet-like
	      source and destination addresses, and often contain
	      Ethernet-like packet types, so you  can  filter  on
	      these FDDI fields just as with the analogous Ether-
	      net  fields.   FDDI  headers  also  contain   other
	      fields,  but  you	 cannot name them explicitly in a
	      filter expression.]

	      In addition to the above, there  are  some  special
	      `primitive' keywords that don't follow the pattern:
	      gateway, broadcast, less,	 greater  and  arithmetic
	      expressions.  All of these are described below.

	      More  complex  filter  expressions  are built up by
	      using the words and, or and not to  combine  primi-
	      tives.   E.g.,  `host  foo and not port ftp and not
	      port ftp-data'.  To save typing,	identical  quali-
	      fier lists can be omitted.  E.g., `tcp dst port ftp
	      or ftp-data or domain' is exactly the same as  `tcp
	      dst  port	 ftp  or tcp dst port ftp-data or tcp dst
	      port domain'.

	      Allowable primitives are:

	      dst host host
		     True if the  IP  destination  field  of  the
		     packet  is	 host,	which  may  be	either an
		     address or a name.

	      src host host
		     True if the IP source field of the packet is
		     host.

	      host host
		     True  if either the IP source or destination
		     of the packet is host.   Any  of  the  above
		     host  expressions	can be prepended with the
		     keywords, ip, arp, or rarp as in:
			  ip host host
		     which is equivalent to:
			  ether proto \ip and host host
		     If	 host  is  a  name   with   multiple   IP
		     addresses,	 each address will be checked for
		     a match.

	      ether dst ehost
		     True if the ethernet destination address  is
		     ehost.   Ehost  may  be  either  a name from
		     /etc/ethers or a number (see ethers(3N)  for
		     numeric format).

	      ether src ehost
		     True  if  the  ethernet  source  address  is
		     ehost.

	      ether host ehost
		     True if either the ethernet source or desti-
		     nation address is ehost.

	      gateway host
		     True  if  the packet used host as a gateway.
		     I.e., the	ethernet  source  or  destination
		     address  was  host but neither the IP source
		     nor the IP destination was host.  Host  must
		     be	  a  name  and	must  be  found	 in  both
		     /etc/hosts and /etc/ethers.  (An  equivalent
		     expression is
			  ether host ehost and not host host
		     which  can be used with either names or num-
		     bers for host / ehost.)

	      dst net net
		     True if the IP destination	 address  of  the
		     packet  has a network number of net. Net may
		     be either a name  from  /etc/networks  or	a
		     network	number	 (see	networks(4)   for
		     details).

	      src net net
		     True if the IP source address of the  packet
		     has a network number of net.

	      net net
		     True  if either the IP source or destination
		     address of the packet has a  network  number
		     of net.

	      net net mask mask
		     True  if the IP address matches net with the
		     specific netmask.	May be qualified with src
		     or dst.

	      net net/len
		     True if the IP address matches net a netmask
		     len bits wide.  May be qualified with src or
		     dst.

	      dst port port
		     True  if  the packet is ip/tcp or ip/udp and
		     has a destination port value of  port.   The
		     port  can	be  a  number  or  a name used in
		     /etc/services (see tcp(4P) and udp(4P)).  If
		     a	name  is  used,	 both the port number and
		     protocol  are  checked.   If  a  number   or
		     ambiguous name is used, only the port number
		     is checked (e.g., dst port	 513  will  print
		     both  tcp/login traffic and udp/who traffic,
		     and port domain will print	 both  tcp/domain
		     and udp/domain traffic).

	      src port port
		     True  if  the packet has a source port value
		     of port.

	      port port
		     True if either  the  source  or  destination
		     port  of  the  packet  is	port.  Any of the
		     above port expressions can be prepended with
		     the keywords, tcp or udp, as in:
			  tcp src port port
		     which  matches only tcp packets whose source
		     port is port.

	      less length
		     True if the packet has a length less than or
		     equal to length.  This is equivalent to:
			  len <= length.

	      greater length
		     True if the packet has a length greater than
		     or equal to length.  This is equivalent to:
			  len >= length.

	      ip proto protocol
		     True if the packet	 is  an	 ip  packet  (see
		     ip(4P)) of protocol type protocol.	 Protocol
		     can be a number or one of	the  names  icmp,
		     igrp,  udp, nd, or tcp.  Note that the iden-
		     tifiers tcp, udp, and icmp are also keywords
		     and must be escaped via backslash (\), which
		     is \\ in the C-shell.

	      ether broadcast
		     True if the packet is an ethernet	broadcast
		     packet.  The ether keyword is optional.

	      ip broadcast
		     True  if  the  packet  is	an  IP	broadcast
		     packet.  It checks for both  the  all-zeroes
		     and   all-ones  broadcast	conventions,  and
		     looks up the local subnet mask.

	      ether multicast
		     True if the packet is an ethernet	multicast
		     packet.   The  ether  keyword  is	optional.
		     This is shorthand for `ether[0] & 1 != 0'.

	      ip multicast
		     True  if  the  packet  is	an  IP	multicast
		     packet.

	      ether proto protocol
		     True  if  the packet is of ether type proto-
		     col.  Protocol can be a  number  or  a  name
		     like  ip,	arp, or rarp.  Note these identi-
		     fiers are also keywords and must be  escaped
		     via  backslash  (\).   [In	 the case of FDDI
		     (e.g., `fddi protocol  arp'),  the	 protocol
		     identification  comes from the 802.2 Logical
		     Link Control (LLC) header, which is  usually
		     layered  on top of the FDDI header.  Tcpdump
		     assumes,  when  filtering	on  the	 protocol
		     identifier, that all FDDI packets include an
		     LLC header, and that the LLC  header  is  in
		     so-called SNAP format.]

	      decnet src host
		     True  if  the DECNET source address is host,
		     which  may	 be  an	 address  of   the   form
		     ``10.123'',  or a DECNET host name.  [DECNET
		     host  name	 support  is  only  available  on
		     Ultrix  systems  that  are configured to run
		     DECNET.]

	      decnet dst host
		     True if the DECNET	 destination  address  is
		     host.

	      decnet host host
		     True   if	 either	  the  DECNET  source  or
		     destination address is host.

	      ip, arp, rarp, decnet
		     Abbreviations for:
			  ether proto p
		     where p is one of the above protocols.

	      lat, moprc, mopdl
		     Abbreviations for:
			  ether proto p
		     where p is one of the above protocols.  Note
		     that  Snort  does	not currently know how to
		     parse these protocols.

	      tcp, udp, icmp
		     Abbreviations for:
			  ip proto p
		     where p is one of the above protocols.

	      expr relop expr
		     True if the relation holds, where	relop  is
		     one  of  >, <, >=, <=, =, !=, and expr is an
		     arithmetic expression  composed  of  integer
		     constants	(expressed in standard C syntax),
		     the normal binary operators [+, -, *, /,  &,
		     |],  a  length  operator, and special packet
		     data accessors.  To access data  inside  the
		     packet, use the following syntax:
			  proto [ expr : size ]
		     Proto  is one of ether, fddi, ip, arp, rarp,
		     tcp, udp, or icmp, and indicates the  proto-
		     col layer for the index operation.	 The byte
		     offset, relative to the  indicated	 protocol
		     layer,  is	 given by expr.	 Size is optional
		     and indicates the number  of  bytes  in  the
		     field  of	interest;  it  can be either one,
		     two, or four,  and	 defaults  to  one.   The
		     length  operator,	indicated  by the keyword
		     len, gives the length of the packet.

		     For example, `ether[0] & 1 != 0' catches all
		     multicast	traffic.  The expression `ip[0] &
		     0xf  !=  5'  catches  all	IP  packets  with
		     options.  The expression `ip[6:2] & 0x1fff =
		     0' catches only unfragmented  datagrams  and
		     frag  zero	 of  fragmented	 datagrams.  This
		     check is implicitly applied to the	 tcp  and
		     udp  index operations.  For instance, tcp[0]
		     always means  the	first  byte  of	 the  TCP
		     header, and never means the first byte of an
		     intervening fragment.

	      Primitives may be combined using:

		     A	parenthesized  group  of  primitives  and
		     operators	(parentheses  are  special to the
		     Shell and must be escaped).

		     Negation (`!' or `not').

		     Concatenation (`&&' or `and').

		     Alternation (`||' or `or').

	      Negation has highest precedence.	 Alternation  and
	      concatenation  have  equal precedence and associate
	      left to right.  Note that explicit and tokens,  not
	      juxtaposition,  are now required for concatenation.

	      If an identifier is given without	 a  keyword,  the
	      most recent keyword is assumed.  For example,
		   not host vs and ace
	      is short for
		   not host vs and host ace
	      which should not be confused with
		   not ( host vs or ace )

	      Expression  arguments  can  be  passed  to Snort as
	      either a single argument or as multiple  arguments,
	      whichever	 is  more  convenient.	Generally, if the
	      expression contains  Shell  metacharacters,  it  is
	      easier  to  pass	it  as a single, quoted argument.
	      Multiple arguments  are  concatenated  with  spaces
	      before being parsed.

RULES
       Snort  uses  a  simple  but  flexible  rules  language  to
       describe network packet signatures and associate them with
       actions.	  The  current	rules  document	 can  be found at
       http://www.snort.org/snort_rules.html.

NOTES
       The following signals have the specified effect when  sent
       to the daemon process using the kill(1) command:


       SIGHUP Causes  the  daemon  to  close all opened files and
	      restart.	Please note that this will only	 work  if
	      the full pathname is used to invoke snort in daemon
	      mode, otherwise snort will just exit with an  error
	      message being sent to syslogd(8)


       SIGUSR1
	      Causes  the program to dump its current packet sta-
	      tistical information to the cosole or syslogd(8) if
	      in daemon mode.

       Any  other  signal  causes  the daemon to close all opened
       files and exit.


HISTORY
       Snort has been freely  available	 under	the  GPL  license
       since 1998.

DIAGNOSTICS
       Snort  returns  a 0 on a successful exit, 1 if it exits on
       an error.

BUGS
       Send   bug    reports	to    roesch@clark.net,	   snort-
       devel@lists.sourceforge.net

AUTHOR
       Martin Roesch <roesch@clark.net>

SEE ALSO
       tcpdump(1), pcap(3)


			   January 2001			       11


