projects / feed / packages.git / blob
? search:
summary | shortlog | log | commit | commitdiff | tree
history | raw | HEAD
banip: update to 0.7.3
[feed/packages.git] / net / banip / files / README.md
1 <!-- markdownlint-disable -->
2
3 # banIP - ban incoming and/or outgoing ip adresses via ipsets
4
5 ## Description
6 IP address blocking is commonly used to protect against brute force attacks, prevent disruptive or unauthorized address(es) from access or it can be used to restrict access to or from a particular geographic area — for example.
7
8 ## Main Features
9 * Support of the following fully pre-configured domain blocklist sources (free for private usage, for commercial use please check their individual licenses)
10
11 | Source | Focus | Information |
12 | :------------------ | :----------------------------: | :-------------------------------------------------------------------------------- |
13 | asn | ASN block | [Link](https://asn.ipinfo.app) |
14 | bogon | Bogon prefixes | [Link](https://team-cymru.com) |
15 | country | Country blocks | [Link](https://www.ipdeny.com/ipblocks) |
16 | darklist | blocks suspicious attacker IPs | [Link](https://darklist.de) |
17 | debl | Fail2ban IP blacklist | [Link](https://www.blocklist.de) |
18 | doh | Public DoH-Provider | [Link](https://github.com/dibdot/DoH-IP-blocklists) |
19 | drop | Spamhaus drop compilation | [Link](https://www.spamhaus.org) |
20 | dshield | Dshield IP blocklist | [Link](https://www.dshield.org) |
21 | edrop | Spamhaus edrop compilation | [Link](https://www.spamhaus.org) |
22 | feodo | Feodo Tracker | [Link](https://feodotracker.abuse.ch) |
23 | firehol1 | Firehol Level 1 compilation | [Link](https://iplists.firehol.org/?ipset=firehol_level1) |
24 | firehol2 | Firehol Level 2 compilation | [Link](https://iplists.firehol.org/?ipset=firehol_level2) |
25 | firehol3 | Firehol Level 3 compilation | [Link](https://iplists.firehol.org/?ipset=firehol_level3) |
26 | firehol4 | Firehol Level 4 compilation | [Link](https://iplists.firehol.org/?ipset=firehol_level4) |
27 | greensnow | blocks suspicious server IPs | [Link](https://greensnow.co) |
28 | iblockads | Advertising blocklist | [Link](https://www.iblocklist.com) |
29 | iblockspy | Malicious spyware blocklist | [Link](https://www.iblocklist.com) |
30 | myip | Myip Live IP blacklist | [Link](https://myip.ms) |
31 | nixspam | iX spam protection | [Link](http://www.nixspam.org) |
32 | proxy | Firehol list of open proxies | [Link](https://iplists.firehol.org/?ipset=proxylists) |
33 | ssbl | SSL botnet IP blacklist | [Link](https://sslbl.abuse.ch) |
34 | talos | Cisco Talos IP Blacklist | [Link](https://talosintelligence.com/reputation_center) |
35 | threat | Emerging Threats | [Link](https://rules.emergingthreats.net) |
36 | tor | Tor exit nodes | [Link](https://fissionrelays.net/lists) |
37 | uceprotect1 | Spam protection level 1 | [Link](http://www.uceprotect.net/en/index.php) |
38 | uceprotect2 | Spam protection level 2 | [Link](http://www.uceprotect.net/en/index.php) |
39 | voip | VoIP fraud blocklist | [Link](http://www.voipbl.org) |
40 | yoyo | Ad protection blacklist | [Link](https://pgl.yoyo.org/adservers/) |
41
42 * zero-conf like automatic installation & setup, usually no manual changes needed
43 * automatically selects one of the following download utilities: aria2c, curl, uclient-fetch, wget
44 * Really fast downloads & list processing as they are handled in parallel as background jobs in a configurable 'Download Queue'
45 * full IPv4 and IPv6 support
46 * ipsets (one per source) are used to ban a large number of IP addresses
47 * supports blocking by ASN numbers
48 * supports blocking by iso country codes
49 * supports local white & blacklist (IPv4, IPv6 & CIDR notation), located by default in /etc/banip/banip.whitelist and /etc/banip/banip.blacklist
50 * auto-add unsuccessful LuCI and ssh login attempts via 'dropbear' or 'sshd' to local blacklist (see 'ban_autoblacklist' option)
51 * auto-add the uplink subnet to local whitelist (see 'ban_autowhitelist' option)
52 * provides a small background log monitor to ban unsuccessful login attempts in real-time
53 * per source configuration of SRC (incoming) and DST (outgoing)
54 * integrated IPSet-Lookup
55 * integrated RIPE-Lookup
56 * blocklist source parsing by fast & flexible regex rulesets
57 * minimal status & error logging to syslog, enable debug logging to receive more output
58 * procd based init system support (start/stop/restart/reload/refresh/status)
59 * procd network interface trigger support
60 * automatic blocklist backup & restore, they will be used in case of download errors or during startup
61 * Provides comprehensive runtime information
62 * Provides a detailed IPSet Report
63 * Provides a powerful query function to quickly find blocked IPs/CIDR in banIP related IPSets
64 * Provides an easily configurable blocklist update scheduler called 'Refresh Timer'
65 * strong LuCI support
66 * optional: add new banIP sources on your own
67
68 ## Prerequisites
69 * [OpenWrt](https://openwrt.org), tested with the stable release series (19.07.x) and with the latest rolling snapshot releases. On turris devices it has been successfully tested with TurrisOS 5.2.x
70 <b>Please note:</b> Older OpenWrt releases like 18.06.x or 17.01.x are _not_ supported!
71 <b>Please note:</b> Devices with less than 128 MByte RAM are _not_ supported!
72 <b>Please note:</b> If you're updating from former banIP 0.3x please manually remove your config (/etc/config/banip) before you start!
73 * A download utility with SSL support: 'wget', 'uclient-fetch' with one of the 'libustream-*' ssl libraries, 'aria2c' or 'curl' is required
74 * A certificate store like 'ca-bundle', as banIP checks the validity of the SSL certificates of all download sites by default
75 * Optional E-Mail notification support: for E-Mail notifications you need to install the additional 'msmtp' package
76
77 ## Installation & Usage
78 * Update your local opkg repository (_opkg update_)
79 * Install 'banip' (_opkg install banip_). The banIP service is disabled by default
80 * Install the LuCI companion package 'luci-app-banip' (_opkg install luci-app-banip_)
81 * It's strongly recommended to use the LuCI frontend to easily configure all aspects of banIP, the application is located in LuCI under the 'Services' menu
82
83 ## banIP CLI
84 * All important banIP functions are accessible via CLI as well.
85 <pre><code>
86 ~# /etc/init.d/banip
87 Syntax: /etc/init.d/banip [command]
88
89 Available commands:
90 start Start the service
91 stop Stop the service
92 restart Restart the service
93 reload Reload configuration files (or restart if service does not implement reload)
94 enable Enable service autostart
95 disable Disable service autostart
96 enabled Check if service is started on boot
97 refresh Refresh ipsets without new list downloads
98 suspend Suspend banIP processing
99 resume Resume banIP processing
100 query &lt;IP&gt; Query active banIP IPSets for a specific IP address
101 report [&lt;cli&gt;|&lt;mail&gt;|&lt;gen&gt;|&lt;json&gt;] Print banIP related IPset statistics
102 list [&lt;add&gt;|&lt;add_asn&gt;|&lt;add_country&gt;|&lt;remove>|&lt;remove_asn&gt;|&lt;remove_country&gt;] &lt;source(s)&gt; List/Edit available sources
103 timer [&lt;add&gt; &lt;tasks&gt; &lt;hour&gt; [&lt;minute&gt;] [&lt;weekday&gt;]]|[&lt;remove&gt; &lt;line no.&gt;] List/Edit cron update intervals
104 version Print version information
105 running Check if service is running
106 status Service status
107 trace Start with syscall trace
108 </code></pre>
109
110 ## banIP config options
111 * Usually the auto pre-configured banIP setup works quite well and no manual overrides are needed
112
113 | Option | Type | Default | Description |
114 | :---------------------- | :----- | :---------------------------- | :------------------------------------------------------------------------------------ |
115 | ban_enabled | option | 0 | enable the banIP service |
116 | ban_autodetect | option | 1 | auto-detect wan interfaces, devices and subnets |
117 | ban_debug | option | 0 | enable banIP related debug logging |
118 | ban_mail_enabled | option | 0 | enable the mail service |
119 | ban_monitor_enabled | option | 0 | enable the log monitor, e.g. to catch failed ssh/luci logins |
120 | ban_logsrc_enabled | option | 0 | enable the src-related logchain |
121 | ban_logdst_enabled | option | 0 | enable the dst-related logchain |
122 | ban_autoblacklist | option | 1 | add suspicious IPs automatically to the local blacklist |
123 | ban_autowhitelist | option | 1 | add wan IPs/subnets automatically to the local whitelist |
124 | ban_maxqueue | option | 4 | size of the download queue to handle downloads and processing in parallel |
125 | ban_reportdir | option | /tmp/banIP-Report | directory where banIP stores the report files |
126 | ban_backupdir | option | /tmp/banIP-Backup | directory where banIP stores the compressed backup files |
127 | ban_ifaces | list | - | list option to add logical wan interfaces manually |
128 | ban_sources | list | - | list option to add banIP sources |
129 | ban_countries | list | - | list option to add certain countries as an alpha-2 ISO code, e.g. 'de' for germany |
130 | ban_asns | list | - | list option to add certain ASNs (autonomous system number), e.g. '32934' for facebook |
131 | ban_chain | option | banIP | name of the root chain used by banIP |
132 | ban_global_settype | option | src+dst | global settype as default for all sources |
133 | ban_settype_src | list | - | special SRC settype for a certain sources |
134 | ban_settype_dst | list | - | special DST settype for a certain sources |
135 | ban_settype_all | list | - | special SRC+DST settype for a certain sources |
136 | ban_target_src | option | DROP | default src action (used by log chains as well) |
137 | ban_target_dst | option | REJECT | default dst action (used by log chains as well) |
138 | ban_lan_inputchains_4 | list | input_lan_rule | list option to add IPv4 lan input chains |
139 | ban_lan_inputchains_6 | list | input_lan_rule | list option to add IPv6 lan input chains |
140 | ban_lan_forwardchains_4 | list | forwarding_lan_rule | list option to add IPv4 lan forward chains |
141 | ban_lan_forwardchains_6 | list | forwarding_lan_rule | list option to add IPv6 lan forward chains |
142 | ban_wan_inputchains_4 | list | input_wan_rule | list option to add IPv4 wan input chains |
143 | ban_wan_inputchains_6 | list | input_wan_rule | list option to add IPv6 wan input chains |
144 | ban_wan_forwardchains_4 | list | forwarding_wan_rule | list option to add IPv4 wan forward chains |
145 | ban_wan_forwardchains_6 | list | forwarding_wan_rule | list option to add IPv6 wan forward chains |
146 | ban_mailreceiver | option | - | receiver address for banIP related notification E-Mails |
147 | ban_mailsender | option | no-reply@banIP | sender address for banIP related notification E-Mails |
148 | ban_mailtopic | option | banIP notification | topic for banIP related notification E-Mails |
149 | ban_mailprofile | option | ban_notify | mail profile used in 'msmtp' for banIP related notification E-Mails |
150 | ban_srcarc | option | /etc/banip/banip.sources.gz | full path to the compressed source archive file used by banIP |
151 | ban_localsources | list | maclist, whitelist, blacklist | limit the selection to certain local sources |
152 | ban_extrasources | list | - | add additional, non-banIP related IPSets e.g. for reporting or queries |
153 | ban_maclist_timeout | option | - | individual maclist IPSet timeout |
154 | ban_whitelist_timeout | option | - | individual whitelist IPSet timeout |
155 | ban_blacklist_timeout | option | - | individual blacklist IPSet timeout |
156 | ban_logterms | list | dropbear, sshd, luci, nginx | limit the log monitor to certain log terms |
157 | ban_loglimit | option | 100 | parse only the last stated number of log entries for suspicious events |
158 | ban_ssh_logcount | option | 3 | number of the failed ssh login repetitions of the same ip in the log before banning |
159 | ban_luci_logcount | option | 3 | number of the failed luci login repetitions of the same ip in the log before banning |
160 | ban_nginx_logcount | option | 5 | number of the failed nginx requests of the same ip in the log before banning |
161
162 ## Examples
163 **list/edit banIP sources:**
164
165 <pre><code>
166 ~# /etc/init.d/banip list
167 ::: Available banIP sources
168 :::
169 Name Enabled Focus Info URL
170 ---------------------------------------------------------------------------
171 + asn ASN blocks https://asn.ipinfo.app
172 + bogon Bogon prefixes https://team-cymru.com
173 + country x Country blocks https://www.ipdeny.com/ipblocks
174 + debl x Fail2ban IP blacklist https://www.blocklist.de
175 + doh x Public DoH-Provider https://github.com/dibdot/DoH-IP-blocklists
176 + drop x Spamhaus drop compilation https://www.spamhaus.org
177 + dshield x Dshield IP blocklist https://www.dshield.org
178 + edrop Spamhaus edrop compilation https://www.spamhaus.org
179 + feodo x Feodo Tracker https://feodotracker.abuse.ch
180 + firehol1 x Firehol Level 1 compilation https://iplists.firehol.org/?ipset=firehol_level1
181 + firehol2 Firehol Level 2 compilation https://iplists.firehol.org/?ipset=firehol_level2
182 + firehol3 Firehol Level 3 compilation https://iplists.firehol.org/?ipset=firehol_level3
183 + firehol4 Firehol Level 4 compilation https://iplists.firehol.org/?ipset=firehol_level4
184 + iblockads Advertising blocklist https://www.iblocklist.com
185 + iblockspy x Malicious spyware blocklist https://www.iblocklist.com
186 + myip Myip Live IP blacklist https://myip.ms
187 + nixspam x iX spam protection http://www.nixspam.org
188 + proxy Firehol list of open proxies https://iplists.firehol.org/?ipset=proxylists
189 + sslbl x SSL botnet IP blacklist https://sslbl.abuse.ch
190 + threat x Emerging Threats https://rules.emergingthreats.net
191 + tor x Tor exit nodes https://fissionrelays.net/lists
192 + uceprotect1 x Spam protection level 1 http://www.uceprotect.net/en/index.php
193 + uceprotect2 Spam protection level 2 http://www.uceprotect.net/en/index.php
194 + voip x VoIP fraud blocklist http://www.voipbl.org
195 + yoyo x Ad protection blacklist https://pgl.yoyo.org/adservers/
196 ---------------------------------------------------------------------------
197 * Configured ASNs: -
198 * Configured Countries: af, bd, br, cn, hk, hu, id, il, in, iq, ir, kp, kr, no, pk, pl, ro, ru, sa, th, tr, ua, gb
199 </code></pre>
200
201 **receive banIP runtime information:**
202
203 <pre><code>
204 ~# /etc/init.d/banip status
205 ::: banIP runtime information
206 + status : enabled
207 + version : 0.7.0
208 + ipset_info : 23 IPSets with 302008 IPs/Prefixes
209 + active_sources : blacklist, country, debl, doh, drop, dshield, feodo, firehol1, iblockspy, nixspam, sslbl, threat,
210 tor, uceprotect1, voip, whitelist, yoyo
211 + active_devs : eth3
212 + active_ifaces : wan, wan6
213 + active_logterms : dropbear, sshd, luci
214 + active_subnets : xxx.xxx.x.xxx/24, xxxx:xxxx:xxxx:x:xxxx:xxxx:xxxx:xxxx/64
215 + run_infos : settype: src+dst, backup_dir: /mnt/data/banip, report_dir: /tmp/banIP-Report
216 + run_flags : protocols (4/6): ✔/✔, log (src/dst): ✔/✘, monitor: ✔, mail: ✔
217 + last_run : refresh, 0m 16s, 4019/3527/3680, 03.02.2021 19:57:46
218 + system : PC Engines apu4, OpenWrt SNAPSHOT r15556-20a0d435d8
219 </code></pre>
220
221 **generate an IPSet report:**
222
223 <pre><code>
224 ~# /etc/init.d/banip report
225 :::
226 ::: report on all banIP related IPSets
227 :::
228 + Report timestamp ::: 04.02.2021 06:24:41
229 + Number of all IPSets ::: 24
230 + Number of all entries ::: 302448
231 + Number of IP entries ::: 224748
232 + Number of CIDR entries ::: 77700
233 + Number of MAC entries ::: 0
234 + Number of accessed entries ::: 36
235 :::
236 ::: IPSet details
237 :::
238 Name Type Count Cnt_IP Cnt_CIDR Cnt_MAC Cnt_ACC Entry details (Entry/Count)
239 --------------------------------------------------------------------------------------------------------------------
240 whitelist_4 src+dst 1 0 1 0 1
241 xxx.xxxx.xxx.xxxx/24 85
242 --------------------------------------------------------------------------------------------------------------------
243 whitelist_6 src+dst 2 0 2 0 1
244 xxxx:xxxx:xxxx::/64 29
245 --------------------------------------------------------------------------------------------------------------------
246 blacklist_4 src+dst 513 513 0 0 2
247 192.35.168.16 3
248 80.82.65.74 1
249 --------------------------------------------------------------------------------------------------------------------
250 blacklist_6 src+dst 1 1 0 0 0
251 --------------------------------------------------------------------------------------------------------------------
252 country_4 src 52150 0 52150 0 23
253 124.5.0.0/16 1
254 95.188.0.0/14 1
255 121.16.0.0/12 1
256 46.161.0.0/18 1
257 42.56.0.0/14 1
258 113.64.0.0/10 1
259 113.252.0.0/14 1
260 5.201.128.0/17 1
261 125.64.0.0/11 1
262 90.188.0.0/15 1
263 60.0.0.0/11 1
264 78.160.0.0/11 1
265 1.80.0.0/12 1
266 183.184.0.0/13 1
267 175.24.0.0/14 1
268 119.176.0.0/12 1
269 59.88.0.0/13 1
270 103.78.12.0/22 1
271 123.128.0.0/13 1
272 116.224.0.0/12 1
273 42.224.0.0/12 1
274 82.80.0.0/15 1
275 14.32.0.0/11 1
276 --------------------------------------------------------------------------------------------------------------------
277 country_6 src 20099 0 20099 0 0
278 --------------------------------------------------------------------------------------------------------------------
279 debl_4 src+dst 29389 29389 0 0 1
280 5.182.210.16 4
281 --------------------------------------------------------------------------------------------------------------------
282 debl_6 src+dst 64 64 0 0 0
283 --------------------------------------------------------------------------------------------------------------------
284 doh_4 src+dst 168 168 0 0 0
285 --------------------------------------------------------------------------------------------------------------------
286 doh_6 src+dst 122 122 0 0 0
287 --------------------------------------------------------------------------------------------------------------------
288 drop_4 src+dst 965 0 965 0 0
289 --------------------------------------------------------------------------------------------------------------------
290 drop_6 src+dst 36 0 36 0 0
291 --------------------------------------------------------------------------------------------------------------------
292 dshield_4 src+dst 20 0 20 0 1
293 89.248.165.0/24 1
294 --------------------------------------------------------------------------------------------------------------------
295 feodo_4 src+dst 325 325 0 0 0
296 --------------------------------------------------------------------------------------------------------------------
297 firehol1_4 src+dst 2763 403 2360 0 0
298 --------------------------------------------------------------------------------------------------------------------
299 iblockspy_4 src+dst 3650 2832 818 0 0
300 --------------------------------------------------------------------------------------------------------------------
301 nixspam_4 src+dst 9577 9577 0 0 0
302 --------------------------------------------------------------------------------------------------------------------
303 sslbl_4 src+dst 104 104 0 0 0
304 --------------------------------------------------------------------------------------------------------------------
305 threat_4 src+dst 1300 315 985 0 0
306 --------------------------------------------------------------------------------------------------------------------
307 tor_4 src+dst 1437 1437 0 0 0
308 --------------------------------------------------------------------------------------------------------------------
309 tor_6 src+dst 478 478 0 0 0
310 --------------------------------------------------------------------------------------------------------------------
311 uceprotect1_4 src+dst 156249 156249 0 0 6
312 192.241.220.137 1
313 128.14.137.178 1
314 61.219.11.153 1
315 138.34.32.33 1
316 107.174.133.130 2
317 180.232.99.46 1
318 --------------------------------------------------------------------------------------------------------------------
319 voip_4 src+dst 12563 12299 264 0 0
320 --------------------------------------------------------------------------------------------------------------------
321 yoyo_4 src+dst 10472 10472 0 0 1
322 204.79.197.200 2
323 --------------------------------------------------------------------------------------------------------------------
324 </code></pre>
325
326 **Enable E-Mail notification via 'msmtp':**
327 To use the email notification you have to install & configure the package 'msmtp'.
328 Modify the file '/etc/msmtprc', e.g.:
329 <pre><code>
330 [...]
331 defaults
332 auth on
333 tls on
334 tls_certcheck off
335 timeout 5
336 syslog LOG_MAIL
337 [...]
338 account ban_notify
339 host smtp.gmail.com
340 port 587
341 from <address>k@gmail.com
342 user <gmail-user>
343 password <password>
344 </code></pre>
345 Finally enable E-Mail support and add a valid E-Mail receiver address in LuCI.
346
347 **Edit, add new banIP sources:**
348 The banIP blocklist sources are stored in an external, compressed JSON file '/etc/banip/banip.sources.gz'.
349 This file is directly parsed in LuCI and accessible via CLI, just call _/etc/init.d/banip list_.
350
351 To add new or edit existing sources extract the compressed JSON file _gunzip /etc/banip/banip.sources.gz_.
352 A valid JSON source object contains the following required information, e.g.:
353 <pre><code>
354 [...]
355 "tor": {
356 "url_4": "https://lists.fissionrelays.net/tor/exits-ipv4.txt",
357 "url_6": "https://lists.fissionrelays.net/tor/exits-ipv6.txt",
358 "rule_4": "/^(([0-9]{1,3}\\.){3}(1?[0-9][0-9]?|2[0-4][0-9]|25[0-5])(\\/(1?[0-9]|2?[0-9]|3?[0-2]))?)([[:space:]]|$)/{print \"add tor_4 \"$1}",
359 "rule_6": "/^(([0-9A-f]{0,4}:){1,7}[0-9A-f]{0,4}:?(\\/(1?[0-2][0-8]|[0-9][0-9]))?)([[:space:]]|$)/{print \"add tor_6 \"$1}",
360 "focus": "Tor exit nodes",
361 "descurl": "https://fissionrelays.net/lists"
362 },
363 [...]
364 </code></pre>
365 Add an unique object name, make the required changes to 'url_4', 'rule_4' (and/or 'url_6', 'rule_6'), 'focus' and 'descurl' and finally compress the changed JSON file _gzip /etc/banip/banip.sources.gz_ to use the new source object in banIP.
366 <b>Please note:</b> if you're going to add new sources on your own, please make a copy of the default file and work with that copy further on, cause the default will be overwritten with every banIP update. To reference your copy set the option 'ban\_srcarc' which points by default to '/etc/banip/banip.sources.gz'
367
368 ## Support
369 Please join the banIP discussion in this [forum thread](https://forum.openwrt.org/t/banip-support-thread/16985) or contact me by mail <dev@brenken.org>
370
371 ## Removal
372 * stop all banIP related services with _/etc/init.d/banip stop_
373 * optional: remove the banip package (_opkg remove banip_)
374
375 Have fun!
376 Dirk
Mirror of packages feed