feat(ics-protocol): DNP3 production YAML manifest (Phase 5.A)

Rule #52 instance digitalandrew#3 / Phase 5.A — Rule digitalandrew#25 per-piece commit: ships
the second ICS protocol catalog production manifest (after Session 1's
modbus_tcp_v0_system). Mirrors the Modbus YAML shape exactly with
DNP3-specific port + banner + function-code values.

DNP3 (IEEE 1815-2012; IANA TCP/UDP 20000) detector signals:
- string_in_binary needle set: 'dnp3' / 'opendnp3' / 'libdnp3'
  (case-insensitive; combine=any min_count=1)
- port_signature: 20000 (little-endian uint16 constant in head)
- function_code_set: 14 DNP3 standard FCs (0x01 READ / 0x02 WRITE /
  0x03 SELECT / 0x04 OPERATE / 0x05 DIRECT_OPERATE / 0x06
  DIRECT_OPERATE_NR / 0x0D COLD_RESTART / 0x0E WARM_RESTART /
  0x14 ENABLE_UNSOLICITED / 0x15 DISABLE_UNSOLICITED /
  0x17 DELAY_MEASURE / 0x18 RECORD_CURRENT_TIME /
  0x81 RESPONSE / 0x82 UNSOLICITED_RESPONSE) — min_count=3 within
  512-byte window per W2-β A8 floor.

W2-β §SC5-NEW-ICS-2 mitigation: combine=all_required prevents
single-signal false positives. Modbus FCs (0x01-0x06) overlap
conceptually with DNP3 0x01-0x06 but the port + banner co-requirement
disambiguates — see cross-protocol matrix tests in Phase 5.B.

Tests (tests/test_ics_protocol_dnp3_e2e.py — Rule #35b live canary
against the in-tree production YAML):
- test_production_catalog_loads_dnp3_v0: load smoke + schema shape
- test_dnp3_resolves_all_three_signals_fire: happy path
- test_dnp3_rejects_banner_only_combine_all_required: §SC5-NEW-ICS-2
- test_dnp3_rejects_port_only: §SC5-NEW-ICS-2
- test_dnp3_rejects_function_codes_only: §SC5-NEW-ICS-2

5 tests pass in 0.59s.

Cross-protocol matrix (Modbus + DNP3 + S7Comm disjointness) ships in
Phase 5.B alongside s7comm.yaml — those tests require both YAMLs
present.

Phase 5.B (next): s7comm.yaml + cross-protocol matrix tests.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: eastmadc

backend/app/services/ics_protocol_catalog/data/ics_protocols/_system/dnp3.yaml

