monjaka/netsudo
GitHub: monjaka/netsudo
netsudo 是一个类 sudo 的 CLI 工具，用于在 pfSense 防火墙上授予临时、可审计的跨网段访问权限。
Stars: 0 | Forks: 0
# netsudo
`netsudo` 是一个类似于 sudo 的 CLI，用于跨 pfSense 防火墙边界进行临时的、可审计的访问。
它专为分段式家庭实验室和小型实验室设计，在这些场景中，防火墙策略默认应保持关闭，但受信任的管理员有时需要短期访问某个 VLAN、主机或服务。
## 功能
- 在较短的时间窗口内授予特定源 IP 的访问权限。
- 通过强制使用具有最大持续时间的命名配置文件。
- 更新 pfSense 别名和固定的防火墙规则，而不是禁用防火墙策略。
- 记录每一次授权、撤销和过期。
- 通过移除源 IP 并终止匹配的防火墙状态来撤销访问。
- 默认通过 SSH 连接到 pfSense，因此防火墙上不需要 REST API 包。
## 示例
```
netsudo allow admin --for 20m --reason "fix Wazuh agent"
netsudo allow service-jellyfin --for 2h
netsudo status
netsudo revoke last
netsudo revoke all
```
`allow all` 并不会禁用防火墙。它的意思是“在有限的时间内，允许此源 IP 访问由 `all` 配置文件定义的目标和端口。”
## 模型
pfSense 需要进行一次性配置，包括：
- 每个配置文件一个源别名，例如 `NETSUDO_ADMIN_SRC`
- 每个配置文件一个目标别名，例如 `NETSUDO_ADMIN_DST`
- 可选的端口别名
- 引用这些别名的放行规则
默认情况下，源别名包含一个占位 IP。授权操作会用该配置文件当前活跃的源 IP 替换别名内容，并重新加载 pfSense 过滤器。过期/撤销操作会再次移除该 IP。
当使用 `--source` 时，`netsudo` 会在请求的时间窗口内动态授予该源 IP 访问权限。配置文件可以设置 `sources` 来限制允许的源 IP。
当使用 `--destination` 时，`netsudo` 会创建临时的、特定于授权的别名和规则，而不是将源 IP 添加到广泛的配置文件源别名中。这样可以将授权限制在请求的主机/CIDR 范围内，并在撤销或过期时移除这些对象。
## 安装说明
### Linux
`netsudo` 支持 Python 3.10 及更新版本。
1. 安装必需的系统包。
Fedora：
sudo dnf install -y git python3 python3-pip openssh-clients
Ubuntu/Debian：
sudo apt update
sudo apt install -y git python3 python3-pip openssh-client
2. 克隆仓库：
git clone https://github.com/monjaka/netsudo.git
cd netsudo
3. 为您的用户安装 `netsudo`：
python3 -m pip install --user .
在克隆的 `netsudo` 目录内运行此命令。这是目前标准的安装方法。
在较新的 Ubuntu/Debian 版本上，如果 pip 退出并提示 `externally-managed-environment`，请使用：
python3 -m pip install --user --break-system-packages .
这仍然会将 `netsudo` 安装在您的用户 site-packages 中；它不会安装 pfSense 凭据或更改防火墙状态。
4. 检查已安装的命令：
netsudo --version
5. 运行安装程序。这将创建 `netsudo.toml` 并可以设置 SSH 密钥：
netsudo-install --config ./netsudo.toml
安装程序会写入本地配置文件。如果它询问是否现在运行设置，请回答 `no`，除非您准备好立即将生成的配置应用到 pfSense。
6. 检查 `netsudo.toml` 并为您的网络编辑配置文件的源、目标、端口和持续时间。
7. 如果您在安装程序中跳过了设置，或者在设置后更改了 `netsudo.toml`，请将配置应用到 pfSense：
netsudo-install --config ./netsudo.toml --setup-only
这与安装程序可以为您运行的设置操作相同。它会读取 `netsudo.toml`，将辅助脚本复制到 pfSense，上传根据该文件渲染的策略，并创建/更新 pfSense 别名和规则。它不会编辑 `netsudo.toml`。
### 在不安装的情况下通过检出的代码运行
仅用于开发或快速测试：
```
cd netsudo
python3 scripts/install.py
python3 -m netsudo.cli --version
```
## 快速入门
完成上述安装步骤后，`netsudo.toml` 应该已经存在，并且 pfSense 辅助脚本也应该已经安装好了。
授权访问：
```
netsudo allow admin --for 20m --reason "maintenance"
```
通过指定源 IP 为另一台设备授权访问：
```
netsudo allow admin --source 192.168.6.60 --for 20m --reason "workstation maintenance"
```
授权访问配置文件范围内更窄的目标：
```
netsudo allow admin --source 192.168.6.60 --destination 192.168.115.100 --for 20m --reason "check Wazuh"
netsudo allow admin --destination 192.168.9.0/24 --destination 192.168.115.100 --for 30m --reason "maintenance"
```
检查授权：
```
netsudo status
```
撤销：
```
netsudo revoke last
```
如果您之后更改了 `netsudo.toml`，请再次将更新后的策略应用到 pfSense：
```
netsudo-install --config ./netsudo.toml --setup-only
```
## 故障排除
如果 `netsudo allow` 提示目标不在配置文件允许的目标范围内，请在 `netsudo.toml` 中编辑该配置文件，并将 `destinations` 扩大到您愿意委托给该配置文件的边界。
您不需要列出每个 VLAN。使用更广泛的内部 CIDR，然后通过 `--destination` 保持每次授权的精确范围：
```
[profiles.admin]
sources = ["192.168.0.0/16"]
destinations = ["192.168.0.0/16"]
```
在该范围内，此授权将被接受，因为 `192.168.6.60` 和 `192.168.115.100` 都位于配置的边界内：
```
netsudo allow admin --source 192.168.6.60 --destination 192.168.115.100 --for 20m --reason "check Wazuh"
```
然后将配置更改应用到 pfSense：
```
netsudo-install --config ./netsudo.toml --setup-only
```
默认情况下，`interfaces = ["auto"]` 使 pfSense 辅助脚本根据请求的源 IP 和防火墙自身的接口网络解析规则位置。例如，从 `192.168.6.60` 发起的访问会解析到子网包含 `192.168.6.60` 的 pfSense 接口。仅在自动解析无法处理特殊情况时，才使用显式的接口名称。
## 安全说明
使用专门的 pfSense SSH 用户。
不要将 pfSense 管理员密码存储在 `netsudo.toml` 中。预期的模型是使用本地 `sudo` 加上专用的 SSH 密钥。
对于设置了 `require_sudo = true` 的配置文件，请以普通用户身份运行 `netsudo allow ...`。`netsudo` 会在需要时自行调用本地 `sudo`。这避免了由于 `pip --user` 将命令安装在 `~/.local/bin` 下而导致的常见 `sudo: netsudo: command not found` 问题。
安装程序可以生成专用的 SSH 密钥，并将公钥安装到 pfSense 上。它可能会通过 `ssh` 或 `ssh-copy-id` 提示输入 pfSense 账户密码，但它不会存储该密码。
设置完成后，安装程序可以通过强制命令和禁用转发/PTY 选项来限制 pfSense `authorized_keys` 中的专用密钥。受限密钥旨在用于日常的 `allow`、`status`、`revoke` 和 `prune` 操作。诸如复制新辅助脚本或策略之类的引导任务仍然需要不受限制的管理员 SSH 路径。
如果您在设置期间没有限制 SSH 密钥，您可以稍后进行此操作：
```
netsudo-install --config ./netsudo.toml --restrict-key-only
```
卸载本地 netsudo 配置/密钥文件，并可选择从 pfSense 中移除辅助脚本文件：
```
netsudo-install --config ./netsudo.toml --uninstall
python3 -m pip uninstall netsudo
```
卸载流程在删除本地文件或 pfSense 辅助脚本文件之前会进行提示。它不会从 `config.xml` 中移除 pfSense 别名/规则；如果您想要完全干净的防火墙配置，请在 pfSense 中移除 `NETSUDO_*` 防火墙对象。
有关操作指南，请参阅 [SECURITY.md](SECURITY.md) 和 [docs/security-model.md](docs/security-model.md)。
## 常用命令
```
netsudo render-policy --config ./netsudo.toml
netsudo install-helper --config ./netsudo.toml
netsudo-install --config ./netsudo.toml --setup-only
netsudo allow admin --for 20m --reason "maintenance"
netsudo allow admin --source 192.168.6.60 --destination 192.168.115.100 --for 20m --reason "maintenance"
netsudo status
netsudo revoke last
netsudo prune
```
## 当前状态
这是一个 alpha 版本的实现。在生产网络中依赖它之前，请先检查生成的 pfSense 规则。
标签：Docker 部署, pfSense, Streamlit, 内存分配, 文档结构分析, 特权管理, 网络运维, 访问控制, 逆向工具, 防火墙管理