icsnpp-c1222

https://github.com/cisagov/icsnpp-c1222
0 1 3 1 Last Push 6/24/25, 5:01 PM

ICSNPP-C12.22

Industrial Control Systems Network Protocol Parsers (ICSNPP) - ANSI C12.22 traffic over TCP and UDP.

Overview

ICSNPP-C12.22 is a Zeek plugin (written in Spicy) for parsing and logging fields used by the ANSI C12.22 protocol as presented in IEEE standard 1703-2012, defining a transmission format for utility end device data tables or control elements.

This parser produces the following log files, defined in scripts/main.zeek:

By Default:

  • c1222.log
  • c1222_user_information.log
  • c1222_service_error.log

Optional:

  • c1222_authentication_value.log
  • c1222_identification_service.log
  • c1222_read_write_service.log
  • c1222_logon_security_service.log
  • c1222_wait_service.log
  • c1222_dereg_reg_service.log
  • c1222_resolve_service.log
  • c1222_trace_service.log

For additional information on this log file, see the Logging Capabilities section below. Note that even the default logs have optional toggles to disable them - they are just enabled by default.

Installation

Package Manager

This script is available as a package for Zeek Package Manager. It requires Spicy and the Zeek Spicy plugin.

$ zkg refresh
$ zkg install icsnpp-c1222

If this package is installed from ZKG, it will be added to the available plugins. This can be tested by running zeek -NN. If installed correctly, users will see ANALYZER_C1222_TCP and ANALYZER_C1222_UDP under the list of Zeek::Spicy analyzers.

If users have ZKG configured to load packages (see @load packages in the ZKG Quickstart Guide), this plugin and these scripts will automatically be loaded and ready to go.

Logging Capabilities

C12.22 Summary Log (c1222.log)

Overview

This log summarizes, by packet, ANSI C12.22 frames transmitted over 1153/tcp or 1153/udp to c1222.log. This log is enabled by default. Users can disable it by appending C1222::log_summary=F to the zeek command on the command line or by adding redef C1222::log_summary = F; to the local.zeek file. The port can be overriden by redefining the c1222_ports_tcp and c1222_ports_udp variables, respectively, e.g.:

$ zeek -C -r c1222_tcp.pcap local "C1222::c1222_ports_tcp={ 40712/tcp }"

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
elements vector of string List of the ASCE Elements utilized in the packet
is_encrypted_epsem bool Flag denoting if the EPSEM data is encrypted
services vector of string List of epsem services in the packet
aso_context string Application context universal identifier
called_ap_title string Unique identifier of message target
calling_ap_title string Unique identifier of message initiator
calling_ae_qualifier vector of string Qualifies data being sent
mechanism_name string Unique security mechanism identifier
calling_auth_value string Authenticatin mechanism used
called_ap_invocation_id string Called AP invocation identifier
calling_ap_invocation_id string Calling AP invocation identifier
  • The calling_ae_qualifier field is comprised of four non-exclusive qualifiers:
    • TEST - test message
    • URGENT - high priority message
    • NOTIFICATION - write services issued as a notification
    • RESERVED - a reserved bit is set
  • The calling_auth_value field contains a summary of the authentication mechanism used. Details of the calling authentication value can be found in c1222_authentication_value.log.

User Information Element Summary Log (c1222_user_information.log)

Overview

This log summarizes the User Information Element and the EPSEM data. This log is enabled by default. Users can disable it by appending C1222::log_user_information=F to the zeek command on the command line or by adding redef C1222::log_user_information = F; to the local.zeek file.

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
indirect_reference_encoding int Identifies encoding used to decipher user-information
padding string Padding for segmentation and encryption
mac string Encryption message authentication code
epsem_control vector of string Datagram control field
ed_class string Transport protocol
encrypted_epsem string Is the epsem encrypted
services vector of string EPSEM services sent in packet
  • The epsem_control field identifies the epsem datagram control field:
    • RECOVERY_SESSION - Used to initate session where response is not subject to restrictions of message accepted window or playback rejection.
    • PROXY_SERVICE_USED - Determines if message was sent through a proxy.
    • ED_CLASS_INCLUDED - ed-class field is included in the ASCE pdu
    • SECURITY_MODE_CLEARTEXT - EPSEM datagram transmitted in cleartext.
    • SECURITY_MODE_CLEARTEXT_WITH_AUTHENTICATION - EPSEM datagram transmitted in cleartext with authentication.
    • SECURITY_MODE_CIPHERTEXT_WITH_AUTHENTICATION - EPSEM datagram transmitted in ciphertext with authentication.
    • RESPONSE_CONTROL_ALWAYS_RESPOND - Used by request message to always receive a response.
    • RESPONSE_CONTROL_RESPOND_ON_EXCEPTION - Used by request message to only receive a response on exception.
    • RESPONSE_CONTROL_NEVER_RESPOND - Used by request message to never receive a response.

