SNEZ Files

Copyright (C) 2011-2021 Gene Guinter

    SNĒZ is free software: you can redistribute
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    SNĒZ is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/.

    Contact the copyright holder at gene@geneguinter.com.


**SECURITY**

While SNĒZ is tested with web vulnerability scanners, DO NOT allow SNĒZ to be accessed from the Internet or an untrusted
or insecure network. Consult the project website and wiki regularly for new versions and hotfixes addressing security
vulnerabilities. The ABSENCE OF A WARRANTY EXTENDS TO ISSUES REGARDING the SECURITY OF THE PROGRAM and ANY NETWORK OR
ACCESSIBLE DEVICES. Several buttons and links will visit external internet sites.  See internet connection in 
REQUIREMENTS and PRE-REQS below. **USE SNĒZ AT YOUR OWN RISK**.


REQUIREMENTS and PRE-REQS

Linux or FreeBSD, MySQL, PHP (and some specific modules), Snort 3.0 or Suricata, Apache, bash and sh shells.

Linux- Installation options are Ubuntu, Fedora, CentOS, OpenSuse, and FreeBSD. While untested, other distros should work
with a little knowledge of file system standards (ie., maybe U form Mint, F for RedHat). The development environment is
Xubuntu 20.04.

Selinux- Feedback on making SNEZ work with Selinux is welcome. At this time, though, Selinux installation/documentation
         is not provided.

MySQL- MySQL or MariaDB are acceptable. 

