Metadata-Version: 2.5
Name: lighthouse-fw
Version: 0.3.0
Summary: Tencent Cloud Lighthouse firewall allowlist updater with interactive CLI.
Author: deali
License: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: cryptography>=45.0.0
Requires-Dist: keyring>=25.6.0
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: questionary>=2.1.1
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=14.0.0
Requires-Dist: tencentcloud-sdk-python>=3.0.0
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: typer>=0.16.0
Description-Content-Type: text/markdown

# lighthouse-fw

一个面向 **Tencent Cloud Lighthouse 防火墙白名单更新** 的 Python 包，支持：

- `uvx lighthouse-fw` / `lhfw` 无参数进入交互式 CLI 菜单
- 添加腾讯云账号后自动扫描全部地域的轻量实例，勾选导入
- 从云上防火墙发现 SSH 类规则（22 / 2222 / 备注含 ssh）并勾选托管
- `lhfw run` 预览 diff，`--apply` 写入前显式确认
- Windows / Linux / macOS 跨平台配置布局
- 密钥优先系统钥匙串，无法使用时回退到本地加密文件

产品交互说明见 [`docs/product-design.md`](docs/product-design.md)。

## English summary

`lighthouse-fw` is a Python package for managing Tencent Cloud Lighthouse SSH firewall allowlists. The default no-arg entry is an interactive CLI: add a Tencent Cloud account, scan every region for Lighthouse instances, import SSH-like firewall rules, then preview and apply the current public IP. Parameterized commands such as `lhfw run --apply --yes` remain for scripts.

## 安装与运行

### 1. 直接用 `uvx`

无参数进入交互式菜单（没有账号时直接添加账号）：

```powershell
uvx lighthouse-fw
```

直接运行 CLI 子命令：

```powershell
uvx lighthouse-fw doctor
uvx lighthouse-fw run
```

### 2. 安装成工具命令

```powershell
uv tool install lighthouse-fw
lhfw doctor
lhfw run
```

### 3. 仓库内本地运行

```powershell
uv run lhfw doctor
uv run lhfw run
```

## 默认行为

- `uvx lighthouse-fw` / `lhfw`：无参数进入交互式 CLI。没有账号时走「添加账号」；已有账号时出现菜单（默认第 1 项：更新防火墙白名单）
- 添加账号只需要名称和 SecretId / SecretKey，随后扫描**全部地域**勾选实例，再勾选云上已有的 SSH 类规则
- 某台机器没有 SSH 类规则时仍然导入，白名单更新对它是空操作，并提示一句
- `lhfw run`：不带筛选条件时，默认运行所有 **enabled** 的 server
- `lhfw run --apply`：会先做 diff 预览，再要求显式确认
- `lhfw doctor`：检查本地环境、密钥后端，以及账号级 API 可达性

## 配置模型

当前包的持久化配置由三部分组成：

1. 普通配置：`config.toml`
2. 密钥：优先系统钥匙串；无安全后端时回退到本地加密文件 `secrets.bin`
3. 本地口令/密钥文件：`secrets.key`

server 支持：

- `enabled` 状态
- 多个自由标签 `tags`
- 完整 `managed_rules`

每条 `managed_rules` 支持：

- `protocol`
- `port`
- `cidr`
- `action`
- `description`
- `replace_existing_same_port`

## 常用 CLI

对外只有这些命令。精细改动（关某台机器、加非 SSH 端口、改 IP 查询源等）直接编辑 `config.toml`。

```powershell
lhfw                         # 交互菜单；没有账号时直接添加
lhfw account add             # 添加腾讯云账号并导入
lhfw sync --account work     # 同步新服务器 / SSH 规则
lhfw sync --account work --all
lhfw run                     # 预览
lhfw run --apply             # 预览后确认写入
lhfw run --apply --yes       # 无人值守写入
lhfw run --tag prod --tag sg
lhfw doctor
lhfw config show
lhfw config history
```

## 交互式 CLI

无参数启动后用方向键选择：

- 更新防火墙白名单
- 添加腾讯云账号
- 同步服务器和规则
- 查看当前配置
- 退出

## 安全说明

- 优先使用系统钥匙串
- 如果当前平台没有安全 keyring backend，会回退到本地加密文件
- SecretId / SecretKey 在交互输入时隐藏
- `doctor` 默认是只读检查，不会逐台 server 修改任何东西

## 腾讯云权限要求

本工具通过腾讯云 API 管理轻量应用服务器的防火墙规则，需要为 API 密钥对应的子账号授予以下**全部**权限，缺一不可。

### 操作步骤

1. 打开 [访问管理 → 策略](https://console.cloud.tencent.com/cam/policy)
2. 新建自定义策略，选择「按策略语法创建」，粘贴下方 JSON
3. 将策略关联到 API 密钥对应的子账号

### 所需权限列表

**预设策略（基础只读，doctor 验证需要）：**

| 策略名 | 说明 |
|---|---|
| `QcloudLighthouseReadOnlyAccess` | 轻量应用服务器只读权限（包含 `DescribeInstances` 等） |

**自定义策略（防火墙规则管理，run 命令需要）：**

```json
{
    "version": "2.0",
    "statement": [
        {
            "effect": "allow",
            "resource": ["*"],
            "action": [
                "lighthouse:DescribeFirewallRules",
                "lighthouse:DescribeFirewallRulesTemplate",
                "lighthouse:DescribePresetFirewallRules",
                "lighthouse:CheckFirewallRules",
                "lighthouse:CheckInstanceFirewallPorts",
                "lighthouse:DescribeFirewallTemplateApplyRecords",
                "lighthouse:DescribeFirewallTemplateQuota",
                "lighthouse:DescribeFirewallTemplateRuleQuota",
                "lighthouse:DescribeFirewallTemplateRules",
                "lighthouse:DescribeFirewallTemplates",
                "lighthouse:ApplyFirewallTemplate",
                "lighthouse:CreateFirewallRules",
                "lighthouse:CreateFirewallTemplate",
                "lighthouse:CreateFirewallTemplateRules",
                "lighthouse:DeleteFirewallRules",
                "lighthouse:DeleteFirewallTemplate",
                "lighthouse:DeleteFirewallTemplateRules",
                "lighthouse:ModifyFirewallRuleDescription",
                "lighthouse:ModifyFirewallRules",
                "lighthouse:ModifyFirewallTemplate",
                "lighthouse:ReplaceFirewallTemplateRule",
                "lighthouse:ResetFirewallTemplateRules"
            ]
        }
    ]
}
```

### 权限与命令的对应关系

| 命令 / 功能 | 所需权限 |
|---|---|
| `lhfw doctor` | `QcloudLighthouseReadOnlyAccess` |
| `lhfw run`（预览 diff） | `QcloudLighthouseReadOnlyAccess` + 自定义策略中的读操作 |
| `lhfw run --apply`（写入规则） | `QcloudLighthouseReadOnlyAccess` + 自定义策略中的全部操作 |

## 开发与测试

```powershell
uv run python -m unittest discover -s tests -v
uv run lhfw doctor
```

## 发布

项目按 PyPI 发布路径设计：

- 包名：`lighthouse-fw`
- 命令名：`lhfw`
- 版本 tag：`v1.2.3`
- 认证：GitHub OIDC Trusted Publishing

推送版本 tag 后，GitHub Actions 会自动构建并发布到 PyPI。

