OT Gateway & Industrial Protocols

The OT Gateway bridges your ITSM Automation platform with Operational Technology networks. It provides protocol translation for industrial systems (Modbus TCP/RTU, DNP3, IEC 61850, OPC UA, BACnet, PROFINET, EtherNet/IP) and enables automated incident creation from SCADA/PLC alerts while maintaining air-gap safety boundaries enforced by the IEC 62443 zone model and a configurable data diode.

Safety-critical operations: Write operations to OT registers and control commands require the ot:write permission scope and are logged to an immutable audit trail retained for 365 days. The gateway enforces Purdue model zone boundaries via IEC 62443 conduit rules -- all cross-zone traffic is validated against allowed protocols, directions, and security levels before forwarding.

Supported protocols

The gateway ships with protocol adapters for the most common industrial communication standards.

Protocol	Transport	Adapter ID prefix	Capabilities
Modbus TCP	TCP/IP	`modbus_tcp_`	Register read/write, coil control, polling
Modbus RTU	Serial RS-485	`modbus_rtu_`	Register read/write, serial polling
DNP3	TCP/Serial	`dnp3_`	Unsolicited responses, integrity polls, event classes
IEC 61850	MMS/GOOSE	`iec61850_`	MMS data access, GOOSE pub/sub, SCL import
IEC 60870-5-104	TCP	`iec104_`	Telecontrol, interrogation commands
OPC UA	TCP	`opc_ua_`	Node browsing, subscriptions, historical access
OPC DA	DCOM	`opc_da_`	Item read/write, group subscriptions
BACnet	UDP/IP	`bacnet_`	Object read/write, COV subscriptions
MQTT	TCP/TLS	`mqtt_`	Topic pub/sub, Sparkplug B payloads
PROFINET	Ethernet	`profinet_`	Cyclic I/O, acyclic read/write
EtherNet/IP	TCP/UDP	`ethernet_ip_`	CIP explicit/implicit messaging

The OT device model

The OT device model describes a registered industrial asset with its protocol configuration, network addressing, IEC 62443 security zone placement, alarm state, and CMDB linkage.

Properties

Name
id
Type
string
Description
Unique identifier for the OT device (UUIDv4).
Name
name
Type
string
Description
Human-readable device display name.
Name
description
Type
string
Description
Optional description of the device's purpose or function.
Name
protocol
Type
string
Description
Communication protocol. One of MODBUS_TCP, MODBUS_RTU, DNP3, IEC61850, IEC104, OPC_UA, OPC_DA, MQTT, BACNET, PROFINET, ETHERNET_IP, GOOSE, or MMS.
Name
device_class
Type
string
Description
Device classification. One of PLC, RTU, HMI, SCADA_SERVER, DCS, SENSOR, ACTUATOR, GATEWAY, METER, IED, HISTORIAN, RELAY, SWITCH, TRANSFORMER, BREAKER, or RECLOSER.
Name
manufacturer
Type
string
Description
Device manufacturer (e.g., Siemens, Allen-Bradley, SEL).
Name
model
Type
string
Description
Device model number.
Name
serial_number
Type
string
Description
Unique hardware serial number.
Name
address
Type
object
Description
Network address configuration. Contains ip_address (string), mac_address (string), hostname (string), and ports (integer array).
Name
unit_id
Type
integer
Description
Modbus unit ID or DNP3 outstation address.
Name
zone
Type
string
Description
IEC 62443 security zone identifier. Zones enforce allowed protocols, authentication requirements, and encryption policies.
Name
security_level
Type
integer
Description
IEC 62443 security level (0-4). SL0 = no requirements, SL4 = state-sponsored attack resilience.
Name
status
Type
string
Description
Current device status. One of active, inactive, maintenance, decommissioned, commissioning, or faulted.
Name
last_poll_at
Type
timestamp
Description
Timestamp of the last successful data poll from the device.
Name
poll_interval_ms
Type
integer
Description
Configured polling interval in milliseconds (100 - 60000).
Name
registers
Type
array
Description
Configured register/data-point mappings. Each entry contains address (string), name (string), data_type (string), scale_factor (number), unit (string), and quality (object with online, valid, stale booleans).
Name
alarms
Type
array
Description
Active alarms on this device. Each entry contains id (string), severity (string), message (string), state (string), triggered_at (timestamp), and threshold (number).
Name
firmware_version
Type
string
Description
Currently installed firmware version.
Name
auto_ticket
Type
boolean
Description
When true, alarms from this device automatically create ITSM tickets using the linked template.
Name
ticket_template_id
Type
string
Description
Template ID for auto-created tickets from alarm events.
Name
ci_id
Type
string
Description
CMDB Configuration Item reference for IT/OT asset federation.
Name
location
Type
object
Description
Physical location. Contains site (string), building (string), substation (string), bay (string), rack (string), and optional coordinates object with latitude/longitude.
Name
tags
Type
array
Description
Freeform tags for filtering and grouping.
Name
org_id
Type
string
Description
Organization that owns this device.
Name
created_at
Type
timestamp
Description
Timestamp of when the device was registered.
Name
updated_at
Type
timestamp
Description
Timestamp of the last update to the device record.

