# GeoIP Firewall

**Repository Path**: dws9088/geo-ip-firewall

## Basic Information

- **Project Name**: GeoIP Firewall
- **Description**: GeoIP Firewall - 基于国家IP段的防火墙管理工具。设置国家IP白名单，完美解决国外IP经常扫描、恶意访问等痛点。
是一个跨平台的防火墙管理程序，通过自动下载指定国家的IP地址段，配置系统防火墙仅允许来自允许国家的流量访问你的服务器，同时支持白名单IP和端口。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GeoIP Firewall - 基于国家IP段的防火墙管理工具

[![Python Version](https://img.shields.io/badge/python-3.6+-blue.svg)](https://python.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows-lightgrey.svg)]()

GeoIP Firewall 是一个跨平台的防火墙管理程序，通过自动下载指定国家的IP地址段，配置系统防火墙仅允许来自允许国家的流量访问你的服务器。它特别适合需要限制境外访问、保护服务器免受国际扫描和攻击的场景。

## ✨ 特性

- 🌍 **基于国家IP段** – 默认仅允许中国IP访问，可自定义允许的国家列表（ISO代码）
- 🔄 **增量更新** – 仅添加新增的IP段、删除过期的IP段，避免全量清空风险，即使更新中断也不会导致规则空窗期
- 🕒 **定时窗口** – 可设置在凌晨低峰期自动更新，仅更新国家IP段，白名单规则保持不变
- 🛡️ **安全设计** – 白名单IP和端口仅在程序启动时同步一次（增量添加/删除），更新失败不影响现有防火墙规则；支持试运行模式（dry-run）
- 🔁 **命令重试** – 防火墙命令执行失败时自动重试（重试次数可配置），提高更新成功率
- 💻 **跨平台** – 支持 Linux（iptables / nftables）和 Windows 系统（Windows 采用全量模式，适合单条规则管理）
- 📦 **零依赖** – 纯Python标准库实现，无需安装第三方包
- 🔧 **简单易用** – 提供无参数常驻运行、`--reset` 恢复默认策略
- 📝 **完整日志** – 记录所有操作和错误，便于排查

## 🚀 快速开始

### 1. 下载程序

```bash
git clone https://github.com/yourname/geoip-firewall.git
cd geoip-firewall
# 或者直接下载单个文件
wget https://raw.githubusercontent.com/yourname/geoip-firewall/main/geoip_f.py
```

### 2. 首次运行（生成配置文件）

```bash
# Linux
sudo python3 geoip_f.py

# Windows（以管理员身份运行CMD）
python geoip_f.py
```

程序会自动生成 `config.json` 配置文件并退出。

### 3. 编辑配置文件

修改 `config.json`，**务必添加你的当前公网IP到白名单**，否则规则生效后你会立即断开连接。

```json
{
    "allowed_countries": ["CN"],
    "whitelist_ips": [
        "127.0.0.0/8",
        "10.0.0.0/8",
        "172.16.0.0/12",
        "192.168.0.0/16",
        "你的公网IP/32"
    ],
    "whitelist_ports": [22, 3389],
    "update_interval_days": 7,
    "update_window_start": 0,
    "update_window_end": 5,
    "firewall_backend": "auto",
    "dry_run": false,
    "command_retries": 3
}
```

### 4. 应用防火墙规则并持续运行

```bash
sudo python3 geoip_f.py
```

规则生效后，只有来自中国IP（以及白名单中的IP）的流量可以访问你的服务器。程序将进入后台定时更新模式。

## 📖 详细使用说明

### 命令行参数

| 参数 | 说明 |
|------|------|
| 无参数 | 立即执行一次国家IP段更新并应用规则，然后进入定时循环（按配置间隔和窗口自动更新） |
| `--reset` | 清除本程序添加的所有规则，恢复防火墙为默认允许所有入站流量 |

### 常用操作

```bash
# 立即应用规则并持续运行（首次运行或手动触发更新后进入定时任务）
sudo python3 geoip_f.py

# 取消所有拦截，恢复防火墙为允许所有入站
sudo python3 geoip_f.py --reset

# 试运行（不实际修改防火墙，仅打印要执行的命令）
# 编辑 config.json 设置 "dry_run": true，然后运行
sudo python3 geoip_f.py
```

### 配置项详解

| 配置项 | 类型 | 说明 |
|--------|------|------|
| `allowed_countries` | 列表 | 允许访问的国家代码（ISO 3166-1 alpha-2），如 `["CN","HK"]` |
| `whitelist_ips` | 列表 | 额外放行的IPv4/IPv6 CIDR地址段（仅在程序启动时同步一次） |
| `whitelist_ports` | 列表 | 放行的TCP端口（仅在程序启动时同步一次） |
| `update_interval_days` | 整数 | 自动更新国家IP段间隔（天），默认7 |
| `update_window_start` | 整数 | 更新窗口开始小时（0-23），默认0 |
| `update_window_end` | 整数 | 更新窗口结束小时（不包含），默认5 |
| `data_sources` | 字典 | IP段数据源（一般无需修改） |
| `firewall_backend` | 字符串 | 防火墙后端：`auto`/`iptables`/`nftables`/`windows` |
| `dry_run` | 布尔 | 试运行模式，`true` 时不实际修改防火墙 |
| `command_retries` | 整数 | 防火墙命令执行失败时的重试次数，默认3 |

### 验证规则是否生效

#### Linux (iptables)
```bash
iptables -L INPUT -n --line-numbers
iptables -L GEOIP_ALLOW -n | wc -l   # 应显示数千条规则
```
期望输出：
```
Chain INPUT (policy DROP)
num  target     prot opt source         destination
1    ACCEPT     all  --  0.0.0.0/0      0.0.0.0/0      state RELATED,ESTABLISHED
2    GEOIP_ALLOW all  --  0.0.0.0/0      0.0.0.0/0
```

#### Linux (nftables)
```bash
nft list ruleset
nft list set inet filter geoip_allowed   # 查看国家IP集合
```

#### Windows
```powershell
Get-NetFirewallRule -DisplayName "GeoIP_Allow_*" | Select DisplayName, Enabled, Direction, Action
```

## 🛠 常见问题

### 1. 运行后我自己无法连接服务器了？
- **原因**：未将自己的公网IP添加到 `whitelist_ips`。
- **解决**：通过VNC或带外管理执行 `sudo python3 geoip_f.py --reset` 恢复，然后正确配置白名单。

### 2. 增量更新有什么好处？
- 旧版本每次更新都会清空整条链再重建，存在规则空窗风险（可能把自己锁在外面）。新版本仅添加/删除变化的IP段，始终保持有效规则，更新中断也不会导致全部丢失。

### 3. 白名单IP或端口修改后为什么没生效？
- 白名单仅在程序启动时同步一次。修改 `whitelist_ips` 或 `whitelist_ports` 后需要**重启程序**才会生效。

### 4. 出现 `iptables: Chain already exists` 警告
- 正常现象，表示自定义链已存在，程序会直接使用，不影响功能。

### 5. 下载IP段失败（404）怎么办？
- 程序会自动重试最多 `command_retries` 次，每次间隔2秒。如果全部失败，本次更新取消，保留原有规则。请检查网络连接和 `ipdeny.com` 是否可访问。

### 6. 如何让某个端口（如80）允许全球访问？
- 当前程序设计为：只有来自允许国家IP的流量才能访问所有端口。如果需要无条件放行特定端口，可自行在 `apply_rules` 中在 INPUT 链直接添加 `-p tcp --dport 80 -j ACCEPT`。

### 7. 程序多次运行后规则重复怎么办？
- 新版本已自动清理重复规则（基于增删机制）。如果仍有重复，请先执行 `--reset` 清理，再重新运行。

### 8. Windows 下为什么还是全量替换？
- Windows 防火墙单条规则支持批量IP（最多800个），全量替换是原子操作，不会出现空窗期，因此保留原有设计。建议限制允许IP段总数在800以内。

## 📂 文件说明

| 文件 | 说明 |
|------|------|
| `geoip_f.py` | 主程序 |
| `config.json` | 用户配置文件（首次运行自动生成） |
| `geoip_firewall.log` | 运行日志 |
| `allowed_ips_state.txt` | 上次下载的IP段列表（自动维护，勿手动修改） |

## 🖥 部署为系统服务（可选）

### Linux systemd
创建 `/etc/systemd/system/geoip-firewall.service`：
```ini
[Unit]
Description=GeoIP Firewall Updater
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/python3 /opt/geoip_f/geoip_f.py
Restart=always
User=root

[Install]
WantedBy=multi-user.target
```
然后：
```bash
sudo systemctl daemon-reload
sudo systemctl enable geoip-firewall
sudo systemctl start geoip-firewall
```

### Windows 任务计划程序
- 创建任务，触发器设为“开机启动”
- 操作：启动 `python.exe`，参数为脚本路径
- 勾选“使用最高权限运行”

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)。

## 🙏 致谢

IP段数据来源于 [ipdeny.com](http://www.ipdeny.com)，感谢他们提供的免费服务。

---

**注意**：本程序仅基于IP地理位置进行过滤，不能作为唯一的安全手段。建议配合SSH密钥认证、应用层防火墙等综合防护措施。