# iti/ics-security-tools architecture

> Architecture diagram of the GitHub repository iti/ics-security-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iti/ics-security-tools
- Repository: https://github.com/iti/ics-security-tools

## Overview

This is a community collection of ICS security tools, not one integrated application. The clearest end-to-end workflow in the sampled code is Grassmarlin’s packet-import path: capture parsers produce packet/import data, a session dispatches imports, and graph UI components present network models. The tree also documents Grassmarlin capabilities for Bro, Cisco, CSV and live imports, fingerprinting, serialization and SVG export; these are represented as subsystems where implementation links were not sampled. Other tools are independent. Evidence is limited to the README, tree and cited source-index references or excerpts.

Main entry points: [`tools/mirrored/grassmarlin/GM3/src/core/importmodule/inputIterators/pcap/PcapFileParser.java`](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/inputIterators/pcap/PcapFileParser.java) (PCAP parser), [`tools/mirrored/grassmarlin/GM3/src/core/document/Session.java`](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/document/Session.java) (Session), [`tools/mirrored/grassmarlin/GM3/src/core/importmodule/ImportItem.java`](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/ImportItem.java) (Import items), [`tools/mirrored/grassmarlin/GM3/src/core/importmodule/LogicalProcessor.java`](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/LogicalProcessor.java) (Logical processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Grassmarlin ingestion"]
  node_session["Session<br/>[Session.java]"]
  node_import["Import items<br/>[ImportItem.java]"]
  node_pcap["PCAP parser"]
  node_offline["Offline PCAP<br/>[PacketHandler.java]"]
  node_otherimports["Other importers"]
  node_pipeline["Import pipeline<br/>[Pipeline.java]"]
end

subgraph group_model["Analysis model"]
  node_logical["Logical processing"]
  node_packet["Packet data<br/>[PacketData.java]"]
  node_fingerprints["Fingerprints"]
  node_protocols["Protocol decoding"]
  node_topology["Network topology"]
  node_serialization["Session serialization"]
end

subgraph group_present["Visualization"]
  node_graphui["Graph views<br/>[Graph.java]"]
  node_treeui["Graph tree"]
  node_physicalui["Physical topology view"]
  node_svg["SVG export<br/>[iadgov.svgexport]"]
end

subgraph group_collection["Other tools"]
  node_serial2pcap["Serial capture conversion<br/>[libserial2pcap.py]"]
  node_serialreader["Serial reader"]
  node_modbus["SMOD Modbus<br/>[Modbus.py]"]
  node_scapy["Scapy shell<br/>[main.py]"]
end

node_user(("Analyst"))

node_user -.->|"submits imports"| node_session
node_session -->|"accepts"| node_import
node_import -->|"selects iterator"| node_pcap
node_import -.->|"keys iterators"| node_pipeline
node_pcap -->|"creates packet data"| node_packet
node_offline -->|"builds packet data"| node_packet
node_pcap -->|"queues hosts"| node_logical
node_offline -->|"references processor"| node_logical
node_logical -.->|"updates model"| node_topology
node_packet -.->|"provides packet fields"| node_fingerprints
node_pcap -->|"decodes frames"| node_protocols
node_session -->|"uses XML"| node_serialization
node_graphui -->|"wraps network graph"| node_topology
node_treeui -->|"extends graph controller"| node_graphui
node_physicalui -->|"extends controller"| node_treeui
node_svg -.->|"exports visualization"| node_user
node_serial2pcap -->|"uses reader"| node_serialreader
node_modbus -->|"uses Scapy"| node_scapy

click node_session "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/document/Session.java"
click node_import "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/ImportItem.java"
click node_pcap "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/inputIterators/pcap/PcapFileParser.java"
click node_offline "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/data/plugins/iadgov.offlinepcap/PacketHandler.java"
click node_otherimports "https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule"
click node_pipeline "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/Pipeline.java"
click node_logical "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/LogicalProcessor.java"
click node_packet "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/fingerprint/PacketData.java"
click node_fingerprints "https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/src/core/fingerprint"
click node_protocols "https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/src/core/protocol"
click node_topology "https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/src/core/document/graph"
click node_serialization "https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/src/core/document/serialization"
click node_graphui "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/ui/graphing/Graph.java"
click node_treeui "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/ui/graphing/GraphTreeController.java"
click node_physicalui "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/ui/graphing/physical/PhysicalGraphTreeController.java"
click node_svg "https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/data/plugins/iadgov.svgexport"
click node_serial2pcap "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/serial2pcap/libserial2pcap.py"
click node_serialreader "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/serial2pcap/Lib/SerialPortReader.py"
click node_modbus "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/smod/System/Core/Modbus.py"
click node_scapy "https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/smod/System/Lib/scapy/main.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_session,node_import,node_pcap,node_offline,node_otherimports,node_pipeline toneBlue
class node_logical,node_packet,node_fingerprints,node_protocols,node_topology,node_serialization toneAmber
class node_graphui,node_treeui,node_physicalui,node_svg toneMint
class node_serial2pcap,node_serialreader,node_modbus,node_scapy toneRose
class node_user toneIndigo
```

## Components

### Grassmarlin ingestion

- [Session](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/document/Session.java): `tools/mirrored/grassmarlin/GM3/src/core/document/Session.java`
- [Import items](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/ImportItem.java): `tools/mirrored/grassmarlin/GM3/src/core/importmodule/ImportItem.java`
- [PCAP parser](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/inputIterators/pcap/PcapFileParser.java): `tools/mirrored/grassmarlin/GM3/src/core/importmodule/inputIterators/pcap/PcapFileParser.java`
- [Offline PCAP](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/data/plugins/iadgov.offlinepcap/PacketHandler.java): `tools/mirrored/grassmarlin/GM3/data/plugins/iadgov.offlinepcap/PacketHandler.java`
- [Other importers](https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule): `tools/mirrored/grassmarlin/GM3/src/core/importmodule`
- [Import pipeline](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/Pipeline.java): `tools/mirrored/grassmarlin/GM3/src/core/importmodule/Pipeline.java`

### Analysis model

- [Logical processing](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/importmodule/LogicalProcessor.java): `tools/mirrored/grassmarlin/GM3/src/core/importmodule/LogicalProcessor.java`
- [Packet data](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/core/fingerprint/PacketData.java): `tools/mirrored/grassmarlin/GM3/src/core/fingerprint/PacketData.java`
- [Fingerprints](https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/src/core/fingerprint): `tools/mirrored/grassmarlin/GM3/src/core/fingerprint`
- [Protocol decoding](https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/src/core/protocol): `tools/mirrored/grassmarlin/GM3/src/core/protocol`
- [Network topology](https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/src/core/document/graph): `tools/mirrored/grassmarlin/GM3/src/core/document/graph`
- [Session serialization](https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/src/core/document/serialization): `tools/mirrored/grassmarlin/GM3/src/core/document/serialization`

### Visualization

- [Graph views](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/ui/graphing/Graph.java): `tools/mirrored/grassmarlin/GM3/src/ui/graphing/Graph.java`
- [Graph tree](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/ui/graphing/GraphTreeController.java): `tools/mirrored/grassmarlin/GM3/src/ui/graphing/GraphTreeController.java`
- [Physical topology view](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/grassmarlin/GM3/src/ui/graphing/physical/PhysicalGraphTreeController.java): `tools/mirrored/grassmarlin/GM3/src/ui/graphing/physical/PhysicalGraphTreeController.java`
- [SVG export](https://github.com/iti/ics-security-tools/tree/master/tools/mirrored/grassmarlin/GM3/data/plugins/iadgov.svgexport): `tools/mirrored/grassmarlin/GM3/data/plugins/iadgov.svgexport`

### Other tools

- [Serial capture conversion](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/serial2pcap/libserial2pcap.py): `tools/mirrored/serial2pcap/libserial2pcap.py`
- [Serial reader](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/serial2pcap/Lib/SerialPortReader.py): `tools/mirrored/serial2pcap/Lib/SerialPortReader.py`
- [SMOD Modbus](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/smod/System/Core/Modbus.py): `tools/mirrored/smod/System/Core/Modbus.py`
- [Scapy shell](https://github.com/iti/ics-security-tools/blob/master/tools/mirrored/smod/System/Lib/scapy/main.py): `tools/mirrored/smod/System/Lib/scapy/main.py`

### Other components

- **Analyst**

## Connections

- Analyst → Session: submits imports
- Session → Import items: accepts (evidence: `tools/mirrored/grassmarlin/GM3/src/core/document/Session.java`)
- Import items → PCAP parser: selects iterator (evidence: `tools/mirrored/grassmarlin/GM3/src/core/importmodule/ImportItem.java`)
- Import items → Import pipeline: keys iterators (evidence: `tools/mirrored/grassmarlin/GM3/src/core/importmodule/ImportItem.java`)
- PCAP parser → Packet data: creates packet data (evidence: `tools/mirrored/grassmarlin/GM3/src/core/importmodule/inputIterators/pcap/PcapFileParser.java`)
- Offline PCAP → Packet data: builds packet data (evidence: `tools/mirrored/grassmarlin/GM3/data/plugins/iadgov.offlinepcap/PacketHandler.java`)
- PCAP parser → Logical processing: queues hosts (evidence: `tools/mirrored/grassmarlin/GM3/src/core/importmodule/inputIterators/pcap/PcapFileParser.java`)
- Offline PCAP → Logical processing: references processor (evidence: `tools/mirrored/grassmarlin/GM3/data/plugins/iadgov.offlinepcap/PacketHandler.java`)
- Logical processing → Network topology: updates model (evidence: `tools/mirrored/grassmarlin/GM3/src/core/importmodule/LogicalProcessor.java`)
- Packet data → Fingerprints: provides packet fields (evidence: `tools/mirrored/grassmarlin/GM3/src/core/fingerprint/PacketData.java`)
- PCAP parser → Protocol decoding: decodes frames (evidence: `tools/mirrored/grassmarlin/GM3/src/core/importmodule/inputIterators/pcap/PcapFileParser.java`)
- Session → Session serialization: uses XML (evidence: `tools/mirrored/grassmarlin/GM3/src/core/document/Session.java`)
- Graph views → Network topology: wraps network graph (evidence: `tools/mirrored/grassmarlin/GM3/src/ui/graphing/Graph.java`)
- Graph tree → Graph views: extends graph controller (evidence: `tools/mirrored/grassmarlin/GM3/src/ui/graphing/GraphTreeController.java`)
- Physical topology view → Graph tree: extends controller (evidence: `tools/mirrored/grassmarlin/GM3/src/ui/graphing/physical/PhysicalGraphTreeController.java`)
- SVG export → Analyst: exports visualization
- Serial capture conversion → Serial reader: uses reader (evidence: `tools/mirrored/serial2pcap/libserial2pcap.py`)
- SMOD Modbus → Scapy shell: uses Scapy (evidence: `tools/mirrored/smod/System/Core/Modbus.py`)