http://shoki.sourceforge.net/

shoki@meshuggeneh.net

SHOKI 0.3.0
shoki@meshuggeneh.net
http://shoki.sourceforge.net/


INTRODUCTION:

Shoki is a free, open source network intrusion detection system
for conducting traffic analysis.

The fundamental design goals of shoki are:

	-Simplicity.  The components of shoki are designed to be
	 as straightforward (and therefore as easy to understand) as
	 possible
	-Modularity.  The functionalities provided by the various components
	 of shoki are intended to be as decoupled from each other as
	 practically possible

Major features include:

	-Signature matching using libpcap-style filter expressions
	-Support for searches using POSIX extended regular expressions
	-Optional support for searches using Perl-compatible regular expressions
	-Dynamic rule-based signature generation
	-Correlation of data from multiple sources

Minor features include:

	-Sending of alerts to IM clients via the Jabber protocol
	-Visualisation of packet data via OpenGL
	-Traffic analysis via clustering
	-Anomaly scoring based on questionable math
	-Correlation of events to local assets (and known vulnerabilities)
	-Remote OS identification via passive fingerprinting
	-RFC 815-style fragment reassembly
	-Configurable scan detection
	-Configurable threshold-based signature detection
	-Analysis of entropy in IP packet fields


YOU WILL NEED:

	libpcap		http://www.tcpdump.org/
			Libpcap is included with many OS distributions.
			Starting with shoki 0.3.0, you need a version of
			libpcap more recent than libpcap 0.7.2.  As of the
			time of this writing, that means you have to use
			libpcap-0.8.1 or libpcap-current.
			This is required because of an error in 0.7.2
			(and some earlier releases) that causes bus errors
			on SPARC64, as well as a memory leak in the
			pcap filter compiler.

	flex		http://www.gnu.org/software/flex/
	yacc		
			Flex (a lex(1) replacement) and yacc are available
			for virtually all UNIX-like environments.  They
			are included with many OS distributions, including
			all of the ones shoki is known to compile on.
			Flex is needed (rather than lex) for support
			of the -P flag.

	zlib		http://www.zlib.org
			Zlib is included in many OS distributions.


YOU MAY NEED:

	fftw 2.x	http://www.fftw.org/

			FFTW (the Fastest Fourier Transform in the West)
			is a math library for doing FFTs (Fast Fourier
			Transforms)
			Needed for:  hustler

	jabber 2.x	http://www.jabber.org/
	loudmouth	http://projects.imendio.com/loudmouth

			Jabber is an open instant messaging protocol,
			and loudmouth is a Jabber client library in C.
			Shoki can send alerts via Jabber (so an analyst
			can receive alerts in their IM client).
			Needed for:  shoki_sez

	gtk 2.x		http://www.gtk.org/
			GTK+ is a toolkit for programming GUIs.
			Needed for:  hustler

	gtkglext 1.x	http://gtkglext.sourceforge.net/

			gtkglext is an extension to GTK+ that allows OpenGL
			rendering in GTK widgets.
			Needed for:  hustler

	Nessus		http://www.nessus.org/

			Nessus is a free remote vulnerability scanner.  Shoki
			can import Nessus reports and use the vulnerability
			to evaluate the criticality of certain kinds of
			events.

	Postgresql	http://www.postgresql.org
	DBI		http://www.cpan.org
	DBD::Pg		http://www.cpan.org
			Needed for:  Database logging support

			Postgres is used for all the database functions
			of shoki.  If you do not have Postgres you will
			still be able to collect and categorise network
			traffic data, but most of the aggregation and
			correlation functionality of shoki will be
			unavailable.
			Note that postgresql must have OpenSSL support
			in order to work with the default configuration
			of shoki.

	pcre		http://www.pcre.org/

			PCRE is the Perl Compatible Regular Expression
			library, a regex library with syntax and semantics
			similar to Perl 5's.
			Use of pcre is optional.  If pcre support is
			compiled in, all widgets that support regex
			searches (in filter rules) will also support
			pcre search expressions.

	OpenSSH		http://www.openssh.org/
	rsync		http://samba.anu.edu.au/rsync/

			OpenSSH and rsync are used to collect data from
			the sensors for centralised analysis.  If you're
			planning on using the default shoki data collection
			model, you'll need both.

	RRDtool		http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/

			RRDtool databases are used to store derived
			anomaly data (raw data is stored in the Postgres
			database)



HOW TO INSTALL:

Create a `shoki' user (via adduser(8) or the equivalent), then:

	# ./configure [ --with-pgsql ] [ --with-gtk ] [ --with-pcap=DIR ]
	# make
	# make test
	# make install
	# make chroot

...and if you're using the Postgres stuff (and you should be), add the
postgres user to the shoki group and then...

	# make db

For more detailed instructions, consult the INSTALL document in the ./doc
directory of the shoki distribution.  Alternately, take a look at the CHECKLIST
document for a more general overview with pointers to the relevant
documentation.