eris-ot/marlinspike

# MarlinSpike 当前版本：`3.5.4` MarlinSpike 是一个从头构建的被动 OT/ICS 网络分析平台，继承了 GrassMarlin 风格的拓扑映射传统，并将其封装在一个专为实际任务设计的多用户 Web 工作台中。它分析 PCAP 和 PCAPNG 捕获文件，构建拓扑图，推断 Purdue 层级，识别设备供应商指纹，并提取出可供一线响应人员使用的风险指标（如跨区域通信、明文服务、信标活动、可疑外部通信和 DNS 隧道窃取），然后将所有内容导出为可移植的 JSON 报告产物，方便团队传递与共享。  **专为现场团队任务设计** — 多用户、零 JS 核心工作流、`1核心 / 1 GB RAM`，以及可移植的 JSON 报告产物。 **双语工作台** (English / Français) — 每个界面都可在语言之间切换，包括引擎发出的发现分类、描述和修复建议。 **2.45M 数据包 (1.7 GB) -> 2,449 个节点, 2,662 条边, 75 项发现，耗时 58 秒。** 代码库：[github.com/eris-ot/marlinspike](https://github.com/eris-ot/marlinspike) ## MarlinSpike 是什么 MarlinSpike 不仅仅是一个拓扑查看器，也不仅仅是一个数据包解析器。 它是一个围绕以下四个理念构建的可现场部署的分析师平台： - 被动 OT/ICS 分析优先：输入捕获文件，不会向网络发送任何数据包。 - 从头构建的 GrassMarline 风格替代品：现代化的拓扑重建、感知协议的分类以及对分析师友好的报告，且不继承旧的单用户桌面模型。 - 多用户工作台：支持项目、上传、报告、历史记录、管理，以及一个可供整个任务团队同时使用的共享 URL。 - 可移植报告契约：引擎可以在无头模式下运行，生成报告产物，这些产物可以在内置工作台中查看或在其他地方使用。 其结果是一种与桌面分析器不同的运行模式。MarlinSpike 旨在部署在临时任务主机上，接收来自分接头 (TAP)、SPAN 端口或外部采集的数据包捕获，并在分诊和评估期间支持协同使用。 ## 设计原则 MarlinSpike 是围绕一些实际约束构建的： - 引擎保持独立，并且可以在无头模式下生成报告产物。 - 报告产物是数据包分析和下游审查之间的交接物。 - 主工作流是 `项目 -> 扫描 -> 报告 -> 工作台 -> 分诊操作`。 - 核心 Web 工作流在没有客户端 JavaScript 的情况下仍然可用。 - 代码库特意保持可扩展性，面向 OT/ICS 一线响应人员，而不仅仅是系统程序员。 交互式浏览器功能可以提高速度和便利性，但核心的分诊体验仍然应该可以直接从渲染的 HTML 访问。 ## 亮点 - 仅被动分析：无主动扫描或数据包传输 - 支持 Modbus, EtherNet/IP, S7, DNP3, PROFINET, OPC UA, BACnet 等的 OT 协议解析 - 通过 `marlinspike-dpi` 扩展了 Rust DPI 基础：34 个协议解析器、Bronze v2 事件输出、帧完整性检查、ICMP 异常检查以及有状态的 L2 异常分析；bilgepump `parse_anomaly` 事件现在被消费并作为 `l2_anomalies` 显示在报告产物中，并且在 tshark 路径上收集每个数据包的 ARP 观测 (`arp_observations`)，用于下游的 ARP 分析插件 - 拓扑构建，支持 Purdue 层级推断和供应商指纹识别 - 风险呈现：包括远程访问暴露、类似 C2 的信标活动、可疑外部通道、DNS 熵异常、策略违规、完整的 MITRE ATT&CK 映射（包含战术、子技术、矩阵视图、响应指南）以及面向 IEC 62443 SR 的修复指导 - Flask Web UI，配备升级版多模式分析师工作台、项目管理、报告查看器、基线/漂移比较、资产清单、扫描历史记录，以及由数据源支持的 `/capabilities` 检测覆盖目录 - 双语 UI (English / Français) — Jinja 框架、JS 渲染的工作台面板以及引擎发出的发现类别/描述/修复建议，均通过自主研发的 JSON 字典 i18n 层进行切换，无需引入新的 pip 依赖；导航栏中提供区域设置选择器，在会话中持久保存，并支持 `Accept-Language` 回退机制 - IR 分诊工作台流程，包含两个新的左侧导航面板，与 NetworkMiner / Arkime / Wireshark / Corelight / Dragos 的共识模式对齐（来源 → 资产清单 → 流量统计 → 协议下钻 → 异常/IOC）：**流量统计**面板（捕获量 KPI、按字节数排列的主要会话、协议字节分布、主要源/目标端点、用于信标活动/高熵 DNS/未安全保护的 OPC 的会话异常标志），以及**协议下钻**面板（针对 Modbus, S7, DNP3, IEC 60870-5-104, CIP, MMS, GOOSE, BACnet, OMRON, PROFINET, OPC, DNS 的每个解析器证据 — 带有一个列出静默家族的名单头，因此某种协议的缺失本身就是报告的一部分） - 工作台中的 L2 / ARP 异常界面：bilgepump `mac_local` / `arp_spoof` / `mac_flap` 检测结果按异常类型分组，包含每个分组的计数、严重性直方图和代表性样本；ARP 观测结果同时展示 - 项目概览选项卡作为默认的项目着陆界面：遍历项目中的每份报告，跨捕获文件对资产（以 MAC 为主键，IP 为后备）和发现（`(category, sorted(affected_nodes), sorted(affected_edges))`）进行去重，将发现严重性提升至历史最高级别，并呈现一个汇总的 KPI 条带、严重性条形图、发现表格、资产清单、协议列表和 ATT&CK 覆盖芯片集 — 纯计算，无数据库 Schema 迁移 - 可通过 pip 安装的 Python 包 (v3.0.0)：`pip install marlinspike` 暴露出 `from marlinspike import create_app, db`；下游封装器（例如 cloudmarlin）可以通过新的 `csrf_exempt` 和 `set_concurrent_check_fn` 扩展钩子扩展应用程序，而无需 Fork - 可选的**实时捕获**边车容器 (`marlinspike-capd`，默认关闭，仅限 Linux)：非特权 Web 应用程序通过 unix 域套接字与特权守护程序通信；守护程序使用 2 GB 滚动环监督 `dumpcap`，实时验证 BPF 过滤器，枚举物理网卡，并将轮换后的 PCAP 输送到现有分析管道中，以便在捕获运行时在项目中积累报告。支持每个项目保存的过滤器库、每个接口的锁定以及管理员强制停止。参见 [docs/live-capture.md](docs/live-capture.md) - **扫描中恢复 (v3.4.0)：** Flask 重启不再导致扫描卡在 `running` 状态。引擎子进程被重新附加到 init/launchd 并继续执行直到完成；在下一次启动时，marlinspike 的回收程序会通过保存的 PID + argv 找到它（防御 PID 重用），重新附加一个监视线程，并在引擎退出时导入报告。已完成报告的死亡引擎会自动标记为完成；真正死亡的引擎会显示为 `failed` 并附带诊断信息 `error_tail`。可选的 `MARLINSPIKE_RUN_STORE=db` 模式通过 `scan_history` 路由活动运行的查找，以便在多个 Gunicorn worker 之间保持每层级的并发限制准确无误。参见 [docs/run-store-and-recovery.md](docs/run-store-and-recovery.md) - **地图优先工作台 + 多透镜关系图绘制 (v3.5.0)：** 分析师工作台围绕一个持久的**地图画布**进行了重建，顶部有一个**透镜芯片条**，右侧有一个**可停靠的检查器**，底部有一个带有七个选项卡表格的**向上滑出抽屉**（发现 / 会话 / 资产 / IOC / 异常 / ATT&CK / DNS）。六个透镜使用不同的边类型重新渲染地图：通信（主机-主机会话）、发现（按严重性排序的卡片覆盖层，支持点击跳转）、IOC（匹配资产的资产光晕）、ATT&CK（来自 `marlinspike-mitre` 插件输出的实时按战术分组技术网格，ICS + 企业领域）、基线（从项目级基线端点获取的按资产的新颖性卡片）以及同级（角色/供应商/Purdue 分组，带有基于上下文的异常标志）。所有实体渲染均源自一个正式的分类模块（`marlinspike/taxonomy.py`，12 个实体 + 12 种关系） — 每个页面上的每个芯片、徽章、表格列和工具提示都使用相同的真实数据源。参见 [docs/taxonomy.md](docs/taxonomy.md) 和 [docs/workbench-guide.md](docs/workbench-guide.md) - **HP-HMI 模式 (v3.5.0)：** 在应用范围内应用 ISA-101 / ASM Consortium 的规范。在导航栏（或工作台透镜条控制栏）中的切换开关可以将整个 UI 翻转为高性能 HMI 惯例 — 颜色专用于可操作的异常情况，设备去饱和为灰色，视线直接被吸引到报警状态的资产上。CRITICAL 和 HIGH 严重性保持醒目；MEDIUM / LOW / INFO 去饱和（属于信息性质，不可操作）。拓扑画布原地重新渲染 — 正常状态的资产褪色，报警状态的资产保留报警颜色。特别适用于控制室壁挂显示和密集网络分诊。按浏览器持久保存。参见 [docs/workbench-guide.md#hp-hmi-mode](docs/workbench-guide.md#hp-hmi-mode) - 使用 PostgreSQL 作为应用支持的 Docker Compose 部署 - 通过 [`marlinspike-dpi`](https://github.com/eris-ot/marlinspike-dpi) 提供的 Rust DPI 引擎默认启用 (`--dpi-engine auto`)，在镜像构建时从固定的 GitHub 引用内置 — 在大型捕获上比 Python tshark 后备方案快 14 倍 - MITRE ATT&CK 运行时数据源来自独立的 [`marlinspike-mitre`](https://github.com/eris-ot/marlinspike-mitre) 仓库，在镜像构建期间使用固定的 GitHub 引用 - 当提供构建参数时，可选的 Stage 4b 恶意软件 IOC 运行时数据源自独立的 `marlinspike-malware` 和 `marlinspike-malware-rules` 仓库 ## 快速开始 1. 克隆代码库并进入项目目录。 ``` git clone https://github.com/eris-ot/marlinspike.git cd marlinspike ``` 2. 复制示例环境文件并设置强密码。 ``` cp .env.example .env ``` 3. 构建并启动堆栈。 ``` docker compose up -d --build ``` 4. 在 `http://127.0.0.1:5001` 或通过您的反向代理打开应用。 首次启动时，MarlinSpike 会创建一个管理员用户。如果 `ADMIN_PASSWORD` 为空，则会生成一个随机密码并打印到容器日志中。 有关通用部署演练，请参见 [INSTALL.md](INSTALL.md)。 ## 文档 完整的文档索引位于 **[docs/README.md](docs/README.md)** — 它 按意图（操作员 / 管理员 / 开发者 / 架构 / 研究）对所有文档进行分组，并根据 您要执行的操作告诉您从哪里开始。 最常用的入口： **操作员（面向分析师）** - [docs/triage-methodology.md](docs/triage-methodology.md) — 分析师 循环，八步流程，请先阅读此文档。 - [docs/workbench-guide.md](docs/workbench-guide.md) — 报告查看器中的 每个面板。 - [docs/projects-and-engagements.md](docs/projects-and-engagements.md) — 项目模型、项目概览、多捕获工作流。 - [docs/asset-context.md](docs/asset-context.md) — 资产标记， 发现备注，上下文严重性覆盖。 - [docs/asset-baselines.md](docs/asset-baselines.md) — 按资产划分的 纵向页面，新颖性与基线对比。 - [docs/time-scrubbing-and-extract.md](docs/time-scrubbing-and-extract.md) — 时间窗口选择和子 PCAP 切割。 - [docs/ioc-threat-hunting.md](docs/ioc-threat-hunting.md) — `/iocs` 页面工作流。 - [docs/live-capture.md](docs/live-capture.md) — 可选的 capd 边车容器 (仅限 Linux)。 - [docs/mitre-attack-guide.md](docs/mitre-attack-guide.md) — 工作台中的 ATT&CK。 - [docs/i18n-and-locale.md](docs/i18n-and-locale.md) — 双语 工作 (EN/FR)。 **管理员 / 部署** - [INSTALL.md](INSTALL.md) — 安装、环境变量、部署模式。 - [docs/admin-and-audit.md](docs/admin-and-audit.md) — `/users`， `/audit`，密码重置，会话失效。 - [UPGRADING.md](UPGRADING.md) — 跨版本迁移。 **开发者 / 集成商** - [docs/cli-and-headless.md](docs/cli-and-headless.md) — 在无 Web 应用情况下 运行引擎。 - [docs/extensibility-contracts.md](docs/extensibility-contracts.md) — 三个扩展边界。 - [docs/bronze-consumer-contract.md](docs/bronze-consumer-contract.md) — DPI 引擎的 Bronze 事件契约。 - [docs/msbundle-format.md](docs/msbundle-format.md) — 提议的 压缩包格式。 **架构 / 方向** - [COMPATIBILITY.md](COMPATIBILITY.md) — 兼容性模型， 契约边界。 - [docs/repo-family.md](docs/repo-family.md) — 套件 + 组件 仓库模型。 - [docs/analyst-workspace-roadmap.md](docs/analyst-workspace-roadmap.md) / [docs/defender-features-roadmap.md](docs/defender-features-roadmap.md) — 产品方向。 **其他** - [CONTRIBUTING.md](CONTRIBUTING.md) — 贡献工作流。 - [releases.md](releases.md) — 发布历史。 - [presets/README.md](presets/README.md) — 预设样本库。 - 组件仓库：[`plugins/marlinspike_mitre/`](plugins/marlinspike_mitre/)， [`rules/mitre/base.yaml`](rules/mitre/base.yaml)， [`scripts/sync-mitre-bootstrap.sh`](scripts/sync-mitre-bootstrap.sh)， [`scripts/update-subtrees.sh`](scripts/update-subtrees.sh)， [`scripts/sync-msengine-bootstrap.sh`](scripts/sync-msengine-bootstrap.sh)。 此代码库中关键的可扩展性术语是： - Rust 引擎：面向数据包和事件密集型的组件，例如 DPI - Python 插件：面向报告的分析、丰富化和分诊逻辑 - YAML 规则包：声明式映射、抑制规则和本地策略 关键的仓库族术语是： - `marlinspike`：套件仓库，将选定的组件仓库作为基于子树的子仓库进行供应，并可以固定独立的构建依赖项 - `marlinspike-msengine`：核心引擎仓库，内部包和 CLI 名称为 `msengine` - `marlinspike-workbench`：Web UI 仓库，可以在调用或不调用本地引擎的情况下查看报告 - `marlinspike-mitre`：独立的共享 MITRE ATT&CK 插件仓库，作为固定的构建依赖项被运行时插件和规则表面所消费 - `marlinspike-dpi`：独立的共享 Rust DPI 仓库，在应用镜像中作为固定的构建依赖项被消费 - `marlinspike-malware`：独立的共享 Rust IOC 引擎仓库，在应用镜像中作为可选的固定构建依赖项被消费 - `marlinspike-malware-rules`：独立的共享规则内容仓库，用于已发布的 IOC 包、清单和编译的包产物，作为可选的固定构建依赖项被消费 组件仓库是权威来源。套件仓库的存在是为了为希望使用一个包含所有更新部分的克隆的团队固定和供应一个已知良好的组合。 最初的 `msengine/` 子树前缀现在以引导程序的形式存在。在完全提取完成之前，根目录下的 `_ms_engine.py` 仍然是操作引擎源码，[`scripts/sync-msengine-bootstrap.sh`](scripts/sync-msengine-bootstrap.sh) 会将其镜像到子树副本中。 当前的 Docker 构建默认通过 `MARLINSPIKE_DPI_REF` 将 `marlinspike-dpi` 固定到 `326bdbb744a7b8f71295381fd209d9587dc09a3b` (发布版本 v1.7.0)，通过 `MARLINSPIKE_MITRE_REF` 将 `marlinspike-mitre` 固定到 `c3583ec2d189b8cde69f2160da6a5e8e5b643f7b`，通过 `MARLINSPIKE_MALWARE_REF` 将 `marlinspike-malware` 固定到 `02eb369c32e5050796c76be500c009dc0cb8940d`，并通过 `MARLINSPIKE_MALWARE_RULES_REF` 将 `marlinspike-malware-rules` 固定到 `99cbe9358d0a5047d9b5e57a7e4ff5eafdee9bd4`。在 2026 年 3 月 28 日，规则引用被刷新为有效的已发布提交，并且确认恶意软件仓库在固定的引用处是公开可读的。如果您需要不同的已知良好组合，请在您的环境中覆盖这些构建参数。应用在发现规则时优先使用已发布的 `packs/` 而非引擎仓库的开发/测试副本。 ## ATT&CK 演练 MarlinSpike 现在在报告工作流程中包含完整的 ATT&CK 实现， 包括 ATT&CK 版本元数据、按战术分组的矩阵视图、子技术、 缓解措施和响应指导。 请在此处查看面向用户的演练： - [docs/mitre-attack-guide.md](docs/mitre-attack-guide.md) 该指南包含屏幕截图，并解释了在分诊期间如何在发现、 ATT&CK 映射、资产和拓扑之间进行跳转。 ## 定位：分析师工作台 vs 桌面工具 MarlinSpike 不是一个通用的桌面分析器。它是专为 OT 安全任务和评估构建的临时现场分析师工作台。 | 方面 | MarlinSpike (本项目) | 典型的桌面版 GRASSMARLIN 风格工具 | |------|------|------| | **主要用例** | 在工厂车间评估期间，在 IPC 或现场笔记本电脑上启动，审查团队收集的 PCAP，并交还便携式评估产物 | 在单个工作站上进行单人深度分析 | | **用户模型** | 多用户、项目范围的工作流，具有身份验证、管理控制和审计历史记录 | 通常首先是单用户 | | **部署** | 轻量级 Docker Compose Web 应用，具有零 JS 核心工作流和 `1 core / 1 GB RAM` 目标 | 桌面 GUI 应用程序，具有较重的客户端运行时预期 | | **报告工作流** | PCAP 从任何地方生成独立的 JSON 报告产物，可在此处查看或在其他地方消费，外加 PDF/PNG/CSV 导出 | 以工具为中心的工作流，与本地应用程序紧密耦合 | | **运行模型** | 任务团队的共享 URL，快速设置和拆卸，适用于临时或隔离的现场使用 | 永久性分析师桌面环境 | | **可扩展性** | Python 分析管道和 HTML 模板，对大多数安全团队来说易于上手 | 通常以编译的桌面技术栈为中心，定制化门槛更高 | 简而言之： 将 MarlinSpike 放置在隔离或临时的任务主机上，将 URL 分发给团队，将其收集的捕获文件输入进去，导出干净的可移植 JSON 报告，并在工作完成后将其卸载。 如果您正在寻找一个具有不同功能侧重点的永久性单用户桌面应用程序，那么 MarlinSpike 并不试图成为那样的工具，这是有意为之的。 ## 与 GrassMarlin 的功能对等性 MarlinSpike 旨在取代人们过去使用 GrassMarlin 的核心被动映射工作流，同时将其外围环境从单用户桌面应用程序转变为共享的 Web 工作台。 | 能力 | MarlinSpike 状态 | 备注 | |------|------|------| | 被动 PCAP 分析 | 是 | 从 Web UI 或独立引擎接受 `pcap` 和 `pcapng` | | 感知 OT 的拓扑映射 | 是 | 关系图、节点/边图、供应商提示和 Purdue 推断 | | 资产清单 | 是 | 每个资产的角色、服务、协议和面向响应者的上下文 | | 感知协议的 OT 分析 | 是 | Modbus, EtherNet/IP, S7, DNP3, PROFINET, OPC UA, BACnet, IEC 104, LLDP/CDP/STP/LACP 等 | | 从被动流量中发现风险 | 是 | 明文工程访问、可写入路径、可疑外部通信、信标活动、DNS 窃取和 Purdue 违规 | | 可导出的输出 | 是 | 可移植的 JSON 报告产物，外加通过 UI 提供的 PDF/PNG/CSV 导出路径 | | 团队分析师工作流 | 超出预期 | 项目范围的合作、共享 URL 访问、历史记录、基线/漂移审查和管理控制是一等公民，而不是后期附加的 | | 无头分析契约 | 超出预期 | 引擎可以独立运行，发出可移植的报告产物，并在稍后在工作台或其他地方进行审查 | | 臃肿的桌面客户端 | 设计上的不同 | 被基于浏览器的工作台和零 JS 核心工作流取代，用于临时的、共享的现场部署 | ### 积极改进中 - 跨越更多供应商和设备系列的指纹深度和分类置信度 - 查看器中服务器渲染的分析师向下钻取流程 - 在报告 UI 中更丰富地使用 Bronze 级别的协议观测和提取的产物 - 在当前报告契约之外更广泛的协议原生丰富化 ### 明确的界限 - MarlinSpike 是一个 **PCAP 分析工具**，而不是一个连续监控平台。使用您自己的工具（Wireshark, tshark, 分接器, SPAN 端口）进行捕获，并将 PCAP 带入 MarlinSpike 进行分析。对于连续的实时捕获、多传感器收集和集中的 OT 网络监控，请参见 [FATHOM](https://github.com/eris-ot)。 - MarlinSpike 不是一个主动扫描器。 - MarlinSpike 不是一个永久性的重型桌面客户端。 - 独立的 Rust DPI 引擎是一个解剖基础，而不是整个产品。 - 一些协议覆盖和更高级别的评分目前仍然存在于 Python 分析层中，这是设计使然。 ## 引擎架构 MarlinSpike 将数据包解剖与分析师工作流分开。 ### 当前分析栈 - 阶段 1：捕获导入和验证 - 阶段 2：协议解剖 - 阶段 3：拓扑构建，Purdue 推断和指纹识别 - 阶段 4：违规分诊和风险呈现 - 输出：由 Web 工作台消费的可移植 JSON 报告产物 ### DPI 引擎选项 MarlinSpike 目前可以通过两种方式运行阶段 2： - 通过 `_ms_engine.py` 内置的基于 Python/tshark 的解剖 - 通过 [`marlinspike-dpi`](https://github.com/eris-ot/marlinspike-dpi) 的外部 Rust 解剖 Rust 路径被有意限定为独立的 DPI 引擎。MarlinSpike 可以将其作为外部阶段 2 解析器调用，将其 Bronze 输出重新适配到当前的报告管道中，并继续使用现有的拓扑、分诊和报告层。这使得数据包解析器可重用，而不必强迫分析师产品并入该解析器。 ### `marlinspike-dpi` 目前的意义 - 它是一个独立的 Rust DPI 引擎，具有 CLI、库和 FFI 接口。 - 它接受经典的 `pcap` 和 `pcapng` 捕获输入。 - 它目前提供了 34 个跨 OT/ICS, IT 和 L2 流量的协议解析器。 - 它发出 MarlinSpike 可以跨五个系列消费的 Bronze v2 事件：协议事务、资产观测、拓扑观测、解析异常和提取的产物。 - 它通过 `stovetop` 帧完整性检查、`icmpeeker` ICMP 异常分析和 `bilgepump` 有状态的 L2 异常跟踪，分层次进行额外的解析器相关检查。 - 它替代了解剖阶段，而不是更高级别的违规分诊逻辑。 这是有意为之的。MarlinSpike 的价值不仅仅在于快速解码数据包。它的价值在于将被动 OT 流量转化为拓扑、发现和团队可以实际使用的响应决策。 ### 可扩展性模型 MarlinSpike 刻意使用了三个扩展面： - Rust 引擎：面向数据包或事件密集型的组件，在这些组件中吞吐量、内存安全性和解析器复用最为重要。目前这主要是指像 [`marlinspike-dpi`](https://github.com/eris-ot/marlinspike-dpi) 这样的 DPI 风格引擎。 - Python 插件：面向报告的分析、丰富化、分诊逻辑和后处理，它们对可移植的 MarlinSpike JSON 产物进行操作，而不是对原始数据包进行操作。 - YAML 规则包：声明式映射、启用/禁用控制、站点覆盖和其他策略内容，供插件使用，而无需将配置变成另一种编程语言。 简而言之： - Rust 从原始流量中发现事实。 - Python 将这些事实转化为面向响应者的判断。 - YAML 声明映射和本地。 这种拆分是有意为之的。MarlinSpike 并不是“全面使用 Rust”编写的，因为主应用程序的目的是为了方便更广泛的 OT/ICS 社区（包括响应者、防御者和顾问）进行扩展，他们可能需要在主动修复事件期间调整逻辑。Rust 非常适合内存安全的、可重用的数据包引擎。当团队主动对环境进行分诊时，Python 仍然是快速迭代、特定于站点的扩展和对现场友好的报告逻辑的更好选择。 当前随附的示例： - `marlinspike-mitre`：位于 `marlinspike-mitre` 的权威姐妹仓库，应用镜像现在在构建期间将固定独立仓库中的运行时插件和规则表面覆盖到 [`plugins/marlinspike_mitre/`](plugins/marlinspike_mitre/) 和 [`rules/mitre/base.yaml`](rules/mitre/base.yaml)。成功的扫描可以发出 `-mitre.json` 边车产物，并且工作台查看器可以从报告的 `extensions` 表面加载它。 当前的运行时公开了完整的 ATT&CK 元数据和版本控制、战术、子技术、适配矩阵的战术分组、缓解措施、ATT&CK URL 以及查看器中丰富的响应指导。 面向用户的解读说明位于 [docs/mitre-attack-guide.md](docs/mitre-attack-guide.md)。 - `marlinspike-malware`：位于 `marlinspike-malware` 的权威姐妹仓库，`_ms_engine.py` 将其作为可选的阶段 4b 引擎调用。如果在镜像构建期间提供了 `MARLINSPIKE_MALWARE_REPO` 和 `MARLINSPIKE_MALWARE_REF`，则运行时二进制文件会被分层到 `/opt/marlinspike-malware/bin/` 中。 - `marlinspike-malware-rules`：位于 `marlinspike-malware-rules` 的权威姐妹仓库，包含已发布的 `packs/`、`manifests/index.yaml` 和编译的包产物。当前已发布的表面为 30 个包和 921 条规则。如果在镜像构建期间提供了 `MARLINSPIKE_MALWARE_RULES_REPO` 和 `MARLINSPIKE_MALWARE_RULES_REF`，这些资产将被分层到 `/usr/share/marlinspike-malware/rules/`，并且引擎指向 `/usr/share/marlinspike-malware/rules/packs`。 有关 Rust 引擎、Python 插件和 YAML 规则包的具体契约边界，请参见 [`docs/extensibility-contracts.md`](docs/extensibility-contracts.md)。 如果您正在决定新工作属于哪里，请使用以下经验法则： - 如果它消费原始的 `pcap`、数据包流或大容量协议事件，那么它可能属于 Rust 引擎。 - 如果它消费完成的 MarlinSpike 报告产物，那么它可能属于 Python 插件。 - 如果分析师应该能够在不更改代码的情况下对其进行调整，那么它可能属于 YAML 规则包。 ## 检测和标准覆盖 MarlinSpike 目前公开的检测和标准情况有意限定为引擎目前已经发出的内容。 - 完整的 MITRE ATT&CK 实现现在通过共享的 `marlinspike-mitre` 运行时提供，包括 ATT&CK 版本元数据、按战术分组的矩阵输出、子技术、父技术上下文、缓解措施和响应指导 - `marlinspike-dpi` 现在提供了更广泛的被动可观测表面：34 个协议解析器、Bronze v2 事件系列，以及来自 `stovetop`、`icmpeeker` 和 `bilgepump` 的解析器相关异常流 - Purdue 模型推断和跨层级通信检查是核心分诊工作流程的一部分 - 阶段 4 修复指南与当前引擎生成的发现类别的 IEC 62443 SR 要求保持一致 - 已部署的实例在 `/capabilities` 发布了一个内置的检测覆盖目录，该目录明确表述为 MarlinSpike 能够检测到的内容，而不是它在特定环境中已经检测到的内容 - `/capabilities` 页面现在将当前的报告发现类别、`marlinspike-dpi` 解析器覆盖范围、`marlinspike-malware` 可观测项和规则覆盖范围，以及当前的 ATT&CK 映射集，归类到可按来源、类型、系列、严重性和搜索进行过滤的控件之后 - 当前的 `marlinspike-malware` 部分反映了已发布的 `marlinspike-malware-rules` 内容表面（现为 30 个包和 921 条规则），ATT&CK 部分反映了由 `marlinspike-mitre` 提供的完整的 ATT&CK 实现 这现在被定位为 MarlinSpike 面向报告工作流的完整 ATT&CK 实现。它仍然有意识地限定为被动流量证据和分析师分诊，而不是更广泛的合规交叉比对或每一种可能的 ATT&CK 分析。 ## 功能概述 MarlinSpike 将原始数据包捕获转化为 OT 操作员、资产所有者或响应人员实际可以使用的工作流。 ### 分析 - 具有感知 OT 协议解剖的被动 PCAP 和 PCAPNG 分析 - 具有 Purdue 推断的关系图和拓扑重建 - 具有风险发现、C2 指标和资产上下文的报告驱动分诊 - 详细的资产清单、服务暴露、会话分析和 MAC 表报告 ### 工作流 - 从 Web UI 执行临时扫描 - 多捕获处理，包括带有流式进度的大型 PCAP 处理 - 用于捕获和报告的项目范围组织 - 项目概览选项卡作为默认的项目着陆界面 — 跨项目中的每个捕获进行跨报告聚合（资产去重、带严重性提升的发现去重、协议汇总、ATT&CK 覆盖） - 报告历史记录、重试支持以及报告产物之间的基线与漂移比较 - 可在 MarlinSpike 内部或其他地方查看的可移植 JSON 报告产物 ### 管理 - 具有管理员控制的多用户访问 - 扫描历史记录和审计跟踪 - 系统健康和监控视图 - 样本库管理 ## 导出支持 报告工作流支持直接从 UI 导出： - 从报告查看器打印或保存为 PDF - 从拓扑查看器导出 PNG - 从资产清单视图导出 CSV ## 项目概览 — 跨报告聚合 大多数任务产生的捕获文件不止一个。一个站点可能在一周内每天都进行捕获，或者在同一天对不同的交换机进行分接捕获，或者同一个 PCAP 可能在规则更改后重新运行。MarlinSpike 过去将这些报告并排展示为独立的报告产物；分析师必须在脑海中对它们进行合并。 项目概览选项卡替您完成了这种合并，并且是您打开项目时的默认界面。 它的作用是： - 遍历项目中的每份报告（引擎报告以及通过现有扩展桥接器——APT, ARP, MITRE——展示的任何插件边车产物）。 - 首先按 MAC，其次按 IP 对资产进行去重。每条资产记录包含 `first_seen_report` / `last_seen_report` 和一个 `report_count`。 - 按 `(category, sorted(affected_nodes), sorted(affected_edges))` 对发现进行去重。严重性提升为跨报告所见的最高级别；最新的报告用于描述文本。每项发现显示其出现次数为 `seen in N of M reports`。 - 汇总跨报告的协议和 ATT&CK 技术覆盖范围。 - 渲染一个 KPI 条带、一个严重性分布条形图、一个按严重性及出现次数排序的发现表格、一个带有固定过滤工具栏的资产清单、一个协议分布芯片集以及一个 ATT&CK 覆盖芯片集。 它不是什么： - 不是数据库迁移。聚合是对磁盘上的 JSON 报告产物进行的纯计算，每次打开选项卡时运行。没有 Schema 变更，没有额外存储，也没有后台作业。 - 不是对单报告查看器的替代。单报告的 MITRE 矩阵、证据跳转、基线/漂移和报告级别的导出路径仍然位于报告本身上。将概览用于“这项任务总体上是什么样子”，而将特定报告用于“这次捕获中发生了什么”。 聚合 API 在 `/api/projects//aggregate` 公开，供希望消费相同汇总数据而无需渲染选项卡的工具使用。根据 v2.4.0 发行说明，聚合器在单报告去重、跨报告去重、严重性提升、IP 后备键、ATT&CK 汇总、扫描配置文件细分和加载器故障隔离方面进行了单元测试；Playwright 冒烟测试涵盖了完整的 登录 → 项目选择 → 概览渲染 → KPI / 严重性条形图 / 发现排序 / 资产过滤 / 选项卡切换 路径。 ## 其他功能 - 基线和漂移审查，包含添加、移除、更改和未更改的拓扑比较 - 活动扫描期间的实时拓扑查看 - 扫描阶段进度流式传输，可见导入、分析、分类和报告状态 - 每用户管理控制，包括密码重置和上传限制 - 多报告生命周期操作，包括查看、下载、删除和比较 - 从扫描历史记录中重试失败或中断的扫描 - 具有类别管理和 PCAP 上传/删除控制的样本库管理 - 扫描工作流中的捕获过滤输入和临时端口抑制控制 - 与主评估视图并排的 MAC 表报告 ## 屏幕截图 点击任何缩略图查看全尺寸图像。 ### 项目概览（跨报告聚合） 项目概览选项卡是默认的项目着陆界面。它将项目中的每份报告汇总到一个视图中：KPI、严重性分布、按严重性及出现次数排序的去重发现，以及带有固定过滤工具栏的资产清单。严重性条形图一目了然地显示了分布情况及内联计数，发现表格跟踪了每个不同的发现出现在项目多少份报告中（`SEEN IN` 列）。资产和发现记录默认以 MAC 为主键，IP 作为后备，并带有首次/最后一次出现在报告中的归属。 此屏幕截图是在 4SICS 基准项目上捕获的，运行了三天的 `4SICS-GeekLounge` 捕获（`151020`、`151021`、`151022`）以及一次 `151022` 的重跑，共计四份报告。聚合器将四个捕获中的 119 次发现去重为 96 个不同的发现和 48 个独特的资产。

