StewAlexander-com/ShadowVendor

# 🚀 ShadowVendor  **概览仪表板** - 交互式厂商分布可视化： - 将鼠标悬停在饼图扇区上可查看设备数量、百分比和 VLAN 存在情况 - 快速识别主导厂商和设备多样性 - 可直接导出用于报告和演示 ## ⚡ TL;DR：为什么您应该关注 - **将 MAC 表转化为仪表板**：将原始网络设备输出转化为交互式 HTML 可视化和 CSV 报告 - **检测新/未知厂商**：识别以前未见的设备，并跟踪厂商分布随时间的变化 - **导出 SIEM 事件**：生成用于 Elastic、Splunk 和其他 SIEM 的标准化 CSV/JSONL 导出，以实现态势变化检测 **快速开始：** `python3 ShadowVendor.py input_file.txt` → 检查 `output/` 中的结果 **60 秒内试用：** `python3 ShadowVendor.py tests/data/test-mac-table.txt`（然后在浏览器中打开 `output/vendor_distribution.html`）→ 无需触碰您自己的网络数据即可查看仪表板 **隐私与本地执行：** ShadowVendor 完全在您的机器上处理您的文件。输入文件和完整的 MAC 地址永远不会被上传。在默认模式下，未缓存的厂商查询仅向外部 API 发送 OUI 前缀（前 3 个八位字节）。使用 `--offline` 可实现完全的气隙隔离运行，零外部网络调用。 ## 👥 适用人群？ - **SOC 分析师**：检测新厂商并跟踪设备变化，用于安全监控 - **网络工程师**：分析 MAC 地址表和 ARP 数据以了解网络构成 - **资产/CMDB 所有者**：通过厂商识别维护准确的设备清单 - **安全架构师**：将态势变化检测集成到 SIEM 工作流中 ## 📖 介绍 **ShadowVendor** 是一款 Python 工具，专为网络管理员和网络安全专业人员设计，用于分析和可视化网络上设备的厂商分布。它可以处理来自各种网络设备（包括 Cisco、HP/Aruba、Juniper、Extreme、Brocade 等）的 MAC 地址表和 ARP 数据，为您提供有关网络组成的详细洞察。 **在您的机器上运行：** ShadowVendor 不是一项云服务——您的网络导出文件和完整的 MAC 地址均在本地处理，从不上传；使用 `--offline` 可实现零外部网络调用。 当与 SIEM（Elastic、Splunk、QRadar 等）集成时，ShadowVendor 会从一个静态清单工具转变为一个**态势变化传感器**，从而实现主动的安全监控和事件响应。 ## 📚 文档概览 ShadowVendor 包含全面的文档，按受众和用例进行分类。本 README 提供了快速入门所需的基本信息。如需深入了解，请参阅专门的文档： | 文档 | 目的 | 最适合 | |----------|---------|----------| | **[README.md](README.md)**（您在此处） | 快速开始、常见工作流、基本用法 | 初次使用者、快速参考 | | **[TUTORIAL.md](TUTORIAL.md)** | 技术深入探讨、架构、代码解读 | 贡献者、开发者、了解内部原理 | | **[ADVANCED.md](ADVANCED.md)** | 运维最佳实践、SIEM 集成、生产部署 | SOC 工程师、网络运维、生产环境用户 | | **[CONFIG.md](CONFIG.md)** | 配置文件、环境变量、自动化设置 | 自动化工程师、DevOps、周期性任务 | | **[EXECUTION_PATHS.md](EXECUTION_PATHS.md)** | 完整的执行路径文档、行为图 | 测试人员、QA、了解所有执行模式 | | **[TEST_COVERAGE.md](TEST_COVERAGE.md)** | 测试覆盖率详情、测试策略 | 贡献者、QA 工程师 | **导航指南：** - **初次使用 ShadowVendor？** → 从这里（README.md）开始，然后尝试 [快速开始](#-getting-started) - **想了解它是如何工作的？** → 阅读 [TUTORIAL.md](TUTORIAL.md) 了解架构和代码解读 - **要部署到生产环境？** → 请参阅 [ADVANCED.md](ADVANCED.md) 了解运维最佳实践 - **正在设置自动化？** → 请查看 [CONFIG.md](CONFIG.md) 获取配置示例 - **想要贡献代码？** → 请查阅 [TUTORIAL.md](TUTORIAL.md#for-contributors) 了解扩展点和测试 ## 📑 目录 - [✨ 功能](#-features) - [🔄 常见工作流](#-common-workflows) - [🚀 入门指南](#-getting-started) - [前置条件](#prerequisites) - [安装说明](#installation) - [📋 快速参考](#-quick-reference) - [运行 ShadowVendor 的方式](#ways-to-run-shadowvendor) - [预期输出](#expected-outputs) - [📋 详细用法](#-detailed-usage) - [命令行参数](#command-line-flags) - [离线模式](#offline-mode) - [历史漂移分析](#historical-drift-analysis) - [SIEM 友好导出](#siem-friendly-export) - [Windows 用法](#windows-usage) - [详细输出](#verbose-output) - [运行时日志](#runtime-logging) - [配置](#configuration) - [Python API](#python-api) - [📥 支持的输入格式](#-supported-input-formats) - [📊 输出详情](#-output-details) - [🌟 成功案例与已知部署](#-success-stories--known-deployments) - [🔒 安全注意事项](#-security-considerations) - [🔧 高级主题](#-advanced-topics) - [技术教程](#technical-tutorial) - [🧪 测试与质量](#-testing--quality) - [📈 项目状态](#-project-status) - [🤝 社区](#-community) ## ✨ 功能 - **多厂商 MAC 地址解析：** 支持 Cisco、HP/Aruba、Juniper、Extreme、Brocade 等。 - **灵活的输入：** 接受各种格式的 MAC 地址列表、MAC 表和 ARP 表。 - **厂商识别：** 使用本地 IEEE OUI 缓存进行快速、安全的查询。 - **全面的报告：** 生成 CSV、摘要和交互式 HTML 仪表板。 - **VLAN 和端口分析：** 提取并可视化可用的 VLAN 和端口数据。 - **历史漂移跟踪：** 归档厂商摘要，并通过元数据关联分析随时间变化的趋势。 - **SIEM 集成：** 导出标准化的 CSV/JSONL 事件，用于安全监控和态势变化检测。 - **可扩展且稳健：** 轻松添加对新格式的支持；并使用真实数据进行了全面测试。 ## 🔄 常见工作流 **基础分析：** ``` python3 ShadowVendor.py input_file.txt ``` → 生成标准输出：设备 CSV、端口 CSV（如果是 MAC 表）、HTML 仪表板、厂商摘要 **离线分析（气隙隔离网络）：** ``` python3 ShadowVendor.py --offline input_file.txt ``` → 仅使用本地 OUI 缓存，不进行任何外部 API 调用 **SIEM 集成：** ``` python3 ShadowVendor.py \ --siem-export \ --site DC1 \ --environment prod \ input_file.txt ``` → 生成标准输出 + SIEM 就绪的 CSV/JSONL 文件 **带有漂移分析的历史跟踪：** ``` python3 ShadowVendor.py \ --history-dir history \ --site DC1 \ --change-ticket CHG-12345 \ --analyze-drift \ input_file.txt ``` → 生成标准输出 + 带有元数据的归档摘要 + 创建漂移分析 CSV **完整工作流（所有功能）：** ``` python3 ShadowVendor.py \ --offline \ --history-dir history \ --analyze-drift \ --siem-export \ --site DC1 \ --environment prod \ --change-ticket CHG-12345 \ input_file.txt ``` → 离线运行，生成所有输出，带元数据归档，创建漂移分析，并导出 SIEM 事件 ## 🚀 入门指南 ### 前置条件 - Python 3.9 或更高版本（支持 Python 3.8+） - pip（Python 包安装器） ### 安装说明 **选项 1：作为包安装（推荐用于 Python API 使用）** ``` git clone https://github.com/StewAlexander-com/ShadowVendor.git cd ShadowVendor && pip install -e . ``` **选项 2：使用独立脚本（无需安装）** ``` git clone https://github.com/StewAlexander-com/ShadowVendor.git cd ShadowVendor pip install -r requirements.txt # Install dependencies only python3 ShadowVendor.py input_file.txt # Run directly ``` 当您运行 `pip install -e .` 或 `pip install -r requirements.txt` 时，**运行时依赖** 将被自动安装。必需的包： - `requests`（用于 OUI API 查询） - `plotly`（用于交互式 HTML 仪表板） - `tqdm`（用于进度条） - `rich`（用于增强的终端输出） **开发依赖**（用于测试和安全扫描）： - 安装命令：`pip install -r requirements-dev.txt` - 包含：`pytest`、`pytest-cov` 和 `bandit`（安全扫描器） - 用于：运行测试（`pytest`）、安全扫描（`pytest --bandit`）和代码覆盖率报告 - **注意**：开发依赖对于最终用户是可选的；仅供贡献者和 CI/CD 流水线使用 ## 📋 快速参考 ### 运行 ShadowVendor 的方式 **1. 简单的包入口点**（基本用法，无参数）： ``` shadowvendor input_file.txt # 或 python3 -m shadowvendor input_file.txt ``` *仅限于基本分析——不支持高级功能* **2. 独立脚本**（具有所有参数的完整功能集）： ``` python3 ShadowVendor.py input_file.txt ``` **重要提示：** 要使用所有高级功能（离线模式、历史跟踪、SIEM 导出、漂移分析），请使用 `python3 ShadowVendor.py`。包入口点（`shadowvendor`）是一个简单的包装器，仅接受输入文件参数，不支持各种命令行参数。 ### 预期输出 ShadowVendor 会在 `output/` 目录中生成多个输出文件： **输出行为：** - **始终生成**：设备 CSV、交互式 HTML 仪表板、厂商摘要文本文件 - **条件生成**：端口 CSV（仅适用于 MAC 地址表，不适用于 ARP 或简单列表） - **可选**（带参数）：SIEM 导出（CSV/JSONL）、历史归档、漂移分析 CSV 有关完整的文件说明，请参阅下方的 [输出详情](#-output-details)。 ### 典型的首次运行 **初次使用者的快速工作流：** 1. **将您的网络输出粘贴**到文件中（例如 `my_switch.txt`）： # 从以下命令复制输出：show mac address-table # 或者：show arp # 或者：仅仅是 MAC 地址列表 2. **运行 ShadowVendor**： python3 ShadowVendor.py my_switch.txt 3. **打开结果**： - **交互式仪表板**：在浏览器中打开 `output/vendor_distribution.html` - **设备列表**：查看 `output/my_switch-Devices.csv` 获取详细的设备信息 - **摘要**：阅读 `output/vendor_summary.txt` 获取快速的厂商统计 **就是这样！** 您现在拥有了一份关于您网络数据的完整厂商分析报告。 ## 📋 详细用法 ### 命令行参数 | 参数 | 说明 | 示例 | |------|-------------|---------| | `--offline` | 禁用外部厂商查询（仅缓存） | `--offline` | | `--history-dir DIR` | 用于归档厂商摘要的目录（如果不存在则自动创建） | `--history-dir history` | | `--analyze-drift` | 对归档的摘要运行漂移分析 | `--analyze-drift` | | `--site SITE` | 用于 SIEM/漂移元数据的站点/区域标识符 | `--site DC1` | | `--environment ENV` | 用于 SIEM 导出的环境标识符 | `--environment prod` | | `--change-ticket ID` | 用于漂移关联的变更工单/事件 ID | `--change-ticket CHG-12345` | | `--siem-export` | 生成对 SIEM 友好的 CSV/JSONL 导出 | `--siem-export` | **注意**：配置文件值和环境变量可以为这些参数提供默认值。请参阅下方的 [配置](#configuration) 章节。 ### 离线模式 当您希望避免任何外部厂商查询时（例如在气隙隔离网络中），请使用 `--offline` 参数。本地 OUI 缓存中尚不存在的设备将显示为 `Unknown`。 ``` python3 ShadowVendor.py --offline input_file.txt ``` ### 历史漂移分析 跟踪厂商构成如何随时间变化，并与变更窗口/事件进行关联： ``` python3 ShadowVendor.py \ --history-dir history \ --site DC1 \ --change-ticket CHG-12345 \ --analyze-drift \ input_file.txt ``` **它的作用：** - 如果历史目录不存在，则自动创建 - 将 `vendor_summary.txt` 归档到 `history/vendor_summary-YYYYMMDD-HHMMSS.txt` - 创建配套的 `.metadata.json` 文件，包含 `run_timestamp`、`site`、`change_ticket_id` - 生成 `history/vendor_drift.csv`，包含元数据行和厂商百分比趋势 **SIEM 关联：** 漂移 CSV 的元数据支持与变更窗口和事件进行关联，辅助 8D/5-why 工作流。您可以使用 `run_timestamp` 和 `site` 将漂移数据与 SIEM 事件进行关联，并通过 `change_ticket` 关联厂商构成的转变。 ### SIEM 友好导出 为了进行 SIEM 集成（Elastic、Splunk 等），生成标准化的 CSV 和 JSONL 事件： ``` python3 ShadowVendor.py \ --siem-export \ --site DC1 \ --environment prod \ input_file.txt ``` **稳定的 Schema**（每条记录中均包含所有字段）： - `timestamp`、`site`、`environment`、`mac`、`vendor`、`device_name`、`vlan`、`interface`、`input_type`、`source_file` **便于关联的设计：** - 所有字段命名一致，且在每条记录中均存在 - MAC 地址经过标准化处理，确保可靠的关联 - UTC ISO-8601 时间戳，用于基于时间的关联 - 站点和环境标签支持多站点/多环境仪表板 **如需完整的 SIEM 集成：** 请参阅 [ADVANCED.md](ADVANCED.md#-posture-change-detection--security-monitoring) 了解： - 详细的 SIEM 集成工作流 - 关联规则示例（Elastic、Splunk） - 态势变化检测策略 - 持续监控设置 ### 跨平台兼容性 ShadowVendor 设计用于在 **Linux (Debian/Ubuntu)、macOS (Intel 和 Apple Silicon) 以及 Windows** 上运行。所有文件操作均使用 UTF-8 编码和跨平台路径处理，确保在各环境中无缝运行。 **Windows 用法：** ``` $env:PYTHONIOENCODING="utf-8"; $env:PYTHONUTF8="1"; python3 ShadowVendor.py input_file.txt ``` 或单独设置环境变量： ``` $env:PYTHONIOENCODING = "utf-8" $env:PYTHONUTF8 = "1" python3 ShadowVendor.py input_file.txt ``` **Linux/macOS 用法：** ``` python3 ShadowVendor.py input_file.txt ``` **跨平台注意事项：** - **文件路径**：所有路径均使用 `pathlib.Path` 以实现跨平台兼容性（自动处理 `/` 与 `\`） - **文件编码**：所有文件操作均显式使用 UTF-8 编码，以防止 Windows 上出现编码问题 - **换行符**：Python 的文本模式会自动处理 CRLF (Windows) 和 LF (Unix) - **文件锁定**：缓存写入使用原子操作（先写入临时文件，再重命名），以防止多个进程同时运行时发生损坏 - **API 超时**：所有网络请求都有 5 秒的超时时间，防止在缓慢/不可靠的网络上挂起 - **错误处理**：所有平台上的权限错误和文件系统错误均会被优雅地处理 ### 详细输出 使用 `SHADOWVENDOR_VERBOSE` 环境变量控制调试输出（仅由 `ShadowVendor.py` 支持）： ``` # Quiet mode（默认） python3 ShadowVendor.py input_file.txt # Verbose mode - 详细的处理信息 SHADOWVENDOR_VERBOSE=1 python3 ShadowVendor.py input_file.txt ``` 启用详细模式后，您将看到文件类型检测细节、逐行处理信息、示例设备条目、CSV 写入进度以及输出文件内容预览。 ### 运行时日志 为了进行故障排除和性能分析，ShadowVendor 可以将运行时行为记录到结构化的日志文件中： ``` # 启用 runtime logging SHADOWVENDOR_LOG=1 python3 ShadowVendor.py input_file.txt ``` 启用后，系统将创建一个 JSONL 格式的日志文件（每行一个 JSON 对象），位置在 `output/shadowvendor_runtime.log`。每个条目包含： - `timestamp`：UTC ISO-8601 时间戳 - `event_type`：事件类型（例如 "processing_start"、"file_type_detection"、"error"） - `event_data`：特定于事件的数据 - `context`：附加上下文信息 该日志记录器会捕获关键的运行时事件，包括文件处理、错误条件、输出生成和性能指标。日志默认禁用，未启用时不会对性能产生影响。 ### 配置 ShadowVendor 支持配置文件和环境变量，以减少周期性任务中 CLI 参数的重复输入。 **配置文件位置**（按顺序检查）： 1. 当前目录：`./shadowvendor.conf`（或 `.yaml`、`.toml`） 2. 用户配置：`~/.config/shadowvendor/shadowvendor.conf` 3. 系统配置：`/etc/shadowvendor/shadowvendor.conf` **支持的格式**：INI/ConfigParser（`.conf`、`.ini`）、YAML（`.yaml`、`.yml` - 需要 PyYAML）、TOML（`.toml` - 需要 tomli/tomllib） **配置示例**（`shadowvendor.conf`）： ``` [shadowvendor] offline = true history_dir = /var/lib/shadowvendor/history site = DC1 environment = prod siem_export = true ``` **优先级**：命令行参数 > 环境变量 > 配置文件 > 默认值 **如需了解完整的配置详情：** 请参阅 [CONFIG.md](CONFIG.md) 了解： - 完整的配置文件示例（INI、YAML、TOML） - 环境变量参考 - 配置优先级规则 - 自动化设置示例 ### Python API ShadowVendor 提供了可编程的 Python API，以便集成到自动化脚本和其他工具中： ``` from shadowvendor import analyze_file # 基本用法 result = analyze_file("mac_table.txt", offline=True) print(f"Processed {result['device_count']} devices") print(f"Found {result['vendor_count']} unique vendors") print(f"Output files: {result['output_files']}") # 访问设备数据 for mac, info in result['devices'].items(): print(f"{mac}: {info['vendor']} (VLAN: {info['vlan']})") # 使用 SIEM export result = analyze_file( input_file="mac_table.txt", offline=True, siem_export=True, site="DC1", environment="prod" ) # 使用历史记录跟踪 result = analyze_file( input_file="mac_table.txt", history_dir="history", analyze_drift_flag=True, site="DC1", change_ticket="CHG-12345" ) ``` **API 参考**：请参阅 `shadowvendor/api.py` 获取完整的函数签名和返回值文档。有关代码示例和集成模式，请参阅 [TUTORIAL.md](TUTORIAL.md#for-contributors)。 ## 📥 支持的输入格式 **只需将您原始的 `show mac address-table` 输出粘贴到文件中；ShadowVendor 会自动检测格式。** 无需繁重的数据清洗——该工具会自动处理表头、空格和不同厂商的格式。 ShadowVendor 会自动检测并解析以下格式： ### 1. 简单的 MAC 地址列表 ``` 00:11:22:33:44:55 00-11-22-33-44-55 001122334455 0011.2233.4455 ``` ### 2. MAC 地址表（多厂商） **Cisco：** ``` Vlan Mac Address Type Ports 10 0011.2233.4455 DYNAMIC Gi1/0/1 ``` **HP/Aruba：** ``` Vlan Mac Address Type Ports 20 00:24:81:44:55:66 DYNAMIC 1 ``` **Juniper：** ``` Vlan Mac Address Type Ports 30 00:0E:83:11:22:33 DYNAMIC ge-0/0/0 ``` **Extreme：** ``` Vlan Mac Address Type Ports 40 B8-AC-6F-77-88-99 DYNamic 1:1 ``` **Brocade：** ``` Vlan Mac Address Type Ports 50 00:11:22:33:44:55 DYNAMIC 1/1 ``` ### 3. ARP 表 ``` Protocol Address Age (min) Hardware Addr Type Interface Internet 192.168.1.1 - 0011.2233.4455 ARPA Vlan10 ``` **格式检测特性：** - 基于内容的自动文件类型检测 - 灵活的 MAC 解析：接受冒号、连字符、点号和掩码/前缀格式 - 从多个来源（列、接口等）提取 VLAN - 端口提取，用于详细的交换机分析 - 跳过表头和稳健的错误处理 **想了解格式检测是如何工作的？** 请参阅 [TUTORIAL.md](TUTORIAL.md#file-type-detection) 了解详细的实现，以及如何添加对新的厂商格式的支持。 ## 📊 输出详情 ### 标准输出 **在变更窗口期间使用这些仪表板，以确认没有出现意外的厂商。**  **安全仪表板** - 每个 VLAN 的设备数量分析： - 识别具有高设备密度的 VLAN 以便进行安全监控 - 发现网络分段间设备分布的异常 - 为安全审查提供快速的可视化参考  **厂商仪表板** - 全面的多面板 VLAN 分析： - 设备数量、厂商多样性和热图 - 各网络分段的热门厂商分布 - 用于变更验证的跨 VLAN 厂商比较 **设备信息 CSV**（`{input_file}-Devices.csv`）： - 每个设备一行，包含列：MAC、Vendor、VLAN、Port - 始终生成 **端口报告 CSV**（`{input_file}-Ports.csv`）： - 端口利用率和设备映射 - 列：Port、Total Devices、VLANs、Vendors、Device Details - 仅针对 MAC 地址表生成（不适用于 ARP 或简单列表） **厂商分布 HTML**（`vendor_distribution.html`）： - 带有厂商分布饼图和 VLAN 分析子图的交互式仪表板 - 始终生成 **厂商摘要文本**（`vendor_summary.txt`）： - 带有格式化表格的厂商数量和百分比的纯文本摘要 - 始终生成 ### 可选输出 **SIEM 导出文件**（需要 `--siem-export`，写入 `output/siem/` 目录）： - `siem/shadowvendor_siem.csv`：带表头的行分隔 CSV 文件 - `siem/shadowvendor_siem.json`：JSONL 格式（每行一个 JSON 对象） - 两者包含相同的数据，具有用于 SIEM 关联的稳定 schema **历史归档文件**（需要 `--history-dir`）： - `vendor_summary-YYYYMMDD-HHMMSS.txt`：带有时间戳的厂商摘要快照 - `vendor_summary-YYYYMMDD-HHMMSS.metadata.json`：配套的元数据文件，包含： - `run_timestamp`：UTC ISO-8601 时间戳 - `site`：站点/区域标识符 - `change_ticket_id`：变更工单/事件 ID **漂移分析 CSV**（需要 `--analyze-drift`）： - `history/vendor_drift.csv`：跨越所有归档运行的厂商百分比趋势 - 顶部包含元数据行：`run_timestamp`、`site`、`change_ticket_id` - 厂商百分比行展示了随时间的变化 ## 🌟 成功案例与已知部署 ShadowVendor 被用于生产环境进行网络监控、安全态势跟踪和资产管理。虽然具体的部署细节保密，但该工具已成功部署于： - **企业 SOC 环境**：与 Elastic Stack 和 Splunk 集成，用于跨多个数据中心的持续态势变化检测 - **网络运营团队**：每日分析来自 Cisco、Juniper 和 Aruba 交换机的 MAC 地址表，以跟踪设备清单和厂商分布 - **气隙隔离网络**：离线模式在孤立的环境中实现了厂商识别，而无需依赖外部 API - **变更管理工作流**：带有变更工单关联的历史漂移分析可辅助事件响应和根因分析 **有想要分享的成功案例吗？** 我们很乐意听到您如何使用 ShadowVendor！请参阅 [社区部分](#-community) 了解如何贡献您的成功案例。 ## 🔒 安全注意事项 ShadowVendor 在设计时充分考虑了安全性： - **只读操作**：ShadowVendor 仅读取文本导出文件，不会对网络设备进行任何更改 - **本地优先处理**：输入文件和完整的 MAC 地址永远不会离开您的机器 - **默认模式**：未缓存的厂商查询仅向外部 API 发送 OUI 前缀（前 3 个八位字节）；所有其他处理均在本地进行 - **离线模式**：`--offline` 参数支持零外部网络调用的气隙隔离分析 - **对生产环境安全**：无设备修改，不存储凭据，无持久连接 - **HTML 仪表板**：打开生成的 HTML 可能会在您的浏览器中从 CDN 加载 Plotly - **代码安全扫描**：使用 Bandit 进行定期安全扫描，以检测潜在的漏洞和代码执行风险 对于正在评估该工具的安全团队：ShadowVendor 处理静态文本文件并在本地生成报告。它不会连接到网络设备或修改配置。如需了解完整的网络和 API 行为详情，请参阅 [ADVANCED.md — 网络与 API 行为](ADVANCED.md#network--api-behavior)。要报告 ShadowVendor 中的漏洞，请参阅 [SECURITY.md](SECURITY.md)。 ## 🔧 高级主题 ### 运维指南 有关高级主题和生产部署的详细信息，请参阅 **[ADVANCED.md](ADVANCED.md)**： - **态势变化检测与安全监控**：SIEM 集成工作流、关联规则和持续监控策略 - **运维最佳实践**：厂商查询优化、缓存管理、输出组织、故障排除和跨平台注意事项 - **运行时注意事项**：性能基准、网络行为、磁盘空间规划和错误处理细节 ### 技术深入探讨 **想了解 ShadowVendor 的底层工作原理？** 请参阅 **[TUTORIAL.md](TUTORIAL.md)** 获取全面的技术深入探讨，涵盖： - **架构概览**：模块化设计、组件关系、数据流 - **执行流程**：从代码执行到输出生成的逐步解读 - **核心组件**：文件类型检测、MAC 标准化、厂商查询系统、OUI 缓存管理 - **面向贡献者**：扩展点、添加新格式、测试策略、调试指南 **非常适合：** - 想要修改或扩展 ShadowVendor 的开发者 - 需要了解生产环境中行为的工程师 - 希望添加新功能或格式的贡献者 ## 🧪 测试与质量 **TL;DR**：全面的测试套件（41+ 个测试），涵盖所有执行路径、输入格式和功能。运行 `pytest -q` 进行快速验证。详情请参阅 [EXECUTION_PATHS.md](EXECUTION_PATHS.md) 和 [TEST_COVERAGE.md](TEST_COVERAGE.md)。 ShadowVendor 包含一个全面的测试套件，可验证所有执行路径、输入格式和功能，以确保可靠性和正确性。测试套件使用真实的网络设备输出和模拟数据进行可重现的验证。 ### 运行测试 **快速测试运行：** ``` pytest -q ``` **详细的测试输出：** ``` pytest -v ``` **运行特定的测试类别：** ``` # 测试所有执行路径（package entry、standalone script、Python API） pytest tests/test_execution_paths.py -v # 测试核心解析和格式检测 pytest tests/test_shadowvendor.py -v # 测试厂商查找和 caching pytest tests/test_oui_manager.py -v # 测试输出生成 pytest tests/test_vendor_output_handler.py -v # 测试 Python API pytest tests/test_api.py -v ``` **运行带有覆盖率报告的测试：** ``` pytest --cov=shadowvendor --cov-report=html ``` ### 测试覆盖率 **覆盖率摘要**：41+ 个测试，涵盖执行路径、配置、输入处理和错误处理。`tests/data/` 中的测试数据包含真实的 MAC 表、ARP 表和 MAC 列表。 **已测试内容：** - ✅ 执行路径（包入口、脚本、Python API） - ✅ 配置文件（INI、YAML、TOML）和环境变量 - ✅ 输入处理（MAC 列表、MAC 表、ARP 表） - ✅ 错误处理（缺失文件、空文件、无效输入） - ✅ 核心功能（解析、标准化、厂商查询） - ✅ 输出生成（CSV、HTML、端口报告） **详细的测试文档：** - **[EXECUTION_PATHS.md](EXECUTION_PATHS.md)** - 完整的执行路径文档 - **[TEST_COVERAGE.md](TEST_COVERAGE.md)** - 详细的测试覆盖率摘要 - **[TUTORIAL.md](TUTORIAL.md#test-strategy)** - 测试策略和调试指南 ### 安全扫描 **Bandit** 是一个安全 linter，用于扫描 Python 代码以查找常见的安全漏洞。它作为开发依赖包含在内，可以作为测试套件的一部分运行。 **安装：** ``` # 安装开发依赖项（包含 bandit、pytest、pytest-cov） pip install -r requirements-dev.txt ``` **将 Bandit 安全扫描器作为测试套件的一部分运行：** ``` # 运行所有测试并执行安全扫描 pytest --bandit # 运行特定测试并执行安全扫描 pytest tests/test_api.py --bandit -v ``` **Bandit 检查内容：** - SQL 注入漏洞 - 命令注入风险 - 不安全的加密函数使用 - 硬编码的密码和密钥 - 不安全的随机数生成 - 代码执行漏洞 - 以及其他安全反模式 **当前状态**：✅ 未发现安全问题（对有意设计的模式配置了排除项） **注意**：`--bandit` 参数会在执行测试之前运行安全扫描。如果发现安全问题，测试套件将在运行任何测试之前失败。Bandit 是一个**开发依赖**，正常的 ShadowVendor 使用不需要它。 ### 可选的 Linting/类型检查 如果在本地进行了配置： ``` ruff check . mypy shadowvendor ``` ## 📈 项目状态 **TL;DR**：积极维护，生产就绪。最新版本：[v14.0.0](https://github.com/StewAlexander-com/ShadowVendor/releases/tag/v14.0.0)，完成全面的品牌重塑、全面的测试和增强的文档。自 v14.0.0 起 API 和 CLI 保持稳定。  ShadowVendor 展示了全面的软件工程实践，包括测试驱动开发（41+ 个测试）、详尽的技术文档、注重安全的设计（离线模式、只读操作）以及生产就绪的功能（SIEM 集成、历史漂移分析、跨平台兼容性）。 ### 最新版本：v14.0.0 **主要版本：项目更名为 ShadowVendor** **主要亮点：** - 🎉 从 NetVendor 彻底更名为 ShadowVendor - ✅ 全面的测试套件（41+ 个涵盖所有执行路径的测试） - 📚 增强的文档（TUTORIAL.md、ADVANCED.md、EXECUTION_PATHS.md、TEST_COVERAGE.md） - 🐍 用于可编程使用的 Python API - ⚙️ 配置文件支持（INI、YAML、TOML） - 🧪 包含测试数据以用于快速入门示例 **近期的改进：** - 增强了 MAC 地址解析（Juniper、Aruba、Extreme、Brocade） - 带有元数据关联的历史漂移分析 - 带有用于态势变化检测的稳定 schema 的 SIEM 导出 - 用于故障排除和性能分析的运行时日志 - 支持气隙隔离网络的离线模式 ### 版本控制与稳定性 - **SIEM schema**：自 v14.0.0 起稳定 - **核心 CLI 参数**：自 v14.0.0 起稳定（向后兼容） - **Python API**：自 v14.0.0 起稳定 ### 计划中的功能 - 更多的厂商格式支持 - 额外的可视化选项 - 网络拓扑映射 - GitHub Discussions 和社区聊天频道 ## 🤝 社区 ShadowVendor 是一个开源项目，我们欢迎社区的贡献！ ### 获取帮助与报告问题 - **报告 Bug 或请求功能**：在 [GitHub 上开启一个 issue](https://github.com/StewAlexander-com/ShadowVendor/issues) - **提问**：对于一般性问题和使用案例，开启一个带有 "question" 标签的 GitHub issue - **安全漏洞**：请参阅 [SECURITY.md](SECURITY.md) —— 通过 [GitHub Security Advisories](https://github.com/StewAlexander-com/ShadowVendor/security/advisories/new) 私密报告 ### 贡献成功案例 我们很乐意听到您如何使用 ShadowVendor！通过以下方式分享您的成功案例： - 开启一个包含您的用例的 GitHub issue（根据需要进行匿名化处理） - 提交一个 pull request，将您的部署添加到 [成功案例部分](#-success-stories--known-deployments) - 在 issue 帖子中分享您的经验 ### 贡献代码 欢迎做出贡献！若要贡献代码： 1. Fork 该仓库 2. 创建一个功能分支 3. 进行您的更改 4. 如果适用，添加测试 5. 提交一个带有清晰描述您所做更改的 pull request ### 社区渠道 - **GitHub Discussions**：请参阅 [计划中](#-project-status) 部分了解即将推出的社区功能 - **社区聊天**：请参阅 [计划中](#-project-status) 部分了解即将推出的社区功能 ## 📄 许可证 本项目基于 [MIT 许可证](LICENSE) 授权。 ## 👤 作者 Stewart Alexander ## 🗺️ 快速导航 **浏览文档的常见路径：** 1. **初次使用用户工作流：** - 从这里开始（README.md） → [入门指南](#-getting-started) → [快速参考](#-quick-reference) → 尝试使用！ 2. **生产环境部署工作流：** - README.md → [高级主题](#-advanced-topics) → [ADVANCED.md](ADVANCED.md) → [CONFIG.md](CONFIG.md) 3. **了解内部原理工作流：** - README.md → [高级主题](#-advanced-topics) → [TUTORIAL.md](TUTORIAL.md) → [工作原理](TUTORIAL.md#how-it-works) 4. **贡献代码工作流：** - README.md → [TUTORIAL.md](TUTORIAL.md#for-contributors) → [扩展点](TUTORIAL.md#extension-points) → [测试策略](TUTORIAL.md#test-strategy) 5. **故障排除工作流：** - README.md → [TUTORIAL.md](TUTORIAL.md#troubleshooting) → [调试指南](TUTORIAL.md#debugging-playbook) → [ADVANCED.md](ADVANCED.md#-operational-best-practices) **💡 提示：** 为了获得最佳效果，请始终使用最新的 OUI 缓存并保持依赖项最新。并记住：当您知道网络上有什么设备时，网络会变得更有趣！😄

标签：Docker 部署, Mutation, Python, Ubuntu, 代码示例, 可视化, 域名侦查, 安全规则引擎, 数据分析, 无后门, 网络运维, 逆向工具