Repository navigation
Expand file tree
/
Copy pathhoneyd.8
More file actions
650 lines (641 loc) · 18.6 KB
/
Copy pathhoneyd.8
File metadata and controls
650 lines (641 loc) · 18.6 KB
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
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
.\"
.\" Copyright (c) 2002 Niels Provos <provos@citi.umich.edu>
.\" Copyright (c) 2013 Datasoft Corp <nova@datasoft.com>
.\"
.Dd February 13, 2013
.Dt HONEYD 8
.Sh NAME
.Nm honeyd
.Nd Honeypot Daemon
.Sh SYNOPSIS
.Nm honeyd
.Op Fl dP
.Op Fl l Ar logfile
.Op Fl s Ar servicelog
.Op Fl p Ar fingerprints
.Op Fl 0 Ar p0f-file
.Op Fl m Ar file \" here is the command for changing command line arguments for the nmap router prefix file
.Op Fl x Ar xprobe
.Op Fl a Ar assoc
.Op Fl f Ar file
.Op Fl i Ar interface
.Op Fl u Ar uid
.Op Fl g Ar gid
.Op Fl c Ar host:port:username:password
.Op Fl -webserver-address Ar address
.Op Fl -webserver-port Ar port
.Op Fl -webserver-root Ar path
.Op Fl -rrdtool-path Ar path
.Op Fl -disable-webserver
.Op Fl -disable-update
.Op Fl -verify-config
.Op Fl -fix-webserver-permissions
.Op Fl V|--version
.Op Fl h|--help
.Op Fl -include-dir
.Op Fl -data-dir
.Op Ar net ...
.Sh DESCRIPTION
.Nm Honeyd
creates virtual hosts for IP addresses
matching the specified
.Ar net .
The daemon simulates the networking stack of the configured
hosts and can simulate any TCP and UDP service. ICMP is fully
supported, too. By default, all UDP ports are closed
and
.Nm
will generate an ICMP unreachable port message if
the configured personality permits that.
.Pp
.Nm Honeyd
enables a single host to claim unused addresses on a LAN for network
simulation.
The
.Ar net
argument may contain multiple addresses and network ranges.
For configured templates (see below) to work all the configured
addreses need to be included in
.Ar net .
Notice that
.Nm
will answer to ICMP requests for all addresses defined in
.Ar net
if there is no configured specific host or default template.
.Pp
In order for
.Nm
to receive network traffic for IP addresses that it should
simulate, it is necessary to either explicitly route traffic to
it, use proxy arp or run
.Xr arpd 8
for unassigned IP addresses on a shared network.
By assigning an ethernet address to a template via
.Bd -literal
set template ethernet "<vendor|mac address>"
.Ed
.Pp
it is possible to integrate virtual honeypots into a production
network without running
.Xr arpd 8 .
Futhermore,
.Nm Honeyd
supports acquiring IP addresses via DHCP.
You can ask a template to be assigned to a DHCP IP address via
.Bd -literal
dhcp template on fxp0 [ethernet "<vendor|mac address>"]
.Ed
.Pp
.Nm Honeyd
exits on an interrupt or termination signal and
rotates logfiles on SIGUSR1.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl d
Do not daemonize, and enable verbose debugging messages.
.It Fl P
On some operating systems, it is not possible to get event notifications
for pcap via
.Xr select 2 .
In that case,
.Nm
needs to run in polling mode. This flag enables polling.
.It Fl m Ar nmap-mac-prefixes
Read
.Nm nmap-mac-prefixes. the prefix file located
in a different location but must be of the same format.
Example file located in /usr/share/honeyd/nmap-mac-prefixes
.It Fl l Ar logfile
Log packets and connections to the logfile specified by
.Ar logfile .
.It Fl s Ar servicelog
Logs information from service scripts to the log file
specified by
.Ar servicelog .
.It Fl p Ar fingerprints
Read
.Nm nmap
style fingerprints. The names defined after the
.va Fingerprint
token are stored as personalities.
The personalities can be used in the configuration file to modify the
behaviour of the simulated TCP stack.
.It Fl x Ar xprobe
Read
.Nm xprobe
style fingerprints.
This file determines how
.Nm
reacts to ICMP fingerprinting tools.
.It Fl a Ar assoc
Read the file that associates
.Nm nmap
style fingerprints with
.Nm xprobe
style fingerprints.
.It Fl 0 Ar p0f-file
Read the database for passive fingerprinting.
The names of the operating systems specified in
this file are recognized by
.Nm Honeyd's
parser and can be used for dynamic templates.
.It Fl u Ar uid
Set the UID that
.Nm Honeyd
is running as.
.It Fl g Ar gid
Set the GID that
.Nm Honeyd
is running as.
.It Fl f Ar file
Read the configuration in
.Ar file .
It is possible to create host templates with the configuration file
that specify which servers should run and which scripts should be
started to simulate them.
.Nm
will reread the configuration file when sent a SIGHUP signal.
.Pp
The syntax is as follows:
.Bd -literal
config = creation | addition | delete | binding | set |
annotate | route [config] | option | broadcast
creation= "create" template-name | "create" "default" |
"dynamic" template-name
broadcast= "broadcast" template-name "srcport" number "dstport" number "time" number action
addition= "add" template-name proto "port" port-number action |
"add" template-name "subsystem" cmd-string ["shared"] |
"add" template-name "use" template-name "if" condition
delete= "delete" template-name |
"delete" template-name proto "port" port-number
binding = "bind" ip-address template-name |
"bind" condition ip-address template-name |
"bind" ip-address "to" interface-name |
"dhcp" template-name "on" interface-name ["ethernet" cmd-string] |
"clone" template-name template-name
set = "set" template-name "default" proto "action" action |
"set" template-name "personality" personality-name |
"set" template-name "personality" "random"
"set" template-name "ethernet" cmd-string
"set" template-name "uptime" seconds
"set" template-name "droprate" "in" percent
"set" template-name "uid" number ["gid" number]
"set" template-name "spoof" ["from" ip-address] ["to" ip-address]
"set" template-name "maxfds" number
"set" ip-address "uptime" seconds
annotate= "annotate" personality-name [no] finscan |
"annotate" personality-name "fragment" ("drop" | "old" | "new")
route = "route" "entry" ipaddr |
"route" "entry" ipaddr "network" ipnetwork |
"route" ipaddr "link" ipnetwork |
"route" ipaddr "unreach" ipnetwork |
"route" ipaddr "add" "net" ipnetwork \\
"tunnel" ipaddr(src) ipaddr(dst) |
"route" ipaddr "add" "net" ipnetwork ipaddr \\
["latency" number"ms"] ["loss" percent] \\
["bandwidth" number["Mbps"|"Kbps"] \\
["drop" "between" number "ms" "-" number "ms" ]
proto = "tcp" | "udp" | "icmp"
action = ["tarpit"] ("filtered" | "open" | "closed" | cmd-string | \\
"internal" cmd-string \\
"proxy" ipaddr":"port )
condition = "source os =" cmd-string |
"source ip =" ipaddr | "source ip =" ipnetwork |
"time " timecondition | "proto" protocol | "otherwise"
timecondition = "between" time "-" time
option = "option" plugin option value
.Ed
.Pp
The
.Va cmd-string
and the
.Va personality-name
are arbitrary strings enclosed with quotation marks.
Variable expansion on the tokens
.Va $ipsrc ,
.Va $ipdst ,
.Va $sport ,
.Va $dport
and
.Va $date
is performed when executing the command string or when resolving
the proxy address. Additionally, the environment variables
.Va HONEYD_IP_SRC ,
.Va HONEYD_IP_DST ,
.Va HONEYD_DST_PORT ,
.Va HONEYD_SRC_PORT ,
.Va HONEYD_PERSONALITY
and
.Va HONEYD_REMOTE_OS
are available, too.
.Pp
If the
.Va internal
key word is use,
.Nm
interprets the command string as Python module.
These modules are executed within
.Nm
without forking a new process.
As a result, internal scripts are very fast and cheap to execute.
.Pp
The special keyword
.Va tarpit
is used to slow down the progress of a TCP connection.
This is used to hold network resources of the connecting computer.
.Pp
If an IP address
is not bound to a template, the actions specified in the
.Va default
template are executed.
.Pp
.Bd -literal
The action keywords behave as follows,
ICMP
open : respond to ICMP requests
closed : do not respond to ICMP requests
TCP
open : respond with SYN/ACK and establish connections
closed : respond with SYN/RST
filtered : do not respond at all
UDP
open : same as UDP filtered
closed : respond with ICMP Unreachable message
filtered : do not respond at all
.Ed
.Pp
Personalities need to be annotated before they are assigned to
a template or an IP address.
.Pp
The default fragment policy is to accept fragment and resolve overlaps
in favor of old data. If the personality returns TCP timestamps, the
default uptime is a randomly chosen between zero and twenty days.
.Pp
The special
.Va include
directive may be used to include other configuration files, for
example to keep all personality annotations separate from the
main configuration file.
.Pp
All honeyd plugins can be configured via the configuration file.
Each configuration option goes in one line, indicated by the
.Va option
keyword.
It is followed by three items: the name of the plugin, the name of the
configuration option, and a value.
The value can be either an integer, a float, or a character string.
The options are picked up when honeyd reads the configuration file and
can then be queried by the plugins.
.It Fl i Ar interface
Listen on
.Ar interface .
It is possible to specify multiple interfaces.
.It Fl c Ar hostname:port:username:password
Using this flag,
functions as a traffic statistic collector.
Collected statistics get propagated upstream to an aggregator
running at the specified hostname and port.
The username and password is used to create a signature on the
data packet that can be used to verify the integrity of the data.
The statistics can be used to automatically detect anomalies like
worm propagation.
.It Fl -webserver-address Ar address
Specifies the address on which the web server should listen.
By default, this is
.Va 127.0.0.1
so that only local requests are served.
By specifying
.Va 0.0.0.0 ,
the webserver is going to answer to external requests, too.
.It Fl -webserver-port Ar port
Specifies the port on which the web server should listen.
.It Fl -webserver-root Ar path
The path to the document tree of the webserver.
This is usually
.Pa {prefix}/shared/honeyd/webserver/htdocs/ .
.It Fl -rrdtool-path Ar path
Specifies the path for
.Xr rrdtool 1 .
Without
.Nm rrdtool
no traffic graphs can be generated.
.It Fl -disable-webserver
Disables the builtin webserver.
.It Fl -disable-update
Prevents
.Nm Honeyd
from checking if there are any security problems with the current
version of the application.
.It Fl -verify-config
Verifies that
.Nm Honeyd
can parse the configuration correctly.
This does not require any special permissions, although some configurations
that require direct access to interfaces might fail to validate.
.It Fl -fix-webserver-permissions
Changes the ownership of the web server files to the user,
.Nm Honeyd
is going to run as.
.It Fl V|--version
Print version information and exit.
.It Fl h|--help
Print summary of command line options and exit.
.It Fl -include-dir
For plugin development.
Reports the directory in which
.Nm
stores its header files.
.It Fl -data-dir
Reports the directory in which
.Nm
stores data files like Python modules.
.It Ar net
The IP address or network (specified in CIDR notation) or IP address
ranges to claim
(e.g. ``10.0.0.3'', ``10.0.0.0/16'' or ``10.0.0.5-10.0.0.15'').
If unspecified,
.Nm
will attempt to claim any IP address it sees traffic for.
.El
.Sh ROUTING TOPOLOGY
.Nm
supports the creation of a complete network topology including
routing. In order to enable the simulation of a network topology,
a router entry point has to be configured with
.Bd -literal
route entry <IP address>
.Ed
.Pp
By adding a
.Va network
to a router entry point,
.Nm
is told about the network addresses this entry point is responsible
for.
This enables multiple entry points into the routing topology.
.Pp
Every
.Va route add net
directive creates the specified gateway as a new router.
In the case of tunneling, no new router is created, instead
packets are
.Xr gre 4
encapsulated and sent to the tunnel destination address.
It is assumed that the tunnel destination address routes
the encapsulated packets to a
.Nm
machine.
.Pp
The virtual machines that can be directly accessed by a router
are defined as network range in the
.Va route link
command.
.Pp
A link may carry attributes like
.Va latency ,
.Va loss ,
and
.Va bandwidth .
The
.Va latency
specifies a constant delay for packets travelling across the link.
The
.Va bandwidth
on the other hand tracks the bandwidth related queuing delay for
each link.
If a packet is still being transmitted on the link then the
queue delay for another packet is the propagating delay depending
on the bandwidth plus the time for the previous packet to clear
the link.
.Pp
Unless the link is configured to drop packets between a configurable
delay threshold,
.Nm Honeyd
currently assumes infinite buffer space, so use this option
with care.
.Pp
An address space can be made unrouteable via the
.Va route unreach
command.
.Pp
The router entry point is the first address that inspects
a packet. The packet follows a path defined by the network
topology until the current router has the destination IP address
<
8000
div>
on its local network.
.Pp
It is possible to integrate real machines into the routing topology.
.Nm
takes care of ARP requests and replies and encapsulates packets
that go to external machines into ethernet packets.
.Pp
External machines can be configured with the following command:
.Bd -literal
bind <IP address> to <interface name>
.Ed
.Pp
.Sh SUBSYSTEM VIRTUALIZATION
Subsystem virtualization allows you to run regular network applications
under a virtual IP address controlled by
.Nm honeyd .
The application's network calls are intercepted and virtualized
to the honeypot that they are configured to.
As a result, all network calls that subsytem applications make appear
to originate from the virtual IP address of a honeypot.
This includes binding ports, accepting and initiating UDP and TCP connections.
Raw sockets are not supported.
.Pp
Subsystem are configured as follows
.Bd -literal
set template subsystem "/usr/sbin/httpd"
.Ed
.Pp
and are started as a separate process for every bound template.
Applications started as a
.Nm
subsystem need to be dynamically linked in order to work under
.Nm Honeyd .
.Pp
It is possible to shared subsystems across different addresses
if they are created with the
.Va shared
flag.
This allows a subsystem to bind to several virtual IP addresses
and may also be used to increase the performance of subsystems
across addresses.
.Sh DYNAMIC TEMPLATES
Dynamic templates give
.Nm Honeyd
the ability to change networking behavior based on several
different conditions:
.Bl -tag -width operatingxsystemx
.It source address
The source address of the network connection determines which
template is going to be used.
.It operating system
The operating system as determined by passive fingerprinting
needs to be matched for the template to be activated.
.It time
The template is only being used between a certain time interval.
This allows Honeyd to simulate machines being turned on and off.
.El
.Pp
A dynamic template can be created with the following command:
.Bd -literal
dynamic magichost
add magichost use windowsxp if source os = windows
add magichost use linux if source ip = 192.168.0.0/16
add magichost use invisible if time between 12:00am - 5:00am
add magichost otherwise use default
.Ed
.Pp
As an alternative, it is possible to use a short cut in the
bind command to create dynamic templates:
.Bd -literal
bind source ip = 192.168.0.0/16 10.0.0.5 cisco
bind source ip = 10.0.0.0/8 10.0.0.5 juniper
.Ed
.Pp
In this example, the host on
.Va 10.0.0.5
behaves like a cisco router if it is contacted from IP addresses
in the
.Va 192.168
network.
If it is contacted from IP addresses in the
.Va 10
network, it behaves like a juniper router.
.Sh MANAGEMENT CONSOLE
The
.Xr honeydctl 1
command allows the dynamic configuration of
.Nm Honeyd
while it is running; see
.Xr honeydctl 1
for more information.
.Sh LOGGING
.Nm Honeyd
has two different logging modes.
The syslog facility is used to log connection establishment and
termination including other relevant packet events. Most
messages can be disabled when configuring
.Xr syslog.conf 5
to drop all messages for the
.Dv LOG_DAEMON
facility if the log level is below
.Dv LOG_NOTICE .
.Pp
Services started by
.Nm
can cause the daemon to log data by sending information to
.Va stderr .
.Pp
The second way of logging network activity is by using the
.Fl l
flag.
This causes
.Nm
to log all received packets in a human readable format.
For UDP and TCP connections,
.Nm
logs the start and end of a flow including the amount of
data transfered.
.Pp
For logging any other information, it is suggested to run
a separate intrusion detection system.
.Sh SCRIPTING WITH PYTHON
.Nm Honeyd
supports internal service scripts that have been written in Python.
To improve the performance of these services,
.Nm Honeyd
provides an event-driven model.
The services need to indiciate when they are ready to read and when
they are ready to write data.
.Nm Honeyd
keeps track of state that is provided to the Python scripts on
every invocation.
.Pp
The folowing example uses a Python script to implement a simple
echo server:
.Bd -literal
import honeyd
import sys
def honeyd_init(data):
mydata = {}
honeyd.read_selector(honeyd.EVENT_ON)
return mydata
def honeyd_readdata(mydata, data):
honeyd.read_selector(honeyd.EVENT_ON)
honeyd.write_selector(honeyd.EVENT_ON)
mydata["write"] = data
return 0
def honeyd_writedata(mydata):
data = mydata["write"]
del mydata["write"]
return data
def honeyd_end(mydata):
del mydata
return 0
.Ed
.Pp
.Sh EXAMPLES
A sample configuration file looks as follows:
.Bd -literal
# Example of a simple host template and its binding
include annotations
# Set up the hosts
create template
set template personality "OpenBSD 2.6-2.7"
add template tcp port 80 "sh scripts/web.sh"
add template tcp port 22 "sh scripts/test.sh $ipsrc $dport"
add template udp port 53 proxy yournameserver:53
set template default tcp action closed
set template uid 32767 gid 32767
bind 10.11.69.2 template
set 10.11.69.2 uptime 1327650
.Ed
.Pp
A simple example of a routing topology:
.Bd -literal
route entry 10.0.0.1
route 10.0.0.1 link 10.2.0.0/24
route 10.0.0.1 add net 10.2.1.0/24 10.2.0.10 latency 10ms loss 3.4
route 10.2.0.10 link 10.2.1.0/24
.Ed
.Pp
For this topology to work the
.Ar net
value in the command line has to be
.Ar 10.0.0.1 10.2.0.0/24 10.2.1.0/24 .
.Sh FILES
.Bl -tag -width {prefix}/share/honeyd/xprobe2.conf
.It Pa /var/run/honeyd.pid
The PID of the current daemon.
.It Pa {prefix}/lib/honeyd/webserver/
Python modules and web server documents used by the internal webserver.
.It Pa {prefix}/lib/honeyd/libhoneyd.so
A shared library that can be preloaded to virtualize applications within
.Nm honeyd .
.It Pa {prefix}/share/honeyd/nmap.assoc
An association file to match
.Nm xprobe2
fingerprints against
.Nm nmap .
.It Pa {prefix}/share/honeyd/nmap-os-db
.Nm Nmap
fingerprints used by
.Nm
to impersonate operating system stacks.
.It Pa {prefix}/share/honeyd/xprobe2.conf
.Nm Xprobe
fingerprints used by
.Nm
to impersonsate the ICMP section of operating system stacks.
.El
.Sh SEE ALSO
.Xr honeydctl 1
.Xr arpd 8
.Sh AUTHORS
Niels Provos
.Aq provos@citi.umich.edu