README
1 d i s c o
2The Passive IP DISCOvery and fingerprinting tool
3
4(c) Copyright 2003 - Preston Wood <p@altmode.com>
5
6
7Description
8-----------
9
10 Disco is a passive IP discovery and fingerprinting utility designed
11 to sit on segments distributed throughout a network to uniquely discover IP's
12 on the network. In addition to IP discovery disco has the ability
13 to passively fingerprint IP SYN packets using techniques detailed
14 in a white paper from Lance Spitzner (see special thanks for
15 location). The intention is for disco to discover IP's on the
16 network, fingerprint the packet if necessary, and load into the
17 Gherkin database for targeted host scans.
18
19 Disco was originally started as a passive discovery tool for Gherkin
20 the scan manager program (see www.altmode.com/gherkin).
21 However, throughout writing the program
22 it was apparent that the tool could be used as a standalone
23 discovery utility as well.
24
25 v1.2 has been released for standalone use, STILL working on
26 Gherkin intetegration.
27
28
29Special Thanks
30--------------
31
32 * Lance Spitzner and his passive fingerprinting white paper at:
33 http://project.honeynet.org/papers/finger/
34
35 * Michal Zalewski and William Stearns and their excellent p0f
36 passive fingerprinting utility and list of fingerprinted OS's
37
38 * Mike Schiffman and all his excellent open source network utilities
39
40 * Mike Schmuhl for feedback, debugging, and with distribution package
41
42 * Josh Glover for some new functionality (INCOGEN, Inc)
43
44 * Alerto Ornaghi (ALoR) and Marco Valleri (NaGA) of ettercap for new fingerprints
45
46Platforms
47---------
48Tested on Redhat and SuSE. However it should compile on most any UNIX platform with libpcap installed. Let me know if you get this working on other platforms.
49
50Using Disco
51-----------
52
53 Once compiled launching disco -h will list the options available:
54
55 default operation will capture packets from defined device listening
56 for only IP packets and recording uniquely identified source IP addresses
57 Outputing the IPs and associated fingerprints (if selected) to STDOUT
58
59 -i device -- this option specifies the ethernet device to start
60 capturing packets, this option is required
61
62 -N do not print IP -- this option suppresses printing the IP and associated
63 fingerprint info to STDOUT
64
65 -f fingerprint -- option fingerprints the IP SYN packet - see listed
66 format below
67
68 -S SYN only -- only record IP SYN packets, useful when used with
69 fingerprint option because it will not record source IP addresses
70 where fingerprinting could not occur
71
72 -A SYNACK -- ability to fingerprint SYNACK packets
73
74 -s Input file -- Parse packets from a previously captured TCPDUMP file verses live data capture
75
76 -o file -- write output to a file, simple as that
77
78 -r filter rule -- define TCPDUMP tyle rules, see TCPDUMP man page
79 for filtering options.
80 Ex: disco -i eth0 -r "ip src net 10.0.0.0/8"
81 When using the -r option you must include ip in the
82 rule with v1.0, planning on fixing with next release. Use this
83 option to filter on IP's you expect to see on the segment rather
84 than no rule and seeing all source IP's even if they are not on
85 the network segment
86
87 -u unique ip -- must be used with fingerprint option, will force
88 only fingerprinting IP SYN packets or SYNACK packets that are unique since disco
89 started. This option is useful from a discovery perspective to
90 only record IP SYN/SYNACK packets that are unique, without this option
91 disco will fingerprint EVERY IP SYN/SYNACK packet it sees.
92
93 -h help -- display options available
94
95 -g enable gherkin -- output discovered IP's and fingerprinted hosts
96 to the Gherkin database. THIS OPTION IS NOT YET ENABLED
97
98 -p pipeargs -- pipe output to a program (see README.pipe for more info)
99
100 -P pipeargs with string -- string to print before output when using -p (see README.pipe for more info
101
102 -t timestamp -- adds a system timestamp to the outfile file (-o option)
103
104 -v verbose -- output full fingerprint info to output file (-o option) including number of NOPS and relative location of SACKOK and NOP options
105
106 -e ethmode -- for running on some devices without IP addresses assigned, if an error is displayed regarding "pcap_lookupnet () failed" try this option
107
108
109When disco cannot determine the host OS from the fingerprint it will
110display the fingerprint so you can check the host and note the host
111fingerprint in the disco.fp fingerprint file.
112
113Ex: 10.1.1.1: 16384:255:1460:1:0:0:1:44:S
114
115Disco 1.2 fingerprint format:
116
117wwwww:ttt:mmmm:D:W:S:N:I:PT
118
119wwww - window size
120ttt - time to live
121mmmm - maximum segment size
122D - do not fragment flag (0=notset, 1=set)
123W - window scaling (-1=notpresent)
124S - sackOK flag (0=notset, 1=set)
125N - nop flag (o=notset, 1=set)
126I - packet size (-1=irrelevant)
127PT - packet type (S for SYN, A for SYNACK)
128
129When determining host - fingerprint be aware of the TTL field, you
130will need to determine the original TTL which is usually equal to the
131first power of 2 greater than the TTL you are seeing.
132
133
134To Do
135-----
136
137 * Enable Gherkin database output support
138 * Enable command line daemon mode
139 * Continue updating fingerprint list
140 * Fixing found bugs!
141
142 Please send an email to p@altmode.com for questions and or comments
143 for enhancements.
144
README.pipe
1This file documents the -p and -P options to DISCO
2--------------------------------------------------
3
4It is possible to have DISCO report the hosts it discovers to standard out,
5a file, or via another program, e.g. sendmail. To accomplish the latter, you
6should make use of the -p option. -p requires an argument, which is a string
7of arguments to the program, the first argument being the name of the program
8itself (think of it as argv--argv[0] is the name of the program, and argv[1]
9and up are the arguments). -P can be used to write a string to the pipe
10before the normal DISCO output.
11
12For example, to have DISCO report new hosts via email:
13
14disco -i eth0 -p '/usr/sbin/sendmail -oi -t' \
15-P "`echo -e 'To: admin@domain.com\nSubject: DISCO\n\nNew host: '`"
16
17<admin@domain.com> will receive an email every time a new host is discovered.
18
19A cleaner way of dealing with the -P flag for email is to make a text file to
20serve as a template for the email:
21
22
23-------------------------------------------------------------------------------
24From: DISCO <disco@domain.com>
25To: Administrator <admin@domain.com>
26Subject: New Host Detected by DISCO
27
28DISCO detected a new host:
29
30-------------------------------------------------------------------------------
31
32And then invoke DISCO like this:
33
34disco -i eth0 -p 'sendmail -oi -t' -P "`cat file.txt`"
35