GET/v1/ot/devices

List OT devices

This endpoint returns a paginated list of registered OT devices. You can filter by protocol, device class, zone, status, site, and manufacturer. Results are sorted by updated_at descending by default.

Optional attributes

Name
limit
Type
integer
Description
Maximum number of devices to return. Default 20, maximum 100.
Name
offset
Type
integer
Description
Number of devices to skip for pagination.
Name
protocol
Type
string
Description
Filter by protocol, e.g. MODBUS_TCP, DNP3, IEC61850.
Name
device_class
Type
string
Description
Filter by device class, e.g. PLC, RTU, SCADA_SERVER.
Name
zone
Type
string
Description
Filter by IEC 62443 zone identifier.
Name
status
Type
string
Description
Filter by status: active, inactive, maintenance, faulted, commissioning, or decommissioned.
Name
site
Type
string
Description
Filter by physical site location.

Request

GET

/v1/ot/devices

curl -G http://localhost:3000/v1/ot/devices \
  -H "Authorization: Bearer {token}" \
  -d limit=10 \
  -d protocol=MODBUS_TCP \
  -d status=active

Response

{
  "has_more": true,
  "data": [
    {
      "id": "d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04",
      "name": "Pump Station PLC #12",
      "protocol": "MODBUS_TCP",
      "device_class": "PLC",
      "manufacturer": "Siemens",
      "model": "S7-1500",
      "serial_number": "SN-S7-2024-00312",
      "address": {
        "ip_address": "10.20.3.112",
        "hostname": "plc-pump-12.ot.local",
        "ports": [502]
      },
      "unit_id": 1,
      "zone": "zone_control_north",
      "security_level": 2,
      "status": "active",
      "last_poll_at": 1708732800,
      "poll_interval_ms": 1000,
      "firmware_version": "4.5.2",
      "auto_ticket": true,
      "ci_id": "CI-OT-00312",
      "location": {
        "site": "Plant North",
        "building": "Pump House B",
        "substation": null,
        "bay": "Bay 3"
      },
      "tags": ["critical-infrastructure", "water-treatment"],
      "org_id": "org_7xKpQ2mR4wVb",
      "created_at": 1706140800,
      "updated_at": 1708732800
    },
    {
      "id": "a3b1c9d7-5e2f-48a6-b7c4-9d1e6f3a8b52"
      // ...
    }
  ]
}

POST/v1/ot/devices

Register an OT device

This endpoint registers a new OT device with the gateway. The device is placed into the specified IEC 62443 zone and the gateway begins polling at the configured interval. Protocol-specific validation is applied to the address and unit_id fields.

Required attributes

Name
name
Type
string
Description
Human-readable name for the device.
Name
protocol
Type
string
Description
Communication protocol for this device.
Name
device_class
Type
string
Description
Classification of the device (e.g., PLC, RTU, METER).
Name
manufacturer
Type
string
Description
Device manufacturer name.
Name
model
Type
string
Description
Device model number.
Name
serial_number
Type
string
Description
Hardware serial number.
Name
address
Type
object
Description
Network address configuration with ip_address or serial port path.
Name
zone
Type
string
Description
IEC 62443 security zone to place this device in.
Name
security_level
Type
integer
Description
Required security level (0-4).
Name
location
Type
object
Description
Physical location with at minimum a site field.

Optional attributes

Name
unit_id
Type
integer
Description
Modbus unit ID or DNP3 outstation address. Defaults to 1.
Name
poll_interval_ms
Type
integer
Description
Polling interval in milliseconds. Defaults to 1000.
Name
auto_ticket
Type
boolean
Description
Enable automatic ticket creation from alarms. Defaults to false.
Name
ticket_template_id
Type
string
Description
Template for auto-created tickets.
Name
firmware_version
Type
string
Description
Current firmware version installed on the device.
Name
tags
Type
array
Description
Freeform tags for grouping.

