WikiStart: USAGE

File USAGE, 7.4 KB (added by arthur, 9 years ago)

USAGE for Honeysnap, with examples

Line 
1$Id: USAGE 414 2007-05-10 15:16:57Z arthur $
2
3PURPOSE OF THIS DOCUMENT
4========================
5
6To give detailed information on the operation of Honeysnap.
7In addition, to provide examples of its value and output.
8It's assumed you have already read and understood the INSTALL
9and README docs that accompany the distribution.
10
11
12GETTING STARTED
13===============
14
15The easiest way to get started is to take the sample
16honeynet.cfg file, alter the IP address of the honeypot
17to match your setup (the line HONEYPOTS=). Then to run
18honeysnap over a data file 'myfile.pcap' with most of the
19options turned on, run
20
21honeysnap -c honeynet.cfg myfile.pcap
22
23This should print a large set of output to the screen
24and store a chunk of data in a directory called 'analysis'
25(unless you changed that in the config file).
26
27Doing this should give you a basic idea as to what honeysnap
28can do. In general, you may find it simpler to stick with
29the config file method until you are happy with all the options
30rather than using the (many) command line switches.
31 
32Remember to use a new output directory for each run. In order
33to handle multiple files, honeysnap will append to existing files
34for things like IRC and sebek output. This is probably not what
35you want for un-related files!
36                                   
37WORDS
38=====
39
40Honeysnap has the ability to intelligently analyze and report
41on specific words used in IRC communications. This is done
42using the 'words' file.  The words file is used by Honeysnap
43to search IRC traffic for specific key words.  You can specify
44a words file in Honeysnap with --words at the cmd line or by
45setting WORDFILE=/path/to/file in the config file.  The words
46file should can contain as words as the user requires, one
47per line.  If no words file is provided, Honeysnap
48will use a built-in set of words. If a word file is provided,
49honeysnap will append the user-supplied list to its own list.
50
51EXAMPLES
52========
53
54A variety of examples and the expected output.
55
56Here we get the standard command line options
57
58 honeysnap --help
59
60You do not have to have a configuration file to run Honeysnap.  You
61can run Honeysnap strictly using command line options.  When run
62from the command line without a configuration file, you must specify
63-H to tell Honeysnap the ip's of your honeypots.
64
65Here is an example of the most basic Honeysnap command, assuming
6610.1.1.2 and 10.1.1.3 are your honeypots.  This command will open
67pcapfile and output some basic information:
68
69 honeysnap -H10.1.1.2,10.1.1.3 pcapfile
70
71To get some quick stats for packet counts for a few protocols:
72
73 honeysnap -H10.1.1.2,10.1.1.3 --do-packets pcapfile
74
75To extract HTTP info and files.  The extracted data is placed in
76/tmp/analysis by default.  Some information about what Honeysnap
77did will be written to standard out:
78
79 honeysnap -H10.1.1.2,10.1.1.3 --do-http pcapfile
80
81To extract http info and place the data somewhere else:
82
83 honeysnap -H10.1.1.2,10.1.1.3 --do-http -o /home/user/analysis pcapfile
84
85To extract http info and write the results to a file instead of
86standard out:
87 
88 honeysnap -H10.1.1.2,10.1.1.3 --do-http -f /home/user/analysis/results.txt pcapfile
89
90To extract irc statistics, and do honeysnap's irc analysis:
91
92 honeysnap -H10.1.1.2,10.1.1.3 --do-irc pcapfile
93
94To extract from ftp:
95
96 honeysnap -H10.1.1.2,10.1.1.3 --do-ftp pcapfile
97
98To extract sebek info:
99
100 honeysnap -H10.1.1.2,10.1.1.3 --do-sebek pcapfile
101
102To extract smtp:
103
104 honeysnap -H10.1.1.2,10.1.1.3 --do-smtp pcapfile
105
106To look at outbound flow information:
107
108 honeysnap -H10.1.1.2,10.1.1.3 --do-outgoing pcapfile
109
110To get a more verbose look at outbound flows:
111
112 honeysnap -H10.1.1.2,10.1.1.3 --do-outgoing --verbose-summary pcapfile
113
114To do binary extraction from all flows:
115
116 honeysnap -H10.1.1.2,10.1.1.3 --all-flows  pcapfile
117
118All of these options can be combined at the command line:
119
120 honeysnap -H10.1.1.2,10.1.1.3 --do-outgoing --do-irc --do-ftp --do-sebek --do-htp --do-outgoing -o /home/user/analysis -f /home/user/analysis/results.txt -d /home/pcaps
121
122All the command line options are generally useful to do
123quick one off runs against some pcap data.  If a configuration
124file is provided, along with command line options, then any
125options specified at the command line take precedence.
126
127The configuration file provided with the honeysnap distribution
128(honeynet.cfg) is well commented and is a good place to start
129in writing your own config file.
130
131If you want to do a daily run out of cron to generate daily
132reports then you would want something like the following. 
133daily.cfg should contain all the options you want to run every day:
134
135 honeysnap -c daily.cfg -d $YESTERDAYS_DATA_DIRECTORY -o $OUTPUT_DIR -f $RESULTS_FILE
136
137
138CREATING NEW MODULES
139====================
140
141Honeysnap is modular, allowing people to add their own decoding
142routines, extending its capabilities.  To get started, first study
143main.py.  This file contains the core code that makes honeysnap do
144its thing, this is where the main loop resides, option parsing and
145file handling happens here as well.  Looking at the processFile
146function in main.py will show you how Honeysnap's modules are used
147to do the actual processing of the data.  Next look at how some of
148the modules that do the actual processing work.  We suggest
149starting with packetCounter.py, httpDecode.py, smtpDecode.py, etc.
150
151It's also possible to use Honeysnap without changing the code. e.g.
152At some point somebody had made a feature request for honeysnap to
153extract flow statistics of all flows where greater than N bytes
154were transferred in less than X seconds.  To keep adding endless
155variations of analysis to honeysnap will only make it more and
156more complex to use, and more prone to bugs.
157
158We've used this specific feature request as an opportunity
159to illustrate how to use honeysnap modules to write a specific
160application.  xBytesNseconds.py does one thing: it reads pcap
161files and reports flows that are contain more than X bytes in
162N seconds.  It will read regular or gzip compressed pcap files
163or from standard in.   If you look at the code you will see
164the bulk of the program is involved with details of handling
165command line options, file handling, and output.  The actual
166data analysis work itself is contained in only 1 function. 
167
168The code is heavily commented to help the reader follow along.
169
170Here's the basic usage:
171 xBytesNseconds.py [options]
172Options:
173  --version             show program's version number and exit
174  -h, --help            show this help message and exit
175  -b BYTES, --bytes=BYTES
176                        Look for flows greater than bytes, defaults to 0
177  -s SECONDS, --seconds=SECONDS
178                        Ceiling in seconds for candidate flows, defaults to
179                        sys.maxint
180  -H HONEYPOTS, --honeypots=HONEYPOTS
181                        Comma delimited list of honeypots
182
183For examples:
184xBytesNseconds.py -H10.0.0.2,10.0.0.3 -b 1000 -s 10 /data/pcaps/somepcap.gz
185
186This will examine /data/pcaps/somepcap.gz for any flows of less than
18710 seconds duration with more than 1000 bytes transmitted. The code
188is included in the scripts/ directory in this distribution.
189
190MULTIPLE FILES
191==============
192
193Honeysnap can handle multiple pcap files, compressed or
194un-compressed.  You have several options on how to do this.
195
196Multiple Files
197
198 honeysnap -c honeysnap.cfg pcap1 pcap2 pcap3
199
200   
201In general, using a script is a better solution that giving
202multiple files on the command line unless you only have a couple
203of files as it will make the output much easier to deal with and
204reduce the risk of overlapping filenames.
205 
206