Authentication Value Log (c1222_authentication_value.log)

Overview

This log provides the values used for the authentication method in the message. This log is disabled by default. Users can enable it by appending C1222::log_authentication_value=T to the zeek command on the command line or by adding redef C1222::log_authentication_value = T; to the local.zeek file.

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
authentication_mechanism string Authenticatin mechanism used
indirect_reference bool Indirect reference bytes present
octet_aligned string Bytes used to define octet aligned authentication
c1222_key_id int C12.22 auth key identifier
c1222_iv string C12.22 auth initial value
c1221_ident string C12.21 auth identification type
c1221_req string C12.21 auth request type
c1221_resp string C12.21 auth response type

Identification Service Log (c1222_identification_service.log)

Overview

This log provides details of each data field in the Identification EPSEM service. This log is disabled by default. Users can enable it by appending C1222::log_identification_service=T to the zeek command on the command line or by adding redef C1222::log_identification_service = T; to the local.zeek file.

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
req_resp string Request/Response
standard string Reference Standard
version int Reference Version Number
revision int Reference Revision Number
security_mechanism string Universal ID of the security mechanism supported
nbrSession_supported bool Node supports session-based communication
sessionless_supported bool Supports use of read and write outside of session
device_class string Universal device identifier
device_identity_format int Device identity encoding format flag
device_identity string Device identity bytes

Read Write Service Log (c1222_read_write_service.log)

Overview

This log provides details of each data field in the Read/Write EPSEM services. This log is disabled by default. Users can enable it by appending C1222::log_read_write_service=T to the zeek command on the command line or by adding redef C1222::log_read_write_service = T; to the local.zeek file.

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
req_resp string Request/Response
service_type string Name of the EPSEM service represented
table_id int ID of the table being read/written
offset count Offset into data Table in bytes
index string Index value used to locate start of data
element_count int Number of Table Elements to read/write
count_m vector of int Length of data written\returned
data vector of string Table data elements
chksum vector of int Checksum of each table
octet_count int Length of Table data requested starting at offset

Logon Service Log (c1222_logon_security_service.log)

Overview

This log provides details of each data field in the Logon and Security EPSEM service. This log is disabled by default. Users can enable it by appending C1222::log_logon_service=T to the zeek command on the command line or by adding redef C1222::log_logon_service = T; to the local.zeek file.

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
req_resp string Request/Response
service_type string Name of the EPSEM service represented
user_id int User identification code
password string 20 byte field containing password
user string 10 bytes containing user identification
session_idle_timeout int Number of seconds a session may be idle before termination

Wait Service Log (c1222_wait_service.log)

Overview

This log provides details of each data field in the Wait EPSEM service. This log is disabled by default. Users can enable it by appending C1222::log_wait_service=T to the zeek command on the command line or by adding redef C1222::log_wait_service = T; to the local.zeek file.

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
req_resp string Request/Response
time_s int Requested wait period in seconds

Deregistration Registration Service Log (c1222_dereg_reg_service.log)

Overview