Request

POST

/v1/ot/devices

curl -X POST http://localhost:3000/v1/ot/devices \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Substation RTU - Feeder 4",
    "protocol": "DNP3",
    "device_class": "RTU",
    "manufacturer": "SEL",
    "model": "SEL-3530",
    "serial_number": "SN-SEL-2024-08741",
    "address": {
      "ip_address": "10.20.5.41",
      "ports": [20000]
    },
    "unit_id": 4,
    "zone": "zone_control_substation",
    "security_level": 3,
    "location": {
      "site": "Substation East",
      "substation": "Sub-E-04",
      "bay": "Feeder Bay 4"
    },
    "poll_interval_ms": 2000,
    "auto_ticket": true,
    "ticket_template_id": "tmpl_ot_critical_alarm",
    "firmware_version": "R148-V0",
    "tags": ["substation", "distribution", "critical"]
  }'

Response

{
  "id": "c7e2f1a9-4b8d-4c3e-9a5f-1d7b6e2c8f03",
  "name": "Substation RTU - Feeder 4",
  "protocol": "DNP3",
  "device_class": "RTU",
  "manufacturer": "SEL",
  "model": "SEL-3530",
  "serial_number": "SN-SEL-2024-08741",
  "address": {
    "ip_address": "10.20.5.41",
    "ports": [20000]
  },
  "unit_id": 4,
  "zone": "zone_control_substation",
  "security_level": 3,
  "status": "commissioning",
  "last_poll_at": null,
  "poll_interval_ms": 2000,
  "firmware_version": "R148-V0",
  "auto_ticket": true,
  "ticket_template_id": "tmpl_ot_critical_alarm",
  "ci_id": null,
  "location": {
    "site": "Substation East",
    "substation": "Sub-E-04",
    "bay": "Feeder Bay 4"
  },
  "tags": ["substation", "distribution", "critical"],
  "org_id": "org_7xKpQ2mR4wVb",
  "created_at": 1708733100,
  "updated_at": 1708733100
}

GET/v1/ot/devices/:id

Get device details

This endpoint retrieves the full details of a single OT device, including its current register values, active alarms, health summary, and firmware compliance status. Register values reflect the most recent poll.

Request

GET

/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04

curl http://localhost:3000/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04",
  "name": "Pump Station PLC #12",
  "protocol": "MODBUS_TCP",
  "device_class": "PLC",
  "manufacturer": "Siemens",
  "model": "S7-1500",
  "serial_number": "SN-S7-2024-00312",
  "address": {
    "ip_address": "10.20.3.112",
    "hostname": "plc-pump-12.ot.local",
    "ports": [502]
  },
  "unit_id": 1,
  "zone": "zone_control_north",
  "security_level": 2,
  "status": "active",
  "last_poll_at": 1708732800,
  "poll_interval_ms": 1000,
  "registers": [
    {
      "address": "40001",
      "name": "discharge_pressure_psi",
      "value": 62.4,
      "data_type": "FLOAT32",
      "scale_factor": 0.1,
      "unit": "PSI",
      "quality": { "online": true, "valid": true, "stale": false }
    },
    {
      "address": "40003",
      "name": "flow_rate_gpm",
      "value": 1250.8,
      "data_type": "FLOAT32",
      "scale_factor": 0.01,
      "unit": "GPM",
      "quality": { "online": true, "valid": true, "stale": false }
    },
    {
      "address": "00001",
      "name": "pump_running",
      "value": true,
      "data_type": "BOOL",
      "scale_factor": 1,
      "unit": null,
      "quality": { "online": true, "valid": true, "stale": false }
    }
  ],
  "alarms": [
    {
      "id": "alm_9d2e7f4a-1b3c-4e8f",
      "severity": "warning",
      "message": "Discharge pressure approaching high limit",
      "state": "ALARM",
      "triggered_at": 1708732500,
      "threshold": 65.0
    }
  ],
  "firmware_version": "4.5.2",
  "auto_ticket": true,
  "ticket_template_id": "tmpl_ot_critical_alarm",
  "ci_id": "CI-OT-00312",
  "location": {
    "site": "Plant North",
    "building": "Pump House B",
    "bay": "Bay 3",
    "coordinates": {
      "latitude": 40.7128,
      "longitude": -74.006
    }
  },
  "tags": ["critical-infrastructure", "water-treatment"],
  "org_id": "org_7xKpQ2mR4wVb",
  "created_at": 1706140800,
  "updated_at": 1708732800
}