Project Overview after rolling up four 4SICS reports — 4 reports, 48 unique assets, 96 distinct findings, 15 protocols, 2 ATT&CK techniques mapped. Findings table shows occurrence counts as `seen in N of M` and is sorted by severity then occurrences.

### v3.x 工作流界面 跨 v3.0 → v3.3 添加的功能，是在一个包含 4 份报告的 4SICS 任务中捕获的。每个都链接到其操作员指南。

Live Capture (guide) — optional marlinspike-capd sidecar daemon (Linux only). Enumerates physical NICs, validates BPF against the active interface's DLT, supervises dumpcap with a 2 GB rolling ring, and feeds rotated PCAPs into the existing analysis pipeline. Per-project saved-filter library, per-interface locking, admin-override stop.	IOC Threat-Hunting (guide) — per-project IOC lists with bulk-paste import (auto-detects IPv4/v6, MAC, OUI, sha256, md5, domain). Cross-report scan walks every report in the project and matches against nodes, conversations, c2_indicators, risk_findings, dns_queries, and malware_findings.
IOC scan results — cross-report hit table with match surface (node / conversation / c2_indicator), report attribution, severity, and label. Capped at 1000 hits per scan.	Per-asset baselines (guide) — longitudinal profile across every report in a project for one asset. Identity drift detection on vendor / role / device-type, protocol-mix history, peer first-seen / last-seen attribution, finding cadence buckets, anomaly cadence, and the headline novelty-vs-baseline card flagging what's new in the latest capture.
Time-window scrubbing + sub-PCAP extract (guide) — adaptive packet-rate histogram below the workbench toolbar. Drag to select a window; every conversation-driven pane filters live. Per-conversation Extract button carves out a sub-PCAP scoped to the window for Wireshark-level inspection.	Asset context (guide) — site-specific tagging (owner, criticality, zone, business function) drives a contextual-severity overlay on findings. Tagging an asset critical bumps every finding touching it one tier; tagging low drops all-low findings one tier.
Audit log (guide) — admin-only view of every auth.* and capture.* event the app emits. Filters by event type, username, status. Color-coded success / failure pills. Tracks actor user + role + IP at time of event.	Workbench Intel mode (guide) — protocol coverage chips, ATT&CK technique detail with response guidance and IEC 62443 alignment, per-tactic detection coverage. Both Enterprise ATT&CK and ICS ATT&CK are loaded.