@@ -0,0 +1,109 @@
+# yaml-language-server: $schema=../../.schema.json
+# DNP3 (Distributed Network Protocol 3) firmware-embedded protocol-stack
+# detector. IEEE 1815-2012 standard; IANA-registered TCP/UDP port 20000.
+# Predominantly used in electric grid SCADA, water/wastewater telemetry,
+# and other utility SCADA networks.
+#
+# Three signals combine (all_required) for a high-confidence detection:
+#   1. ASCII string `dnp3` / `opendnp3` / `libdnp3` appearing in the
+#      binary's head window (library banner / SONAME / copyright text).
+#   2. DNP3 IANA port 20000 (0x4E20) appearing as a little-endian uint16
+#      constant somewhere in the head.
+#   3. DNP3 application-layer function-code lookup table — at least 3 of
+#      the standard DNP3 FCs (per IEEE 1815-2012 §A.2):
+#        0x01 READ        0x02 WRITE        0x03 SELECT
+#        0x04 OPERATE     0x05 DIRECT_OPERATE 0x06 DIRECT_OPERATE_NR
+#        0x0D COLD_RESTART 0x0E WARM_RESTART  0x14 ENABLE_UNSOLICITED
+#        0x15 DISABLE_UNSOLICITED 0x17 DELAY_MEASURE 0x18 RECORD_CURRENT_TIME
+#        0x81 RESPONSE    0x82 UNSOLICITED_RESPONSE
+#      Floor of 3 codes within a 512-byte window per W2-β A8 high-collision
+#      mitigation (DNP3 FCs overlap conceptually with Modbus 0x01-0x06; the
+#      banner + port co-requirement under all_required disambiguates).
+#
+# Per W2-β §SC5-NEW-ICS-2 mitigation: combine=all_required prevents
+# single-signal false positives. A binary that merely contains the string
+# `dnp3` (e.g. an HTTP server's static asset path) without ALSO showing
+# port 20000 AND the function-code table DOES NOT fire this manifest.
+#
+# References:
+#   - IEEE 1815-2012 "Standard for Electric Power Systems Communications —
+#     Distributed Network Protocol (DNP3)"
+#   - IANA Service Name & Transport Protocol Port Number Registry
+#     (port 20000 / tcp + udp = dnp / "DNP")
+#   - OpenDNP3 project (https://github.com/dnp3/opendnp3)
+#   - ICS-CERT ADVISORY-19-274-01 (DNP3 stack identification guidance)
+schema_version: 1
+manifest_id: dnp3_v0_system
+manifest_source: _system
+precedence: 5
+detection:
+  combine: all_required
+  certainty: stack_present
+  signals:
+    - kind: string_in_binary
+      description: "'dnp3' / 'opendnp3' / 'libdnp3' ASCII banner in head window"
+      string_in_binary_constraint:
+        needles_hex:
+          - "646e7033"                              # 'dnp3'
+          - "6f70656e646e7033"                      # 'opendnp3'
+          - "6c6962646e7033"                        # 'libdnp3'
+        case_sensitive: false
+        combine: any
+        min_count: 1
+    - kind: port_signature
+      description: "IANA-assigned DNP3 port 20000"
+      ports: [20000]
+      transport_required: tcp
+    - kind: function_code_set
+      description: "DNP3 standard application-layer function-code lookup table"
+      function_code_constraint:
+        function_codes_hex:
+          - "01"   # READ
+          - "02"   # WRITE
+          - "03"   # SELECT
+          - "04"   # OPERATE
+          - "05"   # DIRECT_OPERATE
+          - "06"   # DIRECT_OPERATE_NR
+          - "0d"   # COLD_RESTART
+          - "0e"   # WARM_RESTART
+          - "14"   # ENABLE_UNSOLICITED
+          - "15"   # DISABLE_UNSOLICITED
+          - "17"   # DELAY_MEASURE
+          - "18"   # RECORD_CURRENT_TIME
+          - "81"   # RESPONSE
+          - "82"   # UNSOLICITED_RESPONSE
+        # Floor of 3 codes within a 512-byte window — DNP3 application-
+        # layer FCs are sparser than Modbus's; 3 is the W2-β A8 floor
+        # for discriminating from coincidental bytes.
+        min_count: 3
+        window_bytes: 512
+output:
+  protocol_family: dnp3
+  layer: application
+  transport: tcp
+  vendor: generic
+  vendor_product: null
+  protocol_version: null
+  confidence: high
+notes: |
+  Generic DNP3 detector covering opendnp3, libdnp3, vendor-specific DNP3
+  outstation/master implementations. Per W2-β §SC5-NEW-ICS-2 mitigation,
+  combine=all_required forces co-occurrence of (banner + port + function-
+  code table) — single-signal hits do NOT fire this manifest.
+
+  Vendor-specific entries (e.g. SEL, ABB, GE Multilin, Schweitzer relay
+  firmware) ship in v1 as additional manifests at
+  data/ics_protocols/<vendor>/dnp3_*.yaml with vendor-specific banner
+  needles + product attribution; this v0 entry carries vendor='generic'
+  so the matcher returns a baseline detection for unidentified DNP3 stacks.
+
+  Cross-manifest disjointness vs modbus_tcp_v0_system: DNP3's port 20000
+  + FC table (0x01-0x18 + 0x81/0x82) is distinct from Modbus/TCP's port
+  502 + FC table — but the FC SET overlap on 0x01-0x06 means single-
+  signal FC-only hits would be ambiguous. all_required + the port +
+  banner co-requirement resolves the ambiguity in practice.
+references:
+  - "https://standards.ieee.org/ieee/1815/4805/"
+  - "https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml"
+  - "https://github.com/dnp3/opendnp3"
+  - "https://www.cisa.gov/news-events/ics-advisories/icsa-19-274-01"

backend/tests/test_ics_protocol_dnp3_e2e.py

