]> git.wincent.com - bansshee.git/blob - README
Switch to BSD license
[bansshee.git] / README
1 CONTENTS
2
3   * Overview
4   * Donations
5   * Requirements
6   * Configuration
7   * Starting Bansshee
8   * Stopping Bansshee
9   * Bansshee Website
10   * Obtaining Bansshee
11   * Contributing Code
12   * Author
13
14
15 OVERVIEW
16
17 Bansshee is a Perl script that runs as a daemon watching for SSH dictionary
18 attacks. On detecting an attack it uses the firewall to temporarily prevent
19 further access attempts. Many aspects of Bansshee are configurable, including
20 the number of failed access attempts that may be generated by a given IP before
21 they are considered an attack, how long an IP will remain on the blocklist
22 before being removed and what the grace period should be between attempts
23 before the internal counters are reset.
24
25
26 DONATIONS
27
28 Bansshee is provided free of charge under the simplified, 2-clause version of
29 the BSD license, as used by FreeBSD (see the LICENSE file for details) so it is
30 both free "as in beer" and free "libre". Although it is free you can encourage
31 further development by making a donation and you are encouraged to do so if you
32 find it to be useful. Donations can be sent via PayPal to author at
33 win@wincent.com or via the website:
34
35   http://wincent.com/a/products/bansshee/#donations
36
37
38 REQUIREMENTS
39
40 Perl
41 ====
42
43 Bansshee requires a recent version of Perl compiled with multithreading
44 support. Specifically it requires the newer "ithreads" (interpreter threads)
45 implementation available in Perl 5.6.0 and later. This version of Bansshee was
46 built and tested using Perl v5.8.0 (built for "i386-linux-thread-multi"). You
47 can check the version of Perl installed on your system and whether it supports
48 multi-threading by passing the -v or -V switch to Perl on the command line
49 (more information on this below).
50
51 By default Bansshee expects to find perl installed at /usr/bin/perl; if perl is
52 installed at a different location on your system then you must edit the first
53 line of the bansshee script to reflect the location.
54
55 Perl modules
56 ============
57
58 Bansshee relies on a number of Perl modules. More information about any of the
59 modules can be found by going to http://search.cpan.org/ and performing a
60 search for the module name. You can determine if a module is present on your
61 system by using Perl's "-c" command line switch to check the syntax of the
62 "bansshee" script; it will report any required modules missing from your system:
63
64   perl -c bansshee
65
66 To install any missing modules you can use Perl's CPAN module. For example, to
67 install the "File::Tail" module you could use:
68
69   sudo perl -MCPAN -e 'install File::Tail'
70
71 Here follows a list of the modules used by Bansshee:
72
73 * threads
74
75 Bansshee is written to use the newer "ithreads" (interpreter threads) model
76 introduced in Perl 5.6.0. To confirm that your version of Perl is compatible
77 examine the output of "perl -V" and look for the following:
78
79   usethreads=define use5005threads=undef useithreads=define
80
81 Note that "use5005threads" (the old thread model) is set to "undef" and the new
82 thread implementation ("useithreads") is set to "define".
83
84 * Sys::Syslog
85
86 A Perl interface to the UNIX syslog(3) calls. To my knowledge this module is
87 included with the Perl base install.
88
89 * sigtrap
90
91 A Perl pragma to enable simple signal handling. Again I believe this is
92 included with the Perl base install.
93
94 * Proc::Daemon
95
96 A module for running a Perl program as a daemon (background) process.
97
98 * File::Tail
99
100 A Perl extension for efficiently reading from continously updated files.
101
102 iptables
103 ========
104
105 Bansshee uses the iptables administration tool to control the tables of the IP
106 packet filter rules in the kernel.
107
108 General
109 =======
110
111 Bansshee must be run with root privileges so as to be able to make
112 modifications to the firewall using iptables, and also to monitor the log file
113 (which may be owned by root and not world-readable).
114
115
116 CONFIGURATION
117
118 Bansshee has a number of customizable settings that can be used to modify its
119 behaviour. The settings appear near the top of the "bansshee" script itself
120 under the heading "Default Settings". You may either edit the settings directly
121 in the file itself, or place your customized settings in the
122 "/etc/bansshee.conf" file. Settings in the conf file will override settings in
123 the script. By using the conf file you can upgrade the Bansshee script without
124 having to re-apply your customizations to the script each time.
125
126 * permitted_illegal_user
127
128 This is the number of attempts to log in using an illegal (unknown) username
129 that will be permitted from a single IP address before that IP address gets
130 blocked. Defaults to 5 attempts.
131
132 * permitted_incorrect_pass
133
134 This is the number of attempts to log in using a legal (known) username but
135 supplying an invalid password that will be permitted from a single IP address
136 before that IP address gets blocked. Defaults to 5 attempts.
137
138 * unban_wait
139
140 This is the minimum number of seconds that a blocked IP address must wait
141 before it gets automatically removed from the blocklist. Defaults to 3600
142 seconds (1 hour).
143
144 * grace_period
145
146 This is the number of seconds that must pass before prior illegal user or
147 incorrect password attempts from a given IP address are disregarded. Defaults
148 to 3600 seconds (1 hour).
149
150 * unblocking_interval
151
152 This is the number of seconds that Bansshee waits before checking the blocklist
153 and removing any IP addresses which have been in the blocklist for more than
154 "unban_wait" seconds. Defaults to 300 (5 minutes).
155
156
157 PLATFORM-SPECIFIC CONFIGURATION
158
159 In addition to the already-discussed configuration variables, there are a
160 number of settings which may need to be adjusted depending in order to make
161 Bansshee work on different platforms. These settings are:
162
163 * logpath
164
165 The path to the logfile that Bansshee should watch in order to detect breakin
166 attempts. Defaults to "/var/log/secure".
167
168 * illegal_user_regex
169
170 A regular expression used to detect log entries corresponding to attempt to log
171 in using an illegal/invalid (non-existent) user. The regular expression should
172 contain two parenthesised subpatterns, one for the username and one for the
173 remote IP address, so that Bansshee can extract those subpatterns. If you need
174 to use brackets for any other part within the regular expression than you
175 should use a non-capturing subpattern -- denoted with (?:subpattern) --
176 instead; see the RHEL 5.3 configuration file in the contrib directory for an
177 example of this.
178
179 * incorrect_pass_regex
180
181 Like the illegal_user_regex, this setting provides a regular expression to
182 detect connection attempts which supply a valid user but an incorrect password.
183 Again, two parenthesised subpatterns (for username and remote IP) are required
184 so that Bansshee can extract the corresponding information.
185
186 * iptables
187
188 The path to the iptables executable. Defaults to "/sbin/iptables".
189
190 * iptables_create
191
192 Arguments that should be passed to iptables to create the BANSSHEE chain.
193 Defaults to "-N BANSSHEE".
194
195 * iptables_add
196
197 Arguments that should be passed to iptables to add the BANSSHEE jump rule.
198 Defaults to "-I INPUT -p tcp --dport ssh -j BANSSHEE".
199
200 * iptables_remove
201
202 Arguments that should be passed to iptables to remove the BANSSHEE jump rule.
203 Defaults to "-D INPUT -p tcp --dport ssh -j BANSSHEE".
204
205 * iptables_flush
206
207 Arguments that should be passed to iptables to flush the BANSSHEE chain.
208 Defaults to "-F BANSSHEE".
209
210 * iptables_delete
211
212 Arguments that should be passed to iptables to delete the BANSSHEE chain.
213 Defaults to "-X BANSSHEE".
214
215 * id
216
217 Command that should be executed to determine if Bansshee is running as root.
218 Defaults to "/usr/bin/id -u".
219
220 * log_facility
221
222 Controls Bansshee's logging of status messages to /var/log/secure or similar.
223 Defaults to "authpriv".
224
225 The default settings were developed and tested using Red Hat Enterprise Linux
226 ES3 and may work with other platforms.
227
228 In addition there are some user-contributed support files in the "contrib"
229 directory that may be helpful when setting up Bansshee on other platforms.
230
231
232 STARTING BANSSHEE
233
234 For information on installing Bansshee see the INSTALL file.
235
236 For automatic startup at boot time see the platform-specific files in the
237 contrib directory. If Bansshee has been set up to start automatically at boot
238 time then it should always be started (and stopped) using the same control
239 script. For example, on Red Had Enterprise Linux the following command would be
240 used:
241
242   sudo service bansshee start
243
244 For manual startup, working from the directory containing the bansshee script:
245
246   sudo ./bansshee
247
248
249 STOPPING BANSSHEE
250
251 To manually stop Bansshee find its PID and kill it. For example, on a system
252 like Red Hat Enterprise Linux which comes with a "pidof" command the following
253 command can be used to stop Bansshee:
254
255   sudo kill $(pidof -x bansshee)
256
257 Bansshee will catch the kill signal, perform clean-up and then exit.
258
259 If Bansshee has been set up to start automatically at boot time then it should
260 be stopped using the same control script that was used to start it. For
261 example, on Red Hat Enterprise Linux the following command would be used:
262
263   sudo service bansshee stop
264
265 Unlike some other anti-dictionary attack tools currently available, Bansshee
266 makes no attempt to save its state between sessions. This is because most
267 attacks are transitory in nature anyway (the attacker tries and then moves on)
268 and there is little benefit to trying to maintain state information between
269 sessions. As a result the Bansshee code base is cleaner and less likely to
270 contain bugs. It sets up its own IP tables rules on launch and cleans up after
271 itself on exit. The need for a persistent store is also minimized by the fact
272 that Bansshee is solid and stable enough to run for long periods without being
273 restarted. At the time of writing my current Bansshee install has been up and
274 running without interruption for an entire month without any problems.
275
276
277 BANSSHEE WEBSITE
278
279   http://wincent.com/a/products/bansshee/
280
281
282 OBTAINING BANSSHEE
283
284 The latest released version of Bansshee can be downloaded from the website
285 (link appears above).
286
287 You can clone the source code repository using Git:
288
289   git clone git://git.wincent.com/bansshee.git
290
291 Or explore the repository contents using a browser:
292
293   http://git.wincent.com/bansshee.git
294
295 Older versions can be checked out via Subversion:
296
297   svn co svn://svn.wincent.com/bansshee
298
299
300 CONTRIBUTING CODE
301
302 To submit changes to Bansshee please use "git format-patch" (see OBTAINING
303 BANSSHEE for information on cloning the repository) and send your patch via
304 email to win@wincent.com.
305
306
307 AUTHOR
308
309 Bansshee is written and maintained by Wincent Colaiuta:
310
311   http://wincent.com/
312   win@wincent.com