-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
196 lines (157 loc) · 8.31 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
# 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