Modbus threat hunting: structured PDU decoding, correlation, hunt rules and RTU-over-TCP

[dreadl0ck]

Summary

Turns the Modbus stream decoder into a usable threat-hunting source, from MBAP metadata only to structured, correlated evidence, and ships hunt rules plus a practical guide.

Decoding

• Per-function addresses, quantities and written values for FC1-8, 11, 12, 15-17, 20-24 and FC43/MEI14; exception codes, diagnostics, device identification, file records and masks.
• MessageRole (request/response/unknown) and ParseStatus (valid/malformed/unsupported/lost) are explicit. Malformed PDUs never publish partially decoded values, and vendor-defined content (FC17) is left opaque rather than guessed.
• Semantic decoding works without -payload; existing payload behaviour is unchanged.
• Conservative in-connection correlation by transaction, unit and function with bounded pending state, duplicate-ID ambiguity and no negative-latency matches.

Capture loss is visible

A gap or unusable framing emits one marker per loss event with ParseStatus == "lost" and LostBytes (summed extent, -1 when unknown). Decoding resumes at the first byte after a bounded gap with a single validation attempt, and the first message after any arbitrary resume point must parse before it is emitted — header-like payload bytes cannot fabricate records. The framer never scans forward through a body. Correlation does not match across a loss.

This makes coverage auditable: an empty hunt result over a conversation carrying loss markers is not evidence of absence.

RTU over TCP

Opt-in via -modbus-rtu-endpoints / NC_MODBUS_RTU_ENDPOINTS, for explicitly named gateway endpoints only, never CRC-guessing on arbitrary traffic. Shares the PDU parser but has its own function-length + CRC16 framing, broadcast handling and bounded recovery.

Hunting

rules/examples/modbus_hunt.yml (14 rules, six enabled by default): write authorization validating the whole written interval per bank, separate FC21 file writes, FC43/MEI14 and FC17 discovery, disruptive FC8 diagnostics, enumeration by distinct destination/unit/read address, correlated illegal-address exceptions, and visibility/coverage triage. Site-dependent rules ship disabled with documentation IPs and no response actions.

Supporting fixes

• Preserve per-packet capture timestamps through reassembly; merge directions without reordering bytes within a direction (this one affects all stream protocols).
• Honour AllowMissingInit instead of discarding midstream conversations; derive roles from the handshake rather than assuming orientation.
• Bound Modbus metric labels and numeric encoding; align CSV/Encode columns; increment metrics for live/PCAP decoding, not just audit-file export.
• Preserve distinct_field/distinct_threshold when the web UI saves or toggles rule sets.
• Reset recycled reassembly page flags.

Validation

• go test -tags=nodpi ./... — 2326 passed (excluding TestCapturePCAP, whose fixture is not in the repo).
• -race across decoder, reassembly, collector, rules, types, cmd — all passing.
• Fuzzing on the PDU parser and RTU framer; frontend pnpm test 73 passed; full CLI builds.
• End-to-end on pcaps/nDPI-modbus.pcap: 51 valid requests, 47 matched responses with addresses, values and latency, no false loss markers, 14 rules loaded.
• Guard tests were each confirmed to fail against the pre-fix behaviour, including one that runs the shipped YAML against real decoder output.

Notes for review

• Protobuf tags 1-13 are unchanged; new fields occupy 14-51. types/netcap.pb.go is gitignored and regenerated from netcap.proto.
• Function-code matches still include response echoes unless gated on MessageRole == "request"; the guide and rules do this consistently.
• Records are emitted at connection completion, and a match is an observed attempt, not proof of a process change.

Remaining

• Native serial RTU and Modbus ASCII are out of scope.
• Vendor/user-defined function codes and non-MEI14 FC43 decode as unsupported with the raw PDU retained.
• The rules engine still has no sequence or grouping operator, so read-to-write timing remains an offline analysis.

[github-actions]

Thank you for your contribution to NETCAP!

Before we can accept your pull request, you need to sign our Contributor License Agreement (CLA).

To sign the CLA, please read the Individual CLA and comment below with:

I have read and agree to the NETCAP CLA

If you are contributing on behalf of a company or organization, please contact the maintainers to complete the Entity CLA instead.

---

You can re-trigger this check by commenting recheck on this PR.

---

I have read and agree to the NETCAP CLA

---

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}