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
2025-09-17 01:08:13 +02:00
parent 31a9568fd4
commit 00f4fcbc1c
4 changed files with 396 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -13,6 +13,7 @@ Setting up a personal homelab using a ThinkPad laptop running Arch Linux to move
 - [x] Self-hosted media server (Jellyfin)
 - [x] AI voice assistant (local TTS with Piper)
 - [x] Reverse proxy with nginx for multiple services
+- [x] Geographic IP blocking (geoip-shell whitelist)
 - [ ] Gradual migration from commercial cloud services

 ## Hardware
@@ -35,6 +36,7 @@ Setting up a personal homelab using a ThinkPad laptop running Arch Linux to move
 - ✅ Dotfiles management with yadm configured and merged
 - ✅ Development environment setup completed
 - ✅ Network domain setup (DuckDNS + Nginx reverse proxy + SSL)
+- ✅ Geographic IP blocking (geoip-shell whitelist for European countries)
 - ✅ Gitea Git server running (Docker container)
 - ✅ Copyparty file server with working WebDAV support
 - ✅ Jellyfin media server (Docker container)
@@ -60,6 +62,7 @@ homelab/
 ├── docs/                       # Detailed documentation
 │   ├── system-setup.md         # Arch Linux installation & config
 │   ├── network-security.md     # SSH, DNS, VPN, firewall
+│   ├── geoip-blocking.md       # Geographic IP blocking setup
 │   ├── services.md             # Self-hosted services
 │   ├── voice-assistant.md      # AI voice setup with Piper TTS
 │   └── troubleshooting/         # Solutions & troubleshooting guides
@@ -83,6 +86,7 @@ homelab/
 ### Documentation Files
 - **[docs/system-setup.md](docs/system-setup.md)** - Complete Arch Linux installation, TTY config, desktop setup
 - **[docs/network-security.md](docs/network-security.md)** - SSH hardening, DuckDNS, WireGuard VPN, firewall setup
+- **[docs/geoip-blocking.md](docs/geoip-blocking.md)** - Geographic IP blocking with geoip-shell whitelist
 - **[docs/services.md](docs/services.md)** - Self-hosted services: Git hosting, cloud storage, media server
 - **[docs/voice-assistant.md](docs/voice-assistant.md)** - AI voice assistant setup with Piper TTS and FastAPI
 - **[TODO.md](TODO.md)** - Centralized task list with progress tracking by category
@@ -93,5 +97,5 @@ homelab/
 - **System**: Arch Linux with XFCE desktop, ter-124b TTY font, Colemak layout
 - **Network**: Static IP (192.168.0.100), SSH port 2222, DuckDNS (ak-homelab.duckdns.org)
 - **Services**: Nginx reverse proxy, Gitea Git server, Copyparty file server with WebDAV, Jellyfin media server, AI voice assistant
- **Security**: SSH hardened, SSL certificates active, WebDAV authentication enabled
+- **Security**: SSH hardened, SSL certificates active, WebDAV authentication enabled, geographic IP blocking (geoip-shell whitelist)
 - **Development**: yadm dotfiles, tmux with temperature monitoring, zsh with proper history
--- a/TODO.md
+++ b/TODO.md
@@ -5,7 +5,7 @@
 - [x] SSH security hardening *(documented in network-security.md)*
  - [x] Figure out why laptop IP changes: Different eth ports have different MAC?
 - [x] Router port forwarding configuration
- [ ] !!! Set up geoblocking for SSH. Rest of SSH hardening already done.
+- [x] !!! Set up geoblocking for SSH. Rest of SSH hardening already done.
 - [ ] !!! Modify syncthing to sync the NAS folders where appropriate (e.g. Logseq)
 - [ ] Dockerize everything and use symlinks for dockerfiles (tired of constantly copying stuff over)
 - [ ] !!! IMPORTANT: Run setup scripts made by security reviewer agent