Snort-  Snort 3.0.  Output type must be either-
					
					JSON and configured on snort.lua as:
                    alert_json = { file = true, fields = 'action class b64_data dir dst_addr dst_ap dst_port
                    eth_dst eth_len eth_src eth_type gid icmp_code icmp_id icmp_seq icmp_type iface ip_id ip_len
                    msg mpls pkt_gen pkt_len pkt_num priority proto rev rule seconds service sid src_addr src_ap
                    src_port target tcp_ack tcp_flags tcp_len tcp_seq tcp_win timestamp tos ttl udp_len vlan' }
                  
                    jsonreader (read the 'raw' json output) function requires:
                    usermod -a -G snort apache
                    chmod g+x /var/log/snort
                    roll json files on first use
                    
                    or-
                    unified2 output processed by barnyard2
                    
       Snort must be started with -y option to include year in alert timestamps
                                       
Suricata- In /etc/suricata/suricata.yaml, enable eve output.  In order to display packet information, set 
		  payload:yes and payload-buffer-size:1kb
		  
		  unified2 output-> barnyard2 should also work, but note that Suricata is deprecating the unified2 option so
		  this is untested.

Apache- Apache paths are assumed to be the default for your distribution.  See README.xfo for clickjacking protection.

For https connection (default)- mod_ssl and openssl are required. README.SSL contains information to a aid in the
generation of a digital certificate.

PHP- install php, php-common, php-json, php-mysql or php-mysqlnd depending on distribution.

percona-toolkit- intall percona-toolkit if using json output for archiving alerts

Javascript- while primarily written in PHP, SNEZ uses a very small amount of javascript.

Internet connection- pressing the 'Malware Site List Update' button accesses www.malwaredomainlist.com
					 Signature Reference links leave local installtion to www.snort.org, cve.mitre.org,
					 and others to provide signature information.  These links are generated from the 
					 specific Snort or Suricata rule reference designated in the triggered rule.
					 Optionally, reputation websites can be added to the Admin page. You are responsible
					 for following the acceptable use standards of the sites you specify.

 
INFORMATION YOU WILL NEED

- Mysql password for root, or have it in a MySQL option file
- A user and password you will specify for access to the SNEZ db (if unified2, s/b a user with access to the Snort db)
- IP address of Mysql db if not using localhost
- IDS output type, and if json, full path to the json file
- Apache document root and a secure upstream path where a config file containing passwords can ge placed
- Any hotfixes or special instructions in the Hotfixes folder on Sourceforge


CUSTOM INSTALL

The install script attempts to determine the distribution, and sets paths and owners to default values for a limited set of distros
(Fedora, CentOS, Ubuntu, OpenSUSE). Otherwise, some limited customization is provided for at the beginning of the install script.
Comments there discuss these limitations.  A sample is provided for FreeBDD installs.


INSTALLATION

Following are instructions for install from a tarball.  To perform experimental installs from a .deb or .rpm file, see 
README-deb or README-rpm respectively.  Then return to 'Getting Started' section of this README.

1. sudo mkdir /opt/SNEZ
2. cd /opt/SNEZ
3. sudo cp [download location]/SNEZ-[ver].[rel].tar.gz ./
   md5sum SNEZ-[ver].[rel].tar.gz and compare to "i" (info) button on Sourceforge (next to filename downloaded)
4. sudo tar -xzvf SNEZ-[ver].[rel].tar.gz
5. cd SNEZ-[ver].[rel]/install
6. sudo ./install.sh bash install.sh
   Read the GPL and comments and key AGREE
7. Answer questions about your IDS environment
	Answer N for Snort, U for Suricata
	The next prompt is for specifying the ouput format of your ids- J for json, U for unified2.
	If json, you will be asked to supply the full path and filename of the json file output from your ids
8. Path and ownership information will be displayed with a chance to cancel install
9. Enter NEW for a new install requiring building of the SNEZ db and configuration, else enter if upgrading
10.Answer questions about your MySQL environment (new installs)	
	Supply password for root@localhost when prompted.(Key F if password is in a MySQL option file).
	Then supply a username/password/host for access to your SNEZ DB when prompted.
11. Go to Getting Started in this README below.


UPGRADES
Before upgrading- read release notes in README and stop jsonstash if instructed to do so.
Follow install instructions above; just don't answer NEW for a new install
If upgrading from SNEZ < 3.4-
Run /opt/SNEZ/SNEZ-[ver].[rel]/SNEZmigratetables34.sh to add new fields to the database (config table).
If upgrading from SNEZ 3.x-
Run /opt/SNEZ/SNEZ-[ver].[rel]/SNEZmigratetables36.sh to add new fields to the database (config table).


UNINSTALL
Can be used to uninstall product permanently or clean for fresh install
1. sudo /opt/SNEZ/SNEZ-[ver].[rel]/install/SNEZuninstall
2. rm -rf /opt/SNEZ to completely remove downloaded/extracted source


GETTING STARTED

1. Use visudo to make the additions and changes so certain root commands can be executed. Caution! Read the 
sudo and visudo documentation. Mistakes here can render your system inoperable. Never edit the sudoers file with
vi or another editor.  You may skip this step, but SNEZ will not report on Snort/Suricata/jsonstash/Barnyard2 status,
nor will tcpdump nor requested log rotates work.

hostname (get hostname of your system)
visudo (add the following lines, adjusting for your system appropriately; some systems may use 
apache as http server user, Centos for example; FreeBSD may use www)
	www-data hostname=NOPASSWD:/usr/sbin/tcpdump  (substitue your host name for 'hostname'
	www-data hostname=NOPASSWD:/bin/ps             and correct paths to your executables)
	www-data hostname=NOPASSWD:/bin/kill
	www-data hosthame=NOPASSWD:/usr/sbin/logrotate
	www-data hostname=NOPASSWD:/usr/bin/xargs
	   (comment out the following lines if present)
	Defaults requiretty
	Require !visualpwd
!wq (or q! if you make mistakes and want to start over)				

2. Create logins
	a. In a browser- http://[ip address of server]/SNEZ/SNEZlogin.php
	b. Login as 'admin' using password of 'admin'
	c. Modify the config parameters (reference below), paying special attention to the interface being monitored; also specify an
       encryption algorighm such as SHA1 for encrypting user passwords and the GMT for your time zone. Specify path to your sid-msg.map
       file and the version (1 or 2) of our map if you want signature reference lookup capabilities.
	d. Add a user, being sure to check the admin box (you can add other admin and non-admin accounts now or later)
	   It's important to complete step 2c before adding users, or they will not be able to sign on.
	e. Roll the json file if running Snort 3.0
3. Logon with new user, populate malware active ip list, and remove default admin.
	a. Restart your browser and log on with the new administrator id from step 2c, changing the first-first time password as required
	b. Delete user 'admin' from the Admin page.
	c. Go to Alert Summary page and click on the tab to load malware active ip list from malwaredomainlist.com
4. Start processing json output from your IDS- sudo nohup /root/jsonstash.php or sudo nohup /root/jsonstash.php & to run unattended;
   (Don't start jsonstash from the same terminal you started your ids from)
   Or start barnyard2 if output is unified2
5. Begin using SNEZ


CONFIG PARAMETERS REFERENCE 

In SNEZconfig.php:
IDS output =                    U for unified2, J for json
SNEZ database host, user,       host, user, password to the SNEZ database chosen at install time; place within ""
     and password       		do not set this unless you can login as a mysql admin to match it

in SNEZ db config table:
encryption =        			blank or an existing, installed php hash function for password
								NOTE: if you change this after an initial install, immediately add new admin users
									  to prevent being locked out
									  (choosing an encryption method at install time is highely recommended)
https = enforced				all connections https; change to unenforced for http (NOT RECOMMENDED)
newfiltertab = n                set behavior of filtering action display- either a new tab or same tab
inactive timeout = 900	  		page timeout
login attempts = 3              bad logins before account is disabled
gmt = -5		            	GMT offset; default to USA Eastern
maxrow = 10000                  max lines of alerts or summaries displayed (future- not implemented in this release)
max exec time = 120 		 	overrides php.ini max execution time
interface = enp0s3   			sniffer interface for optional use of tcpdump (*Note)
min pwd length = 8				minimum password length for users
pwd complexity = strong         default is strong, letter, number, caps, special chars; can change to simple
sid-msg.map path				specify path to sid-msg.map for signature references lookup capabilities
sid-msg.map version				specify version 1 or version 2

whois = SNEZdoc.php?page=whois   whois or reputation lookup site; select your personal favorite *
(whois1 through whois9 can be added to for up to 10 reputation or lookup sites)

* You can cut from the SNEZ page and paste into the lookup site, however, keyword substitution is also provided
  for ip address and domain lookup information.
Use keyword SNEZip to substitute ip address, and SNEZdns for domain lookup.
You will need to manually visit the site to determine the path and the proper location in the URI for the parameters.
This feature is offered as a convenience, and you are solely responsible for accessing the chosen site properly and
according to the chosen site's terms of use.
Format:
http://favoritelookupdomain.com/....path.../SNEZdns
http://favoriteantimalwaresite.com/...path.../SNEZip
Examples:
http://www.ipvoid.com/scan/SNEZip/
http://www.google.com/safebrowsing/diagnostic?site=SNEZdns
http://www.siteadvisor.com/sites/SNEZdns

Warning Category fields are available to assign categories to alerts, expanding the 'warn' feature.  For example, 
you can assign red to Attacks, orange to Blocked, another color for Reseach or Review, etc.  Enter your own categories
in each colored field to associate a color with a 10 character category.


PERFORMANCE
Occassionally use mysqlcheck --databases SNEZ -vop and mysqlcheck --databases snort -vop.  Best to stop Snort
and jsonstash first.