INSTALL

WORK IN PROGRESS - not ready for public release yet


|\     /|(  ____ \(  ___ \      (  ____ \|\     /|\__   __/(  ____ \( \      (  __  \
| )   ( || (    \/| (   ) )     | (    \/| )   ( |   ) (   | (    \/| (      | (  \  )
| | _ | || (__    | (__/ /_____ | (_____ | (___) |   | |   | (__    | |      | |   ) |
| |( )| ||  __)   |  __ ((_____)(_____  )|  ___  |   | |   |  __)   | |      | |   | |
| || || || (      | (  \ \            ) || (   ) |   | |   | (      | |      | |   ) |
| () () || (____/\| )___) )     /\____) || )   ( |___) (___| (____/\| (____/\| (__/  )
(_______)(_______/|/ \___/      \_______)|/     \|\_______/(_______/(_______/(______/


Your first line of WEB defense against Internet bots, hacks and probes.

This is an IP-based blacklist of known sources for unsavory activity.  If you run a 
legit web site that has no business serving bad actors, this will come in very handy.

If you run a web site where you don't want automated scripts that aren't serving YOUR
purposes, this will come in vary handy.

If you don't need people using VPNs on your site (the lion's share of VPN activity are
attempts to hack/probe web sites), this will come in very handy.

Yea, yea, people say blacklists don't work.  They're wrong.  They do work.  Better than
most other systems. You can't hack what you can't reach, and if you're not doing any
web business with Chinese or Russian cloud providers, why TF should they have access?

See README for more details.

by Dark Phiber, 2022

Installation Instructions
=========================

There are two basic parts to this system:

1.  Setting up the blacklist
2.  Enabling the blacklist

For Part 1, there are several different shell scripts to run. 
First there is a script to create the list, then there are several
different scripts to add different types of IP ranges to the blacklist.

For Part 2, there is a script to configure iptables (your server's 
built in firewall) to act on the blacklist.  Part 2 is an ON/OFF switch.

Dependencies:  Web-Shield uses IPTABLES and IPSET.  Make sure you have
them installed on your system. (i.e. "apt-get ipset" or "yum install ipset")
Iptables should be installed as part of most Linux base kernels.  There may
be some modules that may need to be enabled that are beyond the scope of
this document.

NOTE: This is an IP-based blacklist, so there's always a possibility it could block legit traffic.
      Anybody who uses this should monitor their system to see if any legit activity is blocked.
      See README for more details

To date, this system has been tested on: Centos7, Linux Mint

E-mail me (dolson803@gmail.com) if you have tested it on other systems.

NOTE: There is a single command that runs everything AFTER you've done some basic configuration. 
      See the file START.web-shield.sh, but use this after you've decided everything is set
      the way you want.  Below is a breakdown of what it does.. At first you should run each
      command separately for testing.


Step 1: Set up the Blacklist
============================

Run 

sudo ./webshield-create-blacklist.sh    # This creates the IPset list (does not enable it yet)

Step 2: Edit and examine blacklist files
========================================

Then determine which IP blocks you're going to add to the list. 

There are several differnet lists of IP addresses.  Pick the ones
based on your particular configuration:

webblock-nonUS.lst    - This is the list of non-US based blacklists - the main list
webblock-US.lst       - This consists of mostly US-based blacklists
webblock-other.lst    - This consists of additional blocks that might be optional

CUSTOMIZING:  To customize any of the included blacklists, copy the file to another file of the same name, but with .me as the extension. 
              The system will use that file over the .lst file.  This way you can pull new updates without overwriting any customization.
              Repeat the process if you wish to use newer blacklist files but have custom rules - copy to *.me and edit.

You should determine whether or not any systems you want to access (log in) to your server may reside in any of these IP spaces and 
comment them out from the files.  (precede any IP line with a pound sign # and it will not be blacklisted)

OPTIONAL:  If you're familiar with iptables you could add a rule after the blacklist to specifically whitelist IP spaces, but I
           strongly recommend you examine each of the ipset*.lst files above and see if there are any netblocks that correspond
           to IP space you or your clients may be using.

NOTE: If you modify any of the .lst files (or any files), subsequent git pull commands will fail because of your local modifications.

Step 3: Add the blacklists you want to use
==========================================

Each major blacklist has a corresponding shell file that adds those blocks to the login-shield blacklist.  Run any or
all of the following scripts:

sudo ./blacklist-nonUS.sh
sudo ./blacklist-US.sh
sudo ./blacklist-other.sh

Each time you execute one of the above scripts, it will display how many IP blocks are added to the blacklist.   
You can also add the parameter "del" to remove them if you want to un-do your efforts.

Step 4: Copy/Edit the set-iptables.sh-config script
===================================================

cp webshield-set-iptables.sh-config webshield-set-iptables.sh

Inside the script: set-iptables.sh  contains a number of commented-out lines that allow you to pick which ports you want to apply
for the blacklist.  I've intentionally commented out the key port definition so the script cannot be run and executed until you edit
it, just to be safe.

Step 5: Enable the login-shield blacklist via Iptables
======================================================

Execute the script:
sudo ./webshield-set-iptables.sh

This will add the rules to LOG/DROP/REJECT the blacklisted IP ranges to the active iptables configuration.

NOTE:  This is not persistent unless you make it persistent.

You can also add the "del" parameter to disable the blacklist.  (Note that if you change any of the rule parameters after you've started the script, the delete
command may fail and you may have to manually delete the rules using "iptables -L INPUT --line-numbers" and "iptables -D INPUT <rule#>"

Future updates will probably make things easier to manage.

Other steps: How to handle updates
==================================

Check the file VERSION and UPGRADE_NOTE - for any special instructions regarding program changes.

If you want to set up login-shield to run automatically at boot time, that's beyond the scope of this guide.  But it's obviously not terribly difficult to do.

However, I will go into certain scenarios on how to update/maintain your login-shield system.

* Updates to firewalld/iptables 

If there are updates to core systems upon which Web-Shield relies, you may have to re-load the firewall/iptables rules.  For example if firewalld/iptables gets updated, when it restarts, if you haven't made provisions to re-enable login-shield, then you'll want to run the set-iptables.sh script - basically you can re-run this if there's been an update and the firewall should be back in place.   

Likewise if there's an update to ipset, it may not save the ipset list, and you'll want to re-run those scripts to re-initialized the list.

* Updates to Web-Shield

The most common updates to Web-Shield are going to be changes to the blacklist files.  To update the blacklists, regularly run "git pull" from the Web-Shield root installation.

To add new rules, simply re-run the ./blacklist-****.sh files.  Existing rules will be ignored and new rules will be added.   It is possible I may have removed some IP blacklists, but much more likely I simply added more.  I have yet to remove IP entries yet - but I do keep adding more large networks.  If I do remove some, I'll probably include a note to that effect in the update.


Additional Info & Statistics
============================

Once setup, there are a few scripts to generate stats on the system activity. 

The following reports are available:

attack_stats.sh
attack_cstats.sh

Either of these reports can be run with the optional parameter "lookup" which produces a report that provides a summary of the activity blocked.  attack_stats.sh does it per IP and attack_cstats.sh breaks it town by Class C IP blocks.

Here is an example:

./attack_cstats.sh lookup

|\     /|(  ____ \(  ___ \      (  ____ \|\     /|\__   __/(  ____ \( \      (  __  \
| )   ( || (    \/| (   ) )     | (    \/| )   ( |   ) (   | (    \/| (      | (  \  )
| | _ | || (__    | (__/ /_____ | (_____ | (___) |   | |   | (__    | |      | |   ) |
| |( )| ||  __)   |  __ ((_____)(_____  )|  ___  |   | |   |  __)   | |      | |   | |
| || || || (      | (  \ \            ) || (   ) |   | |   | (      | |      | |   ) |
| () () || (____/\| )___) )     /\____) || )   ( |___) (___| (____/\| (____/\| (__/  )
(_______)(_______/|/ \___/      \_______)|/     \|\_______/(_______/(_______/(______/
======= Attack Statistics based on current log files =======
======= Class C IP version =======
 Using: /var/log/messages

From: Apr 1 03:16:09
To  : Apr 14 10:12:01

-- Number of blocked attacks in log files  : 177063
-- Number of unique Class C IP attacking   : 1435
   Average # of attacks per Class C IP     : 123
   Percentage of attacks from top 50 IPs   : 94.3%
   Percentage of attacks from top 10 IPs   : 81.3%
   Percentage of attacks from top 5 IPs    : 76.9%

      Top 40:
Attacks:  Class C IP:  Country:
-------------------------------
 129029 185.191.171     CY
   2008 157.90.209      DE
   1812 114.119.136     SG
   1728 114.119.133     SG
[..]
    972 114.119.147     SG
    720 114.119.151     SG
    352 5.188.62        RU
    336 46.161.11       RU
    293 103.146.23      VN
    284 109.70.100      AT
    283 212.102.33      US
    280 88.164.137      FR
    264 62.102.148      SE
    241 209.190.81      US
    235 162.142.125     US
    191 185.220.101     DE
    167 74.119.119      US
[..]


Thanks for your support - and be sure to send any suggestions to dolson803@gmail.com but note that opening a case at Github may get faster responses.

- DP