suricata/doc/userguide/lua/libs/dnp3.rst

DNP3
####

The ``suricata.dnp3`` module provides access to DNP3 (Distributed
Network Protocol 3) transaction data in Suricata Lua rules.

It is only available in Suricata Lua rules, not output scripts.

Setup
*****

::

    local dnp3 = require("suricata.dnp3")

Module Functions
****************

.. function:: dnp3.get_tx()

   Returns the current DNP3 transaction object containing request or response data.

   :returns: A table containing the DNP3 transaction data, or nil on error
   :raises error: If the protocol is not DNP3
   :raises error: If no transaction is available

   Example:

   ::

       function match(args)
           local tx = dnp3.get_tx()
           if tx and tx.is_request then
               -- Process DNP3 request
           end
       end

Transaction Object Structure
****************************

The transaction object returned by ``get_tx()`` contains the following fields:

.. attribute:: tx_num

   Transaction number (integer)

.. attribute:: is_request

   Boolean indicating if this is a request (true) or response (false)

.. attribute:: request

   Table containing request data (only present when ``is_request`` is true)

.. attribute:: response

   Table containing response data (only present when ``is_request`` is false)

Request/Response Structure
**************************

Both request and response tables contain:

.. attribute:: done

   Boolean indicating if the transaction is complete

.. attribute:: complete

   Boolean indicating if all data has been received

.. attribute:: link_header

   Table containing DNP3 link layer header fields:

   - ``len``: Frame length
   - ``control``: Control byte
   - ``dst``: Destination address
   - ``src``: Source address
   - ``crc``: CRC value

.. attribute:: transport_header

   Transport layer header byte (integer)

.. attribute:: application_header

   Table containing DNP3 application layer header fields:

   - ``control``: Application control byte
   - ``function_code``: DNP3 function code

.. attribute:: objects

   Array of DNP3 objects in the message

Additionally, response tables contain:

.. attribute:: indicators

   Internal Indication (IIN) field as a 16-bit integer combining IIN1 and IIN2

Objects Structure
*****************

Each object in the ``objects`` array contains:

.. attribute:: group

   DNP3 object group number (integer)

.. attribute:: variation

   DNP3 object variation number (integer)

.. attribute:: points

   Array of data points for this object

Points Structure
****************

Each point in the ``points`` array contains:

.. attribute:: index

   Point index (integer)

Additional point fields depend on the object group and variation. Common fields include:

- ``state``: Binary state value
- ``online``: Online status flag
- ``restart``: Restart flag
- ``comm_lost``: Communication lost flag
- ``remote_forced``: Remote forced flag
- ``local_forced``: Local forced flag
- ``chatter_filter``: Chatter filter flag
- ``reserved``: Reserved bits
- ``value``: Analog value (for analog objects)
- ``timestamp``: Timestamp value (for time-tagged objects)

For all available fields, see ``app-layer-dnp3-objects.h`` in the
Suricata source code.

Example Usage
*************

Complete example checking for specific DNP3 function codes:

::

    local dnp3 = require("suricata.dnp3")

    function init(args)
        return {}
    end

    function match(args)
        local tx = dnp3.get_tx()
        
        if not tx then
            return 0
        end
        
        -- Check for write function code in request
        if tx.is_request and tx.request then
            local func_code = tx.request.application_header.function_code
            if func_code == 2 then  -- WRITE function
                return 1
            end
        end
        
        -- Check for specific object types
        if tx.request and tx.request.objects then
            for _, obj in ipairs(tx.request.objects) do
                if obj.group == 12 and obj.variation == 1 then
                    -- Control Relay Output Block
                    return 1
                end
            end
        end
        
        return 0
    end