sjtrotter/opctl

# opctl **战术级、跨平台的网络配置工具。** 将 hostname、MAC、IP、DNS、防火墙和 NTP 的更改暂存到 JSON 文件中，与当前运行系统进行比对审查，然后按需提交给操作系统。 opctl 运行在 **Linux** 和 **Windows** 上，以**纯 Python 标准库**发布（零第三方 依赖），并在同一个核心上提供两个前端：单次执行的 POSIX CLI 和 交互式的 Cisco-IOS 风格 shell。 ## 为什么选择 opctl？ 大多数网络工具会在你输入更改时立即应用它们。而 opctl 采用 **暂存后提交** 模式： 1. **暂存** 你预期的配置到 `session.json` 中 —— 此时不会对硬件进行任何操作。 2. **审查** 你暂存的预期配置与真实 OS 状态之间的差异（每个字段会标记 `[ SYNC ]` / `[ DIFF ]`）。 3. **提交** 整个配置文件，在一个明确的步骤中将其应用到操作系统。 这使得更改具有可审查性，并在提交时保证原子性，而不是零散地应用 —— 当你 要重新配置主机的网络状态，并希望在触发更改前查看完整的差异时，这非常有用。 ## 功能 - **Hostname** 管理。 - **基于接口** 的配置：MAC 地址（包括 `random`），静态 IPv4/IPv6 或 DHCP，DNS， 以及管理层面的启用(up)/禁用(down)。 - **基于区域的出口防火墙** —— `trusted` / `target` (允许) 和 `excluded` (拒绝，优先级最高)， 使用真正的子集代数（排除 + CIDR 合并）为 IPv4 和 IPv6 进行编译，并支持可选的 `IP:PORT` 覆盖。 - **NTP** 启用/禁用。 - **跨平台** 自动检测 provider —— 它使用你的主机实际拥有的任何网络堆栈 （Linux 上的 NetworkManager/iproute2/net-tools 和 firewalld/ufw/iptables；Windows 上的 PowerShell/netsh/wmic）。 - 提交前进行 **暂存与实时状态对比**。 - **零依赖**，无需构建步骤，使用单一的 `session.json` 存储所有暂存状态。 ## 安装 要求 **Python 3.8+**。工具本身没有其他要求。 ``` # 从此 repo 的一个 clone 开始： pip install -e . # installs the `opctl` console command # …或者直接运行而不进行安装： python opctl.py ``` ## 快速开始 ### 交互式 shell 运行不带参数的 `opctl` 即可进入模态 shell。提示符会显示你当前的模式。 ``` $ opctl opctl# configure opctl(config)# system opctl(config-system)# hostname recon-01 # stage the hostname opctl(config-system)# exit opctl(config)# interface eth0 # configure NIC eth0 opctl(config-if:eth0)# mode static opctl(config-if:eth0)# ip 10.10.0.5/24 opctl(config-if:eth0)# mac random # spoof a random MAC opctl(config-if:eth0)# dns 1.1.1.1 9.9.9.9 opctl(config-if:eth0)# exit opctl(config)# policy # global firewall zones opctl(config-policy)# target 192.168.50.0/24 # allow the objective network opctl(config-policy)# excluded 192.168.50.13 # ...except this host (deny wins) opctl(config-policy)# exit opctl(config)# exit opctl# show # diff staged config against the live system opctl# execute # commit everything to the OS (needs root/admin) ``` 每个设置在暂存时都会打印确认信息（上文已省略）。导航：`configure` 进入 配置模式；`system` / `ntp` / `policy` / `interface ` 进入 子模式；`exit`（或 `quit`）返回上一级，而在根目录下它会退出 shell （Ctrl+D 也可以）。命令接受唯一的缩写前缀（例如 `conf`, `int eth0`）。在任何模式下输入 `help` 可查看该模式下有效的命令。 ### 单次执行 POSIX CLI 相同的操作也可以通过非交互方式完成： ``` opctl system --hostname recon-01 # stage the hostname opctl interface eth0 --mode static --ip 10.10.0.5/24 --mac random # configure a NIC opctl policy --target 192.168.50.0/24 --excluded 192.168.50.13 # global firewall zones opctl show # show the staged-vs-live diff opctl execute # commit to the OS (run with sudo / as admin) ``` ## 组织架构 opctl 采用分层/六边形（端口和适配器）设计；领域层没有外部依赖。 ``` Front-ends POSIX CLI + interactive shell (both generated from one command schema) │ ▼ Use cases load staged state → mutate → save, or drive the OS backend ├─────────────► JSON repository ↔ session.json (staged state) └─────────────► OS backend → providers → OS CLI tools (live system) ▲ Domain models (profile + firewall policy), IP parser, ports, exceptions ``` 每个 OS **backend** 都是一个轻量级的 facade，会自动解析三个 **provider** —— 分别对应 系统、网络和防火墙功能 —— 并选择主机上第一个可用的工具（或你明确指定的工具）： | 功能 | Linux (自动检测顺序) | Windows (自动检测顺序) | |---|---|---| | hostname | `hostnamectl` → `hostname` | PowerShell → `wmic` | | network | `nmcli` → `iproute2` → `ifconfig` | PowerShell → `netsh` | | firewall | `firewalld` → `ufw` → `iptables` | PowerShell → `netsh` | 通过在 `session.json` 中设置 `backend` 块来指定 provider（例如 `"firewall_provider": "iptables"`）；默认的 `"auto"` 会进行自动检测。 ## `session.json` 文件 所有暂存的状态都保存在一个单一的 JSON 文件中，该文件的路径是相对于你运行 opctl 的目录进行解析的 （并且会被 gitignore 忽略 —— 因为它是针对特定机器的、临时性的）。其结构如下： ``` { "system": { "hostname": "recon-01", "unmanaged_policy": "ignore" }, "network": { "global_dns": [], "default_gateway": "", "ipv6_enabled": true, "ip_forwarding": false }, "ntp": { "enabled": false, "servers": [] }, "interfaces": { "eth0": { "name": "eth0", "enabled": true, "mac_address": "", "randomize_mac": true, "mode": "static", "ip_addresses": ["10.10.0.5/24"], "gateway": "", "dns_servers": ["1.1.1.1"], "dhcp_ignore_dns": false, "dhcp_ignore_gw": false, "policy": { "trusted": [], "target": [], "excluded": [] } } }, "global_policy": { "trusted": [], "target": [], "excluded": [] }, "backend": { "firewall_provider": "auto", "network_provider": "auto", "system_provider": "auto" } } ``` 防火墙 **zones** 存在于 `global_policy`（主机范围）和每个接口的 `policy` （绑定到该 NIC）中。在 `policy` 或 `interface` 模式下使用 `trusted` / `target` / `excluded` 命令来设置它们（例如 `target 192.168.50.0/24`）。每个命令都支持 IPv4 的 CIDR、通配符 (`192.168.*.10`) 和 范围符 (`192.168.0-5.10`) 表示法，IPv6 的严格 CIDR，以及用于端口范围规则的 `IP:PORT`。在提交时，`excluded` 会从 `trusted`/`target` 中减去，结果会被折叠 成最少的 CIDR 集合。 ## 开发 ``` pip install -e . # editable install pip install pytest # the test suite's only extra dependency python -m pytest tests/ # run everything python -m pytest tests/test_policy.py # one file python -m pytest tests/test_policy.py::TestOpPolicy::test_compile_with_exclusions # one test ``` 没有构建/编译步骤。添加命令或标志只需对 `opctl/command_schema.py` 进行一次编辑 —— 两个前端都是根据该 schema 生成的。 ## 项目状态 opctl 目前处于 **v0.1.0** 版本，正在积极开发中。目前在 **交互式 shell** 和 **单次执行 POSIX CLI** 上可用的功能包括：hostname、基于接口的 MAC/IP/mode/DNS/up-down、NTP 启用/禁用，以及防火墙区域规则（`trusted`/`target`/`excluded`，支持全局和基于接口的设置）； 暂存与实时状态对比（`show`）；以及一个事务性的 `execute`，它可以提交给 Linux 和 Windows 主机，并在失败时回滚。目前正在完善的功能： - **导入已保存的 playbook** (`ImportConfigUseCase`) 已实现，但尚未连接到 命令。 - 在特定于 `iptables` 的 provider 下，IPv6 防火墙是一个空操作（请使用 `firewalld`/`ufw` 进行 IPv6 拦截）。 - NTP 目前仅支持暂存启用/禁用；设置服务器/池列表的功能正在开发中。 ## 许可证 基于 **GNU GPLv3** 协议分发。请参阅 [`LICENSE`](LICENSE)。 ## 作者 Stephen Trotter —

标签：Awesome, Homebrew安装, Python, 无后门, 系统管理, 网络配置, 运维工具, 逆向工具, 防火墙管理