# Architecture

> Packet dissection, topology, triage, and reporting stay intentionally separate, the five-stage chain, DPI options, protocol coverage, and outputs.

*Canonical HTML: https://grassmarlin.com/wiki/architecture/*
*Markdown source: https://grassmarlin.com/wiki/architecture.md*
*Français: https://grassmarlin.com/fr/wiki/architecture.md*

---

MarlinSpike's architecture is built around a clean responder workflow: passive capture input, a legible multi-stage analysis chain, a portable report artifact, and a shared workbench that does not have to own every downstream use.

**Five-stage chain**, Ingest, dissect, topology, risk, then report.

**Portable report boundary**, The report artifact is the handoff between packet analysis and downstream review.

**Field-first UX**, The workbench is designed for shared OT engagements, not generic packet tinkering.

## Product boundary

MarlinSpike's value is not just packet decoding. The product is the combination of passive analysis, topology reconstruction, asset context, responder-facing findings, and a workbench that can be shared during a live engagement.

The repository documentation keeps returning to the same contract boundary:

- The engine remains capable of producing a finished report artifact headlessly.
- The report artifact becomes the handoff between packet analysis and review.
- The web workbench consumes that report for collaboration, triage, export, and history.
- Core workflows remain usable without making JavaScript mandatory for the primary responder path.

## Five-stage analysis chain

The architecture described in the README breaks down into a simple pipeline:

| Stage | Purpose |
|---|---|
| 1. Capture ingestion | Validate `pcap` or `pcapng`, extract basic metadata, and prepare the input for dissection. |
| 2. Protocol dissection | Parse OT protocols, L2 discovery protocols, and network conversations. |
| 3. Topology construction | Build the node and edge graph, infer Purdue placement, fingerprint vendors, and assign roles. |
| 4. Risk surfacing | Identify cross-zone issues, suspicious external communications, beaconing, DNS entropy anomalies, and other responder-grade findings. |
| 5. Report | Emit the portable JSON artifact the workbench and downstream tooling can consume. |

## DPI options and layering

Stage 2 can currently run two ways:

- The built-in Python and tshark path in `_ms_engine.py`.
- The external Rust dissection path via `marlinspike-dpi`.

The documentation is explicit that the Rust path replaces the packet-facing dissection stage, not the whole product. Topology shaping, triage logic, and report construction remain above it.

## Protocol coverage and findings surface

The current public docs describe MarlinSpike as OT-aware by default, with coverage for protocols such as Modbus, EtherNet/IP, S7, DNP3, PROFINET, OPC UA, BACnet, IEC 104, and L2 discovery families like LLDP, CDP, STP, and LACP.

The responder-facing findings story is equally important. The project docs call out surfaces such as:

- Cross-Purdue and cross-zone communication review
- Cleartext services and write-capable paths
- Suspicious external communications
- Beaconing and connection persistence patterns
- DNS exfiltration indicators
- Selected MITRE ATT&CK mappings and IEC 62443 SR-oriented remediation support

## Outputs and exports

The workbench is built around more than just a topology graph. The docs list these output surfaces as first-class:

- Portable JSON report artifacts
- Topology and relationship review
- Asset inventory and service context
- C2 indicators and risk findings
- PDF, PNG, and CSV export paths from the UI
- Baseline versus drift comparison between reports

The repo-family docs explain the suite repo, component repos, subtree model, and the current transition state for engine and workbench extraction. See [Repo family](/wiki/repo-family.md) and [Extensibility](/wiki/extensibility.md).

Source references: [README.md](https://github.com/eris-ot/marlinspike/blob/main/README.md)