1HONEYD(8) BSD System Manager's Manual HONEYD(8)
2
4 honeyd — Honeypot Daemon
5
7 honeyd [-dP] [-l logfile] [-s servicelog] [-p fingerprints] [-0 p0f-file]
8 [-x xprobe] [-a assoc] [-f file] [-i interface] [-u uid] [-g gid]
9 [-c host:port:username:password] [--webserver-address address]
10 [--webserver-port port] [--webserver-root path]
11 [--rrdtool-path path] [--disable-webserver] [--disable-update]
12 [--verify-config] [--fix-webserver-permissions] [-V|--version]
13 [-h|--help] [--include-dir] [--data-dir] [net ...]
14
16 Honeyd creates virtual hosts for IP addresses matching the specified net.
17 The daemon simulates the networking stack of the configured hosts and can
18 simulate any TCP and UDP service. ICMP is fully supported, too. By
19 default, all UDP ports are closed and honeyd will generate an ICMP
20 unreachable port message if the configured personality permits that.
21 Honeyd enables a single host to claim unused addresses on a LAN for net‐
23 work simulation. The net argument may contain multiple addresses and
24 network ranges. For configured templates (see below) to work all the
25 configured addreses need to be included in net. Notice that honeyd will
26 answer to ICMP requests for all addresses defined in net if there is no
27 configured specific host or default template.
28 In order for honeyd to receive network traffic for IP addresses that it
30 should simulate, it is necessary to either explicitly route traffic to
31 it, use proxy arp or run arpd(8) for unassigned IP addresses on a shared
32 network. By assigning an ethernet address to a template via
33 set template ethernet "<vendor|mac address>"
35 it is possible to integrate virtual honeypots into a production network
37 without running arpd(8). Futhermore, Honeyd supports acquiring IP
38 addresses via DHCP. You can ask a template to be assigned to a DHCP IP
39 address via
40 dhcp template on fxp0 [ethernet "<vendor|mac address>"]
42 Honeyd exits on an interrupt or termination signal and rotates logfiles
44 on SIGUSR1.
45 The options are as follows:
47 -d Do not daemonize, and enable verbose debugging messages.
49 -P On some operating systems, it is not possible to get event noti‐
51 fications for pcap via select(2). In that case, honeyd needs to
52 run in polling mode. This flag enables polling.
53 -l logfile
55 Log packets and connections to the logfile specified by logfile.
56 -s servicelog
58 Logs information from service scripts to the log file specified
59 by servicelog.
60 -p fingerprints
62 Read nmap style fingerprints. The names defined after the token
63 are stored as personalities. The personalities can be used in
64 the configuration file to modify the behaviour of the simulated
65 TCP stack.
66 -x xprobe
68 Read xprobe style fingerprints. This file determines how honeyd
69 reacts to ICMP fingerprinting tools.
70 -a assoc
72 Read the file that associates nmap style fingerprints with xprobe
73 style fingerprints.
74 -0 p0f-file
76 Read the database for passive fingerprinting. The names of the
77 operating systems specified in this file are recognized by
78 Honeyd's parser and can be used for dynamic templates.
79 -u uid Set the UID that Honeyd is running as.
81 -g gid Set the GID that Honeyd is running as.
83 -f file
85 Read the configuration in file. It is possible to create host
86 templates with the configuration file that specify which servers
87 should run and which scripts should be started to simulate them.
88 honeyd will reread the configuration file when sent a SIGHUP sig‐
89 nal.
90 The syntax is as follows:
92 config = creation | addition | delete | binding | set |
94 annotate | route [config] | option
95 creation= "create" template-name | "create" "default" |
96 "dynamic" template-name
97 addition= "add" template-name proto "port" port-number action |
98 "add" template-name "subsystem" cmd-string ["shared"] |
99 "add" template-name "use" template-name "if" condition
100 delete= "delete" template-name |
101 "delete" template-name proto "port" port-number
102 binding = "bind" ip-address template-name |
103 "bind" condition ip-address template-name |
104 "bind" ip-address "to" interface-name |
105 "dhcp" template-name "on" interface-name ["ethernet" cmd-string] |
106 "clone" template-name template-name
107 set = "set" template-name "default" proto "action" action |
108 "set" template-name "personality" personality-name |
109 "set" template-name "personality" "random"
110 "set" template-name "ethernet" cmd-string
111 "set" template-name "uptime" seconds
112 "set" template-name "droprate" "in" percent
113 "set" template-name "uid" number ["gid" number]
114 "set" template-name "spoof" ["from" ip-address] ["to" ip-address]
115 "set" template-name "maxfds" number
116 "set" ip-address "uptime" seconds
117 annotate= "annotate" personality-name [no] finscan |
118 "annotate" personality-name "fragment" ("drop" | "old" | "new")
119 route = "route" "entry" ipaddr |
120 "route" "entry" ipaddr "network" ipnetwork |
121 "route" ipaddr "link" ipnetwork |
122 "route" ipaddr "unreach" ipnetwork |
123 "route" ipaddr "add" "net" ipnetwork \
124 "tunnel" ipaddr(src) ipaddr(dst) |
125 "route" ipaddr "add" "net" ipnetwork ipaddr \
126 ["latency" number"ms"] ["loss" percent] \
127 ["bandwidth" number["Mbps"|"Kbps"] \
128 ["drop" "between" number "ms" "-" number "ms" ]
129 proto = "tcp" | "udp" | "icmp"
130 action = ["tarpit"] ("block" | "open" | "reset" | cmd-string | \
131 "internal" cmd-string \
132 "proxy" ipaddr":"port )
133 condition = "source os =" cmd-string |
134 "source ip =" ipaddr | "source ip =" ipnetwork |
135 "time " timecondition | "proto" protocol | "otherwise"
136 timecondition = "between" time "-" time
137 option = "option" plugin option value
138 The cmd-string and the personality-name are arbitrary strings
140 enclosed with quotation marks. Variable expansion on the tokens
141 $ipsrc, $ipdst, $sport, $dport and $date is performed when exe‐
142 cuting the command string or when resolving the proxy address.
143 Additionally, the environment variables HONEYD_IP_SRC,
144 HONEYD_IP_DST, HONEYD_DST_PORT, HONEYD_SRC_PORT,
145 HONEYD_PERSONALITY and HONEYD_REMOTE_OS are available, too.
146 If the internal key word is use, honeyd interprets the command
148 string as Python module. These modules are executed within
149 honeyd without forking a new process. As a result, internal
150 scripts are very fast and cheap to execute.
151 The special keyword tarpit is used to slow down the progress of a
153 TCP connection. This is used to hold network resources of the
154 connecting computer.
155 If an IP address is not bound to a template, the actions speci‐
157 fied in the default template are executed.
158 Personalities need to be annotated before they are assigned to a
160 template or an IP address.
161 The default fragment policy is to accept fragment and resolve
163 overlaps in favor of old data. If the personality returns TCP
164 timestamps, the default uptime is a randomly chosen between zero
165 and twenty days.
166 The special include directive may be used to include other con‐
168 figuration files, for example to keep all personality annotations
169 separate from the main configuration file.
170 All honeyd plugins can be configured via the configuration file.
172 Each configuration option goes in one line, indicated by the
173 option keyword. It is followed by three items: the name of the
174 plugin, the name of the configuration option, and a value. The
175 value can be either an integer, a float, or a character string.
176 The options are picked up when honeyd reads the configuration
177 file and can then be queried by the plugins.
178 -i interface
180 Listen on interface. It is possible to specify multiple inter‐
181 faces.
182 -c hostname:port:username:password
184 Using this flag, Honeyd functions as a traffic statistic collec‐
185 tor. Collected statistics get propagated upstream to an aggrega‐
186 tor running at the specified hostname and port. The username and
187 password is used to create a signature on the data packet that
188 can be used to verify the integrity of the data. The statistics
189 can be used to automatically detect anomalies like worm propaga‐
190 tion.
191 --webserver-address address
193 Specifies the address on which the web server should listen. By
194 default, this is 127.0.0.1 so that only local requests are
195 served. By specifying 0.0.0.0, the webserver is going to answer
196 to external requests, too.
197 --webserver-port port
199 Specifies the port on which the web server should listen.
200 --webserver-root path
202 The path to the document tree of the webserver. This is usually
203 {prefix}/shared/honeyd/webserver/htdocs/.
204 --rrdtool-path path
206 Specifies the path for rrdtool(1). Without rrdtool no traffic
207 graphs can be generated.
208 --disable-webserver
210 Disables the builtin webserver.
211 --disable-update
213 Prevents Honeyd from checking if there are any security problems
214 with the current version of the application.
215 --verify-config
217 Verifies that Honeyd can parse the configuration correctly. This
218 does not require any special permissions, although some configu‐
219 rations that require direct access to interfaces might fail to
220 validate.
221 --fix-webserver-permissions
223 Changes the ownership of the web server files to the user, Honeyd
224 is going to run as.
225 -V|--version
227 Print version information and exit.
228 -h|--help
230 Print summary of command line options and exit.
231 --include-dir
233 For plugin development. Reports the directory in which honeyd
234 stores its header files.
235 --data-dir
237 Reports the directory in which honeyd stores data files like
238 Python modules.
239 net The IP address or network (specified in CIDR notation) or IP
241 address ranges to claim (e.g. ``10.0.0.3'', ``10.0.0.0/16'' or
242 ``10.0.0.5-10.0.0.15''). If unspecified, honeyd will attempt to
243 claim any IP address it sees traffic for.
244
246 honeyd supports the creation of a complete network topology including
247 routing. In order to enable the simulation of a network topology, a
248 router entry point has to be configured with
249 route entry <IP address>
251 By adding a network to a router entry point, honeyd is told about the
253 network addresses this entry point is responsible for. This enables mul‐
254 tiple entry points into the routing topology.
255 Every route add net directive creates the specified gateway as a new
257 router. In the case of tunneling, no new router is created, instead
258 packets are gre(4) encapsulated and sent to the tunnel destination
259 address. It is assumed that the tunnel destination address routes the
260 encapsulated packets to a honeyd machine.
261 The virtual machines that can be directly accessed by a router are
263 defined as network range in the route link command.
264 A link may carry attributes like latency, loss, and bandwidth. The
266 latency specifies a constant delay for packets travelling across the
267 link. The bandwidth on the other hand tracks the bandwidth related queu‐
268 ing delay for each link. If a packet is still being transmitted on the
269 link then the queue delay for another packet is the propagating delay
270 depending on the bandwidth plus the time for the previous packet to clear
271 the link.
272 Unless the link is configured to drop packets between a configurable
274 delay threshold, Honeyd currently assumes infinite buffer space, so use
275 this option with care.
276 An address space can be made unrouteable via the route unreach command.
278 The router entry point is the first address that inspects a packet. The
280 packet follows a path defined by the network topology until the current
281 router has the destination IP address on its local network.
282 It is possible to integrate real machines into the routing topology.
284 honeyd takes care of ARP requests and replies and encapsulates packets
285 that go to external machines into ethernet packets.
286 External machines can be configured with the following command:
288 bind <IP address> to <interface name>
290
292 Subsystem virtualization allows you to run regular network applications
293 under a virtual IP address controlled by honeyd. The application's net‐
294 work calls are intercepted and virtualized to the honeypot that they are
295 configured to. As a result, all network calls that subsytem applications
296 make appear to originate from the virtual IP address of a honeypot. This
297 includes binding ports, accepting and initiating UDP and TCP connections.
298 Raw sockets are not supported.
299 Subsystem are configured as follows
301 set template subsystem "/usr/sbin/httpd"
303 and are started as a separate process for every bound template. Applica‐
305 tions started as a honeyd subsystem need to be dynamically linked in
306 order to work under Honeyd.
307 It is possible to shared subsystems across different addresses if they
309 are created with the shared flag. This allows a subsystem to bind to
310 several virtual IP addresses and may also be used to increase the perfor‐
311 mance of subsystems across addresses.
312
314 Dynamic templates give Honeyd the ability to change networking behavior
315 based on several different conditions:
316 source address The source address of the network connection deter‐
318 mines which template is going to be used.
319 operating system The operating system as determined by passive finger‐
321 printing needs to be matched for the template to be
322 activated.
323 time The template is only being used between a certain time
325 interval. This allows Honeyd to simulate machines
326 being turned on and off.
327 A dynamic template can be created with the following command:
329 dynamic magichost
331 add magichost use windowsxp if source os = windows
332 add magichost use linux if source ip = 192.168.0.0/16
333 add magichost use invisible if time between 12:00am - 5:00am
334 add magichost otherwise use default
335 As an alternative, it is possible to use a short cut in the bind command
337 to create dynamic templates:
338 bind source ip = 192.168.0.0/16 10.0.0.5 cisco
340 bind source ip = 10.0.0.0/8 10.0.0.5 juniper
341 In this example, the host on 10.0.0.5 behaves like a cisco router if it
343 is contacted from IP addresses in the 192.168 network. If it is con‐
344 tacted from IP addresses in the 10 network, it behaves like a juniper
345 router.
346
348 The honeydctl(1) command allows the dynamic configuration of Honeyd while
349 it is running; see honeydctl(1) for more information.
350
352 Honeyd has two different logging modes. The syslog facility is used to
353 log connection establishment and termination including other relevant
354 packet events. Most messages can be disabled when configuring
355 syslog.conf(5) to drop all messages for the LOG_DAEMON facility if the
356 log level is below LOG_NOTICE.
357 Services started by honeyd can cause the daemon to log data by sending
359 information to stderr.
360 The second way of logging network activity is by using the -l flag. This
362 causes honeyd to log all received packets in a human readable format.
363 For UDP and TCP connections, honeyd logs the start and end of a flow
364 including the amount of data transfered.
365 For logging any other information, it is suggested to run a separate
367 intrusion detection system.
368
370 Honeyd supports internal service scripts that have been written in
371 Python. To improve the performance of these services, Honeyd provides an
372 event-driven model. The services need to indiciate when they are ready
373 to read and when they are ready to write data. Honeyd keeps track of
374 state that is provided to the Python scripts on every invocation.
375 The folowing example uses a Python script to implement a simple echo
377 server:
378 import honeyd
380 import sys
381 def honeyd_init(data):
383 mydata = {}
384 honeyd.read_selector(honeyd.EVENT_ON)
385 return mydata
386 def honeyd_readdata(mydata, data):
388 honeyd.read_selector(honeyd.EVENT_ON)
389 honeyd.write_selector(honeyd.EVENT_ON)
390 mydata["write"] = data
391 return 0
392 def honeyd_writedata(mydata):
394 data = mydata["write"]
395 del mydata["write"]
396 return data
397 def honeyd_end(mydata):
399 del mydata
400 return 0
401
403 A sample configuration file looks as follows:
404 # Example of a simple host template and its binding
406 include annotations
407 # Set up the hosts
409 create template
410 set template personality "OpenBSD 2.6-2.7"
411 add template tcp port 80 "sh scripts/web.sh"
412 add template tcp port 22 "sh scripts/test.sh $ipsrc $dport"
413 add template udp port 53 proxy yournameserver:53
414 set template default tcp action reset
415 set template uid 32767 gid 32767
416 bind 10.11.69.2 template
418 set 10.11.69.2 uptime 1327650
419 A simple example of a routing topology:
421 route entry 10.0.0.1
423 route 10.0.0.1 link 10.2.0.0/24
424 route 10.0.0.1 add net 10.2.1.0/24 10.2.0.10 latency 10ms loss 3.4
425 route 10.2.0.10 link 10.2.1.0/24
426 For this topology to work the net value in the command line has to be
428 10.0.0.1 10.2.0.0/24 10.2.1.0/24.
429
431 /var/run/honeyd.pid The PID of the current daemon.
432 {prefix}/lib/honeyd/webserver/ Python modules and web server docu‐
434 ments used by the internal webserver.
435 {prefix}/lib/honeyd/libhoneyd.so A shared library that can be pre‐
437 loaded to virtualize applications
438 within honeyd.
439 {prefix}/share/honeyd/nmap.assoc An association file to match xprobe2
441 fingerprints against nmap.
442 {prefix}/share/honeyd/nmap.prints Nmap fingerprints used by honeyd to
444 impersonate operating system stacks.
445 {prefix}/share/honeyd/xprobe2.conf Xprobe fingerprints used by honeyd to
447 impersonsate the ICMP section of
448 operating system stacks.
449
451 honeydctl(1) arpd(8)
452
454 Niels Provos ⟨provos@citi.umich.edu⟩
455 April 4, 2002