PATCH/v1/ot/devices/:id

Update device configuration

This endpoint updates the configuration of a registered OT device. You can change polling intervals, zone placement, auto-ticket settings, and metadata. Changing the zone triggers a re-validation against IEC 62443 conduit rules.

Optional attributes

Name
name
Type
string
Description
Updated display name.
Name
poll_interval_ms
Type
integer
Description
New polling interval in milliseconds.
Name
zone
Type
string
Description
New IEC 62443 zone placement.
Name
status
Type
string
Description
Updated status (e.g., transitioning to maintenance).
Name
auto_ticket
Type
boolean
Description
Enable or disable automatic ticket creation.
Name
tags
Type
array
Description
Replacement tag set.

Request

PATCH

/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04

curl -X PATCH http://localhost:3000/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "poll_interval_ms": 500,
    "auto_ticket": true,
    "status": "active",
    "tags": ["critical-infrastructure", "water-treatment", "high-priority"]
  }'

Response

{
  "id": "d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04",
  "name": "Pump Station PLC #12",
  "protocol": "MODBUS_TCP",
  "device_class": "PLC",
  "status": "active",
  "poll_interval_ms": 500,
  "auto_ticket": true,
  "tags": ["critical-infrastructure", "water-treatment", "high-priority"],
  "updated_at": 1708733200
}

DELETE/v1/ot/devices/:id

Remove an OT device

This endpoint deregisters an OT device from the gateway. Active polling is stopped, subscriptions are cancelled, and the device is moved to decommissioned status. Historical alarm and data records are retained per the audit retention policy (default 365 days).

Request

DELETE

/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04

curl -X DELETE http://localhost:3000/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04 \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04",
  "status": "decommissioned",
  "decommissioned_at": 1708733400,
  "alarms_retained_until": 1740269400,
  "data_retained_until": 1740269400
}

GET/v1/ot/devices/:id/registers

Read current register values

This endpoint triggers a live poll of the device and returns the current register/data-point values. Each value includes a quality flag indicating whether the reading is valid, stale, or out of range. For Modbus devices this reads holding registers and coils; for DNP3 this performs a Class 0 integrity poll; for IEC 61850 this reads configured data attributes via MMS.

Optional attributes

Name
addresses
Type
string
Description
Comma-separated list of register addresses to read. If omitted, all configured registers are polled.

Request

GET

/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04/registers

curl -G http://localhost:3000/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04/registers \
  -H "Authorization: Bearer {token}" \
  -d addresses=40001,40003

Response

{
  "device_id": "d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04",
  "polled_at": 1708732850,
  "poll_duration_ms": 23,
  "data": [
    {
      "address": "40001",
      "name": "discharge_pressure_psi",
      "value": 63.1,
      "data_type": "FLOAT32",
      "unit": "PSI",
      "quality": {
        "online": true,
        "valid": true,
        "over_range": false,
        "under_range": false,
        "stale": false,
        "substituted": false
      },
      "timestamp": 1708732850
    },
    {
      "address": "40003",
      "name": "flow_rate_gpm",
      "value": 1248.3,
      "data_type": "FLOAT32",
      "unit": "GPM",
      "quality": {
        "online": true,
        "valid": true,
        "over_range": false,
        "under_range": false,
        "stale": false,
        "substituted": false
      },
      "timestamp": 1708732850
    }
  ]
}

POST/v1/ot/devices/:id/registers/write

Write to a register

This endpoint writes a value to a device register or data point. Write operations are safety-critical and require the ot:write permission scope. Every write is validated against the device's zone security policy and logged to the immutable audit trail. A safety confirmation token is required for writes to devices in zone types SAFETY or BASIC_CONTROL.

This is a controlled operation. The gateway enforces select-before-operate (SBO) semantics for DNP3 control relay output blocks and IEC 61850 command operations. Direct operate is available for Modbus register writes.

Required attributes

Name
address
Type
string
Description
Target register address (e.g., 40001 for Modbus, binary/analog output index for DNP3).
Name
value
Type
number | boolean | string
Description
Value to write. Type must match the register's configured data type.

