API reference
Available Lua libraries
base
string
table
math
debug
utf8
Data types
Class |
FieldInfoAttributes
|
Constructors |
|
Read/write properties |
|
Class |
FunctionCode
|
Constructors |
|
Class |
RtuId
|
Constructors |
|
Class |
DataValue
|
Constructors |
|
Read/write properties |
|
Class |
Variable
|
Methods |
|
Class |
Node
|
Methods |
|
Enum |
DataCause
|
Values |
|
Enum |
DataType
|
Values |
Note:
Only ANALOG, DIGITAL and DOUBLEPOINT types are kept in
consideration by the Process Learning Engine when
detecting deviations from the baseline. |
Enum |
FieldConfidence
|
Values |
|
Enum |
FieldGranularity
|
Values |
|
Enum |
FieldSourceCode
|
Values |
|
Enum |
ProtocolType
|
Values |
|
Functions
Syntax |
data(<index>)
|
Parameters |
|
Description | Return the value of the byte from the specified position, return 0 if index is out of bounds |
Syntax |
data_size()
|
Description | Return the total size of the payload |
Syntax |
remaining_size()
|
Description | Return the size of the payload from the pointer to the end. The result depends on the usage of functions fwd(), rwd() and consume_*(). |
Syntax |
fwd(<amount>)
|
Parameters |
|
Description | Move the payload pointer by the specified number of bytes. |
Syntax |
rwd()
|
Description | Move the payload pointer to the beginning of the payload. |
Syntax |
read_uint8()
|
Description | Read an unsigned 8bit integer at the payload pointer position. |
Syntax |
read_int8()
|
Description | Read an signed 8bit integer at the payload pointer position. |
Syntax |
read_n_uint16()
|
Description | Read a network order unsigned 16bit integer at the payload pointer position. |
Syntax |
read_h_uint16()
|
Description | Read a host order unsigned 16bit integer at the payload pointer position. |
Syntax |
read_n_int16()
|
Description | Read a network order signed 16bit integer at the payload pointer position. |
Syntax |
read_h_int16()
|
Description | Read a host order signed 16bit integer at the payload pointer position. |
Syntax |
read_n_uint32()
|
Description | Read a network order unsigned 32bit integer at the payload pointer position. |
Syntax |
read_h_uint32()
|
Description | Read a host order unsigned 32bit integer at the payload pointer position. |
Syntax |
read_n_int32()
|
Description | Read a network order signed 32bit integer at the payload pointer position. |
Syntax |
read_h_int32()
|
Description | Read a host order signed 32bit integer at the payload pointer position. |
Syntax |
read_n_uint64()
|
Description | Read a network order unsigned 64bit integer at the payload pointer position. |
Syntax |
read_h_uint64()
|
Description | Read a host order unsigned 64bit integer at the payload pointer position. |
Syntax |
read_n_int64()
|
Description | Read a network order signed 64bit integer at the payload pointer position. |
Syntax |
read_h_int64()
|
Description | Read a host order signed 64bit integer at the payload pointer position. |
Syntax |
read_n_float()
|
Description | Read a network order float at the payload pointer position. |
Syntax |
read_h_float()
|
Description | Read a host order float at the payload pointer position. |
Syntax |
read_n_double()
|
Description | Read a network order double at the payload pointer position. |
Syntax |
read_h_double()
|
Description | Read a host order double at the payload pointer position. |
Syntax |
read_string()
|
Description | Read a string at the payload pointer position until the null terminator. |
Syntax |
read_string_with_len(str_len)
|
Description | Read a string at the payload pointer position for
str_len bytes. |
Syntax |
consume_uint8()
|
Description | Read an unsigned 8bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_int8()
|
Description | Read an signed 8bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_n_uint16()
|
Description | Read a network order unsigned 16bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_h_uint16()
|
Description | Read a host order unsigned 16bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_n_int16()
|
Description | Read a network order signed 16bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_h_int16()
|
Description | Read a host order signed 16bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_n_uint32()
|
Description | Read a network order unsigned 32bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_h_uint32()
|
Description | Read a host order unsigned 32bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_n_int32()
|
Description | Read a network order signed 32bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_h_int32()
|
Description | Read a host order signed 32bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_n_uint64()
|
Description | Read a network order unsigned 64bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_h_uint64()
|
Description | Read a host order unsigned 64bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_n_int64()
|
Description | Read a network order signed 64bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_h_int64()
|
Description | Read a host order signed 64bit integer at the payload pointer position and move the pointer after the data. |
Syntax |
consume_n_float()
|
Description | Read a network order float at the payload pointer position and move the pointer after the data. |
Syntax |
consume_h_float()
|
Description | Read a host order float at the payload pointer position and move the pointer after the data. |
Syntax |
consume_n_double()
|
Description | Read a network order double at the payload pointer position and move the pointer after the data. |
Syntax |
consume_h_double()
|
Description | Read a host order double at the payload pointer position and move the pointer after the data. |
Syntax |
consume_string()
|
Description | Read a string at the payload pointer position until the null terminator and move the pointer after the data. |
Syntax |
consume_string_with_len(str_len)
|
Description | Read a string at the payload pointer position for
str_len bytes and move the pointer after the
data. |
Syntax |
consume_xor_data(bytes_len, key, callback_function)
|
Description | Read bytes_len bytes at the payload pointer
position and apply the XOR function with the byte in
key at the same index.
callback_function is then invoked with the
payload pointer changed to the trasformed payload. When exiting from
the callback function, the previous context is restored and the
pointer is moved after the data. Note:
key: must be
an array of hex integers with a length greater or equal than
bytes_len . |
Syntax |
consume_gzip_data(bytes_len, callback_function)
|
Description | Read bytes_len bytes at the payload pointer
position and decompress it with gzip.
callback_function is then invoked with the
payload pointer changed to the decompressed payload. When exiting
from the callback function, the previous context is restored and the
pointer is moved after the data. |
Syntax |
consume_zlib_data(bytes_len, callback_function)
|
Description | Read bytes_len bytes at the payload pointer
position and decompress it with zlib.
callback_function is then invoked with the
payload pointer changed to the decompressed payload. When exiting
from the callback function, the previous context is restored and the
pointer is moved after the data. |
Syntax |
compute_crc16(size, poly, init, xor_out, ref_in,
ref_out)
|
Parameters |
|
Description | Compute the CRC16 of the remaining payload according to the input
parameters. The input parameters for CRC functions can be easily
found online. For example, to get a CRC16/DNP the parameters are:
0x3D65, 0x0000, 0xFFFF, true, true
|
Syntax |
compute_crc32(size, poly, init, xor_out, ref_in,
ref_out)
|
Parameters |
|
Description | Compute the CRC32 of the remaining payload according to the input
parameters. The input parameters for CRC functions can be easily
found online. For example, to get a plain CRC32 the parameters are:
0x04C11DB7, 0xFFFFFFFF, 0xFFFFFFFF, true, true
|
Syntax |
set_roles(<client_role>, <server_role>)
|
Parameters |
|
Description | Set the roles of the involved nodes, valid values are: "consumer", "producer", "historian", "terminal", "web_server", "dns_server", "db_server", "time_server", "other" |
Syntax |
set_source_type(<node_type>)
|
Parameters |
|
Description | Set the type of the source node, valid values are: "switch", "router", "printer", "group", "OT_device", "broadcast", "computer" |
Syntax |
variables_are_on_client()
|
Parameters | |
Description | Notify to Guardian that the variables should be added to the client node |
syntax |
is_packet_from_src_to_dst(<is_from_src>)
|
parameters |
|
description | notify Guardian about the direction of the packet, this function must be called to obtain a link creation |
syntax |
execute_update()
|
parameters | |
description | notify Guardian about the a packet, at least one variant of execute_update should be called for every packet (available for standalone protocols only) |
syntax |
execute_update_with_function_code(<function_code>,
<rtu id>)
|
parameters |
|
description | notify Guardian about the a packet with a function code and a rtu id (available for standalone protocols only) |
syntax |
execute_update_with_variable(<function_code>, <rtu
id>, <var_name>, <value>)
|
parameters |
|
description | notify Guardian about the a packet with a function code, a rtu id, a variable name and a variable value (available for standalone protocols only) |
syntax |
execute_update_with_function(<function_code>, <rtu
id>, <var_name>, <value>,
<function>)
|
parameters |
|
description | notify Guardian about the a packet with a function code, a rtu id, a variable name, a variable value and a function that give the possibility to directly access the variable (available for standalone protocols only) |
syntax |
set_fc_info(<fc_num>, <fc_descr>)
|
parameters |
|
description | establish a correspondence between a function code number and its description. When Guardian is later notified about this function code numerically, then the description will automatically be recalled and used |
syntax |
AlertFactory.new_net_device()
|
description | raise an alert of type VI:NEW-NET-DEV |
syntax |
AlertFactory.firmware_transfer()
|
description | raise an alert of type SIGN:FIRMWARE-TRANSFER |
syntax |
AlertFactory.protocol_error(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:PROTOCOL-ERROR |
syntax |
AlertFactory.wrong_time(<reason>)
|
parameters |
|
description | raise an alert of type PROC:WRONG-TIME |
syntax |
AlertFactory.sync_asked_again(<reason>)
|
parameters |
|
description | raise an alert of type PROC:SYNC-ASKED-AGAIN |
syntax |
AlertFactory.protocol_flow_anomaly(<reason>)
|
parameters |
|
description | raise an alert of type VI:PROC:PROTOCOL-FLOW-ANOMALY |
syntax |
AlertFactory.variable_flow_anomaly(<reason>)
|
parameters |
|
description | raise an alert of type VI:PROC:VARIABLE-FLOW-ANOMALY |
syntax |
AlertFactory.dhcp_request(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:DHCP-OPERATION |
syntax |
AlertFactory.invalid_ip(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:INVALID-IP |
syntax |
AlertFactory.new_arp(<reason>)
|
parameters |
|
description | raise an alert of type VI:NEW-ARP |
syntax |
AlertFactory.duplicated_ip(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:ARP:DUP |
syntax |
AlertFactory.link_reconnection(<reason>)
|
parameters |
|
description | raise an alert of type NET:LINK-RECONNECTION |
syntax |
AlertFactory.rst_from_producer(<reason>)
|
parameters |
|
description | raise an alert of type NET:RST-FROM-PRODUCER |
syntax |
AlertFactory.tcp_syn(<reason>)
|
parameters |
|
description | raise an alert of type NET:TCP-SYN |
syntax |
AlertFactory.tcp_flood(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:TCP-FLOOD |
syntax |
AlertFactory.protocol_flood(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:PROTOCOL-FLOOD |
syntax |
AlertFactory.mac_flood(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:MAC-FLOOD |
syntax |
AlertFactory.network_scan(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:NETWORK-SCAN |
syntax |
AlertFactory.cleartext_password(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:CLEARTEXT-PASSWORD |
syntax |
AlertFactory.ddos_attack(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:DDOS |
syntax |
AlertFactory.unsupported_func(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:UNSUPPORTED-FUNC |
syntax |
AlertFactory.illegal_parameters(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:ILLEGAL-PARAMETERS |
syntax |
AlertFactory.weak_password(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:PASSWORD:WEAK |
syntax |
AlertFactory.malware_detected()
|
description | raise an alert of type SIGN:MALWARE-DETECTED |
syntax |
AlertFactory.unknown_rtu(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:PROC:UNKNOWN-RTU |
syntax |
AlertFactory.missing_variable(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:PROC:MISSING-VAR |
syntax |
AlertFactory.protocol_injection(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:PROTOCOL-INJECTION |
syntax |
AlertFactory.new_variable(<reason>)
|
parameters |
|
description | raise an alert of type VI:PROC:NEW-VAR |
syntax |
AlertFactory.new_variable_value(<reason>)
|
parameters |
|
description | raise an alert of type VI:PROC:NEW-VALUE |
syntax |
AlertFactory.device_state_change(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:DEV-STATE-CHANGE |
syntax |
AlertFactory.configuration_change(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:CONFIGURATION-CHANGE |
syntax |
AlertFactory.malicious_protocol(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:MALICIOUS-PROTOCOL |
syntax |
AlertFactory.weak_encryption(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:WEAK-ENCRYPTION |
syntax |
AlertFactory.malformed_traffic(<triggerId>,
<reason>)
|
parameters |
|
description | raise an alert of type SIGN:MALFORMED-TRAFFIC |
syntax |
AlertFactory.suspicious_time(<triggerId>,
<reason>)
|
parameters |
|
description | raise an alert of type SIGN:SUSP-TIME |
syntax |
AlertFactory.new_node(<nodeId>)
|
parameters |
|
description | raise an alert of type VI:NEW-NODE |
syntax |
AlertFactory.new_target_node(<nodeId>)
|
parameters |
|
description | raise an alert of type VI:NEW-NODE:TARGET |
syntax |
AlertFactory.new_node_malicious_ip(<nodeId>,
<threatName>)
|
parameters |
|
description | raise an alert of type VI:NEW-NODE:MALICIOUS-IP |
syntax |
AlertFactory.new_mac_vendor(<nodeId>,
<macAddress>, <reason>)
|
parameters |
|
description | raise an alert of type VI:GLOBAL:NEW-MAC-VENDOR |
syntax |
AlertFactory.new_mac(<nodeId>, <macAddress>,
<reason>)
|
parameters |
|
description | raise an alert of type VI:NEW-MAC |
syntax |
AlertFactory.malicious_domain(<domain>,
<threatName>, <reason>)
|
parameters |
|
description | raise an alert of type SIGN:MALICIOUS-DOMAIN |
syntax |
AlertFactory.malicious_url(<url>, <threatName>,
<reason>)
|
parameters |
|
description | raise an alert of type SIGN:MALICIOUS-URL |
syntax |
AlertFactory.configuration_mismatch(<nodeId>,
<triggerId>, <reason>)
|
parameters |
|
description | raise an alert of type VI:CONF-MISMATCH |
syntax |
AlertFactory.multiple_ot_device_reservations(<sNodeId>,
<dNodeId>, <protocolId>, <bpfFilter>,
<protocolType>, <reason>)
|
parameters |
|
description | raise an alert of type SIGN:MULTIPLE-OT_DEVICE-RESERVATIONS |
syntax |
AlertFactory.multiple_unsuccessful_logins(<sNodeId>,
<dNodeId>, <protocolId>, <bpfFilter>,
<protocolType>, <reason>)
|
parameters |
|
description | raise an alert of type SIGN:MULTIPLE-UNSUCCESSFUL-LOGINS |
syntax |
AlertFactory.generic_event(<triggerId>,
<reason>)
|
parameters |
|
description | raise an alert of type GENERIC:EVENT |
syntax |
AlertFactory.multiple_access_denied(<sNodeId>,
<dNodeId>, <protocolId>, <bpfFilter>,
<protocolType>, <reason>)
|
parameters |
|
description | raise an alert of type SIGN:MULTIPLE-ACCESS-DENIED |
syntax |
AlertFactory.protocol_injection(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:PROTOCOL-INJECTION |
syntax |
send_alert_malformed_packet(<reason>)
|
parameters |
|
description | raise an alert of type SIGN:MALFORMED-TRAFFIC |
syntax |
notify_captured_url(<clientNodeId>,
<serverNodeId>, <url>, <user>,
<operation>, <size>, <properties>)
|
parameters |
|
description | notify a captured URL to the system. Note that captured
URLs need
to be explicitly enabled by specifying the vi captured_urls
enabled configuration setting. |
syntax |
notify_link_events(<event>,
<parameters>)
|
parameters |
|
description | notify a link event to the system. Note that link events need to
be explicitly enabled by specifying the vi link_events
enabled configuration setting. |
syntax |
packet.source_id()
|
description | return the source node id |
syntax |
packet.destination_id()
|
description | return the destination node id |
syntax |
packet.source_ip()
|
description | return the source node ip |
syntax |
packet.destination_ip()
|
description | return the destination node ip |
syntax |
packet.source_mac()
|
description | return the source node mac |
syntax |
packet.destination_mac()
|
description | return the destination node mac |
syntax |
packet.source_port()
|
description | return the source node port |
syntax |
packet.destination_port()
|
description | return the destination node port |
syntax |
packet.is_ip()
|
description | return true if the packet is an ip
packet |
syntax |
packet.transport_type()
|
description | return the transport layer type, can be "tcp", "udp", "ethernet", "icmp" or "unknown" |
syntax |
packet.source_node()
|
description | returns the source node |
syntax |
packet.destination_node()
|
description | returns the destination node |
syntax |
packet.time()
|
description | return the packet time |
syntax |
session.set_pending_request_number(<request_id>,
<key>, <value>)
|
parameters |
|
description | store a number on the session |
syntax |
session.read_pending_request_number(<request_id>,
<key>)
|
parameters |
|
description | read a number from the session |
syntax |
session.set_pending_request_string(<request_id>,
<key>, <value>)
|
parameters |
|
description | store a string on the session |
syntax |
session.read_pending_request_string(<request_id>,
<key>)
|
parameters |
|
description | read a string from the session |
syntax |
session.has_pending_request(<request_id>)
|
parameters |
|
description | return true if there are values stored with the
request_id |
syntax |
session.has_pending_request_value(<request_id>,
<key>)
|
parameters |
|
description | return true if there are values stored with the
request_id and key |
syntax |
session.close_pending_request(<request_id>)
|
parameters |
|
description | close the pending request and delete the associated data |
syntax |
log_d(<msg>)
|
parameters |
|
description | log a debug message |
syntax |
log_i(<msg>)
|
parameters |
|
description | log an info message |
syntax |
log_e(<msg>)
|
parameters |
|
description | log an error message |