### 实时工作流验证 这些屏幕截图来自一次实时端到端冒烟测试，捕获于 2026 年 3 月 28 日，针对当前托管部署，运行了三个预设 PCAP 后获取：`Modbus.pcap`、`S7comm.pcap` 和 `fast` 模式下的 4SICS 基准。它们展示了核心响应者路径：`项目 -> 扫描 -> 报告 -> 工作台 -> 资产`。

Dashboard with the scan workspace surfaced as the operational starting point.	Project-scoped workspace showing the engagement container used to keep the smoke outputs isolated.
Scan history with multiple completed runs, including the large-PCAP benchmark path.	The operator shell on the 4SICS benchmark report with priority targets, auth gaps, and write paths in view.
A smaller protocol-specific validation pass against Modbus showing the same workbench flow on a focused OT capture.	Assets mode turns the validated report into a sortable responder ledger with device context and risk evidence.

Topology viewer and analyst workbench	Assessment findings and report review
Asset inventory and device context	Large-PCAP execution with live progress
Scan history and audit trail	Project-scoped workflow
Multi-user administration	Baseline and drift review

### 升级的分析师工作台 分析师工作台现在被构建为一个完整的操作员外壳，而不是单一的拥挤查看器。持久的左侧导航栏承载着工作台身份、报告上下文、模式导航和实用工具，而中心舞台和右侧检查器则专注于活跃的分诊工作。 当前的外壳支持 `Dashboard`, `Map`, `Findings`, `Evidence`, `Assets`, `Intel`, `Risk` 和 `Reports` 界面，而无需试图将每个工作流都塞进拓扑画布中。 此屏幕截图来自公开的 `marlinspike-dpi` 更新后的实时验证报告产物，并展示了查看器现在使用的更为密集的操作员外壳。