Optional attributes

Name
operation
Type
string
Description
Control operation type: direct_operate, select, operate, cancel. Defaults to direct_operate for Modbus, select for DNP3/IEC 61850.
Name
safety_token
Type
string
Description
Required for writes to safety-zone devices. Obtained from the safety confirmation flow.
Name
reason
Type
string
Description
Reason for the write operation, stored in the audit log.

Request

POST

/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04/registers/write

curl -X POST http://localhost:3000/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04/registers/write \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "40010",
    "value": 55.0,
    "operation": "direct_operate",
    "reason": "Adjusting setpoint per WO-2024-1847"
  }'

Response

{
  "success": true,
  "operation": "direct_operate",
  "address": "40010",
  "value_written": 55.0,
  "previous_value": 60.0,
  "timestamp": 1708732900,
  "audit_id": "aud_3kNpL7mS9wYr",
  "audit_trail": {
    "user": "ops_engineer@company.com",
    "permission": "ot:write",
    "device_id": "d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04",
    "zone": "zone_control_north",
    "reason": "Adjusting setpoint per WO-2024-1847",
    "logged_at": 1708732900
  }
}

GET/v1/ot/devices/:id/alarms

Get device alarm history

This endpoint returns the alarm history for a specific device. Alarms are returned in reverse chronological order. You can filter by severity, status, and time range. Alarm aggregation groups related alarms by correlation key to reduce noise.

Optional attributes

Name
severity
Type
string
Description
Filter by severity: critical, major, minor, or warning.
Name
status
Type
string
Description
Filter by alarm status: active, acknowledged, cleared, or shelved.
Name
limit
Type
integer
Description
Maximum number of alarms to return. Default 50, maximum 200.
Name
since
Type
timestamp
Description
Only return alarms after this timestamp.

Request

GET

/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04/alarms

curl -G http://localhost:3000/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04/alarms \
  -H "Authorization: Bearer {token}" \
  -d severity=critical \
  -d limit=25

Response

{
  "has_more": false,
  "data": [
    {
      "id": "alm_b4c2d8e1-5f7a-4c9b-a3e6-2d8f1b7c4a09",
      "source_id": "d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04",
      "tag_name": "discharge_pressure_psi",
      "message": "Discharge pressure exceeded high-high limit (75 PSI)",
      "severity": "critical",
      "severity_numeric": 1,
      "status": "acknowledged",
      "state": "ACKNOWLEDGED",
      "category": "PROCESS",
      "current_value": 76.2,
      "threshold": 75.0,
      "limit_type": "high_high",
      "area": "Pump House B",
      "equipment": "Pump Station PLC #12",
      "timestamp": 1708731600,
      "event_time": 1708731600,
      "acknowledged_at": 1708731900,
      "acknowledged_by": "ops_engineer@company.com",
      "ticket_id": "TKT-2024-00892",
      "correlation_id": "corr_pump12_pressure_001"
    },
    {
      "id": "alm_a1d9c3f7-8b2e-4a6d-b5c1-3e9f7a2d8b04",
      "source_id": "d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04",
      "tag_name": "flow_rate_gpm",
      "message": "Flow rate below low limit (800 GPM)",
      "severity": "critical",
      "severity_numeric": 1,
      "status": "cleared",
      "state": "CLEARED",
      "category": "PROCESS",
      "current_value": 750.4,
      "threshold": 800.0,
      "limit_type": "low",
      "area": "Pump House B",
      "equipment": "Pump Station PLC #12",
      "timestamp": 1708728000,
      "event_time": 1708728000,
      "acknowledged_at": 1708728300,
      "acknowledged_by": "shift_lead@company.com",
      "cleared_at": 1708729800,
      "cleared_by": "auto_recovery",
      "ticket_id": "TKT-2024-00887",
      "correlation_id": "corr_pump12_flow_001"
    }
  ]
}

POST/v1/ot/devices/:id/alarms/:alarmId/acknowledge

Acknowledge an alarm

This endpoint acknowledges an active alarm on an OT device. Acknowledgement updates the alarm state from ALARM to ACKNOWLEDGED, records the acknowledging user and timestamp, and optionally attaches a comment. If the device has auto_ticket enabled, the linked ticket is updated with the acknowledgement.

Required attributes

Name
user_id
Type
string
Description
ID or email of the user acknowledging the alarm.

Optional attributes

Name
comment
Type
string
Description
Acknowledgement comment or reason.

