山石防火墙 IP 封禁工具使用文档¶
基于山石网科 StoneOS 5.5R4+ RESTful API，使用 Python 实现的命令行封禁工具。
环境要求¶
| 要求 | 说明 |
|---|---|
| Python | 3.6 及以上 |
| 依赖库 | requests |
| 设备版本 | StoneOS 5.5R4+（密码 base64 编码要求） |
| 动态黑名单版本 | StoneOS 5.5R7 / 5.5R5F4 以上 |
安装依赖：
命令格式¶
参数说明¶
| 参数 | 是否必填 | 默认值 | 说明 |
|---|---|---|---|
--host | 是 | 无 | 防火墙管理 IP 地址 |
--user | 否 | hillstone | 登录用户名 |
--password | 是 | 无 | 登录密码 |
--block | 否 | 无 | 封禁 IP，支持同时指定多个，空格分隔 |
--unblock | 否 | 无 | 解封 IP，支持同时指定多个，空格分隔 |
--age | 否 | 0 | 封禁时长（秒）。0 表示永久封禁（静态黑名单） |
--csv | 否 | 无 | 从 CSV 文件批量导入封禁条目 |
--list | 否 | 无 | 查询当前动态和静态黑名单列表 |
封禁类型说明¶
| 类型 | 对应参数 | API 接口 | 重启后保留 | 说明 |
|---|---|---|---|---|
| 静态黑名单 | --block（不加 --age） | ptf-static-ip-blocklist | 是 | 永久封禁，需手动删除 |
| 动态黑名单 | --block --age <秒> | behavior_blockIp | 否 | 到期自动解封 |
使用示例¶
封禁操作¶
# 永久封禁单个 IP（静态黑名单）
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --block 1.2.3.4
# 永久封禁多个 IP（空格分隔）
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --block 1.2.3.4 5.6.7.8 9.10.11.12
# 临时封禁 1 小时（3600 秒）
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --block 1.2.3.4 --age 3600
# 临时封禁 24 小时（86400 秒）
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --block 1.2.3.4 --age 86400
# 使用自定义用户名登录并封禁
python3 hillstone_block.py --host 192.168.1.1 --user admin --password mypassword --block 1.2.3.4
解封操作¶
# 解封单个 IP
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --unblock 1.2.3.4
# 同时解封多个 IP
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --unblock 1.2.3.4 5.6.7.8
CSV 批量导入¶
# 从 CSV 文件批量导入
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --csv block_list.csv
CSV 文件格式（第一行为表头）：
ip,netmask,direct,type,age
1.2.3.4,32,src,dynamic,3600
5.6.7.0,24,src,static,
8.8.8.8,32,dst,dynamic,7200
CSV 字段说明：
| 字段 | 说明 | 可选值 |
|---|---|---|
ip | 要封禁的 IP 地址 | 合法 IPv4 地址 |
netmask | 子网掩码位数 | 1~32，单 IP 填 32 |
direct | 封禁方向 | src（源）/ dst（目标） |
type | 封禁类型 | dynamic（动态）/ static（静态） |
age | 动态封禁时长（秒） | 整数，静态封禁留空 |
查询黑名单¶
输出示例：
=== 动态黑名单 ===
1.2.3.4 方向:src 剩余:3456s
5.6.7.8 方向:src 剩余:120s
=== 静态黑名单 ===
10.10.10.0 方向:src 启用:1
8.8.8.8 方向:dst 启用:1
组合用法¶
# 同时封禁 + 查询结果
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --block 1.2.3.4 && \
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --list
# CSV 批量导入后查询
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --csv block_list.csv && \
python3 hillstone_block.py --host 192.168.1.1 --password hillstone --list
常见问题¶
Q：运行时提示 SSL 证书错误？ 正常现象，脚本已自动跳过 SSL 验证（verify=False），不影响使用。
Q：动态黑名单解封报错？ 动态黑名单到期后会自动删除，对已过期条目执行解封会返回失败，属于正常情况。
Q：设备使用 HTTP 而非 HTTPS？ 将脚本中所有 https:// 改为 http://，并删除 verify=False 参数。
Q：虚拟系统（VSYS）如何登录？ 用户名格式为 vsys名称\\admin，例如：
Q：单次最多能封禁多少条？ 设备限制单次最多 100 条，脚本已自动分批处理，无需手动拆分。