1LABREA.CONF(5) File Formats Manual LABREA.CONF(5)
2
6 labrea.conf - labrea(1) configuration file
7
9 nnn.nnn.nnn.nnn [- nnn.nnn.nnn.nnn] EXC
10 nnn.nnn.nnn.nnn [- nnn.nnn.nnn.nnn] HAR
12 nnn.nnn.nnn.nnn[/nn] IPI
14 nnnnn [- nnnnn] POR
16 nnnnn [- nnnnn] PMN
18
20 Generalities
21 labrea.conf is the configuration file for the labrea(1) program.
22 Each line consists of a selector field, followed by an action verb.
24 Whitespace is suppressed. Blank lines are ignored, as are lines begin‐
26 ning with "#".
27 Selectors
29 IPs can be specified as either a single address (e.g. "192.168.0.4") or
30 as a range of addresses (e.g. "192.168.0.1 - 192.168.0.50").
31 Ports can be specified as either a single port (e.g. 12345) or as a
33 range of ports (e.g. 1-65535).
34 IP Capturing
36 When labrea sees an ARP request for an unused IP, it does the follow‐
37 ing:
38 On an IP by IP basis, store a time and an originating IP address:
40 1. For an incoming ARP request, check the current time:
42 a. If currently stored time is 0 or the arp comes from a
44 different address than the one stored, then store the
45 current time and the requesting IP and return.
46 b. If the stored time is less than "-r" seconds ago, ignore
48 it and return.
49 c. If currently stored time is more than a minute ago, store
51 0, return. (Max timeout)
52 d. Otherwise, grab the IP.
54 2. See an ARP reply, set stored time to 0.
56 When an ARP request for a particular IP goes unanswered for longer than
58 its "rate" setting (default: 3 seconds), labrea crafts an ARP reply
59 that routes all traffic destined for the IP to a "bogus" MAC address.
60 labrea listens for TCP/IP traffic routed to that MAC address and then
61 responds to any SYN packet (ie incoming connection) with a SYN/ACK
62 packet.
63 Explanation of terms
65 Excluded IPs: Are those IPs that labrea should never capture. Note that
66 automatic mechanisms are also used to prevent capturing IPs with an
67 active machine on it. See labrea(1) for more details.
68 Hard captured IPs: The -h --hard-capture option instructs labrea that
70 once it captures an IP address, then it needn't wait for a "-r" timeout
71 the next time around. These IPs are said to be "hard" captured.
72 Hard excluded IPS: These are IPs that should never be "hard" captured.
74 In other words, each time there is an ARP request for this IP, then
75 labrea will always wait for the timeout -r secs before responding.
76 Tarpitting: On a captured IP, labrea responds to an incoming SYN con‐
78 nection attempt with a SYN/ACK. This causes the remote machine's stack
79 to initiate the Tcp connection and then waste time fruitlessly trying
80 to continue the conversation.
81 Persist state capture: labrea can permanently capture connect attempts
83 by closing the TCP window to force the connection into "persist" state.
84 In this state, the connection never times out, and labrea hangs on to
85 the incoming connection until it is closed from the other end.
86 To accomplish this, short packets are sent every so often to say "keep
88 waiting, my Tcp window is still closed". So a maximum b/w control is
89 implemented to limit the total b/w consumption. (see the -p --max-rate
90 startup option)
91 Auto hard capturing: This is a startup option that says that unless an
93 IP is excluded or hard-excluded, then mark it as being hard captured.
94 This is normally a risky thing to do and should be used with caution.
95 Normal virtual machine behaviour
97 Default port behaviour: Incoming connections on any port will be sub‐
98 ject to tarpitting / persist capturing.
99 Since all connections are inbound, there should be no incoming
101 SYN/ACKs. Labrea will respond RST to an incoming SYN/ACK unless the
102 startup option -a --no-resp-synack disables this behaviour.
103 Excluded ports: Ports that are specifically excluded will not be
105 tarpitted or persist captured.
106 Incoming connection attempts on an excluded port will receive a RST.
108 Virtual machine behaviour when firewalling:
110 Active ports: When firewalling (i.e. -f --no-resp-excluded-ports) is
111 active, then by default only the most widely used ports are active at
112 startup.
113 Incoming connections on these active ports will be tarpitted and/or
115 persist captured as usual.
116 Excluded ports: When firewalling is active, incoming connections on
118 excluded ports will not receive a response. The packets will be
119 dropped.
120 Among other things, this means that nmap scans take much more time to
122 complete.
123 Other ports: Ports that are neither active nor excluded are passively
125 monitored for incoming SYN activity. At startup, they behave as an
126 excluded port (i.e. packets are dropped).
127 However, if there is enough activity on a given port, it will dynami‐
129 cally become active. The threshold is more than 6 SYNs for a given port
130 in an hour. However every 15 minutes, the port's SYN count is reduced
131 by 1 to eliminate noise.
132 If the SYN count for a port finally reaches 255, then the port is con‐
134 sidered permanently active.
135
137 This section describes the configuration statements and their usage:
138 nnn.nnn.nnn.nnn [- nnn.nnn.nnn.nnn] EXC
140 Never capture the specified IP addresses. This applies to local
141 IP addresses (i.e. on the local capture netblock) only.
142 nnn.nnn.nnn.nnn [- nnn.nnn.nnn.nnn] HAR
144 WHen "hard capturing" is in effect ("-h"), then never hard cap‐
145 ture the specified IP addresses. (i.e. Always wait for the ARP
146 timeout before responding.) Applies to local IP addresses only.
147 nnn.nnn.nnn.nnn[/nn] IPI
149 Ignore any packets with source IP address in the specified net‐
150 block. labrea will not tarpit or persist capture connections
151 from the specified IP addresses.
152 Note that this statement can apply to any IP address.
154 Note also that the netblock is specified in CIDR notation (ie
156 nnn.nnn.nnn.nnn/nn) and not as a range of IP addresses.
157 nnnnn [- nnnnn] POR
159 These ports are excluded. labrea will not tarpit / persist cap‐
160 ture incoming connections on these ports. A RST will be returned
161 unless firewalling is active. In that case, the incoming packet
162 will be dropped.
163 nnnnn [- nnnnn] PMN
165 At startup, mark the indicated ports as being active. Incoming
166 connections to these ports are subject to tarpitting / persist
167 capturing.
168 This configuration statement is useful only when firewalling is
170 active. The port becomes immediately active, instead of waiting
171 for enough SYNs to bump the port's SYN count above the activity
172 threshold.
173
175 Suppose that the capture subnet is 192.168.10.0/24.
176 Exclude 192.168.10.5 through .7 from being captured:
178 192.168.10.5 - 192.168.10.7 EXC
180 "Hard exclude" 192.168.10.100:
182 192.168.10.100 HAR
184 Do not attempt to tarpit / persist capture packets from the class C
186 subnet 10.2.3.x:
187 10.2.3.0/24 IPI
189 Put in some comments:
191 #
193 # This is a comment
194 #
195 Do not tarpit / persist capture on ports 21-25:
197 21-25 POR
199 When firewalling, make port 12345 active at startup:
201 12345 PMN
203
205 /usr/local/etc/labrea.conf
206 Default configuration file on unix systems
207 (current directory) LaBrea.cfg
209 Default configuration file on Windows systems
210
212 labrea(1)
213
215 Tom Liston <tliston@hackbusters.net> Bugs: lorgor@users.sourceforge.net
216 or http://labrea.sourceforge.net
217 LABREA.CONF(5)