The operator shell uses a full-height navigation rail, compact status strip, single-row command bar, and persistent inspector so the first viewport stays focused on responder work.

其他屏幕截图详细显示了基于模式的工作台界面。

Evidence mode surfaces enriched sessions, identity clues, hunt pivots, and preserved DPI observables.

Findings mode gives responders a dedicated triage surface instead of forcing everything into the map.

Assets mode turns the workbench into a searchable ledger with evidence density and asset context.

较旧的实时屏幕截图作为特定于协议的验证示例仍然有用：

Live MQTT workbench with preserved client, topic, and asset enrichment.

Live RADIUS workbench with auth metadata, object refs, and triage context.

Live FTP workbench after the public parser panic fix shipped to production.

## 配置 主要环境变量包括： - `DB_PASSWORD`: PostgreSQL 密码 - `SECRET_KEY`: Flask 会话密钥 - `ADMIN_PASSWORD`: 初始管理员密码 - `PCAP_MAX_SIZE`: 最大可接受的上传大小（字节，默认：5 GB） - `MARLINSPIKE_DPI_ENGINE`: DPI 引擎选择 — `auto` (默认，可用时使用 Rust)、`marlinspike-dpi` 或 `python` - `MARLINSPIKE_DPI_BIN`: `marlinspike-dpi` 二进制文件的路径 (默认：从 PATH 自动检测) ## 源码布局 规范的应用程序模块包括： - `_ms_engine.py` - `_auth.py` - `_models.py` - `_config.py` - `app.py` 不带下划线的模块 (`auth.py`、`models.py`、`config.py`) 是兼容性垫片，以便旧工具仍然可以导入它们而不会偏离真正的源代码。 ## 示例数据 公共代码库不捆绑方的 PCAP 语料库。如果您想要一个预设的样本库，请在部署后通过本地 `presets//` 目录或管理员 UI 添加捕获文件。 ## 开发 - `python3 -m py_compile app.py _auth.py _config.py _models.py _ms_engine.py` - `docker compose up --build` 有关贡献指南，包括正在进行的指纹识别和丰富化工作，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## Fathom MarlinSpike 是 [Erisforge Ltd.](https://github.com/eris-ot/marlinspike) 商业 OT 安全平台 **Fathom** 的开源核心。 商业 Fathom 平台增加了分布式收集器、层次结构、数据二极管、取证时间回溯和企业级基线学习。MarlinSpike 是您可以在任何地方启动的轻量级、开源核心工作台。 了解更多信息，请访问 [github.com/eris-ot/marlinspike](https://github.com/eris-ot/marlinspike)。 ## 致谢 MarlinSpike 之所以变得更好，是因为人们花时间测试它、阅读代码并提交问题或 PR。社区贡献者： - **[Michael Sargis (@MichaelMVS)](https://github.com/MichaelMVS)** — 发现了 `ICS_OUI_DB` 中隐藏的 OUI 字典冲突，该问题导致 Honeywell 设备在每份报告中被误识别为 GE ([PR #3](https://github.com/eris-ot/marlinspike/pull/3), v2.0.3) - **Jerrid Brown** (OTPulse) — 将真实的 DCS 数据包捕获通过 MarlinSpike 运行，并暴露了多个分类和 UX 问题，推动了 v2.0.1 / v2.0.2 的修复 (组播错误分类、OUI 网关 MAC 错误归因、NO_AUTH_OBSERVED 噪音、Level 3 "Application Server" 兜底逻辑、Purdue L3 与 L4 启发式判断) 如果您发现错误或有指纹需要添加，[请提交问题](https://github.com/eris-ot/marlinspike/issues) 或 [发送 PR](https://github.com/eris-ot/marlinspike/pulls) — 非常欢迎首次贡献者。 ## 许可证 本代码库采用 GNU Affero 通用公共许可证 v3.0 授权。参见 [LICENSE](LICENSE)。 ## 联系方式 有问题？请在 [github.com/eris-ot/marlinspike/issues](https://github.com/eris-ot/marlinspike/issues) 提交问题。

标签：AES-256, AMSI绕过, Beacon Object File, DNS泄露检测, Docker安全容器, Flask开发, Grassmarlin替代, ICS/SCADA安全, IP 地址批量处理, MarlinSpike, OT安全, PCAP分析, PKINIT, 便携式安全工具, 信标检测, 可视化界面, 多用户平台, 威胁检测, 工控协议分析, 工控安全, 开源安全工具, 插件系统, 数据可视化, 普渡模型, 测试用例, 漏洞评估, 网络安全, 网络拓扑分析, 蓝队评估, 被动网络发现, 请求拦截, 资产指纹识别, 跨区通信分析, 逆向工具, 逆向工程平台, 防御绕过, 隐私保护, 风险评估报告