--- a/docs/geoip-blocking.md
+++ b/docs/geoip-blocking.md
@@ -0,0 +1,176 @@
+# GeoIP Blocking with geoip-shell
+
+## Overview
+
+**Tool:** geoip-shell v0.7.5
+**Repository:** https://github.com/friendly-bits/geoip-shell
+**Installation Method:** Manual from GitHub repository
+**Purpose:** Geographic IP blocking for enhanced security
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/friendly-bits/geoip-shell.git
+cd geoip-shell
+
+# Install the tool
+sudo make install
+```
+
+## Current Configuration
+
+### Core Settings
+- **Firewall Backend:** iptables
+- **IP Lists Source:** RIPE (Réseaux IP Européens)
+- **Network Interfaces:** All interfaces protected
+- **LAN Detection:** Automatic subnet detection enabled
+
+### Update Mechanism
+- **Cron Service:** ✅ Enabled
+- **Update Schedule:** Daily at 4:18 AM (`18 4 * * *`)
+- **Last Update:** September 17, 2025 at 00:57:41
+- **Persistence:** ✅ Enabled (survives reboots)
+- **Backup:** ✅ Automatic IP lists backup enabled
+
+## Inbound Geoblocking Configuration
+
+### Blocking Mode
+- **Type:** Whitelist (only specified countries allowed)
+- **IP Families:** IPv4 and IPv6 supported
+
+### 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
+
+### Protocol Coverage
+- **TCP:** All destination ports blocked for non-whitelisted countries
+- **UDP:** All destination ports blocked for non-whitelisted countries
+
+### Firewall Status
+- **IPv4 Chain:** ✅ Enabled and active
+- **IPv6 Chain:** ✅ Enabled and active
+- **Whitelist Rules:** ✅ Properly configured
+
+## Outbound Geoblocking
+- **Status:** Disabled (no outbound restrictions)
+
+## System Health
+- **Overall Status:** ✅ No problems detected
+- **Firewall Integration:** ✅ Working correctly
+- **Update Process:** ✅ Functioning properly
+
+## Security Impact
+
+### Protection Provided
+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 and Maintenance
+
+### Status Checking
+```bash
+geoip-shell status
+```
+
+### Log Locations
+- Main logs: `/var/log/geoip-shell.log`
+- System logs: `journalctl -u geoip-shell`
+
+### Update Verification
+- Automatic daily updates at 4:18 AM
+- Last update timestamp visible in status
+- Backup of IP lists maintained
+
+## Configuration Philosophy
+
+This setup follows a **whitelist approach** focusing on:
+- **Trusted Regions:** European countries plus select others
+- **Local Access:** Full LAN and Docker network access preserved
+- **Minimal Disruption:** Automatic detection of local networks
+- **Comprehensive Protection:** Both inbound directions covered
+
+## 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
+
+## Troubleshooting
+
+### Common Issues
+- **Service Not Starting:** Check `systemctl status geoip-shell`
+- **Rules Not Applied:** Verify iptables chains with `iptables -L`
+- **Update Failures:** Check `/var/log/geoip-shell.log`
+
+### Recovery Commands
+```bash
+# Restart service
+sudo systemctl restart geoip-shell
+
+# Reload configuration
+sudo geoip-shell reload
+
+# Check for issues
+sudo geoip-shell status
+```
+
+## Future Considerations
+
+### Potential Enhancements
+- **Custom Country Lists:** Add/remove countries based on threat intelligence
+- **Time-based Rules:** Different rules for different times of day
+- **Integration with Monitoring:** Alert on blocked country attempts
+- **Backup Configurations:** Document alternative configurations
+
+### Monitoring Improvements
+- **Log Analysis:** Regular review of blocked attempts by country
+- **Performance Impact:** Monitor system resource usage
+- **False Positives:** Track legitimate traffic being blocked
+
+## References
+
+- **Official Repository:** https://github.com/friendly-bits/geoip-shell
+- **Documentation:** Available in repository wiki
+- **Issue Tracking:** GitHub issues for bug reports and feature requests
--- a/docs/network-security.md
+++ b/docs/network-security.md
@@ -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