├── LICENSE
├── README.rst
├── __init__.py
├── cip.py
├── enip_cpf.py
├── enip_tcp.py
├── enip_udp.py
├── plc.py
└── utils.py


/LICENSE:
--------------------------------------------------------------------------------
 1 | The MIT License (MIT)
 2 | 
 3 | Copyright (c) 2015 SCy-Phy
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 
23 | 


--------------------------------------------------------------------------------
/README.rst:
--------------------------------------------------------------------------------
  1 | ================================
  2 | Ethernet/IP dissectors for Scapy
  3 | ================================
  4 | 
  5 | This repository contains a Python library which can be used to interact with components of a network using ENIP (Ethernet/IP) and CIP (Common Industrial Protocol) protocols.
  6 | It uses scapy (http://www.secdev.org/projects/scapy/) to implement packet dissectors which are able to decode a part of the network traffic.
  7 | These dissectors can also be used to craft packets, which allows directly communicating with the PLCs (Programmable Logic Controllers) of the network.
  8 | 
  9 | This project has been created to help analyzing the behavior of SWaT, a water treatment testbed built at SUTD (Singapore University of Technology and Design). For more information on our work, visit http://scy-phy.net
 10 | 
 11 | Therefore, it mostly implements a subset of CIP specification, which is used in this system.
 12 | 
 13 | 
 14 | Requirements
 15 | ============
 16 | 
 17 | * Python 2.7
 18 | * Scapy (http://www.secdev.org/projects/scapy/)
 19 | 
 20 | 
 21 | Example of packet decoding
 22 | ==========================
 23 | 
 24 | Here is the raw content of a packet sent to a PLC to query a tag (in SWaT), as seen by an hexadecimal viewer::
 25 | 
 26 |     00000000: 801d 9cc8 bde7 001d 9cc6 72e8 0800 4500  ..........r...E.
 27 |     00000010: 005e 2f95 4000 8006 4746 c0a8 0164 c0a8  .^/.@...GF...d..
 28 |     00000020: 010a c203 af12 8e7a 4387 01bd 1e5e 5018  .......zC....^P.
 29 |     00000030: 829c 2a07 0000 7000 1e00 0200 1600 0000  ..*...p.........
 30 |     00000040: 0000 0000 0000 0000 0000 0000 0000 0000  ................
 31 |     00000050: 0000 0000 0200 a100 0400 2042 b5ff b100  .......... B....
 32 |     00000060: 0a00 8a07 4c03 20b2 2500 2200            ....L. .%.".
 33 | 
 34 | This packet can be decoded using this Python script:
 35 | 
 36 | .. code-block:: python
 37 | 
 38 |     #!/usr/bin/env python2
 39 |     import binascii
 40 |     from scapy.all import *
 41 |     import cip
 42 | 
 43 |     rawpkt = binascii.unhexlify(
 44 |         '801d9cc8bde7001d9cc672e808004500005e2f95400080064746c0a80164'
 45 |         'c0a8010ac203af128e7a438701bd1e5e5018829c2a07000070001e000200'
 46 |         '1600000000000000000000000000000000000000000000000200a1000400'
 47 |         '2042b5ffb1000a008a074c0320b225002200')
 48 |     pkt = Ether(rawpkt)
 49 |     pkt.show()
 50 | 
 51 | This script prints the structure of the packet with every protocol layer (Ethernet, IP, ENIP and CIP)::
 52 | 
 53 |     ###[ Ethernet ]###
 54 |       dst       = 00:1d:9c:c8:bd:e7
 55 |       src       = 00:1d:9c:c6:72:e8
 56 |       type      = 0x800
 57 |     ###[ IP ]###
 58 |          version   = 4L
 59 |          ihl       = 5L
 60 |          tos       = 0x0
 61 |          len       = 94
 62 |          id        = 12181
 63 |          flags     = DF
 64 |          frag      = 0L
 65 |          ttl       = 128
 66 |          proto     = tcp
 67 |          chksum    = 0x4746
 68 |          src       = 192.168.1.100
 69 |          dst       = 192.168.1.10
 70 |          \options   \
 71 |     ###[ TCP ]###
 72 |             sport     = 49667
 73 |             dport     = EtherNet_IP_2
 74 |             seq       = 2390377351
 75 |             ack       = 29171294
 76 |             dataofs   = 5L
 77 |             reserved  = 0L
 78 |             flags     = PA
 79 |             window    = 33436
 80 |             chksum    = 0x2a07
 81 |             urgptr    = 0
 82 |             options   = []
 83 |     ###[ ENIP_TCP ]###
 84 |                command_id= SendUnitData
 85 |                length    = 30
 86 |                session   = 1441794
 87 |                status    = success
 88 |                sender_context= 0
 89 |                options   = 0
 90 |     ###[ ENIP_SendUnitData ]###
 91 |                   interface_handle= 0
 92 |                   timeout   = 0
 93 |                   count     = 2
 94 |                   \items     \
 95 |                    |###[ ENIP_SendUnitData_Item ]###
 96 |                    |  type_id   = conn_address
 97 |                    |  length    = 4
 98 |                    |###[ ENIP_ConnectionAddress ]###
 99 |                    |     connection_id= 4290069024
100 |                    |###[ ENIP_SendUnitData_Item ]###
101 |                    |  type_id   = conn_packet
102 |                    |  length    = 10
103 |                    |###[ ENIP_ConnectionPacket ]###
104 |                    |     sequence  = 1930
105 |                    |###[ CIP ]###
106 |                    |        direction = request
107 |                    |        service   = Read_Tag_Service
108 |                    |        \path      \
109 |                    |         |###[ CIP_Path ]###
110 |                    |         |  wordsize  = 3
111 |                    |         |  path      = class 0xb2,instance 0x22
112 |                    |        \status    \
113 | 
114 | Moreover, each component of the packet is accessible in Python.
115 | For example, adding ``print(pkt[cip.CIP].path)`` at the end of the script shows the path of the tag being queried in this CIP request::
116 | 
117 |     [<CIP_Path  wordsize=3 path=class 0xb2,instance 0x22 |>]
118 | 
119 | 
120 | Interfacing with a PLC
121 | ======================
122 | 
123 | The scapy dissectors can be used to craft packet and therefore communicate with a PLC using ENIP and CIP.
124 | These communications require several handshakes:
125 | 
126 | * a TCP handshake to establish a communication channel,
127 | * an ENIP handshake to register an ENIP session,
128 | * an optional CIP handshake (with ForwardOpen messages).
129 | 
130 | The file ``plc.py`` provides ``PLCClient`` class, which implements an abstraction level of the state of a communication with a PLC.
131 | Here is for example how to use this class to read tag ``HMI_LIT101`` on the PLC sitting at address ``192.168.1.10``:
132 | 
133 | .. code-block:: python
134 | 
135 |     import logging
136 |     import sys
137 | 
138 |     from cip import CIP, CIP_Path
139 |     import plc
140 | 
141 |     logging.basicConfig(format='[%(levelname)s] %(message)s', level=logging.DEBUG)
142 | 
143 |     # Connect to PLC
144 |     client = plc.PLCClient('192.168.1.10')
145 |     if not client.connected:
146 |         sys.exit(1)
147 |     print("Established session {}".format(client.session_id))
148 | 
149 |     if not client.forward_open():
150 |         sys.exit(1)
151 | 
152 |     # Send a CIP ReadTag request
153 |     cippkt = CIP(service=0x4c, path=CIP_Path.make_str("HMI_LIT101"))
154 |     client.send_unit_cip(cippkt)
155 | 
156 |     # Receive the response and show it
157 |     resppkt = client.recv_enippkt()
158 |     resppkt[CIP].show()
159 | 
160 |     # Close the connection
161 |     client.forward_close()
162 | 


--------------------------------------------------------------------------------
/__init__.py:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/scy-phy/scapy-cip-enip/89bc10382e8f0c79802950d7b9fca6f8591c1e90/__init__.py


--------------------------------------------------------------------------------
/cip.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python2
  2 | # -*- coding: utf-8 -*-
  3 | # Copyright (c) 2015 Nicolas Iooss, SUTD; David I. Urbina, UTD
  4 | #
  5 | # Permission is hereby granted, free of charge, to any person obtaining a copy
  6 | # of this software and associated documentation files (the "Software"), to deal
  7 | # in the Software without restriction, including without limitation the rights
  8 | # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9 | # copies of the Software, and to permit persons to whom the Software is
 10 | # furnished to do so, subject to the following conditions:
 11 | #
 12 | # The above copyright notice and this permission notice shall be included in
 13 | # all copies or substantial portions of the Software.
 14 | #
 15 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17 | # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18 | # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19 | # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 20 | # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 21 | # THE SOFTWARE.
 22 | """Common Industrial Protocol dissector
 23 | 
 24 | Documentation:
 25 | * http://literature.rockwellautomation.com/idc/groups/literature/documents/pm/1756-pm020_-en-p.pdf
 26 | 
 27 | Wireshark implementation:
 28 | https://code.wireshark.org/review/gitweb?p=wireshark.git;a=blob;f=epan/dissectors/packet-cip.c
 29 | """
 30 | import struct
 31 | import sys
 32 | 
 33 | from scapy import all as scapy_all
 34 | 
 35 | import enip_tcp
 36 | import utils
 37 | 
 38 | 
 39 | class CIP_RespSingleAttribute(scapy_all.Packet):
 40 |     """An attribute... not much information about it"""
 41 |     fields_desc = [scapy_all.StrField("value", None)]
 42 | 
 43 | 
 44 | class CIP_RespAttributesAll(scapy_all.Packet):
 45 |     """Content of Get_Attribute_All response"""
 46 |     fields_desc = [
 47 |         scapy_all.StrField("value", None),
 48 |     ]
 49 | 
 50 | 
 51 | class CIP_RespAttributesList(scapy_all.Packet):
 52 |     """List of attributes in Get_Attribute_List responses
 53 | 
 54 |     There are "count" attributes in the "content" field, in the following format:
 55 |         * attribute ID (INT, LEShortField)
 56 |         * status (INT, LEShortField, 0 means success)
 57 |         * value, type and length depends on the attribute and thus can not be known here
 58 |     """
 59 |     fields_desc = [
 60 |         scapy_all.LEShortField("count", 0),
 61 |         scapy_all.StrField("content", ""),
 62 |     ]
 63 | 
 64 |     def split_guess(self, attr_list, verbose=False):
 65 |         """Split the content of the Get_Attribute_List response with the known attribute list
 66 | 
 67 |         Return a list of (attr, value) tuples, or None if an error occured
 68 |         """
 69 |         content = self.content
 70 |         offset = 0
 71 |         idx = 0
 72 |         result = []
 73 |         while offset < len(content):
 74 |             attr, status = struct.unpack("<HH", content[offset:offset + 4])
 75 |             if attr not in attr_list:
 76 |                 if verbose:
 77 |                     sys.stderr.write("Error: Get_Attribute_List response contains an unknown attribute\n")
 78 |                     sys.stderr.write("... all attrs " + ','.join(hex(a) for a in attr_list) + '\n')
 79 |                     sys.stderr.write(utils.hexdump(content[offset:], indentlvl="... ") + "\n")
 80 |                 return
 81 |             if attr != attr_list[idx]:
 82 |                 if verbose:
 83 |                     sys.stderr.write("Error: attr {:#x} not in position {} of attr list\n".format(attr, idx))
 84 |                     sys.stderr.write("... all attrs " + ','.join(hex(a) for a in attr_list) + '\n')
 85 |                 return
 86 |             offset += 4
 87 |             attr_len = None
 88 |             if idx == len(attr_list) - 1:
 89 |                 # Last attribute
 90 |                 attr_len = len(content) - offset
 91 |             else:
 92 |                 # Find next attribute header
 93 |                 nexthdr = struct.pack('<HH', attr_list[idx + 1], 0)
 94 |                 for i in range(offset + 1, len(content) - 4):
 95 |                     if content[i:i + 4] == nexthdr:
 96 |                         attr_len = i - offset
 97 |                         break
 98 |             if attr_len is None:
 99 |                 if verbose:
100 |                     sys.stderr.write("Error: length not found. Here is the remaining\n")
101 |                     sys.stderr.write("... all attrs " + ','.join(hex(a) for a in attr_list) + '\n')
102 |                     sys.stderr.write(utils.hexdump(content[offset:], indentlvl="... ") + "\n")
103 |                 return
104 |             result.append((attr, content[offset:offset + attr_len]))
105 |             offset += attr_len
106 |             idx += 1
107 |         return result
108 | 
109 |     def split_guess_todict(self, attr_list, verbose=False):
110 |         """Same as split_guess, but return a dict instead of a list of tuples"""
111 |         result = self.split_guess(attr_list, verbose)
112 |         if result is None:
113 |             return
114 |         # assert unicity of attributes IDs
115 |         assert len(frozenset(x[0] for x in result)) == len(result)
116 |         return dict(result)
117 | 
118 | 
119 | class CIP_ReqGetAttributeList(scapy_all.Packet):
120 |     """The list of requested attributes in a CIP Get_Attribute_List request"""
121 |     fields_desc = [
122 |         utils.LEShortLenField("count", None, count_of="attrs"),
123 |         scapy_all.FieldListField("attrs", [], scapy_all.LEShortField("", 0),
124 |                                  count_from=lambda pkt: pkt.count),
125 |     ]
126 | 
127 | 
128 | class CIP_ReqReadOtherTag(scapy_all.Packet):
129 |     """Optional information to be sent with a Read_Tag_Service
130 | 
131 |     FIXME: this packet has been built from experiments, not from official doc
132 |     """
133 |     fields_desc = [
134 |         scapy_all.LEShortField("start", 0),
135 |         scapy_all.LEShortField("zero", 0),
136 |         scapy_all.LEShortField("length", None),
137 |     ]
138 | 
139 | 
140 | class CIP_PathField(scapy_all.StrLenField):
141 |     SEGMENT_TYPES = {
142 |         0: "class",  # 0x20 = 8-bit class ID, 0x21 = 16-bit class ID
143 |         1: "instance",  # 0x24 = 8-bit instance ID, 0x25 = 16-bit instance ID
144 |         2: "element",  # 0x28 = 8-bit element ID, 0x29 = 16-bit element ID, 0x2a = 32-bit element ID
145 |         3: "connection point",
146 |         4: "attribute",  # 0x30 = 8-bit attribute ID, 0x31 = 16-bit attribute ID
147 |     }
148 |     KNOWN_CLASSES = {
149 |         0x01: "Idendity",
150 |         0x02: "Message Router",
151 |         0x06: "Connection Manager",
152 |         0x6b: "Symbol",
153 |         0x6c: "Template",
154 |     }
155 | 
156 |     @classmethod
157 |     def to_tuplelist(cls, val):
158 |         """Return a list of tuples describing the content of the path encoded in val"""
159 |         if ord(val[0]) == 0x91:
160 |             # "ANSI Extended Symbolic", the path is a string
161 |             # Don't check the second byte, which is the length (in bytes) of the strings.
162 |             return {-1: val[2:].rstrip("\0")}
163 | 
164 |         pos = 0
165 |         result = []
166 |         while pos < len(val):
167 |             header = struct.unpack('B', val[pos])[0]
168 |             pos += 1
169 |             if (header & 0xe0) != 0x20:  # 001 high bits is "Logical Segment"
170 |                 sys.stderr.write("WARN: unknown segment class of 0x{:02x}\n".format(header))
171 | 
172 |             seg_format = header & 3
173 |             if seg_format == 0:  # 8-bit segment
174 |                 seg_value = struct.unpack('B', val[pos])[0]
175 |                 pos += 1
176 |             elif seg_format == 1:  # 16-bit segment
177 |                 seg_value = struct.unpack('<H', val[pos + 1:pos + 3])[0]
178 |                 pos += 3
179 |             else:
180 |                 # 2 is 32-bit segment, but alignment needs to be taken into account
181 |                 raise Exception("Unknown seg_format {}".format(seg_format))
182 | 
183 |             seg_type = (header >> 2) & 7
184 |             result.append((seg_type, seg_value))
185 |         return result
186 | 
187 |     @classmethod
188 |     def tuplelist2repr(cls, val_tuplelist):
189 |         """Represent a path tuplelist into a human-readable text"""
190 |         if -1 in val_tuplelist and list(val_tuplelist.keys()) == [-1]:
191 |             # String path
192 |             return repr(val_tuplelist[-1])
193 | 
194 |         descriptions = []
195 |         for type_id, value in val_tuplelist:
196 |             desc = cls.SEGMENT_TYPES.get(type_id, "type{}".format(type_id))
197 |             desc += " 0x{:x}".format(value)
198 |             if type_id == 0 and value in cls.KNOWN_CLASSES:
199 |                 desc += "({})".format(cls.KNOWN_CLASSES[value])
200 |             descriptions.append(desc)
201 |         return ",".join(descriptions)
202 | 
203 |     @classmethod
204 |     def i2repr(cls, pkt, val):
205 |         """Decode the path "val" as human-readable text"""
206 |         return cls.tuplelist2repr(cls.to_tuplelist(val))
207 | 
208 | 
209 | class CIP_Path(scapy_all.Packet):
210 |     name = "CIP_Path"
211 |     fields_desc = [
212 |         scapy_all.ByteField("wordsize", None),
213 |         CIP_PathField("path", None, length_from=lambda p: 2 * p.wordsize),
214 |     ]
215 | 
216 |     def extract_padding(self, p):
217 |         return "", p
218 | 
219 |     @classmethod
220 |     def make(cls, class_id=None, instance_id=None, member_id=None, attribute_id=None):
221 |         """Create a CIP_Path from its attributes"""
222 |         content = b""
223 |         if class_id is not None:
224 |             if class_id < 256:  # 8-bit class ID
225 |                 content += b"\x20" + struct.pack("B", class_id)
226 |             else:  # 16-bit class ID
227 |                 content += b"\x21\0" + struct.pack("<H", class_id)
228 | 
229 |         if instance_id is not None:
230 |             # Always use 16-bit instance ID
231 |             content += b"\x25\0" + struct.pack("<H", instance_id)
232 | 
233 |         if member_id is not None:
234 |             if member_id < 256:  # 8-bit member ID
235 |                 content += b"\x28" + struct.pack("B", member_id)
236 |             else:  # 16-bit attribute ID
237 |                 content += b"\x29\0" + struct.pack("<H", member_id)
238 | 
239 |         if attribute_id is not None:
240 |             if attribute_id < 256:  # 8-bit attribute ID
241 |                 content += b"\x30" + struct.pack("B", attribute_id)
242 |             else:  # 16-bit attribute ID
243 |                 content += b"\x31\0" + struct.pack("<H", attribute_id)
244 | 
245 |         return cls(wordsize=len(content) // 2, path=content)
246 | 
247 |     @classmethod
248 |     def make_str(cls, name):
249 |         content = struct.pack('BB', 0x91, len(name)) + name.encode('ascii')
250 |         if len(content) & 1:
251 |             content += b'\0'
252 |         return cls(wordsize=len(content) // 2, path=content)
253 | 
254 |     def to_tuplelist(self):
255 |         """Return a list of tuples describing the content of the path encoded in val"""
256 |         return CIP_PathField.to_tuplelist(self.path)
257 | 
258 |     def to_repr(self):
259 |         """Return a representation of the path, not of the packet (!= repr(path))"""
260 |         return self.get_field("path").i2repr(self, self.path)
261 | 
262 | 
263 | class CIP_ResponseStatus(scapy_all.Packet):
264 |     """The response field of CIP headers"""
265 |     name = "CIP_ResponseStatus"
266 |     fields_desc = [
267 |         scapy_all.XByteField("reserved", 0),  # Reserved byte, always null
268 |         scapy_all.ByteEnumField("status", 0, {0: "success"}),
269 |         scapy_all.XByteField("additional_size", 0),
270 |         scapy_all.StrLenField("additional", "",  # additionnal status
271 |                               length_from=lambda p: 2 * p.additional_size),
272 |     ]
273 | 
274 |     ERROR_CODES = {
275 |         0x00: "Success",
276 |         0x01: "Connection failure",
277 |         0x02: "Resource unavailable",
278 |         0x03: "Invalid parameter value",
279 |         0x04: "Path segment error",
280 |         0x05: "Path destination unknown",
281 |         0x06: "Partial transfer",
282 |         0x07: "Connection lost",
283 |         0x08: "Service not supported",
284 |         0x09: "Invalid attribute value",
285 |         0x0a: "Attribute list error",
286 |         0x0b: "Already in requested mode/state",
287 |         0x0c: "Object state conflict",
288 |         0x0d: "Object already exists",
289 |         0x0e: "Attribute not settable",
290 |         0x0f: "Privilege violation",
291 |         0x10: "Device state conflict",
292 |         0x11: "Reply data too large",
293 |         0x12: "Fragmentation of a primitive value",
294 |         0x13: "Not enough data",
295 |         0x14: "Attribute not supported",
296 |         0x15: "Too much data",
297 |         0x16: "Object does not exist",
298 |         0x17: "Service fragmentation sequence not in progress",
299 |         0x18: "No stored attribute data",
300 |         0x19: "Store operation failure",
301 |         0x1a: "Routing failure, request packet too large",
302 |         0x1b: "Routing failure, response packet too large",
303 |         0x1c: "Missing attribute list entry data",
304 |         0x1d: "Invalid attribute value list",
305 |         0x1e: "Embedded service error",
306 |         0x1f: "Vendor specific error",
307 |         0x20: "Invalid parameter",
308 |         0x21: "Write-once value or medium already written",
309 |         0x22: "Invalid reply received",
310 |         0x23: "Buffer overflow",
311 |         0x24: "Invalid message format",
312 |         0x25: "Key failure in path",
313 |         0x26: "Path size invalid",
314 |         0x27: "Unexpected attribute in list",
315 |         0x28: "Invalid Member ID",
316 |         0x29: "Member not settable",
317 |         0x2a: "Group 2 only server general failure",
318 |         0x2b: "Unknown Modbus error",
319 |         0x2c: "Attribute not gettable",
320 |     }
321 | 
322 |     def extract_padding(self, p):
323 |         return "", p
324 | 
325 |     def __repr__(self):
326 |         if self.reserved != 0:
327 |             return scapy_all.Packet.__repr__(self)
328 | 
329 |         # Known status
330 |         if self.status in self.ERROR_CODES and self.additional_size == 0:
331 |             return "<CIP_ResponseStatus  status={}>".format(self.ERROR_CODES[self.status])
332 | 
333 |         # Simple status
334 |         if self.additional_size == 0:
335 |             return "<CIP_ResponseStatus  status=%#x>" % self.status
336 | 
337 |         # Forward Open failure
338 |         if self.status == 1 and self.additional == b"\x00\x01":
339 |             return "<CIP_ResponseStatus  status=Connection failure>"
340 |         return scapy_all.Packet.__repr__(self)
341 | 
342 | 
343 | class CIP(scapy_all.Packet):
344 |     name = "CIP"
345 | 
346 |     SERVICE_CODES = {
347 |         0x01: "Get_Attribute_All",
348 |         0x02: "Set_Attribute_All",
349 |         0x03: "Get_Attribute_List",
350 |         0x04: "Set_Attribute_List",
351 |         0x05: "Reset",
352 |         0x06: "Start",
353 |         0x07: "Stop",
354 |         0x08: "Create",
355 |         0x09: "Delete",
356 |         0x0a: "Multiple_Service_Packet",
357 |         0x0d: "Apply_attributes",
358 |         0x0e: "Get_Attribute_Single",
359 |         0x10: "Set_Attribute_Single",
360 |         0x4b: "Execute_PCCC_Service",  # PCCC = Programmable Controller Communication Commands
361 |         0x4c: "Read_Tag_Service",
362 |         0x4d: "Write_Tag_Service",
363 |         0x4e: "Read_Modify_Write_Tag_Service",
364 |         0x4f: "Read_Other_Tag_Service",  # ???
365 |         0x52: "Read_Tag_Fragmented_Service",
366 |         0x53: "Write_Tag_Fragmented_Service",
367 |         0x54: "Forward_Open?",
368 |     }
369 | 
370 |     fields_desc = [
371 |         scapy_all.BitEnumField("direction", None, 1, {0: "request", 1: "response"}),
372 |         utils.XBitEnumField("service", 0, 7, SERVICE_CODES),
373 |         scapy_all.PacketListField("path", [], CIP_Path,
374 |                                   count_from=lambda p: 1 if p.direction == 0 else 0),
375 |         scapy_all.PacketListField("status", [], CIP_ResponseStatus,
376 |                                   count_from=lambda p: 1 if p.direction == 1 else 0),
377 |     ]
378 | 
379 |     def post_build(self, p, pay):
380 |         is_response = (self.direction == 1)
381 |         if self.direction is None and not self.path:
382 |             # Transform the packet into a response
383 |             p = "\x01" + p[1:]
384 |             is_response = True
385 | 
386 |         if is_response:
387 |             # Add a success status field if there was none
388 |             if not self.status:
389 |                 p = p[0:1] + b"\0\0\0" + p[1:]
390 |         return p + pay
391 | 
392 | 
393 | class _CIPMSPPacketList(scapy_all.PacketListField):
394 |     """The list of packets in a CIP MultipleServicePacket message"""
395 | 
396 |     def getfield(self, pkt, remain):
397 |         lst = []
398 |         pkt_count = pkt.count
399 |         cur_offset = 2 + 2 * pkt_count
400 |         shift = pkt.offsets[0] - cur_offset
401 |         if shift > 0:
402 |             # There is some padding between the CIP MSP header and the first packet
403 |             lst.append(scapy_all.conf.raw_layer(load=remain[:shift]))
404 |             remain = remain[shift:]
405 |         cur_offset += shift
406 |         for off in pkt.offsets[1:]:
407 |             # Decode packet remain[:off - cur_offset]
408 |             try:
409 |                 p = self.m2i(pkt, remain[:off - cur_offset])
410 |             except Exception:
411 |                 if scapy_all.conf.debug_dissector:
412 |                     raise
413 |                 p = scapy_all.conf.raw_layer(load=remain[:off - cur_offset])
414 |             remain = remain[off - cur_offset:]
415 |             lst.append(p)
416 |             cur_offset = off
417 | 
418 |         if remain:
419 |             # Last packet contains all the remaining data
420 |             try:
421 |                 p = self.m2i(pkt, remain)
422 |             except Exception:
423 |                 if scapy_all.conf.debug_dissector:
424 |                     raise
425 |                 p = scapy_all.conf.raw_layer(load=remain)
426 |             lst.append(p)
427 |         return "", lst
428 | 
429 | 
430 | class CIP_ConnectionParam(scapy_all.Packet):
431 |     """CIP Connection parameters"""
432 |     name = "CIP_ConnectionParam"
433 |     fields_desc = [
434 |         scapy_all.BitEnumField("owner", 0, 1, {0: "exclusive", 1: "multiple"}),
435 |         scapy_all.BitEnumField("connection_type", 2, 2,
436 |                                {0: "null", 1: "multicast", 2: "point-to-point", 3: "reserved"}),
437 |         scapy_all.BitField("reserved", 0, 1),
438 |         scapy_all.BitEnumField("priority", 0, 2, {0: "low", 1: "high", 2: "scheduled", 3: "urgent"}),
439 |         scapy_all.BitEnumField("connection_size_type", 0, 1, {0: "fixed", 1: "variable"}),
440 |         scapy_all.BitField("connection_size", 500, 9),
441 |     ]
442 | 
443 |     def pre_dissect(self, s):
444 |         b = struct.unpack('<H', s[:2])[0]
445 |         return struct.pack('>H', int(b)) + s[2:]
446 | 
447 |     def do_build(self):
448 |         p = ''
449 |         return p
450 | 
451 |     def extract_padding(self, s):
452 |         return '', s
453 | 
454 | 
455 | class CIP_ReqForwardOpen(scapy_all.Packet):
456 |     """Forward Open request"""
457 |     name = "CIP_ReqForwardOpen"
458 |     fields_desc = [
459 |         scapy_all.BitField("priority", 0, 4),
460 |         scapy_all.BitField("tick_time", 0, 4),
461 |         scapy_all.ByteField("timeout_ticks", 249),
462 |         scapy_all.LEIntField("OT_network_connection_id", 0x80000031),
463 |         scapy_all.LEIntField("TO_network_connection_id", 0x80fe0030),
464 |         scapy_all.LEShortField("connection_serial_number", 0x1337),
465 |         scapy_all.LEShortField("vendor_id", 0x004d),
466 |         scapy_all.LEIntField("originator_serial_number", 0xdeadbeef),
467 |         scapy_all.ByteField("connection_timeout_multiplier", 0),
468 |         scapy_all.X3BytesField("reserved", 0),
469 |         scapy_all.LEIntField("OT_rpi", 0x007a1200),  # 8000 ms
470 |         scapy_all.PacketField('OT_connection_param', CIP_ConnectionParam(), CIP_ConnectionParam),
471 |         scapy_all.LEIntField("TO_rpi", 0x007a1200),
472 |         scapy_all.PacketField('TO_connection_param', CIP_ConnectionParam(), CIP_ConnectionParam),
473 |         scapy_all.XByteField("transport_type", 0xa3),  # direction server, application object, class 3
474 |         scapy_all.ByteField("path_wordsize", None),
475 |         CIP_PathField("path", None, length_from=lambda p: 2 * p.path_wordsize),
476 |     ]
477 | 
478 | 
479 | class CIP_RespForwardOpen(scapy_all.Packet):
480 |     """Forward Open response"""
481 |     name = "CIP_RespForwardOpen"
482 |     fields_desc = [
483 |         scapy_all.LEIntField("OT_network_connection_id", None),
484 |         scapy_all.LEIntField("TO_network_connection_id", None),
485 |         scapy_all.LEShortField("connection_serial_number", None),
486 |         scapy_all.LEShortField("vendor_id", None),
487 |         scapy_all.LEIntField("originator_serial_number", None),
488 |         scapy_all.LEIntField("OT_api", None),
489 |         scapy_all.LEIntField("TO_api", None),
490 |         scapy_all.ByteField("application_reply_size", None),
491 |         scapy_all.XByteField("reserved", 0),
492 |     ]
493 | 
494 | 
495 | class CIP_ReqForwardClose(scapy_all.Packet):
496 |     """Forward Close request"""
497 |     name = "CIP_ReqForwardClose"
498 |     fields_desc = [
499 |         scapy_all.XByteField("priority_ticktime", 0),
500 |         scapy_all.ByteField("timeout_ticks", 249),
501 |         scapy_all.LEShortField("connection_serial_number", 0x1337),
502 |         scapy_all.LEShortField("vendor_id", 0x004d),
503 |         scapy_all.LEIntField("originator_serial_number", 0xdeadbeef),
504 |         scapy_all.ByteField("path_wordsize", None),
505 |         scapy_all.XByteField("reserved", 0),
506 |         CIP_PathField("path", None, length_from=lambda p: 2 * p.path_wordsize),
507 |     ]
508 | 
509 | 
510 | class CIP_MultipleServicePacket(scapy_all.Packet):
511 |     """Multiple_Service_Packet request or response"""
512 |     name = "CIP_MultipleServicePacket"
513 |     fields_desc = [
514 |         utils.LEShortLenField("count", None, count_of="packets"),
515 |         scapy_all.FieldListField("offsets", [], scapy_all.LEShortField("", 0),
516 |                                  count_from=lambda pkt: pkt.count),
517 |         # Assume the offsets are increasing, and no padding. FIXME: remove this assumption
518 |         _CIPMSPPacketList("packets", [], CIP)
519 |     ]
520 | 
521 |     def do_build(self):
522 |         """Build the packet by concatenating packets and building the offsets list"""
523 |         # Build the sub packets
524 |         subpkts = [str(pkt) for pkt in self.packets]
525 |         # Build the offset lists
526 |         current_offset = 2 + 2 * len(subpkts)
527 |         offsets = []
528 |         for p in subpkts:
529 |             offsets.append(struct.pack("<H", current_offset))
530 |             current_offset += len(p)
531 |         return struct.pack("<H", len(subpkts)) + "".join(offsets) + "".join(subpkts)
532 | 
533 | 
534 | class CIP_ReqConnectionManager(scapy_all.Packet):
535 |     fields_desc = [
536 |         scapy_all.BitField("reserved", 0, 3),
537 |         scapy_all.BitField("priority", 0, 1),
538 |         scapy_all.BitField("ticktime", 5, 4),
539 |         scapy_all.ByteField("timeout_ticks", 157),
540 |         utils.LEShortLenField("message_size", None, length_of="message"),
541 |         scapy_all.PacketLenField("message", None, CIP,
542 |                                  length_from=lambda pkt: pkt.message_size),
543 |         scapy_all.StrLenField("message_padding", None,
544 |                               length_from=lambda pkt: pkt.message_size % 2),
545 |         scapy_all.ByteField("route_path_size", 1),  # TODO: size in words
546 |         scapy_all.ByteField("reserved2", 0),
547 |         scapy_all.ByteField("route_path_size_port", 1),
548 |         scapy_all.ByteField("route_path_size_addr", 0),
549 |     ]
550 | 
551 |     def post_build(self, p, pay):
552 |         # Autofill the padding
553 |         if len(p) % 2:
554 |             p = p[:-4] + b"\0" + p[-4:]
555 |         return p + pay
556 | 
557 | 
558 | scapy_all.bind_layers(enip_tcp.ENIP_ConnectionPacket, CIP)
559 | scapy_all.bind_layers(enip_tcp.ENIP_SendUnitData_Item, CIP, type_id=0x00b2)
560 | 
561 | scapy_all.bind_layers(CIP, CIP_RespAttributesAll, direction=1, service=0x01)
562 | scapy_all.bind_layers(CIP, CIP_ReqGetAttributeList, direction=0, service=0x03)
563 | scapy_all.bind_layers(CIP, CIP_RespAttributesList, direction=1, service=0x03)
564 | scapy_all.bind_layers(CIP, CIP_MultipleServicePacket, service=0x0a)
565 | scapy_all.bind_layers(CIP, CIP_RespSingleAttribute, direction=1, service=0x0e)
566 | scapy_all.bind_layers(CIP, CIP_ReqReadOtherTag, direction=0, service=0x4c)
567 | scapy_all.bind_layers(CIP, CIP_ReqReadOtherTag, direction=0, service=0x4f)
568 | scapy_all.bind_layers(CIP, CIP_ReqForwardOpen, direction=0, service=0x54)
569 | scapy_all.bind_layers(CIP, CIP_RespForwardOpen, direction=1, service=0x54)
570 | 
571 | # TODO: this is much imprecise :(
572 | # Need class in path to be 6 (Connection Manager)
573 | scapy_all.bind_layers(CIP, CIP_ReqConnectionManager, direction=0, service=0x52)
574 | 
575 | if __name__ == '__main__':
576 |     # Test building/dissecting packets
577 |     # Build a CIP Get Attribute All request
578 |     path = CIP_Path.make(class_id=1, instance_id=1)
579 |     assert str(path) == b"\x03\x20\x01\x25\x00\x01\x00"
580 |     pkt = CIP(service=1, path=path)
581 |     pkt = CIP(str(pkt))
582 |     pkt.show()
583 |     assert pkt[CIP].direction == 0
584 |     assert pkt[CIP].path[0] == path
585 | 
586 |     # Build a CIP Get_Attribute_List response
587 |     pkt = CIP() / CIP_RespAttributesList(count=1, content="test")
588 |     pkt = CIP(str(pkt))
589 |     pkt.show()
590 |     assert pkt[CIP].direction == 1
591 |     assert pkt[CIP].service == 0x03
592 |     assert pkt[CIP].status[0].reserved == 0
593 |     assert pkt[CIP].status[0].status == 0
594 |     assert pkt[CIP].status[0].additional_size == 0
595 |     assert pkt[CIP].status[0].additional == ""
596 |     assert pkt[CIP].payload == pkt[CIP_RespAttributesList]
597 |     assert pkt[CIP_RespAttributesList].count == 1
598 |     assert pkt[CIP_RespAttributesList].content == "test"
599 | 
600 |     # Build a Multiple Service Packet Request
601 |     pkt = CIP(path=CIP_Path.make(class_id=2, instance_id=1))
602 |     pkt /= CIP_MultipleServicePacket(packets=[
603 |         CIP(path=CIP_Path.make(class_id=0x70, instance_id=1)) / CIP_ReqGetAttributeList(attrs=[1, 2]),
604 |         CIP(service=0x0e, path=CIP_Path.make(class_id=0x8e, instance_id=1, attribute_id=0x1b)),
605 |     ])
606 |     pkt = CIP(str(pkt))
607 |     pkt.show()
608 |     assert pkt[CIP].direction == 0
609 |     assert pkt[CIP].service == 0x0a
610 |     assert pkt[CIP].path[0] == CIP_Path.make(class_id=2, instance_id=1)
611 |     assert pkt[CIP].payload == pkt[CIP_MultipleServicePacket]
612 |     assert pkt[CIP_MultipleServicePacket].count == 2
613 |     assert pkt[CIP_MultipleServicePacket].offsets == [6, 20]
614 |     assert pkt[CIP_MultipleServicePacket].packets[0].service == 0x03
615 |     assert pkt[CIP_MultipleServicePacket].packets[0].payload.count == 2
616 |     assert pkt[CIP_MultipleServicePacket].packets[0].payload.attrs == [1, 2]
617 |     assert pkt[CIP_MultipleServicePacket].packets[1].service == 0x0e
618 | 


--------------------------------------------------------------------------------
/enip_cpf.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python2
 2 | # -*- coding: utf-8 -*-
 3 | # Copyright (c) 2015 David I. Urbina, david.urbina@utdallas.edu
 4 | #
 5 | # Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | # of this software and associated documentation files (the "Software"), to deal
 7 | # in the Software without restriction, including without limitation the rights
 8 | # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | # copies of the Software, and to permit persons to whom the Software is
10 | # furnished to do so, subject to the following conditions:
11 | #
12 | # The above copyright notice and this permission notice shall be included in
13 | # all copies or substantial portions of the Software.
14 | #
15 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 | # THE SOFTWARE.
22 | """Ethernet/IP Common Packet Format Scapy dissector."""
23 | import struct
24 | 
25 | from scapy import all as scapy_all
26 | 
27 | import utils
28 | 
29 | 
30 | class CPF_SequencedAddressItem(scapy_all.Packet):
31 |     name = "CPF_SequencedAddressItem"
32 |     fields_desc = [
33 |         scapy_all.LEIntField("connection_id", 0),
34 |         scapy_all.LEIntField("sequence_number", 0),
35 |     ]
36 | 
37 | 
38 | class CPF_AddressDataItem(scapy_all.Packet):
39 |     name = "CPF_AddressDataItem"
40 |     fields_desc = [
41 |         scapy_all.LEShortEnumField('type_id', 0, {
42 |             0x0000: "Null Address",
43 |             0x00a1: "Connection-based Address",
44 |             0x00b1: "Connected Transport Packet",
45 |             0x00b2: "Unconnected Message",
46 |             0x0100: "ListServices response",
47 |             0x8002: 'Sequenced Address Item',
48 |         }),
49 |         scapy_all.LEShortField("length", None),
50 |     ]
51 | 
52 |     def extract_padding(self, p):
53 |         return p[:self.length], p[self.length:]
54 | 
55 |     def post_build(self, p, pay):
56 |         if self.length is None and pay:
57 |             l = len(pay)
58 |             p = p[:2] + struct.pack("<H", l) + p[4:]
59 |         return p + pay
60 | 
61 | 
62 | class ENIP_CPF(scapy_all.Packet):
63 |     name = "ENIP_CPF"
64 |     fields_desc = [
65 |         utils.LEShortLenField("count", 2, count_of="items"),
66 |         scapy_all.PacketListField("items", [CPF_AddressDataItem('', 0, 0), CPF_AddressDataItem('', 0, 0)],
67 |                                   CPF_AddressDataItem, count_from=lambda p: p.count),
68 |     ]
69 | 
70 |     def extract_padding(self, p):
71 |         return '', p
72 | 
73 | 
74 | scapy_all.bind_layers(CPF_AddressDataItem, CPF_SequencedAddressItem, type_id=0x8002)
75 | 


--------------------------------------------------------------------------------
/enip_tcp.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python2
  2 | # -*- coding: utf-8 -*-
  3 | # Copyright (c) 2015 Nicolas Iooss, SUTD
  4 | #
  5 | # Permission is hereby granted, free of charge, to any person obtaining a copy
  6 | # of this software and associated documentation files (the "Software"), to deal
  7 | # in the Software without restriction, including without limitation the rights
  8 | # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9 | # copies of the Software, and to permit persons to whom the Software is
 10 | # furnished to do so, subject to the following conditions:
 11 | #
 12 | # The above copyright notice and this permission notice shall be included in
 13 | # all copies or substantial portions of the Software.
 14 | #
 15 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17 | # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18 | # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19 | # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 20 | # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 21 | # THE SOFTWARE.
 22 | """Ethernet/IP over TCP scapy dissector"""
 23 | import struct
 24 | 
 25 | from scapy import all as scapy_all
 26 | 
 27 | import utils
 28 | 
 29 | 
 30 | class ENIP_ConnectionAddress(scapy_all.Packet):
 31 |     name = "ENIP_ConnectionAddress"
 32 |     fields_desc = [scapy_all.LEIntField("connection_id", 0)]
 33 | 
 34 | 
 35 | class ENIP_ConnectionPacket(scapy_all.Packet):
 36 |     name = "ENIP_ConnectionPacket"
 37 |     fields_desc = [scapy_all.LEShortField("sequence", 0)]
 38 | 
 39 | 
 40 | class ENIP_SendUnitData_Item(scapy_all.Packet):
 41 |     name = "ENIP_SendUnitData_Item"
 42 |     fields_desc = [
 43 |         scapy_all.LEShortEnumField("type_id", 0, {
 44 |             0x0000: "null_address",  # NULL Address
 45 |             0x00a1: "conn_address",  # Address for connection based requests
 46 |             0x00b1: "conn_packet",  # Connected Transport packet
 47 |             0x00b2: "unconn_message",  # Unconnected Messages (eg. used within CIP command SendRRData)
 48 |             0x0100: "listservices_response",  # ListServices response
 49 |         }),
 50 |         scapy_all.LEShortField("length", None),
 51 |     ]
 52 | 
 53 |     def extract_padding(self, p):
 54 |         return p[:self.length], p[self.length:]
 55 | 
 56 |     def post_build(self, p, pay):
 57 |         if self.length is None and pay:
 58 |             l = len(pay)
 59 |             p = p[:2] + struct.pack("<H", l) + p[4:]
 60 |         return p + pay
 61 | 
 62 | 
 63 | class ENIP_SendUnitData(scapy_all.Packet):
 64 |     """Data in ENIP header specific to the specified command"""
 65 |     name = "ENIP_SendUnitData"
 66 |     fields_desc = [
 67 |         scapy_all.LEIntField("interface_handle", 0),
 68 |         scapy_all.LEShortField("timeout", 0),
 69 |         utils.LEShortLenField("count", None, count_of="items"),
 70 |         scapy_all.PacketListField("items", [], ENIP_SendUnitData_Item,
 71 |                                   count_from=lambda p: p.count),
 72 |     ]
 73 | 
 74 | 
 75 | class ENIP_SendRRData(scapy_all.Packet):
 76 |     name = "ENIP_SendRRData"
 77 |     fields_desc = ENIP_SendUnitData.fields_desc
 78 | 
 79 | 
 80 | class ENIP_RegisterSession(scapy_all.Packet):
 81 |     name = "ENIP_RegisterSession"
 82 |     fields_desc = [
 83 |         scapy_all.LEShortField("protocol_version", 1),
 84 |         scapy_all.LEShortField("options", 0),
 85 |     ]
 86 | 
 87 | 
 88 | class ENIP_TCP(scapy_all.Packet):
 89 |     """Ethernet/IP packet over TCP"""
 90 |     name = "ENIP_TCP"
 91 |     fields_desc = [
 92 |         scapy_all.LEShortEnumField("command_id", None, {
 93 |             0x0004: "ListServices",
 94 |             0x0063: "ListIdentity",
 95 |             0x0064: "ListInterfaces",
 96 |             0x0065: "RegisterSession",
 97 |             0x0066: "UnregisterSession",
 98 |             0x006f: "SendRRData",  # Send Request/Reply data
 99 |             0x0070: "SendUnitData",
100 |         }),
101 |         scapy_all.LEShortField("length", None),
102 |         scapy_all.LEIntField("session", 0),
103 |         scapy_all.LEIntEnumField("status", 0, {0: "success"}),
104 |         scapy_all.LELongField("sender_context", 0),
105 |         scapy_all.LEIntField("options", 0),
106 |     ]
107 | 
108 |     def extract_padding(self, p):
109 |         return p[:self.length], p[self.length:]
110 | 
111 |     def post_build(self, p, pay):
112 |         if self.length is None and pay:
113 |             l = len(pay)
114 |             p = p[:2] + struct.pack("<H", l) + p[4:]
115 |         return p + pay
116 | 
117 | 
118 | scapy_all.bind_layers(scapy_all.TCP, ENIP_TCP, dport=44818)
119 | scapy_all.bind_layers(scapy_all.TCP, ENIP_TCP, sport=44818)
120 | 
121 | scapy_all.bind_layers(ENIP_TCP, ENIP_RegisterSession, command_id=0x0065)
122 | scapy_all.bind_layers(ENIP_TCP, ENIP_SendRRData, command_id=0x006f)
123 | scapy_all.bind_layers(ENIP_TCP, ENIP_SendUnitData, command_id=0x0070)
124 | scapy_all.bind_layers(ENIP_SendUnitData_Item, ENIP_ConnectionAddress, type_id=0x00a1)
125 | scapy_all.bind_layers(ENIP_SendUnitData_Item, ENIP_ConnectionPacket, type_id=0x00b1)
126 | 
127 | if __name__ == '__main__':
128 |     # Test building/dissecting packets
129 |     # Build a raw packet over ENIP
130 |     pkt = scapy_all.Ether(src='01:23:45:67:89:ab', dst='ba:98:76:54:32:10')
131 |     pkt /= scapy_all.IP(src='192.168.1.1', dst='192.168.1.42')
132 |     pkt /= scapy_all.TCP(sport=10000, dport=44818)
133 |     pkt /= ENIP_TCP()
134 |     pkt /= ENIP_SendUnitData(items=[
135 |         ENIP_SendUnitData_Item() / ENIP_ConnectionAddress(connection_id=1337),
136 |         ENIP_SendUnitData_Item() / ENIP_ConnectionPacket(sequence=4242) / scapy_all.Raw(load='test'),
137 |     ])
138 | 
139 |     # Build!
140 |     data = str(pkt)
141 |     pkt = scapy_all.Ether(data)
142 |     pkt.show()
143 | 
144 |     # Test the value of some fields
145 |     assert pkt[ENIP_TCP].command_id == 0x70
146 |     assert pkt[ENIP_TCP].session == 0
147 |     assert pkt[ENIP_TCP].status == 0
148 |     assert pkt[ENIP_TCP].length == 26
149 |     assert pkt[ENIP_SendUnitData].count == 2
150 |     assert pkt[ENIP_SendUnitData].items[0].type_id == 0x00a1
151 |     assert pkt[ENIP_SendUnitData].items[0].length == 4
152 |     assert pkt[ENIP_SendUnitData].items[0].payload == pkt[ENIP_ConnectionAddress]
153 |     assert pkt[ENIP_ConnectionAddress].connection_id == 1337
154 |     assert pkt[ENIP_SendUnitData].items[1].type_id == 0x00b1
155 |     assert pkt[ENIP_SendUnitData].items[1].length == 6
156 |     assert pkt[ENIP_SendUnitData].items[1].payload == pkt[ENIP_ConnectionPacket]
157 |     assert pkt[ENIP_ConnectionPacket].sequence == 4242
158 |     assert pkt[ENIP_ConnectionPacket].payload.load == 'test'
159 | 


--------------------------------------------------------------------------------
/enip_udp.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python2
  2 | # -*- coding: utf-8 -*-
  3 | # Copyright (c) 2015 Nicolas Iooss, SUTD
  4 | #
  5 | # Permission is hereby granted, free of charge, to any person obtaining a copy
  6 | # of this software and associated documentation files (the "Software"), to deal
  7 | # in the Software without restriction, including without limitation the rights
  8 | # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9 | # copies of the Software, and to permit persons to whom the Software is
 10 | # furnished to do so, subject to the following conditions:
 11 | #
 12 | # The above copyright notice and this permission notice shall be included in
 13 | # all copies or substantial portions of the Software.
 14 | #
 15 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17 | # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18 | # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19 | # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 20 | # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 21 | # THE SOFTWARE.
 22 | """Ethernet/IP over UDP scapy dissector
 23 | 
 24 | This dissector only supports a "keep-alive" kind of packet which has been seen
 25 | in SUTD's secure water treatment testbed.
 26 | """
 27 | import struct
 28 | 
 29 | from scapy import all as scapy_all
 30 | 
 31 | import utils
 32 | 
 33 | # Keep-alive sequences
 34 | ENIP_UDP_KEEPALIVE = (
 35 |     b'\x01\x00\xff\xff\xff\xff' +
 36 |     b'\xff\xff\xff\xff\x00\x00\x00\x00' +
 37 |     b'\xff\xff\xff\xff\x00\x00\x00\x00' +
 38 |     b'\xff\xff\xff\xff\x00\x00\x00\x00' +
 39 |     b'\xff\xff\xff\xff\x00\x00\x00\x00')
 40 | 
 41 | 
 42 | class ENIP_UDP_SequencedAddress(scapy_all.Packet):
 43 |     name = "ENIP_UDP_SequencedAddress"
 44 |     fields_desc = [
 45 |         scapy_all.LEIntField("connection_id", 0),
 46 |         scapy_all.LEIntField("sequence", 0),
 47 |     ]
 48 | 
 49 | 
 50 | class ENIP_UDP_Item(scapy_all.Packet):
 51 |     name = "ENIP_UDP_Item"
 52 |     fields_desc = [
 53 |         scapy_all.LEShortEnumField("type_id", 0, {
 54 |             0x00b1: "Connected_Data_Item",
 55 |             0x8002: "Sequenced_Address",
 56 |         }),
 57 |         scapy_all.LEShortField("length", None),
 58 |     ]
 59 | 
 60 |     def extract_padding(self, p):
 61 |         return p[:self.length], p[self.length:]
 62 | 
 63 |     def post_build(self, p, pay):
 64 |         if self.length is None and pay:
 65 |             l = len(pay)
 66 |             p = p[:2] + struct.pack("<H", l) + p[4:]
 67 |         return p + pay
 68 | 
 69 | 
 70 | class ENIP_UDP(scapy_all.Packet):
 71 |     """Ethernet/IP packet over UDP"""
 72 |     name = "ENIP_UDP"
 73 |     fields_desc = [
 74 |         utils.LEShortLenField("count", None, count_of="items"),
 75 |         scapy_all.PacketListField("items", [], ENIP_UDP_Item,
 76 |                                   count_from=lambda p: p.count),
 77 |     ]
 78 | 
 79 |     def extract_padding(self, p):
 80 |         return "", p
 81 | 
 82 | 
 83 | scapy_all.bind_layers(scapy_all.UDP, ENIP_UDP, sport=2222, dport=2222)
 84 | scapy_all.bind_layers(ENIP_UDP_Item, ENIP_UDP_SequencedAddress, type_id=0x8002)
 85 | 
 86 | if __name__ == '__main__':
 87 |     # Test building/dissecting packets
 88 |     # Build a keep-alive packet
 89 |     pkt = scapy_all.Ether(src='00:1d:9c:c8:13:37', dst='01:00:5e:40:12:34')
 90 |     pkt /= scapy_all.IP(src='192.168.1.42', dst='239.192.18.52')
 91 |     pkt /= scapy_all.UDP(sport=2222, dport=2222)
 92 |     pkt /= ENIP_UDP(items=[
 93 |         ENIP_UDP_Item() / ENIP_UDP_SequencedAddress(connection_id=1337, sequence=42),
 94 |         ENIP_UDP_Item(type_id=0x00b1) / scapy_all.Raw(load=ENIP_UDP_KEEPALIVE),
 95 |     ])
 96 | 
 97 |     # Build!
 98 |     data = str(pkt)
 99 |     pkt = scapy_all.Ether(data)
100 |     pkt.show()
101 | 
102 |     # Test the value of some fields
103 |     assert pkt[ENIP_UDP].count == 2
104 |     assert pkt[ENIP_UDP].items[0].type_id == 0x8002
105 |     assert pkt[ENIP_UDP].items[0].length == 8
106 |     assert pkt[ENIP_UDP].items[0].payload == pkt[ENIP_UDP_SequencedAddress]
107 |     assert pkt[ENIP_UDP_SequencedAddress].connection_id == 1337
108 |     assert pkt[ENIP_UDP_SequencedAddress].sequence == 42
109 |     assert pkt[ENIP_UDP].items[1].type_id == 0x00b1
110 |     assert pkt[ENIP_UDP].items[1].length == 38
111 |     assert pkt[ENIP_UDP].items[1].payload.load == ENIP_UDP_KEEPALIVE
112 | 


--------------------------------------------------------------------------------
/plc.py:
--------------------------------------------------------------------------------
  1 | #!/usr/bin/env python2
  2 | # -*- coding: utf-8 -*-
  3 | # Copyright (c) 2015 Nicolas Iooss, SUTD
  4 | #
  5 | # Permission is hereby granted, free of charge, to any person obtaining a copy
  6 | # of this software and associated documentation files (the "Software"), to deal
  7 | # in the Software without restriction, including without limitation the rights
  8 | # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  9 | # copies of the Software, and to permit persons to whom the Software is
 10 | # furnished to do so, subject to the following conditions:
 11 | #
 12 | # The above copyright notice and this permission notice shall be included in
 13 | # all copies or substantial portions of the Software.
 14 | #
 15 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17 | # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18 | # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19 | # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 20 | # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 21 | # THE SOFTWARE.
 22 | """Establish all what is needed to communicate with a PLC"""
 23 | import logging
 24 | import socket
 25 | import struct
 26 | 
 27 | from scapy import all as scapy_all
 28 | 
 29 | from cip import CIP, CIP_Path, CIP_ReqConnectionManager, \
 30 |     CIP_MultipleServicePacket, CIP_ReqForwardOpen, CIP_RespForwardOpen, \
 31 |     CIP_ReqForwardClose, CIP_ReqGetAttributeList, CIP_ReqReadOtherTag
 32 | from enip_tcp import ENIP_TCP, ENIP_SendUnitData, ENIP_SendUnitData_Item, \
 33 |     ENIP_ConnectionAddress, ENIP_ConnectionPacket, ENIP_RegisterSession, ENIP_SendRRData
 34 | 
 35 | # Global switch to make it easy to test without sending anything
 36 | NO_NETWORK = False
 37 | 
 38 | logger = logging.getLogger(__name__)
 39 | 
 40 | 
 41 | class PLCClient(object):
 42 |     """Handle all the state of an Ethernet/IP session with a PLC"""
 43 | 
 44 |     def __init__(self, plc_addr, plc_port=44818):
 45 |         if not NO_NETWORK:
 46 |             try:
 47 |                 self.sock = socket.create_connection((plc_addr, plc_port))
 48 |             except socket.error as exc:
 49 |                 logger.warn("socket error: %s", exc)
 50 |                 logger.warn("Continuing without sending anything")
 51 |                 self.sock = None
 52 |         else:
 53 |             self.sock = None
 54 |         self.session_id = 0
 55 |         self.enip_connid = 0
 56 |         self.sequence = 1
 57 | 
 58 |         # Open an Ethernet/IP session
 59 |         sessionpkt = ENIP_TCP() / ENIP_RegisterSession()
 60 |         if self.sock is not None:
 61 |             self.sock.send(str(sessionpkt))
 62 |             reply_pkt = self.recv_enippkt()
 63 |             self.session_id = reply_pkt.session
 64 | 
 65 |     @property
 66 |     def connected(self):
 67 |         return True if self.sock else False
 68 | 
 69 |     def send_rr_cip(self, cippkt):
 70 |         """Send a CIP packet over the TCP connection as an ENIP Req/Rep Data"""
 71 |         enippkt = ENIP_TCP(session=self.session_id)
 72 |         enippkt /= ENIP_SendRRData(items=[
 73 |             ENIP_SendUnitData_Item(type_id=0),
 74 |             ENIP_SendUnitData_Item() / cippkt
 75 |         ])
 76 |         if self.sock is not None:
 77 |             self.sock.send(str(enippkt))
 78 | 
 79 |     def send_rr_cm_cip(self, cippkt):
 80 |         """Encapsulate the CIP packet into a ConnectionManager packet"""
 81 |         cipcm_msg = [cippkt]
 82 |         cippkt = CIP(path=CIP_Path.make(class_id=6, instance_id=1))
 83 |         cippkt /= CIP_ReqConnectionManager(message=cipcm_msg)
 84 |         self.send_rr_cip(cippkt)
 85 | 
 86 |     def send_rr_mr_cip(self, cippkt):
 87 |         """Encapsulate the CIP packet into a MultipleServicePacket to MessageRouter"""
 88 |         cipcm_msg = [cippkt]
 89 |         cippkt = CIP(path=CIP_Path(wordsize=2, path=b'\x20\x02\x24\x01'))
 90 |         cippkt /= CIP_MultipleServicePacket(packets=cipcm_msg)
 91 |         self.send_rr_cip(cippkt)
 92 | 
 93 |     def send_unit_cip(self, cippkt):
 94 |         """Send a CIP packet over the TCP connection as an ENIP Unit Data"""
 95 |         enippkt = ENIP_TCP(session=self.session_id)
 96 |         enippkt /= ENIP_SendUnitData(items=[
 97 |             ENIP_SendUnitData_Item() / ENIP_ConnectionAddress(connection_id=self.enip_connid),
 98 |             ENIP_SendUnitData_Item() / ENIP_ConnectionPacket(sequence=self.sequence) / cippkt
 99 |         ])
100 |         self.sequence += 1
101 |         if self.sock is not None:
102 |             self.sock.send(str(enippkt))
103 | 
104 |     def recv_enippkt(self):
105 |         """Receive an ENIP packet from the TCP socket"""
106 |         if self.sock is None:
107 |             return
108 |         pktbytes = self.sock.recv(2000)
109 |         pkt = ENIP_TCP(pktbytes)
110 |         return pkt
111 | 
112 |     def forward_open(self):
113 |         """Send a forward open request"""
114 |         cippkt = CIP(service=0x54, path=CIP_Path(wordsize=2, path=b'\x20\x06\x24\x01'))
115 |         cippkt /= CIP_ReqForwardOpen(path_wordsize=3, path=b"\x01\x00\x20\x02\x24\x01")
116 |         self.send_rr_cip(cippkt)
117 |         resppkt = self.recv_enippkt()
118 |         if self.sock is None:
119 |             return
120 |         cippkt = resppkt[CIP]
121 |         if cippkt.status[0].status != 0:
122 |             logger.error("Failed to Forward Open CIP connection: %r", cippkt.status[0])
123 |             return False
124 |         assert isinstance(cippkt.payload, CIP_RespForwardOpen)
125 |         self.enip_connid = cippkt.payload.OT_network_connection_id
126 |         return True
127 | 
128 |     def forward_close(self):
129 |         """Send a forward close request"""
130 |         cippkt = CIP(service=0x4e, path=CIP_Path(wordsize=2, path=b'\x20\x06\x24\x01'))
131 |         cippkt /= CIP_ReqForwardClose(path_wordsize=3, path=b"\x01\x00\x20\x02\x24\x01")
132 |         self.send_rr_cip(cippkt)
133 |         if self.sock is None:
134 |             return
135 |         resppkt = self.recv_enippkt()
136 |         cippkt = resppkt[CIP]
137 |         if cippkt.status[0].status != 0:
138 |             logger.error("Failed to Forward Close CIP connection: %r", cippkt.status[0])
139 |             return False
140 |         return True
141 | 
142 |     def get_attribute(self, class_id, instance, attr):
143 |         """Get an attribute for the specified class/instance/attr path"""
144 |         # Get_Attribute_Single does not seem to work properly
145 |         # path = CIP_Path.make(class_id=class_id, instance_id=instance, attribute_id=attr)
146 |         # cippkt = CIP(service=0x0e, path=path)  # Get_Attribute_Single
147 |         path = CIP_Path.make(class_id=class_id, instance_id=instance)
148 |         cippkt = CIP(path=path) / CIP_ReqGetAttributeList(attrs=[attr])
149 |         self.send_rr_cm_cip(cippkt)
150 |         if self.sock is None:
151 |             return
152 |         resppkt = self.recv_enippkt()
153 |         cippkt = resppkt[CIP]
154 |         if cippkt.status[0].status != 0:
155 |             logger.error("CIP get attribute error: %r", cippkt.status[0])
156 |             return
157 |         resp_getattrlist = str(cippkt.payload)
158 |         assert resp_getattrlist[:2] == b'\x01\x00'  # Attribute count must be 1
159 |         assert struct.unpack('<H', resp_getattrlist[2:4])[0] == attr  # First attribute
160 |         assert resp_getattrlist[4:6] == b'\x00\x00'  # Status
161 |         return resp_getattrlist[6:]
162 | 
163 |     def set_attribute(self, class_id, instance, attr, value):
164 |         """Set the value of attribute class/instance/attr"""
165 |         path = CIP_Path.make(class_id=class_id, instance_id=instance)
166 |         # User CIP service 4: Set_Attribute_List
167 |         cippkt = CIP(service=4, path=path) / scapy_all.Raw(load=struct.pack('<HH', 1, attr) + value)
168 |         self.send_rr_cm_cip(cippkt)
169 |         if self.sock is None:
170 |             return
171 |         resppkt = self.recv_enippkt()
172 |         cippkt = resppkt[CIP]
173 |         if cippkt.status[0].status != 0:
174 |             logger.error("CIP set attribute error: %r", cippkt.status[0])
175 |             return False
176 |         return True
177 | 
178 |     def get_list_of_instances(self, class_id):
179 |         """Use CIP service 0x4b to get a list of instances of the specified class"""
180 |         start_instance = 0
181 |         inst_list = []
182 |         while True:
183 |             cippkt = CIP(service=0x4b, path=CIP_Path.make(class_id=class_id, instance_id=start_instance))
184 |             self.send_rr_cm_cip(cippkt)
185 |             if self.sock is None:
186 |                 return
187 |             resppkt = self.recv_enippkt()
188 | 
189 |             # Decode a list of 32-bit integers
190 |             data = str(resppkt[CIP].payload)
191 |             for i in range(0, len(data), 4):
192 |                 inst_list.append(struct.unpack('<I', data[i:i + 4])[0])
193 | 
194 |             cipstatus = resppkt[CIP].status[0].status
195 |             if cipstatus == 0:
196 |                 return inst_list
197 |             elif cipstatus == 6:
198 |                 # Partial response, query again from the next instance
199 |                 start_instance = inst_list[-1] + 1
200 |             else:
201 |                 logger.error("Error in Get Instance List response: %r", resppkt[CIP].status[0])
202 |                 return
203 | 
204 |     def read_full_tag(self, class_id, instance_id, total_size):
205 |         """Read the content of a tag which can be quite big"""
206 |         data_chunks = []
207 |         offset = 0
208 |         remaining_size = total_size
209 | 
210 |         while remaining_size > 0:
211 |             cippkt = CIP(service=0x4c, path=CIP_Path.make(class_id=class_id, instance_id=instance_id))
212 |             cippkt /= CIP_ReqReadOtherTag(start=offset, length=remaining_size)
213 |             self.send_rr_cm_cip(cippkt)
214 |             if self.sock is None:
215 |                 return
216 |             resppkt = self.recv_enippkt()
217 | 
218 |             cipstatus = resppkt[CIP].status[0].status
219 |             received_data = str(resppkt[CIP].payload)
220 |             if cipstatus == 0:
221 |                 # Success
222 |                 assert len(received_data) == remaining_size
223 |             elif cipstatus == 6 and len(received_data) > 0:
224 |                 # Partial response (size too big)
225 |                 pass
226 |             else:
227 |                 logger.error("Error in Read Tag response: %r", resppkt[CIP].status[0])
228 |                 return
229 | 
230 |             # Remember the chunk and continue
231 |             data_chunks.append(received_data)
232 |             offset += len(received_data)
233 |             remaining_size -= len(received_data)
234 |         return b''.join(data_chunks)
235 | 
236 |     @staticmethod
237 |     def attr_format(attrval):
238 |         """Format an attribute value to be displayed to a human"""
239 |         if len(attrval) == 1:
240 |             # 1-byte integer
241 |             return hex(struct.unpack('B', attrval)[0])
242 |         elif len(attrval) == 2:
243 |             # 2-byte integer
244 |             return hex(struct.unpack('<H', attrval)[0])
245 |         elif len(attrval) == 4:
246 |             # 4-byte integer
247 |             return hex(struct.unpack('<I', attrval)[0])
248 |         elif all(x == b'\0' for x in attrval):
249 |             # a series of zeros
250 |             return '[{} zeros]'.format(len(attrval))
251 |         # format in hexadecimal the content of attrval
252 |         return ''.join('{:2x}'.format(ord(x)) for x in attrval)
253 | 


--------------------------------------------------------------------------------
/utils.py:
--------------------------------------------------------------------------------
 1 | #!/usr/bin/env python
 2 | # -*- coding: utf-8 -*-
 3 | # Copyright (c) 2015 Nicolas Iooss, SUTD
 4 | #
 5 | # Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | # of this software and associated documentation files (the "Software"), to deal
 7 | # in the Software without restriction, including without limitation the rights
 8 | # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | # copies of the Software, and to permit persons to whom the Software is
10 | # furnished to do so, subject to the following conditions:
11 | #
12 | # The above copyright notice and this permission notice shall be included in
13 | # all copies or substantial portions of the Software.
14 | #
15 | # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21 | # THE SOFTWARE.
22 | """Useful routines and utilities which simplify code writing"""
23 | from scapy import all as scapy_all
24 | 
25 | 
26 | def hexdump(data, columns=16, indentlvl=""):
27 |     """Return the hexadecimal representation of the data"""
28 | 
29 |     def do_line(line):
30 |         return (
31 |             indentlvl +
32 |             " ".join("{:02x}".format(ord(b)) for b in line) +
33 |             "   " * (columns - len(line)) +
34 |             "  " +
35 |             "".join(b if 32 <= ord(b) < 127 else "." for b in line))
36 | 
37 |     return "\n".join(do_line(data[i:i + columns]) for i in range(0, len(data), columns))
38 | 
39 | 
40 | class LEShortLenField(scapy_all.FieldLenField):
41 |     """A len field in a 2-byte integer"""
42 | 
43 |     def __init__(self, name, default, count_of=None, length_of=None):
44 |         scapy_all.FieldLenField.__init__(self, name, default, fmt="<H",
45 |                                          count_of=count_of, length_of=length_of)
46 | 
47 | 
48 | class XBitEnumField(scapy_all.BitEnumField):
49 |     """A BitEnumField with hexadecimal representation"""
50 | 
51 |     def __init__(self, name, default, size, enum):
52 |         scapy_all.BitEnumField.__init__(self, name, default, size, enum)
53 | 
54 |     def i2repr_one(self, pkt, x):
55 |         if x in self.i2s:
56 |             return self.i2s[x]
57 |         return scapy_all.lhex(x)
58 | 


--------------------------------------------------------------------------------