cognis-digital/wavewatch

# wavewatch **从捕获文件中进行离线 RF 信号侦察与分类处理。** wavewatch 使用纯 Python 编写的 DSP 核心，完全离线地从标准 IQ 和频谱捕获文件中检测、提取指纹并对无线电辐射源进行分类。它将原始录音转换为可重现的、机器可读的分析结果——并为每次分类提供决策追踪记录——从而使 RF 分类处理能够直接融入自动化分析 pipeline 中。 由 Cognis Digital 提供的工具。 ## 范围：防御性，合规性设计 wavewatch **仅用于分析**。它只读取捕获文件并报告其观察到的内容。 - **无发射路径。** 此软件包中没有任何能够发射 RF 的功能。 - **无干扰或对抗措施。** 干扰检测器仅标记扫频/压制式干扰和 GNSS 欺骗的*特征*，以便分析师能够评估链路的健康状况——它们绝不生成或对抗信号。 - **无 payload 解调。** 辐射源通过其*稳定性和循环平稳特征*进行标记，而不是通过解码其内容。这是一种刻意为之的隐私保护及合规性设计选择。 - **无武器化。** 不包含任何瞄准、引导或控制功能。 这些边界由测试套件 (`tests/test_defensive_scope.py`) 强制执行，因此任何增加攻击性能力的更改都将导致 CI 失败。 请仅在您被授权记录和分析的信号上运行 wavewatch，并遵守适用的法律和频谱管理规定。 ## 核心特性 - **零第三方运行时依赖。** 仅需 Python 3.11+ 标准库。 FFT（基-2 Cooley–Tukey + 用于任意长度的 Bluestein 算法）、PSD (Welch)、频谱图以及带注解的**PNG 编码器** (`zlib` + `struct`) 均从零开始实现。不依赖 NumPy、SciPy、PIL 或 matplotlib。 - **无需 SDR 硬件即可运行。** 支持 **SigMF**、**WAV-IQ** 和 **CSV 功率谱**。内置合成信号生成器，意味着测试和演示无需外部数据。 - **辐射源检测。** 支持 CFAR / 能量带检测、突发信号分段以及跳频信号分组。 - **指纹与分类。** 通过相位抖动、频率稳定性、频谱平坦度和循环平稳特征，在不解码任何 payload 的情况下，为辐射源标记可能的分类（`drone-link` / `wifi` / `ble` / `gnss` / `unknown`）并给出置信度评分。 - **干扰标记。** 标记扫频和压制式干扰特征，以及 GNSS 欺骗提示（与 `spoofwatch` 互操作）。 - **可重现的决策。** 每次分类都包含其特征、阈值以及逐步的决策追踪记录。 - **输出。** 支持 JSON、SARIF 风格的分析结果、GeoJSON（当存在位置元数据时）以及带注解的频谱图 PNG。 - **MCP server。** 提供一个独立的 JSON-RPC/stdio MCP server，为 agent pipeline 暴露 `analyze_capture` 工具。 ## 安装说明 ``` pip install . # 或者直接从 checkout 运行，无需安装： python -m wavewatch --help ``` 需要 Python 3.11+。仅在运行测试时需要 `pytest`。 ## 快速开始 分析一个合成场景（无需捕获文件）并生成所有输出： ``` python -m wavewatch analyze --scenario drone-link \ --json out/report.json --sarif out/findings.sarif \ --geojson out/emitters.geojson --png out/spectrogram.png ``` 分析真实的捕获文件（根据扩展名自动检测格式）： ``` python -m wavewatch analyze capture.sigmf-meta --json - python -m wavewatch analyze recording.wav --png spec.png python -m wavewatch analyze spectrum.csv --json report.json ``` 将合成的捕获文件生成到磁盘（SigMF 或 WAV-IQ）： ``` python -m wavewatch generate wifi --out samples/wifi # SigMF python -m wavewatch generate ble --out samples/ble.wav # WAV-IQ ``` 可用场景：`noise`、`tone`、`wifi`、`drone-link`、`ble`、`gnss`、`sweep`、`barrage`。 ## 库用法 ``` from wavewatch import analyze_capture, load_capture, generate capture, _ = generate("drone-link") # or: load_capture("capture.sigmf-meta") report = analyze_capture(capture) print(report.summary()) for e in report.emitters: emitter = e.emitter cls = e.classification print(emitter["rf_center_hz"], cls["label"], cls["confidence"]) for step in cls["decision_trace"]: print(" ", step) ``` ## MCP server 运行 stdio MCP server 并从 agent 中调用 `analyze_capture` 工具： ``` python -m wavewatch serve-mcp ``` 该 server 通过 JSON-RPC 2.0（每行一条 JSON 消息）实现 `initialize`、`tools/list` 和 `tools/call`。`analyze_capture` 接受捕获 `path` 或合成 `scenario`，并以 JSON 或 SARIF 格式返回结构化的分析结果。 ## 工作原理 1. **数据摄取** — 将捕获文件读取到内存中的 `Capture` 对象（IQ 采样或预计算的频谱），包含采样率、中心频率和可选的地理位置信息。 2. **信号转换** — 使用纯 Python 的 DSP 核心计算 Welch PSD 和 STFT 频谱图。 3. **信号检测** — 通过 CFAR 风格的频带检测分割已占用的频谱；逐频带的突发分段用于测量时域活动；散布在整个频段内的窄带、突发信道将被分组为单个跳频辐射源。 4. **提取指纹** — 针对每个辐射源，在原始采样上测量稳定性和结构特征（相位抖动、频率稳定性、频谱平坦度、循环平稳强度）——绝不涉及 payload。 5. **执行分类** — 通过可解释的成员资格规则对每个类别进行评分；得分最高者获胜，并且特征、阈值和推理过程将被记录为决策追踪。 6. **标记与报告** — 干扰检测器添加干扰/欺骗标记，并将结果以 JSON / SARIF / GeoJSON / 带注解的 PNG 格式输出。 ## 捕获格式 | 格式 | 读取 | 写入 | 备注 | | -------------- | :--: | :---: | -------------------------------------------------------- | | SigMF | ✓ | ✓ | `cf32`, `cf64`, `ci16`, `ci8`, `cu8` (+ 实数变体) | | WAV-IQ | ✓ | ✓ | 双通道 (I=左, Q=右), 16位 PCM 或 32位 float | | CSV 频谱 | ✓ | ✓ | `frequency,power` 行，或单一功率列 | 提供了一个仅用于接收的实时捕获适配器*接口* (`wavewatch.io.live.LiveCaptureAdapter`)，可用于外部 SDR 后端。核心代码 不附带任何硬件驱动程序，并保持基于文件和完全离线的状态。刻意设计为 没有发射功能。 ## 测试 ``` python -m pytest -q ``` 该套件涵盖了针对直接 DFT 的 FFT 正确性、PSD/频谱图行为、 每个检测器和分类器路径、所有读写器、PNG 编码器有效性、 MCP server 和 CLI、边缘情况（空 / 仅含 DC / 纯噪声 / 削峰 捕获）以及防御性范围的防护措施。 ## 许可证 MIT — 请参阅 [LICENSE](LICENSE)。

标签：MCP, Python标准库, 信号情报, 图数据库, 射频信号分析, 数字信号处理, 无线检测, 逆向工具