docs: Add comprehensive geoip-shell and permanent ban documentation
- Add docs/geoip-blocking.md with complete geoip-shell setup documentation - Update README.md to include geoip blocking in goals, status, and documentation structure - Update docs/network-security.md with geoip blocking and permanent ban sections - Mark geoip blocking task as completed in TODO.md - Document permanent-ban-repeat-offenders.sh script and its cron job
This commit is contained in:
@@ -366,6 +366,220 @@ sudo fail2ban-client status sshd
|
||||
sudo fail2ban-client get sshd banned
|
||||
```
|
||||
|
||||
## Geographic IP Blocking with geoip-shell
|
||||
|
||||
### Overview
|
||||
**Status:** ✅ **Implemented** - Whitelist mode protecting all interfaces
|
||||
|
||||
**Tool:** geoip-shell v0.7.5
|
||||
**Repository:** https://github.com/friendly-bits/geoip-shell
|
||||
**Purpose:** Geographic IP blocking for enhanced security
|
||||
|
||||
### Current Configuration
|
||||
- **Firewall Backend:** iptables
|
||||
- **IP Lists Source:** RIPE (Réseaux IP Européens)
|
||||
- **Network Interfaces:** All interfaces protected
|
||||
- **LAN Detection:** Automatic subnet detection enabled
|
||||
- **Mode:** Whitelist (only specified countries allowed)
|
||||
- **IP Families:** IPv4 and IPv6 supported
|
||||
- **Update Schedule:** Daily at 4:18 AM
|
||||
- **Last Update:** September 17, 2025 at 00:57:41
|
||||
|
||||
### Whitelisted Countries
|
||||
```
|
||||
AL (Albania), AD (Andorra), AM (Armenia), AT (Austria), AZ (Azerbaijan)
|
||||
BY (Belarus), BE (Belgium), BA (Bosnia and Herzegovina), BG (Bulgaria)
|
||||
HR (Croatia), CY (Cyprus), CZ (Czech Republic), DK (Denmark)
|
||||
EE (Estonia), FO (Faroe Islands), FI (Finland), FR (France)
|
||||
GE (Georgia), DE (Germany), GI (Gibraltar), GR (Greece)
|
||||
GG (Guernsey), HU (Hungary), IS (Iceland), IE (Ireland)
|
||||
IM (Isle of Man), IT (Italy), JE (Jersey), KZ (Kazakhstan)
|
||||
LV (Latvia), LI (Liechtenstein), LT (Lithuania), LU (Luxembourg)
|
||||
MT (Malta), MD (Moldova), MC (Monaco), ME (Montenegro)
|
||||
NL (Netherlands), MK (North Macedonia), NO (Norway), PL (Poland)
|
||||
PT (Portugal), RO (Romania), RU (Russia), SM (San Marino)
|
||||
RS (Serbia), SK (Slovakia), SI (Slovenia), ES (Spain)
|
||||
SE (Sweden), CH (Switzerland), TR (Turkey), UA (Ukraine)
|
||||
GB (United Kingdom), VA (Vatican City)
|
||||
```
|
||||
|
||||
### Network Exceptions (Always Allowed)
|
||||
**IPv4 Networks:**
|
||||
- `172.18.0.0/16` - Docker network
|
||||
- `172.17.0.0/16` - Docker network
|
||||
- `169.254.0.0/16` - Link-local addresses
|
||||
- `192.168.0.0/24` - Local LAN
|
||||
- `172.20.0.0/16` - Docker network
|
||||
- `172.19.0.0/16` - Docker network
|
||||
|
||||
**IPv6 Networks:**
|
||||
- `fdaa:bbcc:ddee::/64` - Custom network
|
||||
- `fe80::/10` - Link-local addresses
|
||||
|
||||
### Security Impact
|
||||
1. **Geographic Blocking:** Blocks all traffic from countries not in whitelist
|
||||
2. **Comprehensive Coverage:** Both IPv4 and IPv6 protection
|
||||
3. **Full Protocol Coverage:** TCP and UDP traffic controlled
|
||||
4. **Network Awareness:** Automatically detects and allows local networks
|
||||
5. **Persistence:** Rules survive system reboots
|
||||
6. **Automatic Updates:** IP lists updated daily
|
||||
|
||||
### Integration with Existing Security
|
||||
- **Complements fail2ban:** Provides geographic layer above intrusion detection
|
||||
- **Works with UFW:** Uses iptables backend compatible with UFW
|
||||
- **Docker Compatible:** Automatically allows Docker networks
|
||||
- **LAN Friendly:** Preserves local network access
|
||||
|
||||
### Monitoring
|
||||
```bash
|
||||
# Check geoip-shell status
|
||||
geoip-shell status
|
||||
|
||||
# View logs
|
||||
journalctl -u geoip-shell
|
||||
tail -f /var/log/geoip-shell.log
|
||||
```
|
||||
|
||||
### Manual Setup Process
|
||||
The tool was installed manually with interactive prompts rather than scripted installation due to security considerations. Key decisions made during setup:
|
||||
|
||||
1. **Whitelist Mode:** Chosen over blacklist for better control
|
||||
2. **European Focus:** Primary whitelist consists of European countries
|
||||
3. **Network Exceptions:** Docker and LAN networks automatically detected
|
||||
4. **Dual Stack:** Both IPv4 and IPv6 protection enabled
|
||||
5. **Full Protocol Coverage:** TCP and UDP both protected
|
||||
|
||||
### Detailed Documentation
|
||||
For complete setup details, see **[docs/geoip-blocking.md](docs/geoip-blocking.md)**
|
||||
|
||||
## Permanent Ban System for Repeat Offenders
|
||||
|
||||
### Overview
|
||||
**Status:** ✅ **Implemented** - Automated permanent banning of persistent attackers
|
||||
|
||||
**Script:** `scripts/permanent-ban-repeat-offenders.sh`
|
||||
**Purpose:** Automatically identify and permanently ban IPs that have been banned by fail2ban more than a threshold number of times
|
||||
|
||||
### How It Works
|
||||
|
||||
#### Detection Logic
|
||||
1. **Log Analysis:** Scans `/var/log/fail2ban.log*` for ban entries
|
||||
2. **IP Extraction:** Extracts IP addresses from ban log entries
|
||||
3. **Frequency Counting:** Counts how many times each IP has been banned
|
||||
4. **Threshold Check:** Identifies IPs banned more than the threshold (4 times)
|
||||
|
||||
#### Permanent Banning Process
|
||||
For each repeat offender:
|
||||
1. **Country Lookup:** Uses `whois` to determine the country of origin
|
||||
2. **Banlist Update:** Adds IP to `/etc/fail2ban/permanent-banlist.conf`
|
||||
3. **Firewall Rule:** Creates permanent iptables DROP rule
|
||||
4. **Persistence:** Saves iptables rules to `/etc/iptables/iptables.rules`
|
||||
5. **Service Reload:** Reloads fail2ban to recognize the updated banlist
|
||||
|
||||
### Configuration
|
||||
|
||||
#### Threshold Settings
|
||||
```bash
|
||||
THRESHOLD=4 # Ban after 4 fail2ban bans
|
||||
```
|
||||
|
||||
#### File Locations
|
||||
- **Log File:** `/var/log/permanent-ban.log`
|
||||
- **Banlist:** `/etc/fail2ban/permanent-banlist.conf`
|
||||
- **Iptables Rules:** `/etc/iptables/iptables.rules`
|
||||
|
||||
#### Cron Schedule
|
||||
- **Frequency:** Every 6 hours (`0 */6 * * *`)
|
||||
- **User:** root
|
||||
- **Command:** `/home/hoborg/homelab/scripts/permanent-ban-repeat-offenders.sh`
|
||||
|
||||
### Security Benefits
|
||||
|
||||
#### Multi-Layer Protection
|
||||
1. **fail2ban:** Temporary bans for suspicious activity
|
||||
2. **Permanent Bans:** Long-term blocking of persistent attackers
|
||||
3. **Geographic Blocking:** Country-level filtering via geoip-shell
|
||||
4. **Network-Level:** iptables rules at the firewall level
|
||||
|
||||
#### Attack Prevention
|
||||
- **Brute Force:** Blocks IPs that repeatedly attempt attacks
|
||||
- **Botnets:** Prevents automated attacks from compromised hosts
|
||||
- **Persistence:** Maintains bans across system reboots
|
||||
- **Resource Protection:** Reduces server load from repeat offenders
|
||||
|
||||
### Monitoring and Maintenance
|
||||
|
||||
#### Log Analysis
|
||||
```bash
|
||||
# View permanent ban activity
|
||||
tail -f /var/log/permanent-ban.log
|
||||
|
||||
# Check current permanent bans
|
||||
cat /etc/fail2ban/permanent-banlist.conf
|
||||
|
||||
# View iptables permanent rules
|
||||
iptables -L | grep DROP
|
||||
```
|
||||
|
||||
#### Manual Execution
|
||||
```bash
|
||||
# Run the script manually (requires root)
|
||||
sudo /home/hoborg/homelab/scripts/permanent-ban-repeat-offenders.sh
|
||||
```
|
||||
|
||||
#### Unban Procedure
|
||||
To manually unban a permanently banned IP:
|
||||
```bash
|
||||
# Remove from banlist
|
||||
sudo sed -i "/^192\.168\.1\.100/d" /etc/fail2ban/permanent-banlist.conf
|
||||
|
||||
# Remove iptables rule (find the rule number first)
|
||||
sudo iptables -L --line-numbers | grep "192.168.1.100"
|
||||
sudo iptables -D INPUT <rule_number>
|
||||
|
||||
# Save iptables rules
|
||||
sudo iptables-save > /etc/iptables/iptables.rules
|
||||
|
||||
# Reload fail2ban
|
||||
sudo systemctl reload fail2ban
|
||||
```
|
||||
|
||||
### Integration with Security Stack
|
||||
|
||||
#### Complementary Tools
|
||||
- **fail2ban:** Provides temporary bans that feed into permanent ban detection
|
||||
- **geoip-shell:** Geographic blocking at the network level
|
||||
- **UFW:** Additional firewall layer
|
||||
- **SSH Hardening:** Reduces initial attack surface
|
||||
|
||||
#### Workflow
|
||||
```
|
||||
Attack Attempt → fail2ban Detection → Temporary Ban → Repeat Offense → Permanent Ban → Geographic Block
|
||||
```
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
#### Common Issues
|
||||
- **Script Not Running:** Check cron job configuration
|
||||
- **Permission Errors:** Ensure script is executable and paths are correct
|
||||
- **whois Failures:** Some IPs may not return country information
|
||||
- **iptables-save Issues:** Check if iptables-persistent is installed
|
||||
|
||||
#### Diagnostic Commands
|
||||
```bash
|
||||
# Check cron service
|
||||
sudo systemctl status cron
|
||||
|
||||
# Test script manually
|
||||
sudo bash -x /home/hoborg/homelab/scripts/permanent-ban-repeat-offenders.sh
|
||||
|
||||
# Verify iptables rules
|
||||
sudo iptables -L -n | grep DROP
|
||||
|
||||
# Check fail2ban integration
|
||||
sudo fail2ban-client status
|
||||
```
|
||||
|
||||
## Router Configuration
|
||||
|
||||
### Port Forwarding
|
||||
|
||||
Reference in New Issue
Block a user