eve-0607/portwatch

# Portwatch — 轻量级端口扫描器与服务追踪工具 [](https://python.org) [](LICENSE) 一款用于监控监听 TCP 端口、追踪 homelab 环境中的服务，并将关键基础设施标记为不可触碰的 CLI 工具。由 [Eve](https://github.com/eve-0607) 开发。 ## ✨ 功能 | 功能 | 描述 | |---------|-------------| | 🔍 **端口扫描** | 发现所有监听的 TCP 端口及其进程信息（通过 `ss` 或 `/proc/net/tcp`） | | 📋 **服务注册表** | 基于 JSON 的持久化注册表，用于记录已知服务及其名称 | | 🔒 **关键端口** | 将基础设施端口标记为关键——该工具绝不会建议触碰这些端口 | | 🔎 **空闲端口查找** | 在指定范围内查找可用端口，排除已使用和已保留的端口 | | 🏷️ **服务标记** | 为端口号提供易于理解的名称，方便识别 | ## 🚀 安装 ### 从源码安装（推荐） ``` git clone https://github.com/eve-0607/portwatch.git cd portwatch pip install -e . --break-system-packages ``` 这将以可编辑/开发模式安装 `portwatch` CLI 命令。 ## 💻 用法 Portwatch 使用 argparse 实现清晰的子命令，并内置帮助信息： ``` # 获取帮助 portwatch --help # 扫描系统上所有 listening ports portwatch scan # 显示已保存的 service registry 状态 portwatch status # 通过端口号注册新 service portwatch add 8080 "qBittorrent" # 将端口标记为 critical（永不建议修改） portwatch critical 22 --name "SSH daemon" # 在默认范围 (5000-6500) 内查找空闲端口 portwatch free # 在自定义范围内查找空闲端口 portwatch free 10000 20000 # 从 registry 中移除 service portwatch remove 8080 ``` ### 示例：完整扫描输出 ``` $ portwatch scan Port Status Process Name --------------------------------------------------------------------------- 22 🔒 CRITICAL sshd SSH daemon 5678 ✅ tracked n8n N8n 8080 ✅ tracked qbittorrent qBittorrent 8123 ✅ tracked homeassistant HomeAssistant 9999 ⚠️ unknown python3 (unregistered) ``` ## 🏗 架构 ``` portwatch/ ├── src/portwatch/ │ ├── __init__.py # Package metadata & version │ ├── cli.py # CLI entry point with argparse subcommands │ ├── port_scanner.py # Port discovery (ss / /proc/net/tcp) │ └── service_registry.py # JSON-backed persistent registry ├── tests/ # Test suite ├── pyproject.toml # Build config & dependencies └── README.md # You are here ``` ### 设计原则 - **零外部依赖** — 仅使用 Python 标准库（`subprocess`、`json`、`os`） - **数据隔离** — 所有状态都保存在 `~/.eve/services.json` 中，从不修改系统文件 - **平滑降级** — 如果 `ss` 不可用，会直接回退到解析 `/proc/net/tcp` - **原子写入** — 注册表更新采用“临时文件-然后重命名”机制以防止数据损坏 - **CLI 优先** — 专为终端使用而设计，带有 emoji 状态指示器和整洁的表格输出 ## ⚙️ 配置 服务注册表位于 `~/.eve/services.json`。其结构如下： ``` { "critical": [22, 80, 443], "services": { "22": "SSH daemon", "80": "Heimdall dashboard", "5678": "N8n" } } ``` 你也可以通过设置 `EVE_TRACKER_DATA` 环境变量来指定自定义的数据文件路径： ``` export EVE_TRACKER_DATA="/path/to/custom/services.json" ``` ## 🧪 开发 ### 运行测试 ``` pytest tests/ -v ``` ### 代码风格 本项目遵循 PEP 8 规范并使用 type hints。提交前请运行格式化工具： ``` ruff check src/ tests/ ruff format src/ tests/ ``` ## 📜 许可证 MIT — 详情请参阅 [LICENSE](LICENSE)。 由 [Eve](https://eve-0607.github.io) 用 💜 构建。

标签：Awesome, Homebrew安装, Python, 家庭实验室, 插件系统, 数据统计, 无后门, 服务监控, 端口扫描, 系统管理, 逆向工具