# PortScope **Repository Path**: scorpio1975/port-scope ## Basic Information - **Project Name**: PortScope - **Description**: PortScope: 一个为受限环境设计的、轻量级的、无需SNMP的端口监控与分析套件。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-07-20 - **Last Updated**: 2025-07-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # PortScope: 核心交换机端口监控与分析系统 ## 1. 项目简介 **PortScope** 是一套完整的网络设备端口监控与分析解决方案， 由两部分组成： 1. **后端数据采集系统** (Shell & Expect 脚本): 负责自动 登录多种型号的网络设备，并发采集端口的流量和光功率 数据，存储到数据库，并生成日报、月报和实时告警。 2. **前端数据分析工具** (C# WinForms 应用): 提供一个图形 用户界面，用于加载和可视化分析由后端生成的 CSV 报告 数据，包括带宽、速率和光功率。 该项目旨在为网络管理员提供一个从数据采集到可视化分析的 端到端、低成本、高度可扩展的端口监控工具，便于追踪带宽 使用情况、排查物理链路问题和进行容量规划。 ## 2. 适用场景 本解决方案专为在具有严格限制的环境中进行网络监控而设计， 特别适用于以下情况： - **网络隔离环境**: 部署在完全的内部网络（内网）中， 服务器无法访问互联网。 - **严格的软件安装策略**: 服务器上禁止安装大型商业或 复杂的开源监控套件（如 Zabbix, Prometheus）。 - **最小化的依赖需求**: 目标服务器无法使用包管理器 （如 Pip, NPM）。本系统仅依赖于 Linux 发行版自带的 核心工具。 - **SNMP 协议受限或禁用**: 通过模拟管理员的 Telnet/SSH 登录操作，完全绕过了对 SNMP 的依赖。 - **轻量级与非侵入式部署**: 所有组件均为脚本和小型二进制 文件，易于部署和移除，对系统无污染。 ## 3. 功能特性 - **多设备型号支持**: 通过配置文件驱动的 `expect` 脚本，可 轻松扩展支持不同厂商、不同型号的设备（如 9900, 12812 等）。 - **高效并发采集**: `collect_traffic.sh` 脚本能够并发执行 多个数据采集任务，通过可配置的并发数和任务间隔，平衡 采集速度与设备负载，大幅缩短采集周期。 - **自动化数据采集**: 通过 `run_collect.sh` 守护进程，以10分钟 为周期，持续采集多台设备多个端口的流量和光功率数据。 - **端到端安全设计**: - **凭据静态加密**: 设备登录凭据通过 `openssl` 进行强加密后存储。 - **内存中密码传递**: 密码通过环境变量在进程间安全传递， 避免在命令行中暴露。 - **数据持久化**: 采集到的数据（速率、利用率、端口状态、光功率） 存储在本地 SQLite 数据库 (`traffic.db`) 中。 - **双重实时告警**: - **流量阈值告警**: 当端口利用率超过预设阈值时，发送邮件告警。 - **端口状态告警**: 当端口状态从 `up` 变为 `down` 或其他 异常状态时，发送邮件告警。 - **自动化报告与推送**: 自动生成日报、月报，并将包含流量与 光功率数据的报告通过邮件发送。 - **自动化系统维护**: 通过 `cron` 定期执行清理任务，删除旧日志、 报告和数据库备份。 - **健壮的服务管理与日志记录**: 提供标准的服务管理命令 （`start`, `stop`, `status`, `restart`），并对守护进程和 工作脚本进行分离式、带毫秒精度的时间戳日志记录。 ## 4. 安全性设计 (后端脚本) 本系统的设计将安全性作为核心考量之一。 - **凭据静态加密 (Encryption at Rest)**: - 所有网络设备的登录凭据都存储在加密的 `acc` 文件中。 该文件必须通过 `encrypt_acc.sh` 脚本（使用 `openssl` 和强加密算法）进行加密。 - 加密密钥存储在 `key.txt` 文件中。这两个文件都必须 设置为 `600` 权限。 - 明文凭据文件 `acc.plain` 在加密后会被安全擦除。 - **凭据动态安全传递 (Secure Credential-in-Transit)**: - 密码被临时导出到一个环境变量中 (`export DEVICE_PASS=...`)， `expect` 脚本从中读取。 - 一旦 `expect` 脚本执行完毕，该环境变量会立即被 `unset` 命令销毁。 - **安全编码实践 (Secure Coding Practices)**: - **避免命令注入**: 脚本中使用 Bash 数组来安全地构建和 执行命令，防范命令注入风险。 - **安全临时文件**: 脚本使用 `mktemp` 命令来创建不可预测的、 唯一的临时文件和目录。 - **最小化攻击面 (Minimized Attack Surface)**: - 本系统不作为网络服务运行，不监听任何端口。 - 依赖关系极少，减少了因第三方依赖库漏洞而带来的风险。 - **严格的临时数据与变量清理 (Strict Cleanup)**: - 包含凭据的内存变量在使用完毕后会被立即 `unset`。 - 解密后的凭据通过进程替换 (`<()`) 直接以流的形式输入， 完全**避免了将明文凭据写入任何临时文件**。 - 临时文件和目录通过 `trap` 机制确保在脚本正常或异常 退出时都能被可靠地清理。 ## 5. 文件结构 ``` /root/ports_workflow/ ├── acc # (加密后) 设备登录凭据文件 ├── acc.plain # (建议保留) 凭据的明文主文件，用于管理 ├── backups/ # 数据库备份目录 ├── collect_traffic.sh # 核心逻辑脚本：数据采集、报告生成、清理 ├── encrypt_acc.sh # 用于加密和解密 acc 文件的脚本 ├── get_port_traffic.exp # (可扩展的) Expect 脚本，用于登录设备并获取数据 ├── key.txt # 加密密钥文件 ├── logs/ # 日志文件目录 │ ├── run_collect_daemon.log # 守护进程日志 │ ├── traffic_collect_YYYYMMDD.log # 数据采集日志 │ └── daily_report_YYYYMMDD.log # 日报生成日志 ├── ports_master_list.txt # (已统一) 主设备与端口字典文件 ├── reports/ # 生成的报告存放目录 ├── run_collect.sh # 守护进程管理脚本 (start/stop/status) └── traffic.db # SQLite 数据库文件 ``` ## 6. 安装与部署 (后端脚本) ### 6.1 环境要求 - **操作系统**: Linux (CentOS/Ubuntu/Debian 等，推荐 Bash 4.x 或更高版本) - **必要工具**: `bash`, `expect`, `sqlite3`, `mailutils` (或 `mutt`), `bc`, `openssl` **安装命令示例 (以 CentOS 为例):** ```bash yum install -y expect sqlite mailutils bc openssl nstall -y expect sqlite mailutils bc openssl ``` ### 6.2 部署步骤 1. **上传文件**: 将所有脚本上传到目标目录，例如 `/root/ports_workflow/`。 2. **配置目录和权限**: ```bash cd /root/ports_workflow chmod +x collect_traffic.sh get_port_traffic.exp run_collect.sh encrypt_acc.sh mkdir -p backups logs reports ``` 3. **配置脚本参数**: - 打开 `collect_traffic.sh`，修改 `CONFIG` 数组中的参数： - `EMAIL_FROM`, `EMAIL_TO`: 配置邮箱。 - `MAX_CONCURRENT_JOBS`, `INTER_JOB_DELAY`: 配置并发参数。 - 打开 `run_collect.sh`，修改 `CYCLE_INTERVAL_SECONDS` 来设置采集周期。 4. **配置设备和端口**: - **`acc.plain` 文件**: 创建 `acc.plain`。按照 `IP地址 用户名 密码 协议 端口` 的格式填写设备登录信息。 - **`ports_master_list.txt` 文件**: - 创建 `ports_master_list.txt` 文件。 - 使用 `!MODEL_NAME` (如 `!9900`, `!12812`) 作为设备型号的 开始标志。 - 在每个标志下，按照 `IP地址 端口名称 端口描述` 的格式 填写端口信息，每行一个。 - 支持 `#` 注释和空行。 5. **加密凭据 (关键安全步骤)**: - **A. 生成密钥**: `openssl rand -base64 32 > key.txt` - **B. 执行加密**: `./encrypt_acc.sh encrypt` (此操作会安全删除 `acc.plain`) - **C. 设置权限**: `chmod 600 acc key.txt` 6. **启动数据采集服务**: ```bash ./run_collect.sh start ``` - 检查状态：`./run_collect.sh status` - 查看日志：`tail -f logs/run_collect_daemon.log` 和 `tail -f logs/traffic_collect_*.log` ## 7. 使用方法 (后端脚本) ### 7.1 服务管理 (`run_collect.sh`) - **启动服务**: `./run_collect.sh start` - **停止服务**: `./run_collect.sh stop` - **查看状态**: `./run_collect.sh status` - **重启服务**: `./run_collect.sh restart` ### 7.2 手动执行任务 (`collect_traffic.sh`) `collect_traffic.sh` 通常由 `run_collect.sh` 或 `cron` 自动调用， 但也可以手动执行。手动执行时，日志会同时打印到屏幕和文件中。 - **生成日报**: `./collect_traffic.sh --daily` - **生成月报**: `./collect_traffic.sh --monthly` - **执行清理**: `./collect_traffic.sh --cleanup` - **清理锁文件 (异常处理)**: `./collect_traffic.sh --clean-locks` - **显示帮助**: `./collect_traffic.sh --help` ## 8. Crontab 自动化调度 (可选) 虽然 `run_collect.sh` 已经内置了报告的定时触发逻辑，但如果您 更倾向于使用 `cron` 来管理所有定时任务（包括清理），可以不启动 守护进程，而是直接使用 `cron`。 **编辑 crontab:** `crontab -e` **添加以下规则:** ```crontab # 每10分钟执行一次数据采集 */10 * * * * /root/ports_workflow/collect_traffic.sh >/dev/null 2>&1 # 每天 23:00 生成日报并备份数据库 0 23 * * * /root/ports_workflow/collect_traffic.sh --daily >/dev/null 2>&1 # 每月 1 号凌晨 01:00 生成上个月的月报并备份数据库 0 1 1 * * /root/ports_workflow/collect_traffic.sh --monthly >/dev/null 2>&1 # 每月 1 号凌晨 03:00 执行系统清理 0 3 1 * * /root/ports_workflow/collect_traffic.sh --cleanup >/dev/null 2>&1 ``` ## 9. 带宽分析工具 (CsvChartApp) 本项目包含一个配套的 Windows 桌面应用程序 (`CsvChartApp.exe`)， 用于直观地分析 CSV 报告文件。 ### 9.1 工具特性 - **多维数据可视化**: 同时提供“带宽利用率”、“流量速率”和“**光功率**” 三个图表，通过 Tab 页切换。 - **智能数据加载**: 支持加载包含多设备、多端口数据的 `full_summary_report_*.csv` 文件或单个端口的详细数据文件。 - **交互式数据筛选**: 自动识别并填充下拉列表，方便用户选择 特定端口进行分析。 - **交互式图表分析**: - 支持鼠标拖拽选区进行放大（Zoom In）。 - 提供“重置缩放”功能。 - **状态变化标注**: 在所有图表中，使用**垂直虚线**清晰地标注出 端口 `up`/`down` 状态发生变化的时间点。 - **图表导出**: 可将当前显示的任何图表一键导出为高质量的 PNG 图片文件。 - **智能聚合显示**: 当加载的数据时间跨度超过3天（如月报）时， 程序会自动聚合数据（流量取峰值，利用率和光功率取平均值） 以优化长周期趋势的可视化效果。 ### 9.2 运行要求 - **操作系统**: Windows 10 或更高版本。 - **依赖环境**: **.NET 8 Desktop Runtime**。 ### 9.3 使用说明 1. **启动程序**: 双击运行 `CsvChartApp.exe`。 2. **加载报告**: 点击 **【选择 CSV 文件】**，推荐选择 `full_summary_report_*.csv`。 3. **选择数据源**: 从 **【数据源】** 下拉列表中选择您想分析的端口。 4. **分析图表**: - **切换视图**: 点击 "带宽利用率", "流量速率", "光功率" Tab 页切换。 - **查看状态变化**: 观察图表中的绿色（变为up）或红色 （变为down）的垂直虚线。 - **缩放与重置**: 使用鼠标缩放，或点击 **【重置缩放】**。 5. **导出图表**: 点击 **【导出当前图表】**，选择保存位置。 ### 9.4 安全性设计 (前端工具) `CsvChartApp` 遵循安全第一的原则： - **完全离线**: 程序不建立任何网络连接，所有操作均在本地完成。 - **受控的文件访问**: 仅在用户明确选择后才只读访问 CSV 文件， 写入操作也需要用户指定位置。 - **强大的输入验证**: 对加载的文件大小、记录数和表头格式进行 严格校验，防止因恶意文件导致的程序崩溃。无效的数据点会被 安全地忽略。 - **无特权运行**: 无需管理员权限即可运行。 - **基于可信赖的框架**: 基于微软官方的 .NET 8 平台构建。 综上所述，`CsvChartApp` 通过隔离、受控访问、严格验证和最小权限等多种手段，确保了用户在分析报告数据时的安全性。