Request

POST

/v1/ot/devices/d8f4e2a1-.../alarms/alm_b4c2d8e1-.../acknowledge

curl -X POST http://localhost:3000/v1/ot/devices/d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04/alarms/alm_b4c2d8e1-5f7a-4c9b-a3e6-2d8f1b7c4a09/acknowledge \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "ops_engineer@company.com",
    "comment": "Acknowledged - dispatching field tech to inspect pressure relief valve"
  }'

Response

{
  "id": "alm_b4c2d8e1-5f7a-4c9b-a3e6-2d8f1b7c4a09",
  "status": "acknowledged",
  "state": "ACKNOWLEDGED",
  "acknowledged_at": 1708733000,
  "acknowledged_by": "ops_engineer@company.com",
  "comment": "Acknowledged - dispatching field tech to inspect pressure relief valve",
  "ticket_updated": true,
  "ticket_id": "TKT-2024-00892"
}

GET/v1/ot/zones

List network zones

This endpoint returns all configured IEC 62443 network zones with their device counts, security policies, and aggregate health status. Zones enforce the Purdue model hierarchy, controlling which protocols can traverse zone boundaries via conduits.

Request

GET

/v1/ot/zones

curl http://localhost:3000/v1/ot/zones \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "zone_id": "zone_enterprise",
      "zone_name": "Enterprise Network (Level 4-5)",
      "zone_type": "ENTERPRISE",
      "security_level": "SL1",
      "parent_zone_id": null,
      "conduit_ids": ["conduit_enterprise_dmz"],
      "allowed_protocols": ["HTTPS", "MQTT"],
      "requires_authentication": true,
      "requires_encryption": true,
      "max_session_duration": 3600000,
      "audit_logging": true,
      "device_count": 12,
      "health": "healthy"
    },
    {
      "zone_id": "zone_dmz",
      "zone_name": "IT/OT DMZ (Level 3.5)",
      "zone_type": "DMZ",
      "security_level": "SL3",
      "parent_zone_id": "zone_enterprise",
      "conduit_ids": ["conduit_enterprise_dmz", "conduit_dmz_control"],
      "allowed_protocols": ["OPC_UA", "MQTT"],
      "requires_authentication": true,
      "requires_encryption": true,
      "max_session_duration": 1800000,
      "audit_logging": true,
      "device_count": 4,
      "health": "healthy"
    },
    {
      "zone_id": "zone_control_north",
      "zone_name": "Control Zone North (Level 2)",
      "zone_type": "CONTROL",
      "security_level": "SL2",
      "parent_zone_id": "zone_dmz",
      "conduit_ids": ["conduit_dmz_control", "conduit_control_field"],
      "allowed_protocols": ["MODBUS_TCP", "DNP3", "IEC61850", "OPC_UA"],
      "requires_authentication": true,
      "requires_encryption": false,
      "max_session_duration": 3600000,
      "audit_logging": true,
      "device_count": 47,
      "health": "degraded"
    },
    {
      "zone_id": "zone_field_north",
      "zone_name": "Field Zone North (Level 0-1)",
      "zone_type": "BASIC_CONTROL",
      "security_level": "SL2",
      "parent_zone_id": "zone_control_north",
      "conduit_ids": ["conduit_control_field"],
      "allowed_protocols": ["MODBUS_TCP", "MODBUS_RTU", "DNP3", "PROFINET"],
      "requires_authentication": false,
      "requires_encryption": false,
      "max_session_duration": 0,
      "audit_logging": true,
      "device_count": 128,
      "health": "healthy"
    }
  ]
}

GET/v1/ot/protocols

List supported protocols

This endpoint returns the list of supported industrial protocols, their transport types, available capabilities, and the count of currently connected adapters per protocol.

Request

GET

/v1/ot/protocols

curl http://localhost:3000/v1/ot/protocols \
  -H "Authorization: Bearer {token}"

Response

