omniproc/fwrqst

# fwrqst        一个抽象了针对 [tufin](https://www.tufin.com/de/tufin-orchestration-suite/securechange) 创建防火墙配置更改请求复杂性的库。 # Requests ## 验证 如果您使用的 _IDE_ 支持 `YAML` 或 `JSON` schema 验证，可以随意使用 _JSON-schema_ 进行输入验证和自动补全。 您可以使用 `fwrqst schema accessrequest` 获取您当前版本的 _fwrqst_ 所对应的访问请求 _JSON-schema_。本仓库的 [examples](/examples/) 文件夹中提供了示例。 您可以在 `YAML` 文件中使用文件内声明，通过类似这样的 modeline 将其指向 schema：`# yaml-language-server: $schema=./examples/tickets.schema.json`。 一些 _IDE_ 允许您将文件扩展名明确映射到 schema。例如，在安装了 [YAML 插件](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)的 VSCode 中，假设您当前的 VSCode 工作区设置为本仓库，请将以下内容添加到您的 VSCode `settings.json` 中并重启 VSCode： ``` { "yaml.schemas": { "${workspaceFolder}/examples/tickets.schema.json": [".tufin.yaml"] } } ``` 当您现在创建一个以 `.tufin.yaml` 结尾的新文件时，VSCode 将自动使用指定的 schema。请参见 [examples 文件夹](/examples/)。 # CLI 使用方法 安装带有 CLI 扩展的版本：`pip install fwrqst[cli]` ## `securechange` — Tufin SecureChange API 管理针对 Tufin SecureChange API 的访问请求工单。 ``` # 从 YAML 文件创建 ticket fwrqst securechange -u admin -p secret create -i tickets.yaml # 读取现有的 ticket fwrqst securechange -u admin -p secret read -t TICKET_ID # 取消挂起的 ticket fwrqst securechange -u admin -p secret cancel -t TICKET_ID ``` 连接参数（`--username`、`--password`、`--domain`、`--port`、`--cafile`、`--workflow`）也可以通过环境变量或 `settings.toml` 文件进行设置。参见[设置](#settings)。 ## `schema` — JSON schema 导出 ``` # 将 access request JSON schema 打印到 stdout fwrqst schema accessrequest # 将 schema 写入文件 fwrqst schema accessrequest -o tickets.schema.json ``` ## `config` — 配置管理 ``` # 显示当前设置 fwrqst config show # 查找磁盘上的设置文件位置 fwrqst config find # 设置特定设置（持久化到 settings.toml） fwrqst config set -k secure_change_port -v 8443 # 将设置重置为默认值 fwrqst config set -k secure_change_port ``` # API 使用方法 ``` from pathlib import Path from datetime import date, timedelta from fwrqst.io import load_tickets, dump_tickets from fwrqst.models.ticket import ( AccessRequestTicket, AccessRequest, IpEndpoint, DnsEndpoint, TcpService, ) from fwrqst.models.types import Priority, Action from fwrqst.api.securechange import AccessRequestService # 从 YAML 加载 tickets tickets = load_tickets(Path("examples/tickets.yaml")) # 以编程方式创建 ticket ticket = AccessRequestTicket( subject="Temporary HTTPS Access", workflow="Standard", priority=Priority.NORMAL, expiration=date.today() + timedelta(days=30), access_requests=[ AccessRequest( source_domain="Default", sources=[IpEndpoint(address="192.168.1.100", cidr=32)], destination_domain="Default", destinations=[DnsEndpoint(fqdn="example.com")], services=[TcpService(port=443)], action=Action.ACCEPT, comment="Allow HTTPS to SaaS provider", ), ], ) # 保存为 YAML dump_tickets(Path("my_ticket.yaml"), [ticket]) # 提交到 Tufin SecureChange service = AccessRequestService( username="admin", password="secret", domain="tufin.example.com", ) ticket_id = service.create_ticket(ticket) ``` # 设置 本项目在底层使用了 Dynaconf，以提供便捷的配置接口。您可以使用 `fwrqst config show` 查看当前应用的默认设置。您在使用 CLI 或 API 时提供的任何参数都将覆盖默认值。 ## 默认设置 可以通过持久化的方式更改默认设置。有两种方法可以做到这一点： 1. 使用 `fwrqst config find` 定位 `settings.toml` 并对文件进行更改。 2. 使用 `fwrqst config set` 配置 `settings.toml` 文件的单个设置。 如果您需要一个包含所有可用设置及其默认值的空白 `settings.toml`，只需运行 `fwrqst config set` 并附带有效的 key 但不提供任何值即可，例如 `fwrqst config set -k secure_change_port`。这会将 `secure_change_port` 设置重置为其默认值，并将当前应用程序设置持久化到 `fwrqst config find` 返回的位置。 想要更类似 12-factor（十二要素应用）的方式吗？您只需使用环境变量即可配置所有应用程序设置。只需为您想要更改的任何设置加上 `FWRQST_` 前缀，例如 `export FWRQST_SECURE_CHANGE_PORT=80` ## 优先级 1. 传递给 CLI 或方法/函数的参数 2. 使用操作系统环境变量定义的设置 3. 在 `settings.toml` 文件中定义的设置 4. 默认设置 需要注意的几点： - 给定命令可用的所有参数并不一定都能作为 CLI 参数使用。有些可能只能通过环境变量或 `settings.toml` 文件访问。 - `settings.toml` 文件的设置可以通过直接编辑文件或使用 CLI 的 `config` 子命令来设置。 # 开发 ## 前置条件 - Python 3.14+ - `make`（可选但推荐 — 在 Windows 上：`winget install GnuWin32.Make` 或使用 Git Bash / WSL） ## 快速开始 ``` # 安装所有依赖项和 git hooks（自动创建 venv） make install ``` 如果虚拟环境尚不存在，所有 make 目标都会自动创建虚拟环境。 ## 可用的 Make 目标 | Target | 描述 | | ---------------- | ------------------------------------------------- | | `make help` | 显示所有可用目标 | | `make venv` | 创建 `.venv` 虚拟环境 | | `make activate` | 打印 venv 激活说明 | | `make install` | 安装所有依赖和 git hooks | | `make format` | 使用 black 自动格式化代码 | | `make lint` | 使用 flake8 对代码进行 lint | | `make typecheck` | 使用 mypy 对代码进行类型检查 | | `make security` | 使用 bandit 进行安全扫描 | | `make test` | 运行带有覆盖率的单元测试 | | `make build` | 构建 sdist 和 wheel | | `make check` | 运行所有检查（lint、typecheck、security、test） | | `make clean` | 删除生成的文件 | ## 手动设置（不使用 Make） ``` python -m venv .venv # 激活 venv # Linux / macOS: source .venv/bin/activate # Windows (PowerShell): .venv\Scripts\Activate.ps1 # 安装依赖项 pip install --upgrade pip pip install -e ".[all]" build # 安装 git hooks git config core.hooksPath .githooks ``` ## 在本地运行检查 ``` black . # Format flake8 . # Lint mypy src/ # Type check bandit -c pyproject.toml -r . # Security pytest # Tests ``` ## VS Code 工作区包含调试启动配置（`.vscode/launch.json`）： | 配置 | 描述 | | ---------------- | ---------------------------------- | | **Debug: CLI** | 调试 CLI 入口点 | | **Debug: Pytest** | 调试带有断点支持的测试 | 推荐的扩展已在 `.vscode/extensions.json` 中列出，并会在首次打开时提示安装。 ## 提交规范 本项目使用 [Conventional Commits](https://www.conventionalcommits.org/)。git hooks 会自动强制执行此格式。允许的前缀：`feat`、`fix`、`perf`、`refactor`、`docs`、`test`、`ci`、`chore`、`build`、`style`。 示例： ``` feat: add bulk ticket creation fix: handle empty YAML input gracefully docs: update CLI usage examples ``` [release-please](https://github.com/googleapis/release-please) 使用这些提交来自动生成 changelog 并确定版本升级。 ## 构建 ``` make build # 或：python -m build ``` # Tufin API 文档 最新版本的类 OpenAPI 文档可以在[这里](https://forum.tufin.com/support/kc/rest-api/R23-2/securechangeworkflow/apidoc/#!/Tickets)找到。 此代码已针对 SecureChange 版本 **23.1 PHF1.2.0** 进行了测试。遗憾的是，Tufin API 中没有类似 SemVer 的 API 版本，也没有可用的 mock-server 来使其更可靠 😿。

标签：API封装, Docker 部署, Python, Tufin, 无后门, 网络运维, 逆向工具, 配置自动化, 防火墙管理