hoborg/homelab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
00f4fcbc1c132bee8a3399e853b02ffcd27d1814
homelab/docs/geoip-blocking.md
Arpad Krejczinger 00f4fcbc1c 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

5.8 KiB
Raw Blame History

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

# 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

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

# 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