# 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