{
  "data": [
    {
      "protocol": "MODBUS_TCP",
      "transport": "TCP/IP",
      "capabilities": ["register_read", "register_write", "coil_read", "coil_write", "polling"],
      "default_port": 502,
      "adapters_connected": 14,
      "supports_subscriptions": false,
      "supports_unsolicited": false
    },
    {
      "protocol": "DNP3",
      "transport": "TCP/Serial",
      "capabilities": ["integrity_poll", "event_poll", "unsolicited_response", "select_before_operate", "time_sync", "file_transfer"],
      "default_port": 20000,
      "adapters_connected": 8,
      "supports_subscriptions": true,
      "supports_unsolicited": true
    },
    {
      "protocol": "IEC61850",
      "transport": "MMS/GOOSE/Ethernet",
      "capabilities": ["mms_read", "mms_write", "goose_subscribe", "scl_import", "reporting", "logging"],
      "default_port": 102,
      "adapters_connected": 6,
      "supports_subscriptions": true,
      "supports_unsolicited": true
    },
    {
      "protocol": "OPC_UA",
      "transport": "TCP",
      "capabilities": ["node_browse", "read", "write", "subscribe", "historical_access", "method_call"],
      "default_port": 4840,
      "adapters_connected": 3,
      "supports_subscriptions": true,
      "supports_unsolicited": false
    },
    {
      "protocol": "BACNET",
      "transport": "UDP/IP",
      "capabilities": ["object_read", "object_write", "cov_subscribe", "who_is", "alarm_summary"],
      "default_port": 47808,
      "adapters_connected": 2,
      "supports_subscriptions": true,
      "supports_unsolicited": false
    },
    {
      "protocol": "MQTT",
      "transport": "TCP/TLS",
      "capabilities": ["publish", "subscribe", "sparkplug_b", "retained_messages", "qos_levels"],
      "default_port": 1883,
      "adapters_connected": 5,
      "supports_subscriptions": true,
      "supports_unsolicited": true
    }
  ]
}

POST/v1/ot/gateway/discover

Run device discovery

This endpoint runs a protocol-specific device discovery scan on a network segment. For Modbus, it scans a range of unit IDs on a given IP; for DNP3, it sends link-layer broadcast frames; for OPC UA, it performs a FindServers request; for BACnet, it sends Who-Is broadcasts. Discovery results are returned as candidate devices that can be registered.

Discovery scans are rate-limited to prevent disruption to OT networks. Only one scan per zone is permitted at a time. Scans on safety-zone networks require explicit approval.

Required attributes

Name
protocol
Type
string
Description
Protocol to use for discovery.
Name
target
Type
string
Description
Target address or CIDR range (e.g., 10.20.3.0/24 or 10.20.3.112).
Name
zone
Type
string
Description
Zone ID where the scan will be performed.

Optional attributes

Name
port
Type
integer
Description
Target port. Defaults to the protocol's standard port.
Name
unit_id_range
Type
object
Description
For Modbus: { "start": 1, "end": 247 } to specify the unit ID scan range.
Name
timeout_ms
Type
integer
Description
Per-device scan timeout in milliseconds. Defaults to 5000.

Request

POST

/v1/ot/gateway/discover

curl -X POST http://localhost:3000/v1/ot/gateway/discover \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "MODBUS_TCP",
    "target": "10.20.3.0/24",
    "zone": "zone_control_north",
    "port": 502,
    "unit_id_range": { "start": 1, "end": 10 },
    "timeout_ms": 3000
  }'

Response

{
  "scan_id": "scan_8mWqR3nT5vXp",
  "protocol": "MODBUS_TCP",
  "target": "10.20.3.0/24",
  "zone": "zone_control_north",
  "status": "completed",
  "started_at": 1708733100,
  "completed_at": 1708733142,
  "duration_ms": 42000,
  "devices_found": 3,
  "candidates": [
    {
      "ip_address": "10.20.3.112",
      "port": 502,
      "unit_id": 1,
      "device_identification": {
        "vendor": "Siemens",
        "product_code": "S7-1500",
        "revision": "4.5.2"
      },
      "responding": true,
      "already_registered": true,
      "existing_device_id": "d8f4e2a1-7c3b-4e9f-a1d6-3b8c5f2e7a04"
    },
    {
      "ip_address": "10.20.3.115",
      "port": 502,
      "unit_id": 1,
      "device_identification": {
        "vendor": "Allen-Bradley",
        "product_code": "1769-L33ER",
        "revision": "33.011"
      },
      "responding": true,
      "already_registered": false,
      "existing_device_id": null
    },
    {
      "ip_address": "10.20.3.118",
      "port": 502,
      "unit_id": 3,
      "device_identification": {
        "vendor": "Schneider Electric",
        "product_code": "M340",
        "revision": "3.20"
      },
      "responding": true,
      "already_registered": false,
      "existing_device_id": null
    }
  ]
}