@@ -0,0 +1,105 @@
+"""End-to-end integration test for the Phase 5 DNP3 v0 YAML.
+
+Session 2 Phase 5.A — proves the schema + catalog + resolver + YAML
+loader chain works against the real ``data/ics_protocols/_system/dnp3.yaml``
+shipped in this commit. Rule #35b live canary form against the IN-TREE
+production YAML.
+
+Cross-protocol matrix tests live in
+``test_ics_protocol_dnp3_s7comm_e2e.py`` (Commit 5.B; ships with
+s7comm.yaml so both YAMLs are present for the matrix checks).
+"""
+from __future__ import annotations
+
+import struct
+from pathlib import Path
+
+import pytest
+
+from app.services.ics_protocol_catalog import (
+    IcsProtocolCatalog,
+    resolve_all,
+)
+
+
+@pytest.fixture
+def production_catalog() -> IcsProtocolCatalog:
+    data_root = (
+        Path(__file__).resolve().parents[1]
+        / "app" / "services" / "ics_protocol_catalog"
+        / "data" / "ics_protocols"
+    )
+    overlay_root = (
+        Path(__file__).resolve().parents[1]
+        / "app" / "services" / "ics_protocol_catalog"
+        / "data" / "ics_protocols.local"
+    )
+    return IcsProtocolCatalog(
+        data_root=data_root, overlay_root=overlay_root,
+    )
+
+
+def test_production_catalog_loads_dnp3_v0(production_catalog):
+    """The shipped _system/dnp3.yaml loads cleanly."""
+    snap = production_catalog.get_snapshot()
+    m = snap.get("dnp3_v0_system")
+    assert m is not None
+    assert m.manifest_source == "_system"
+    assert m.output.protocol_family == "dnp3"
+    assert m.output.layer == "application"
+    assert m.output.transport == "tcp"
+    assert m.detection.combine == "all_required"
+    kinds = [s.kind for s in m.detection.signals]
+    assert set(kinds) == {
+        "string_in_binary", "port_signature", "function_code_set",
+    }
+    assert production_catalog.last_warning is None
+
+
+def test_dnp3_resolves_all_three_signals_fire(production_catalog):
+    """Blob with DNP3 banner ('opendnp3') + port 20000 LE constant +
+    FCs 0x01/0x02/0x03/0x04 in 512-byte window → matches."""
+    snap = production_catalog.get_snapshot()
+    blob = bytearray(4096)
+    blob[100:108] = b"opendnp3"
+    blob[200:202] = struct.pack("<H", 20000)
+    blob[800:804] = bytes([0x01, 0x02, 0x03, 0x04])
+    matches = resolve_all(bytes(blob), "/tmp/dnp3-test.bin", 4096, snap)
+    dnp3 = [m for m in matches if m.protocol_family == "dnp3"]
+    assert len(dnp3) == 1
+    m = dnp3[0]
+    assert m.confidence == "high"
+    assert set(m.matched_signals) == {
+        "string_in_binary", "port_signature", "function_code_set",
+    }
+
+
+def test_dnp3_rejects_banner_only_combine_all_required(production_catalog):
+    """W2-β §SC5-NEW-ICS-2 — banner-only does NOT fire (combine forces
+    co-occurrence)."""
+    snap = production_catalog.get_snapshot()
+    blob = bytearray(4096)
+    blob[100:108] = b"opendnp3"
+    matches = resolve_all(bytes(blob), "/tmp/t.bin", 4096, snap)
+    dnp3 = [m for m in matches if m.protocol_family == "dnp3"]
+    assert len(dnp3) == 0
+
+
+def test_dnp3_rejects_port_only(production_catalog):
+    """Port-only — rejected by combine."""
+    snap = production_catalog.get_snapshot()
+    blob = bytearray(4096)
+    blob[200:202] = struct.pack("<H", 20000)
+    matches = resolve_all(bytes(blob), "/tmp/t.bin", 4096, snap)
+    dnp3 = [m for m in matches if m.protocol_family == "dnp3"]
+    assert len(dnp3) == 0
+
+
+def test_dnp3_rejects_function_codes_only(production_catalog):
+    """Function codes alone — rejected by combine."""
+    snap = production_catalog.get_snapshot()
+    blob = bytearray(4096)
+    blob[800:808] = bytes([0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x0d, 0x82])
+    matches = resolve_all(bytes(blob), "/tmp/t.bin", 4096, snap)
+    dnp3 = [m for m in matches if m.protocol_family == "dnp3"]
+    assert len(dnp3) == 0