# Artemis Network Traffic Virus Monitor
# Author: Andrew Withers (atw31337@gmail.com)


 ________  ________  _________  _______   _____ ______   ___  ________      
|\   __  \|\   __  \|\___   ___\\  ___ \ |\   _ \  _   \|\  \|\   ____\     
\ \  \|\  \ \  \|\  \|___ \  \_\ \   __/|\ \  \\\__\ \  \ \  \ \  \___|_    
 \ \   __  \ \   _  _\   \ \  \ \ \  \_|/_\ \  \\|__| \  \ \  \ \_____  \   
  \ \  \ \  \ \  \\  \|   \ \  \ \ \  \_|\ \ \  \    \ \  \ \  \|____|\  \  
   \ \__\ \__\ \__\\ _\    \ \__\ \ \_______\ \__\    \ \__\ \__\____\_\  \ 
    \|__|\|__|\|__|\|__|    \|__|  \|_______|\|__|     \|__|\|__|\_________\
                                                                \|_________|
                                                                            

################################# Description ###########################################
# Artemis forwarder nodes monitor a specific directory for new files that are extracted #
# from the bitstream by Bro/Zeek NSM. These files are then sent to the scanner node to	# 
# be processed and, if necessary, scanned for viruses. The primary process, on the	#
# scanner node, passes the task to a child node, via a queue, for prescan operations,	# 
# such as comparing the	file hash against a blacklist, a whitelist, and a list of files #
# that have already been scanned. If prescan determines that the file requires scanning,# 
# it is then added to the scan queue. A second script, Orion, monitors that queue and	#
# distributes the workload to worker processes. The maximum number of concurrent	#
# prescan and worker processes can be tuned to provide minimal time to scan without	#
# overloadig the system's available resources. The worker process will collect file	#
# data, perform the scan, and log the results. If the file is determined to be		#
# infected, an email is dispatched to the address(es) specified in the configuration.	#
#########################################################################################


#################################### Notes ##############################################
# Artemis was designed for, and tested on, Ubuntu 16.04 running Security Onion NSM.     #
# At a minimum, Artemis requires that the Bro/Zeek NSM be installed. Bro/Zeek is	#
# utilized to extract executable files from the network data stream allowing them to be	#  
# inspected for known viruses. Artemis "may" be compatible with other flavors of Debian #
# Linux, so long as the systemd service manager is utilized; however, Ubuntu is the     #
# only flavor that has been tested and is currently supported.				#
#											#
# Ubuntu 16.04 downloads:								#  
# http://releases.ubuntu.com/xenial/							#
#											# 
# For more information about Security Onion visit:					#
# https://securityonion.net/								#
#											#
# For more information about Bro/Zeek visit:						#
# https://www.zeek.org/									#
#											#
# Questions, suggestions, and problem reporting:					#
# https://groups.google.com/forum/#!forum/artemis-ntvm					#
#											# 
#########################################################################################


########################### Installation instructions ######################################

# Preinstallation:

## Firewall rules
	The forwarder nodes transmit data to the scanner via 22/tcp and	514/udp. The 
	firewall on the scanner node must allow traffic to these ports from each of the 
	forwarder nodes.
## User privileges
	The user account that Artemis forwarder nodes use to connect to the scanner node
	must be a member of the sudo group during installation . This account will 
	continue to be used by the forwarders post-installation; however, sudo privileges 
	will no longer be required.
	* Create an artemis user account on the scan node and add it to the sudo group
		sudo adduser artemis 
		sudo adduser artemis sudo
	
	* Remove this account from sudo after all forwarder nodes have been installed.
		sudo deluser artemis sudo 

# Scanning node installation:
	Note: The scanning node must be installed prior to installing any forwarder nodes.
	The scanner node installation can be performed interactively by following the
	prompts or automatically by using an answer file. An answer file template, 
	install.conf, is located in the conf directory. Copy this file and edit each 
	field with the appropriate configurations. Run an automatic installation using 
	the -f option and the location of the answer file.
		./artemis-setup -f </path/to/answer/file>
	Alternatively, perform an interactive installation by running the installer
	without any options.
		./artemis-setup
	You will be prompted for the necessary information.