This log provides details of each data field in the Deregistration and Registration EPSEM services. This log is disabled by default. Users can enable it by appending C1222::log_dereg_reg_service=T to the zeek command on the command line or by adding redef C1222::log_dereg_reg_service = T; to the local.zeek file.

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
req_resp string Request/Response
service_type string Name of the EPSEM service represented
node_type vector of string An identification of the C12.22 Node’s Attributes
connection_type vector of string An indication of the type of connection requested
device_class string Device Class
ap_title string ApTitle of the C12.22 Node to be registered
electronic_serial_number string Unique ISO object identifier assigned to this Device
native_address string Native address to use to forward messages to this node
notification_pattern string An ApTitle associated with the Node-population
reg_period count Max period in seconds desired to elapse between re-registration requests
reg_delay int Max delay in seconds the deviceshould wait before registering
reg_info vector of string Registration Info

  • The node_type field identifies a node's attributes:

    • RELAY - Node is a C12.22 Relay
    • MASTER_RELAY - Node is a C12.22 Master Relay
    • HOST - Node is a C12.22 Host
    • NOTIFICATION_HOST - Node is a C12.22 Notification Host
    • AUTHENTIcATION_HOST - Node is a C12.22 Authentication Host
    • END_DEVICE - Node is a C12.19 Device
    • MY_DOMAIN_PATTERN - the my-domain-pattern parameter is present
    • RESERVED - a reserved bit is set

  • The connection_type field is an indication of the type of connection requested and the core capability related to this C12.22 Node in regard to its connection to the C12.22 Network Segment:

    • BROADCAST_AND_MULTICAST_SUPPORTED - Node has the capability to accept broadcast and multicast messages
    • MESSAGE_ACCEPTANCE_WINDOW_SUPPORTED - Node is capable of implementing time-based C12.22 Message acceptance windows
    • PLAYBACK_REJECTION_SUPPORTED - Node is capable of performing playback rejection algorithms
    • CONNECTIONLESS_MODE_SUPPORTED - Node is capable of implementing time-based C12.22 Message acceptance windows
    • ACCEPT_CONNECTIONLESS - Node is capable of implementing time-based C12.22 Message acceptance windows
    • CONNECTION_MODE_SUPPORTED - Node is capable of implementing time-based C12.22 Message acceptance windows
    • ACCEPT_CONNECTIONS - Node is capable of implementing time-based C12.22 Message acceptance windows
    • RESERVED - a reserved bit is set

  • The reg_info field identifies the following:

    • DIRECT_MESSAGING_AVAILABLE - Indicates whether direct messaging is available
    • MESSAGE_ACCEPTANCE_WINDOW_MODE - indicates this Node may enable its incoming message acceptance window
    • PLAYBACK_REJECTION_MODE - indicates that this Node may enable its playback rejection mechanism
    • CONNECTIONLESS_MODE - indicates whether this C12.22 Node shall enable its connectionless-mode communication capability
    • ACCEPT_CONNECTIONLESS - the registering node shall accept unsolicited incoming connectionless messages
    • CONNECTION_MODE - indicates whether this C12.22 Node shall enable its connection-mode communication capability
    • ACCEPT_CONNECTIONS - the registering node shall accept incoming connections
    • RESERVED - a reserved bit is set

Resolve Service Log (c1222_resolve_service.log)

Overview

This log provides details of each data field in the Resolve EPSEM services. This log is disabled by default. Users can enable it by appending C1222::log_resolve_service=T to the zeek command on the command line or by adding redef C1222::log_resolve_service = T; to the local.zeek file.

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
req_resp string Request/Response
ap_title string ApTitle of the requested C12.22 Node
local_address string Local address of the requested ApTitle

Trace Service Log (c1222_trace_service.log)

Overview

This log provides details of each data field in the Trace EPSEM services. This log is disabled by default. Users can enable it by appending C1222::log_trace_service=T to the zeek command on the command line or by adding redef C1222::log_trace_service = T; to the local.zeek file.

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
req_resp string Request/Response
ap_titles vector of string List of Node AP Titles

Service Error Log (c1222_service_error.log)

Overview

This log provides details protocol service error. This log is enabled by default. Users can disable it by appending C1222::log_service_error=F to the zeek command on the command line or by adding redef C1222::log_service_error = F; to the local.zeek file.

Fields Captured

Field Type Description
ts time Timestamp (network time)
uid string Unique ID for this connection
id conn_id Default Zeek connection info (IP addresses, ports)
proto string Transport protocol
service string Related Service Request Type generating the Error
error_code string Error type generated
rqtl_max_request_size int Request too large max request size
rstl_max_response_size int Response too large max response size
sigerr_resp string Segmentation Error Response

ICSNPP Packages

All ICSNPP Packages:

Other Software

Idaho National Laboratory is a national research facility with a focus on development of software and toolchains to improve the security of criticial infrastructure environments around the world. Please review our other software and scientific offerings at:

Primary Technology Overview Page

Supported Open Source Software

Raw Experiment Open Source Software

License

Copyright 2025 Battelle Energy Alliance, LLC. Released under the terms of the 3-Clause BSD License (see LICENSE).

Package Version :

Description :

ANSI C12.22/IEEE Std 1703 describe a protocol for transporting ANSI C12.19 table data over networks,
for the purpose of interoperability among communications modules and meters.

Script Dir :

scripts

Build Command :

mkdir -p build && cd build && SPICYZ=$(command -v spicyz || echo %(package_base)s/spicy-plugin/build/bin/spicyz) cmake .. && cmake --build .

Test Command :

cd testing && btest -c btest.cfg

Depends :

zeek >=4.0.0

Package Checks : ☑

License: ☑
Info:
Found license 'LICENSE'
Readme: ☑
Info:
Found readme 'README.md'
Build Command: ☑
Bad Extension: ☑
Expensive Events: ☑
Unsafe Functions: ☑
Charset: ☑