# Forwarder node installation:
	On the forwarder nodes, navigate to the forwarder_node directory.
	Run the forwarder-setup file and follow the prompts
		./forwarder-setup 
	
	

########################### Uninstall Instructions #########################################

# Run the installer in uninstall mode and follow the prompts
	./artemis-setup -u
	or
	./forwarder-setup -u

The installer/uninstaller script will save a copy of itself in /opt/artemis/ for future use.
This ensures that uninstallation is always an option and that the uninstaller version matches 
the currently installed version of Artemis

#################################### Usage #################################################

# The following scripts are located on the scanning node

Artemis Network Traffic Virus Monitor
Usage: artemis [OPTION]

	Options:

		-h			This message
		-v			Print version information
		-f <file>		Force process a file
		-p			Purge the hash cache
# Notes:
# Hashes and source IP addresses can be either whitelisted or blacklisted. This can be done
# by adding the source IP address or the hash, Md5 or SHA256, to the whitelist or blacklist
# files located in /opt/artemis/conf/ on the scan node.

############################### Auxiliary Scripts ###########################################

arteLog - Artemis log interface
Usage: arteLog [Time OPTION]...[Query OPTION]
If no Time option is selected, the time period will default to the last 24 hours

	Time Period Options:
		-D <YYYY-MM-HH>		Specific date
		-M <YYYY-MM>		Specific month
		-Y <YYYY>		Specific year
		-H <HH>			Specific hour of current day
		-d <n>			Last n number of days
		-w <n>			Last n number of weeks
		-m <n>			Last n number of months
		-y <n>			Last n number of years
		-r <n>			Last n number of hours
		-i <n>			Last n number of minutes
		-R <Start> <End>	Specific start and end Date/Time in YYYY-MM-DD HH:MM:SS format
		-a			all

	Query options:
		-F <SHA256 Hash>		Query file(s) by SHA256 hash
		-e <MD5 Hash>                   Query file(s) by MD5 hash
		-S <Source IP>			Query file(s) by source IP address
		-T <Destination IP>		Query file(s) by destination IP address
		-I <Source or Destination IP>	Query files(s) by Source or Destination IP address
		-f <Filename>			Query file by filename

	Additional option:
		-p				Purge all log data

# Log Notes:
## Field codes:
	Scanned
		0	The file was not scanned because the hash was found in the whitelist, blacklist, or cache of previously scanned files
		1	The file was scanned by clamAV
	Queued
		0	The file was not queued because the hash was found in the whitelist, blacklist, or cache prior to being queued
		1	The file was queued to be scanned
	Result
		0	The file was scanned by clamAV and returned a negative result for infection
		1	The file was scanned by clamAV and returned a positive result for infection
		2	The file was scanned by clamAV; however, an error was detected during the scan
		3	The file hash was found in the whitelist
		4	The file hash was found in the blacklist
		5	The source of the file transfer was found in the whitelist
		6	The source of the file transfer was found in the blacklist

# FileSize is recorded in number of bytes


arteStat - Artemis statistical report generator
Usage: arteStat [OPTION]...
If no option is used, the report period will default to the previous 24 hours

	Report Period Options:
		-D <YYYY-MM-HH>		Specific date
		-M <YYYY-MM>		Specific month
		-Y <YYYY>		Specific year
		-H <HH>			Specific hour of current day
		-d <n>			Last n number of days
		-w <n>			Last n number of weeks
		-m <n>			Last n number of months
		-y <n>			Last n number of years
		-r <n>			Last n number of hours
		-i <n>			Last n number of minutes
		-R <Start> <End>	Specific start and end Date/Time in YYYY-MM-DD HH:MM:SS format


# exit