Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/scapy/packet.py: 47%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# SPDX-License-Identifier: GPL-2.0-only
2# This file is part of Scapy
3# See https://scapy.net/ for more information
4# Copyright (C) Philippe Biondi <phil@secdev.org>
6"""
7Packet class
9Provides:
10 - the default Packet classes
11 - binding mechanisms
12 - fuzz() method
13 - exploration methods: explore() / ls()
14"""
16from collections import defaultdict
18import json
19import re
20import time
21import itertools
22import copy
23import types
24import warnings
26from scapy.fields import (
27 AnyField,
28 BitField,
29 ConditionalField,
30 Emph,
31 EnumField,
32 Field,
33 FlagsField,
34 FlagValue,
35 MultiEnumField,
36 MultipleTypeField,
37 PadField,
38 PacketListField,
39 RawVal,
40 StrField,
41)
42from scapy.config import conf, _version_checker
43from scapy.compat import raw, bytes_encode
44from scapy.base_classes import BasePacket, Gen, SetGen, Packet_metaclass, \
45 _CanvasDumpExtended
46from scapy.interfaces import _GlobInterfaceType
47from scapy.volatile import RandField, VolatileValue
48from scapy.utils import import_hexcap, tex_escape, colgen, issubtype, \
49 pretty_list, EDecimal
50from scapy.error import Scapy_Exception, log_runtime, warning
51from scapy.libs.test_pyx import PYX
53# Typing imports
54from typing import (
55 Any,
56 Callable,
57 ClassVar,
58 Dict,
59 Iterator,
60 List,
61 NoReturn,
62 Optional,
63 Set,
64 Tuple,
65 Type,
66 TypeVar,
67 Union,
68 Sequence,
69 cast,
70)
71from scapy.compat import Self
73try:
74 import pyx
75except ImportError:
76 pass
79_T = TypeVar("_T", Dict[str, Any], Optional[Dict[str, Any]])
82class Packet(
83 BasePacket,
84 _CanvasDumpExtended,
85 metaclass=Packet_metaclass
86):
87 __slots__ = [
88 "time", "sent_time", "name",
89 "default_fields", "fields", "fieldtype",
90 "overload_fields", "overloaded_fields",
91 "packetfields",
92 "original", "explicit", "raw_packet_cache",
93 "raw_packet_cache_fields", "_pkt", "post_transforms",
94 "stop_dissection_after",
95 # then payload, underlayer and parent
96 "payload", "underlayer", "parent",
97 "name",
98 # used for sr()
99 "_answered",
100 # used when sniffing
101 "direction", "sniffed_on",
102 # handle snaplen Vs real length
103 "wirelen",
104 "comments",
105 "process_information"
106 ]
107 # Types of the __slots__ above: __init__ sets them through
108 # object.__setattr__, which leaves nowhere to put an inline type comment.
109 time: Union[EDecimal, float]
110 sent_time: Union[EDecimal, float, None]
111 default_fields: Dict[str, Any]
112 fields: Dict[str, Any]
113 fieldtype: Dict[str, AnyField]
114 overloaded_fields: Dict[str, Any]
115 packetfields: List[AnyField]
116 original: bytes
117 explicit: int
118 raw_packet_cache: Optional[bytes]
119 raw_packet_cache_fields: Optional[Dict[str, Any]]
120 stop_dissection_after: Optional[Type['Packet']]
121 payload: 'Packet'
122 underlayer: Optional['Packet']
123 parent: Optional['Packet']
124 direction: Optional[int]
125 sniffed_on: Optional[_GlobInterfaceType]
126 wirelen: Optional[int]
127 comments: Optional[List[bytes]]
128 process_information: Optional[Dict[str, Any]]
129 name = None # type: Optional[str]
130 fields_desc = [] # type: ClassVar[List[AnyField]]
131 deprecated_fields = {} # type: Dict[str, Tuple[str, str]]
132 overload_fields = {} # type: Dict[Type[Packet], Dict[str, Any]]
133 payload_guess = [] # type: List[Tuple[Dict[str, Any], Type[Packet]]]
134 show_indent = 1
135 show_summary = True
136 match_subclass = False
137 class_dont_cache = {} # type: Dict[Type[Packet], bool]
138 class_packetfields = {} # type: Dict[Type[Packet], Any]
139 class_default_fields = {} # type: Dict[Type[Packet], Dict[str, Any]]
140 class_default_fields_ref = {} # type: Dict[Type[Packet], List[str]]
141 class_fieldtype = {} # type: Dict[Type[Packet], Dict[str, AnyField]] # noqa: E501
143 @classmethod
144 def from_hexcap(cls):
145 # type: (Type[Packet]) -> Packet
146 return cls(import_hexcap())
148 @classmethod
149 def upper_bonds(self):
150 # type: () -> None
151 for fval, upper in self.payload_guess:
152 print(
153 "%-20s %s" % (
154 upper.__name__,
155 ", ".join("%-12s" % ("%s=%r" % i) for i in fval.items()),
156 )
157 )
159 @classmethod
160 def lower_bonds(self):
161 # type: () -> None
162 for lower, fval in self._overload_fields.items():
163 print(
164 "%-20s %s" % (
165 lower.__name__,
166 ", ".join("%-12s" % ("%s=%r" % i) for i in fval.items()),
167 )
168 )
170 def __init__(self,
171 _pkt=b"", # type: Union[bytes, bytearray]
172 post_transform=None, # type: Any
173 _internal=0, # type: int
174 _underlayer=None, # type: Optional[Packet]
175 _parent=None, # type: Optional[Packet]
176 stop_dissection_after=None, # type: Optional[Type[Packet]]
177 **fields # type: Any
178 ):
179 # type: (...) -> None
180 # Every attribute set below is a __slots__ member, so bypass
181 # __setattr__: resolving field names there costs more than the
182 # assignment itself, and this runs for every dissected layer.
183 object.__setattr__(self, "time", 0.0 if _internal else time.time())
184 object.__setattr__(self, "sent_time", None)
185 object.__setattr__(self, "name", self.__class__.__name__
186 if self._name is None else self._name)
187 object.__setattr__(self, "default_fields", {})
188 object.__setattr__(self, "overload_fields", self._overload_fields)
189 object.__setattr__(self, "overloaded_fields", {})
190 object.__setattr__(self, "fields", {})
191 object.__setattr__(self, "fieldtype", {})
192 object.__setattr__(self, "packetfields", [])
193 object.__setattr__(self, "payload", NoPayload())
194 self.init_fields(bool(_pkt))
195 object.__setattr__(self, "underlayer", _underlayer)
196 object.__setattr__(self, "parent", _parent)
197 if isinstance(_pkt, bytearray):
198 _pkt = bytes(_pkt)
199 object.__setattr__(self, "original", _pkt)
200 object.__setattr__(self, "explicit", 0)
201 object.__setattr__(self, "raw_packet_cache", None)
202 object.__setattr__(self, "raw_packet_cache_fields", None)
203 object.__setattr__(self, "wirelen", None)
204 object.__setattr__(self, "direction", None)
205 object.__setattr__(self, "sniffed_on", None)
206 object.__setattr__(self, "comments", None)
207 object.__setattr__(self, "process_information", None)
208 object.__setattr__(self, "stop_dissection_after", stop_dissection_after)
209 if _pkt:
210 self.dissect(_pkt)
211 if not _internal:
212 self.dissection_done(self)
213 # We use this strange initialization so that the fields
214 # are initialized in their declaration order.
215 # It is required to always support MultipleTypeField
216 for field in self.fields_desc:
217 fname = field.name
218 try:
219 value = fields.pop(fname)
220 except KeyError:
221 continue
222 self.fields[fname] = value if isinstance(value, RawVal) else \
223 self.get_field(fname).any2i(self, value)
224 # The remaining fields are unknown
225 for fname in fields:
226 if fname in self.deprecated_fields:
227 # Resolve deprecated fields
228 value = fields[fname]
229 fname = self._resolve_alias(fname)
230 self.fields[fname] = value if isinstance(value, RawVal) else \
231 self.get_field(fname).any2i(self, value)
232 continue
233 raise AttributeError(fname)
234 if isinstance(post_transform, list):
235 self.post_transforms = post_transform
236 elif post_transform is None:
237 self.post_transforms = []
238 else:
239 self.post_transforms = [post_transform]
241 _PickleType = Tuple[
242 Union[EDecimal, float],
243 Optional[Union[EDecimal, float, None]],
244 Optional[int],
245 Optional[_GlobInterfaceType],
246 Optional[int],
247 Optional[bytes],
248 ]
249 _PickleStateType = Union[_PickleType, Dict[str, Any]]
251 @property
252 def comment(self):
253 # type: () -> Optional[bytes]
254 """Get the comment of the packet"""
255 if self.comments and len(self.comments):
256 return self.comments[0]
257 return None
259 @comment.setter
260 def comment(self, value):
261 # type: (Optional[bytes]) -> None
262 """
263 Set the comment of the packet.
264 If value is None, it will clear the comments.
265 """
266 if value is not None:
267 self.comments = [value]
268 else:
269 self.comments = None
271 @classmethod
272 def _rebuild_pkt(cls, raw_packet):
273 # type: (Type[Packet], bytes) -> Packet
274 """Helper used by pickle to reconstruct Packet from raw bytes."""
275 return cls(raw_packet)
277 def __reduce__(self):
278 # type: () -> Tuple[Any, ...]
279 """Used by pickling methods"""
280 state = {
281 "pickle_state_version": 2,
282 "time": self.time,
283 "sent_time": self.sent_time,
284 "direction": self.direction,
285 "sniffed_on": self.sniffed_on,
286 "wirelen": self.wirelen,
287 # Keep both keys for compatibility with historical/transition code.
288 "comment": self.comment,
289 "comments": self.comments,
290 }
291 extra_slots = {}
292 for attr in type(self).__all_slots__ - set(Packet.__slots__):
293 if hasattr(self, attr):
294 extra_slots[attr] = getattr(self, attr)
295 if extra_slots:
296 state["extra_slots"] = extra_slots # type: ignore
297 return (type(self)._rebuild_pkt, (self.build(),), state)
299 def __setstate__(self, state):
300 # type: (Packet._PickleStateType) -> Packet
301 """Rebuild state using pickable methods"""
302 # Legacy format: tuple produced by older Packet.__reduce__.
303 if isinstance(state, tuple):
304 self.time = state[0]
305 self.sent_time = state[1]
306 self.direction = state[2]
307 self.sniffed_on = state[3]
308 self.wirelen = state[4]
309 self.comment = state[5]
310 return self
312 # New format: versioned dict metadata.
313 self.time = state.get("time", self.time)
314 self.sent_time = state.get("sent_time", self.sent_time)
315 self.direction = state.get("direction", self.direction)
316 self.sniffed_on = state.get("sniffed_on", self.sniffed_on)
317 self.wirelen = state.get("wirelen", self.wirelen)
319 if "comments" in state:
320 self.comments = state["comments"]
321 elif "comment" in state:
322 self.comment = state["comment"]
324 extra_slots = state.get("extra_slots", {})
325 if isinstance(extra_slots, dict):
326 for attr, value in extra_slots.items():
327 # Only restore known subclass slots; ignore stale/unknown entries.
328 if attr in type(self).__all_slots__ and attr not in Packet.__slots__:
329 try:
330 setattr(self, attr, value)
331 except AttributeError:
332 pass
333 return self
335 def __deepcopy__(self,
336 memo, # type: Any
337 ):
338 # type: (...) -> Packet
339 """Used by copy.deepcopy"""
340 return self.copy()
342 def init_fields(self, for_dissect_only=False):
343 # type: (bool) -> None
344 """
345 Initialize each fields of the fields_desc dict
346 """
348 if self.class_dont_cache.get(self.__class__, False):
349 self.do_init_fields(self.fields_desc)
350 else:
351 self.do_init_cached_fields(for_dissect_only=for_dissect_only)
353 def do_init_fields(self,
354 flist, # type: Sequence[AnyField]
355 ):
356 # type: (...) -> None
357 """
358 Initialize each fields of the fields_desc dict
359 """
360 default_fields = {}
361 for f in flist:
362 default_fields[f.name] = copy.deepcopy(f.default)
363 self.fieldtype[f.name] = f
364 if f.holds_packets:
365 self.packetfields.append(f)
366 # We set default_fields last to avoid race issues
367 self.default_fields = default_fields
369 def do_init_cached_fields(self, for_dissect_only=False):
370 # type: (bool) -> None
371 """
372 Initialize each fields of the fields_desc dict, or use the cached
373 fields information
374 """
376 cls_name = self.__class__
378 # Build the fields information
379 default_fields = Packet.class_default_fields.get(cls_name)
380 if default_fields is None:
381 self.prepare_cached_fields(self.fields_desc)
382 default_fields = Packet.class_default_fields.get(cls_name)
384 # Use fields information from cache
385 if default_fields:
386 self.default_fields = default_fields
387 self.fieldtype = Packet.class_fieldtype[cls_name]
388 self.packetfields = Packet.class_packetfields[cls_name]
390 # Optimization: no need for references when only dissecting.
391 if for_dissect_only:
392 return
394 # Deepcopy default references
395 for fname in Packet.class_default_fields_ref[cls_name]:
396 value = self.default_fields[fname]
397 try:
398 self.fields[fname] = value.copy()
399 except AttributeError:
400 # Python 2.7 - list only
401 self.fields[fname] = value[:]
403 def prepare_cached_fields(self, flist):
404 # type: (Sequence[AnyField]) -> None
405 """
406 Prepare the cached fields of the fields_desc dict
407 """
409 cls_name = self.__class__
411 # Fields cache initialization
412 if not flist:
413 return
415 class_default_fields = dict()
416 class_default_fields_ref = list()
417 class_fieldtype = dict()
418 class_packetfields = list()
420 # Fields initialization
421 for f in flist:
422 if isinstance(f, MultipleTypeField):
423 # Abort
424 self.class_dont_cache[cls_name] = True
425 self.do_init_fields(self.fields_desc)
426 return
428 class_default_fields[f.name] = copy.deepcopy(f.default)
429 class_fieldtype[f.name] = f
430 if f.holds_packets:
431 class_packetfields.append(f)
433 # Remember references
434 if isinstance(f.default, (list, dict, set, RandField, Packet)):
435 class_default_fields_ref.append(f.name)
437 # Apply
438 Packet.class_default_fields_ref[cls_name] = class_default_fields_ref
439 Packet.class_fieldtype[cls_name] = class_fieldtype
440 Packet.class_packetfields[cls_name] = class_packetfields
441 # Last to avoid racing issues
442 Packet.class_default_fields[cls_name] = class_default_fields
444 def dissection_done(self, pkt):
445 # type: (Packet) -> None
446 """DEV: will be called after a dissection is completed"""
447 self.post_dissection(pkt)
448 self.payload.dissection_done(pkt)
450 def post_dissection(self, pkt):
451 # type: (Packet) -> None
452 """DEV: is called after the dissection of the whole packet"""
453 pass
455 def get_field(self, fld):
456 # type: (str) -> AnyField
457 """DEV: returns the field instance from the name of the field"""
458 return self.fieldtype[fld]
460 def add_payload(self, payload):
461 # type: (Union[Packet, bytes]) -> None
462 if payload is None:
463 return
464 elif not isinstance(self.payload, NoPayload):
465 self.payload.add_payload(payload)
466 else:
467 if isinstance(payload, Packet):
468 self.payload = payload
469 payload.add_underlayer(self)
470 for t in self.aliastypes:
471 if t in payload.overload_fields:
472 self.overloaded_fields = payload.overload_fields[t]
473 break
474 elif isinstance(payload, (bytes, str, bytearray, memoryview)):
475 self.payload = conf.raw_layer(load=bytes_encode(payload))
476 else:
477 raise TypeError("payload must be 'Packet', 'bytes', 'str', 'bytearray', or 'memoryview', not [%s]" % repr(payload)) # noqa: E501
479 def remove_payload(self):
480 # type: () -> None
481 self.payload.remove_underlayer(self)
482 self.payload = NoPayload()
483 self.overloaded_fields = {}
485 def add_underlayer(self, underlayer):
486 # type: (Packet) -> None
487 self.underlayer = underlayer
489 def remove_underlayer(self, other):
490 # type: (Packet) -> None
491 self.underlayer = None
493 def add_parent(self, parent):
494 # type: (Packet) -> None
495 """Set packet parent.
496 When packet is an element in PacketListField, parent field would
497 point to the list owner packet."""
498 self.parent = parent
500 def remove_parent(self, other):
501 # type: (Packet) -> None
502 """Remove packet parent.
503 When packet is an element in PacketListField, parent field would
504 point to the list owner packet."""
505 self.parent = None
507 def copy(self) -> Self:
508 """Returns a deep copy of the instance."""
509 clone = self.__class__()
510 clone.fields = self.copy_fields_dict(self.fields)
511 clone.default_fields = self.copy_fields_dict(self.default_fields)
512 clone.overloaded_fields = self.overloaded_fields.copy()
513 clone.underlayer = self.underlayer
514 clone.parent = self.parent
515 clone.explicit = self.explicit
516 clone.raw_packet_cache = self.raw_packet_cache
517 clone.raw_packet_cache_fields = self.copy_fields_dict(
518 self.raw_packet_cache_fields
519 )
520 clone.wirelen = self.wirelen
521 clone.post_transforms = self.post_transforms[:]
522 clone.payload = self.payload.copy()
523 clone.payload.add_underlayer(clone)
524 clone.time = self.time
525 clone.comments = self.comments
526 clone.direction = self.direction
527 clone.sniffed_on = self.sniffed_on
528 return clone
530 def _resolve_alias(self, attr):
531 # type: (str) -> str
532 new_attr, version = self.deprecated_fields[attr]
533 warnings.warn(
534 "%s has been deprecated in favor of %s since %s !" % (
535 attr, new_attr, version
536 ), DeprecationWarning
537 )
538 return new_attr
540 def getfieldval(self, attr):
541 # type: (str) -> Any
542 if self.deprecated_fields and attr in self.deprecated_fields:
543 attr = self._resolve_alias(attr)
544 try:
545 return self.fields[attr]
546 except KeyError:
547 pass
548 try:
549 return self.overloaded_fields[attr]
550 except KeyError:
551 pass
552 try:
553 return self.default_fields[attr]
554 except KeyError:
555 pass
556 return self.payload.getfieldval(attr)
558 def getfield_and_val(self, attr):
559 # type: (str) -> Tuple[AnyField, Any]
560 if self.deprecated_fields and attr in self.deprecated_fields:
561 attr = self._resolve_alias(attr)
562 if attr in self.fields:
563 return self.fieldtype[attr], self.fields[attr]
564 if attr in self.overloaded_fields:
565 return self.fieldtype[attr], self.overloaded_fields[attr]
566 if attr in self.default_fields:
567 return self.fieldtype[attr], self.default_fields[attr]
568 raise ValueError
570 def __getattr__(self, attr):
571 # type: (str) -> Any
572 try:
573 fld, v = self.getfield_and_val(attr)
574 except ValueError:
575 return self.payload.__getattr__(attr)
576 if fld is not None:
577 return v if isinstance(v, RawVal) else fld.i2h(self, v)
578 return v
580 def setfieldval(self, attr, val):
581 # type: (str, Any) -> None
582 if self.deprecated_fields and attr in self.deprecated_fields:
583 attr = self._resolve_alias(attr)
584 if attr in self.default_fields:
585 fld = self.get_field(attr)
586 if fld is None:
587 any2i = lambda x, y: y # type: Callable[..., Any]
588 else:
589 any2i = fld.any2i
590 self.fields[attr] = val if isinstance(val, RawVal) else \
591 any2i(self, val)
592 self.explicit = 0
593 self.raw_packet_cache = None
594 self.raw_packet_cache_fields = None
595 self.wirelen = None
596 elif attr == "payload":
597 self.remove_payload()
598 self.add_payload(val)
599 else:
600 self.payload.setfieldval(attr, val)
602 def __setattr__(self, attr, val):
603 # type: (str, Any) -> None
604 if attr in self.__all_slots__:
605 return object.__setattr__(self, attr, val)
606 try:
607 return self.setfieldval(attr, val)
608 except AttributeError:
609 pass
610 return object.__setattr__(self, attr, val)
612 def delfieldval(self, attr):
613 # type: (str) -> None
614 if attr in self.fields:
615 del self.fields[attr]
616 self.explicit = 0 # in case a default value must be explicit
617 self.raw_packet_cache = None
618 self.raw_packet_cache_fields = None
619 self.wirelen = None
620 elif attr in self.default_fields:
621 pass
622 elif attr == "payload":
623 self.remove_payload()
624 else:
625 self.payload.delfieldval(attr)
627 def __delattr__(self, attr):
628 # type: (str) -> None
629 if attr == "payload":
630 return self.remove_payload()
631 if attr in self.__all_slots__:
632 return object.__delattr__(self, attr)
633 try:
634 return self.delfieldval(attr)
635 except AttributeError:
636 pass
637 return object.__delattr__(self, attr)
639 def _superdir(self):
640 # type: () -> Set[str]
641 """
642 Return a list of slots and methods, including those from subclasses.
643 """
644 attrs = set() # type: Set[str]
645 cls = self.__class__
646 if hasattr(cls, '__all_slots__'):
647 attrs.update(cls.__all_slots__)
648 for bcls in cls.__mro__:
649 if hasattr(bcls, '__dict__'):
650 attrs.update(bcls.__dict__)
651 return attrs
653 def __dir__(self):
654 # type: () -> List[str]
655 """
656 Add fields to tab completion list.
657 """
658 return sorted(itertools.chain(self._superdir(), self.default_fields))
660 def __repr__(self):
661 # type: () -> str
662 s = ""
663 ct = conf.color_theme
664 for f in self.fields_desc:
665 if isinstance(f, ConditionalField) and not f._evalcond(self):
666 continue
667 if f.name in self.fields:
668 fval = self.fields[f.name]
669 if isinstance(fval, (list, dict, set)) and len(fval) == 0:
670 continue
671 val = f.i2repr(self, fval)
672 elif f.name in self.overloaded_fields:
673 fover = self.overloaded_fields[f.name]
674 if isinstance(fover, (list, dict, set)) and len(fover) == 0:
675 continue
676 val = f.i2repr(self, fover)
677 else:
678 continue
679 if isinstance(f, Emph) or f in conf.emph:
680 ncol = ct.emph_field_name
681 vcol = ct.emph_field_value
682 else:
683 ncol = ct.field_name
684 vcol = ct.field_value
686 s += " %s%s%s" % (ncol(f.name),
687 ct.punct("="),
688 vcol(val))
689 return "%s%s %s %s%s%s" % (ct.punct("<"),
690 ct.layer_name(self.__class__.__name__),
691 s,
692 ct.punct("|"),
693 repr(self.payload),
694 ct.punct(">"))
696 def __str__(self):
697 # type: () -> str
698 return self.summary()
700 def __bytes__(self):
701 # type: () -> bytes
702 return self.build()
704 def __div__(self, other):
705 # type: (Any) -> Self
706 if isinstance(other, Packet):
707 cloneA = self.copy()
708 cloneB = other.copy()
709 cloneA.add_payload(cloneB)
710 return cloneA
711 elif isinstance(other, (bytes, str, bytearray, memoryview)):
712 return self / conf.raw_layer(load=bytes_encode(other))
713 else:
714 return other.__rdiv__(self) # type: ignore
715 __truediv__ = __div__
717 def __rdiv__(self, other):
718 # type: (Any) -> Packet
719 if isinstance(other, (bytes, str, bytearray, memoryview)):
720 return conf.raw_layer(load=bytes_encode(other)) / self
721 else:
722 raise TypeError
723 __rtruediv__ = __rdiv__
725 def __mul__(self, other):
726 # type: (Any) -> List[Packet]
727 if isinstance(other, int):
728 return [self] * other
729 else:
730 raise TypeError
732 def __rmul__(self, other):
733 # type: (Any) -> List[Packet]
734 return self.__mul__(other)
736 def __nonzero__(self):
737 # type: () -> bool
738 return True
739 __bool__ = __nonzero__
741 def __len__(self):
742 # type: () -> int
743 return len(self.__bytes__())
745 def copy_field_value(self, fieldname, value):
746 # type: (str, Any) -> Any
747 return self.get_field(fieldname).do_copy(value)
749 def copy_fields_dict(self, fields):
750 # type: (_T) -> _T
751 if fields is None:
752 return None
753 fieldtype = self.fieldtype
754 return {fname: fieldtype[fname].do_copy(fval)
755 for fname, fval in fields.items()}
757 def _raw_packet_cache_field_value(self, fld, val, copy=False):
758 # type: (AnyField, Any, bool) -> Optional[Any]
759 """Get a value representative of a mutable field to detect changes"""
760 if fld.holds_packets:
761 # avoid copying whole packets (perf: #GH3894)
762 if fld.islist:
763 if copy:
764 return [
765 (fld.do_copy(x.fields), x.payload.raw_packet_cache)
766 for x in val
767 ]
768 return [
769 (x.fields, x.payload.raw_packet_cache) for x in val
770 ]
771 else:
772 if copy:
773 return (fld.do_copy(val.fields),
774 val.payload.raw_packet_cache)
775 return (val.fields, val.payload.raw_packet_cache)
776 elif fld.islist or fld.ismutable:
777 return fld.do_copy(val) if copy else val
778 return None
780 def clear_cache(self):
781 # type: () -> None
782 """Clear the raw packet cache for the field and all its subfields"""
783 self.raw_packet_cache = None
784 for fname, fval in self.fields.items():
785 fld = self.get_field(fname)
786 if fld.holds_packets:
787 if isinstance(fval, Packet):
788 fval.clear_cache()
789 elif isinstance(fval, list):
790 for fsubval in fval:
791 fsubval.clear_cache()
792 self.payload.clear_cache()
794 def self_build(self):
795 # type: () -> bytes
796 """
797 Create the default layer regarding fields_desc dict
798 """
799 if self.raw_packet_cache is not None and \
800 self.raw_packet_cache_fields is not None:
801 for fname, fval in self.raw_packet_cache_fields.items():
802 fld, val = self.getfield_and_val(fname)
803 if self._raw_packet_cache_field_value(fld, val) != fval:
804 self.raw_packet_cache = None
805 self.raw_packet_cache_fields = None
806 self.wirelen = None
807 break
808 if self.raw_packet_cache is not None:
809 return self.raw_packet_cache
810 p = b""
811 for f in self.fields_desc:
812 val = self.getfieldval(f.name)
813 if isinstance(val, RawVal):
814 p += bytes(val)
815 else:
816 try:
817 p = f.addfield(self, p, val)
818 except Exception as ex:
819 try:
820 ex.args = (
821 "While building field '%s': " % f.name +
822 ex.args[0],
823 ) + ex.args[1:]
824 except (AttributeError, IndexError):
825 pass
826 raise ex
827 return p
829 def do_build_payload(self):
830 # type: () -> bytes
831 """
832 Create the default version of the payload layer
834 :return: a string of payload layer
835 """
836 return self.payload.do_build()
838 def do_build(self):
839 # type: () -> bytes
840 """
841 Create the default version of the layer
843 :return: a string of the packet with the payload
844 """
845 if not self.explicit:
846 self = next(iter(self))
847 pkt = self.self_build()
848 for t in self.post_transforms:
849 pkt = t(pkt)
850 pay = self.do_build_payload()
851 if self.raw_packet_cache is None:
852 return self.post_build(pkt, pay)
853 else:
854 return pkt + pay
856 def build_padding(self):
857 # type: () -> bytes
858 return self.payload.build_padding()
860 def build(self):
861 # type: () -> bytes
862 """
863 Create the current layer
865 :return: string of the packet with the payload
866 """
867 p = self.do_build()
868 p += self.build_padding()
869 p = self.build_done(p)
870 return p
872 def post_build(self, pkt, pay):
873 # type: (bytes, bytes) -> bytes
874 """
875 DEV: called right after the current layer is build.
877 :param str pkt: the current packet (build by self_build function)
878 :param str pay: the packet payload (build by do_build_payload function)
879 :return: a string of the packet with the payload
880 """
881 return pkt + pay
883 def build_done(self, p):
884 # type: (bytes) -> bytes
885 return self.payload.build_done(p)
887 def do_build_ps(self):
888 # type: () -> Tuple[bytes, List[Tuple[Packet, List[Tuple[Field[Any, Any], str, bytes]]]]] # noqa: E501
889 p = b""
890 pl = []
891 q = b""
892 for f in self.fields_desc:
893 if isinstance(f, ConditionalField) and not f._evalcond(self):
894 continue
895 p = f.addfield(self, p, self.getfieldval(f.name))
896 if isinstance(p, bytes):
897 r = p[len(q):]
898 q = p
899 else:
900 r = b""
901 pl.append((f, f.i2repr(self, self.getfieldval(f.name)), r))
903 pkt, lst = self.payload.build_ps(internal=1)
904 p += pkt
905 lst.append((self, pl))
907 return p, lst
909 def build_ps(self, internal=0):
910 # type: (int) -> Tuple[bytes, List[Tuple[Packet, List[Tuple[Any, Any, bytes]]]]] # noqa: E501
911 p, lst = self.do_build_ps()
912# if not internal:
913# pkt = self
914# while pkt.haslayer(conf.padding_layer):
915# pkt = pkt.getlayer(conf.padding_layer)
916# lst.append( (pkt, [ ("loakjkjd", pkt.load, pkt.load) ] ) )
917# p += pkt.load
918# pkt = pkt.payload
919 return p, lst
921 def canvas_dump(self, layer_shift=0, rebuild=1):
922 # type: (int, int) -> pyx.canvas.canvas
923 if PYX == 0:
924 raise ImportError("PyX and its dependencies must be installed")
925 canvas = pyx.canvas.canvas()
926 if rebuild:
927 _, t = self.__class__(raw(self)).build_ps()
928 else:
929 _, t = self.build_ps()
930 YTXTI = len(t)
931 for _, l in t:
932 YTXTI += len(l)
933 YTXT = float(YTXTI)
934 YDUMP = YTXT
936 XSTART = 1
937 XDSTART = 10
938 y = 0.0
939 yd = 0.0
940 XMUL = 0.55
941 YMUL = 0.4
943 backcolor = colgen(0.6, 0.8, 1.0, trans=pyx.color.rgb)
944 forecolor = colgen(0.2, 0.5, 0.8, trans=pyx.color.rgb)
945# backcolor=makecol(0.376, 0.729, 0.525, 1.0)
947 def hexstr(x):
948 # type: (bytes) -> str
949 return " ".join("%02x" % c for c in x)
951 def make_dump_txt(x, y, txt):
952 # type: (int, float, bytes) -> pyx.text.text
953 return pyx.text.text(
954 XDSTART + x * XMUL,
955 (YDUMP - y) * YMUL,
956 r"\tt{%s}" % hexstr(txt),
957 [pyx.text.size.Large]
958 )
960 def make_box(o):
961 # type: (pyx.bbox.bbox) -> pyx.bbox.bbox
962 return pyx.box.rect(
963 o.left(), o.bottom(), o.width(), o.height(),
964 relcenter=(0.5, 0.5)
965 )
967 def make_frame(lst):
968 # type: (List[Any]) -> pyx.path.path
969 if len(lst) == 1:
970 b = lst[0].bbox()
971 b.enlarge(pyx.unit.u_pt)
972 return b.path()
973 else:
974 fb = lst[0].bbox()
975 fb.enlarge(pyx.unit.u_pt)
976 lb = lst[-1].bbox()
977 lb.enlarge(pyx.unit.u_pt)
978 if len(lst) == 2 and fb.left() > lb.right():
979 return pyx.path.path(pyx.path.moveto(fb.right(), fb.top()),
980 pyx.path.lineto(fb.left(), fb.top()),
981 pyx.path.lineto(fb.left(), fb.bottom()), # noqa: E501
982 pyx.path.lineto(fb.right(), fb.bottom()), # noqa: E501
983 pyx.path.moveto(lb.left(), lb.top()),
984 pyx.path.lineto(lb.right(), lb.top()),
985 pyx.path.lineto(lb.right(), lb.bottom()), # noqa: E501
986 pyx.path.lineto(lb.left(), lb.bottom())) # noqa: E501
987 else:
988 # XXX
989 gb = lst[1].bbox()
990 if gb != lb:
991 gb.enlarge(pyx.unit.u_pt)
992 kb = lst[-2].bbox()
993 if kb != gb and kb != lb:
994 kb.enlarge(pyx.unit.u_pt)
995 return pyx.path.path(pyx.path.moveto(fb.left(), fb.top()),
996 pyx.path.lineto(fb.right(), fb.top()),
997 pyx.path.lineto(fb.right(), kb.bottom()), # noqa: E501
998 pyx.path.lineto(lb.right(), kb.bottom()), # noqa: E501
999 pyx.path.lineto(lb.right(), lb.bottom()), # noqa: E501
1000 pyx.path.lineto(lb.left(), lb.bottom()), # noqa: E501
1001 pyx.path.lineto(lb.left(), gb.top()),
1002 pyx.path.lineto(fb.left(), gb.top()),
1003 pyx.path.closepath(),)
1005 def make_dump(s, # type: bytes
1006 shift=0, # type: int
1007 y=0., # type: float
1008 col=None, # type: pyx.color.color
1009 bkcol=None, # type: pyx.color.color
1010 large=16 # type: int
1011 ):
1012 # type: (...) -> Tuple[pyx.canvas.canvas, pyx.bbox.bbox, int, float] # noqa: E501
1013 c = pyx.canvas.canvas()
1014 tlist = []
1015 while s:
1016 dmp, s = s[:large - shift], s[large - shift:]
1017 txt = make_dump_txt(shift, y, dmp)
1018 tlist.append(txt)
1019 shift += len(dmp)
1020 if shift >= 16:
1021 shift = 0
1022 y += 1
1023 if col is None:
1024 col = pyx.color.rgb.red
1025 if bkcol is None:
1026 bkcol = pyx.color.rgb.white
1027 c.stroke(make_frame(tlist), [col, pyx.deco.filled([bkcol]), pyx.style.linewidth.Thick]) # noqa: E501
1028 for txt in tlist:
1029 c.insert(txt)
1030 return c, tlist[-1].bbox(), shift, y
1032 last_shift, last_y = 0, 0.0
1033 while t:
1034 bkcol = next(backcolor)
1035 proto, fields = t.pop()
1036 y += 0.5
1037 pt = pyx.text.text(
1038 XSTART,
1039 (YTXT - y) * YMUL,
1040 r"\font\cmssfont=cmss10\cmssfont{%s}" % tex_escape(
1041 str(proto.name)
1042 ),
1043 [pyx.text.size.Large]
1044 )
1045 y += 1
1046 ptbb = pt.bbox()
1047 ptbb.enlarge(pyx.unit.u_pt * 2)
1048 canvas.stroke(ptbb.path(), [pyx.color.rgb.black, pyx.deco.filled([bkcol])]) # noqa: E501
1049 canvas.insert(pt)
1050 for field, fval, fdump in fields:
1051 col = next(forecolor)
1052 ft = pyx.text.text(XSTART, (YTXT - y) * YMUL, r"\font\cmssfont=cmss10\cmssfont{%s}" % tex_escape(field.name)) # noqa: E501
1053 if isinstance(field, BitField):
1054 fsize = '%sb' % field.size
1055 else:
1056 fsize = '%sB' % len(fdump)
1057 if (hasattr(field, 'field') and
1058 'LE' in field.field.__class__.__name__[:3] or
1059 'LE' in field.__class__.__name__[:3]):
1060 fsize = r'$\scriptstyle\langle$' + fsize
1061 st = pyx.text.text(XSTART + 3.4, (YTXT - y) * YMUL, r"\font\cmbxfont=cmssbx10 scaled 600\cmbxfont{%s}" % fsize, [pyx.text.halign.boxright]) # noqa: E501
1062 if isinstance(fval, str):
1063 if len(fval) > 18:
1064 fval = fval[:18] + "[...]"
1065 else:
1066 fval = ""
1067 vt = pyx.text.text(XSTART + 3.5, (YTXT - y) * YMUL, r"\font\cmssfont=cmss10\cmssfont{%s}" % tex_escape(fval)) # noqa: E501
1068 y += 1.0
1069 if fdump:
1070 dt, target, last_shift, last_y = make_dump(fdump, last_shift, last_y, col, bkcol) # noqa: E501
1072 dtb = target
1073 vtb = vt.bbox()
1074 bxvt = make_box(vtb)
1075 bxdt = make_box(dtb)
1076 dtb.enlarge(pyx.unit.u_pt)
1077 try:
1078 if yd < 0:
1079 cnx = pyx.connector.curve(bxvt, bxdt, absangle1=0, absangle2=-90) # noqa: E501
1080 else:
1081 cnx = pyx.connector.curve(bxvt, bxdt, absangle1=0, absangle2=90) # noqa: E501
1082 except Exception:
1083 pass
1084 else:
1085 canvas.stroke(cnx, [pyx.style.linewidth.thin, pyx.deco.earrow.small, col]) # noqa: E501
1087 canvas.insert(dt)
1089 canvas.insert(ft)
1090 canvas.insert(st)
1091 canvas.insert(vt)
1092 last_y += layer_shift
1094 return canvas
1096 def extract_padding(self, s):
1097 # type: (bytes) -> Tuple[bytes, Optional[bytes]]
1098 """
1099 DEV: to be overloaded to extract current layer's padding.
1101 :param str s: the current layer
1102 :return: a couple of strings (actual layer, padding)
1103 """
1104 return s, None
1106 def post_dissect(self, s):
1107 # type: (bytes) -> bytes
1108 """DEV: is called right after the current layer has been dissected"""
1109 return s
1111 def pre_dissect(self, s):
1112 # type: (bytes) -> bytes
1113 """DEV: is called right before the current layer is dissected"""
1114 return s
1116 def do_dissect(self, s):
1117 # type: (bytes) -> bytes
1118 _raw = s
1119 self.raw_packet_cache_fields = {}
1120 for f in self.fields_desc:
1121 s, fval = f.getfield(self, s)
1122 # Skip unused ConditionalField
1123 if f.isconditional and fval is None:
1124 continue
1125 # We need to track fields with mutable values to discard
1126 # .raw_packet_cache when needed.
1127 if (f.islist or f.holds_packets or f.ismutable) and fval is not None:
1128 self.raw_packet_cache_fields[f.name] = \
1129 self._raw_packet_cache_field_value(f, fval, copy=True)
1130 self.fields[f.name] = fval
1131 # Nothing left to dissect
1132 if not s and (f.ismayend or
1133 (fval is not None and f.isconditional and
1134 f.fld.ismayend)): # type: ignore
1135 break
1136 self.raw_packet_cache = _raw[:-len(s)] if s else _raw
1137 self.explicit = 1
1138 return s
1140 def do_dissect_payload(self, s):
1141 # type: (bytes) -> None
1142 """
1143 Perform the dissection of the layer's payload
1145 :param str s: the raw layer
1146 """
1147 if s:
1148 if (
1149 self.stop_dissection_after and
1150 isinstance(self, self.stop_dissection_after)
1151 ):
1152 # stop dissection here
1153 p = conf.raw_layer(s, _internal=1, _underlayer=self)
1154 self.add_payload(p)
1155 return
1156 cls = self.guess_payload_class(s)
1157 try:
1158 p = cls(
1159 s,
1160 stop_dissection_after=self.stop_dissection_after,
1161 _internal=1,
1162 _underlayer=self,
1163 )
1164 except KeyboardInterrupt:
1165 raise
1166 except Exception:
1167 if conf.debug_dissector:
1168 if issubtype(cls, Packet):
1169 log_runtime.error("%s dissector failed", cls.__name__)
1170 else:
1171 log_runtime.error("%s.guess_payload_class() returned "
1172 "[%s]",
1173 self.__class__.__name__, repr(cls))
1174 if cls is not None:
1175 raise
1176 p = conf.raw_layer(s, _internal=1, _underlayer=self)
1177 self.add_payload(p)
1179 def dissect(self, s):
1180 # type: (bytes) -> None
1181 s = self.pre_dissect(s)
1183 s = self.do_dissect(s)
1185 s = self.post_dissect(s)
1187 payl, pad = self.extract_padding(s)
1188 self.do_dissect_payload(payl)
1189 if pad and conf.padding:
1190 self.add_payload(conf.padding_layer(pad))
1192 def guess_payload_class(self, payload):
1193 # type: (bytes) -> Type[Packet]
1194 """
1195 DEV: Guesses the next payload class from layer bonds.
1196 Can be overloaded to use a different mechanism.
1198 :param str payload: the layer's payload
1199 :return: the payload class
1200 """
1201 for t in self.aliastypes:
1202 for fval, cls in t.payload_guess:
1203 try:
1204 if all(v == self.getfieldval(k)
1205 for k, v in fval.items()):
1206 return cls # type: ignore
1207 except AttributeError:
1208 pass
1209 return self.default_payload_class(payload)
1211 def default_payload_class(self, payload):
1212 # type: (bytes) -> Type[Packet]
1213 """
1214 DEV: Returns the default payload class if nothing has been found by the
1215 guess_payload_class() method.
1217 :param str payload: the layer's payload
1218 :return: the default payload class define inside the configuration file
1219 """
1220 return conf.raw_layer
1222 def hide_defaults(self):
1223 # type: () -> None
1224 """Removes fields' values that are the same as default values."""
1225 # use list(): self.fields is modified in the loop
1226 for k, v in list(self.fields.items()):
1227 v = self.fields[k]
1228 if k in self.default_fields:
1229 if self.default_fields[k] == v:
1230 del self.fields[k]
1231 self.payload.hide_defaults()
1233 def clone_with(self, payload=None, **kargs):
1234 # type: (Optional[Any], **Any) -> Any
1235 pkt = self.__class__()
1236 pkt.explicit = 1
1237 pkt.fields = kargs
1238 pkt.default_fields = self.copy_fields_dict(self.default_fields)
1239 pkt.overloaded_fields = self.overloaded_fields.copy()
1240 pkt.time = self.time
1241 pkt.underlayer = self.underlayer
1242 pkt.parent = self.parent
1243 pkt.post_transforms = self.post_transforms
1244 pkt.raw_packet_cache = self.raw_packet_cache
1245 pkt.raw_packet_cache_fields = self.copy_fields_dict(
1246 self.raw_packet_cache_fields
1247 )
1248 pkt.wirelen = self.wirelen
1249 pkt.comments = self.comments
1250 pkt.sniffed_on = self.sniffed_on
1251 pkt.direction = self.direction
1252 if payload is not None:
1253 pkt.add_payload(payload)
1254 return pkt
1256 def __iter__(self):
1257 # type: () -> Iterator[Packet]
1258 """Iterates through all sub-packets generated by this Packet."""
1259 def loop(todo, done, self=self):
1260 # type: (List[str], Dict[str, Any], Any) -> Iterator[Packet]
1261 if todo:
1262 eltname = todo.pop()
1263 elt = self.getfieldval(eltname)
1264 if not isinstance(elt, Gen):
1265 fld = self.get_field(eltname)
1266 if isinstance(fld, MultipleTypeField):
1267 # find out which sub-field is active right now
1268 fld = fld._find_fld_pkt(self)
1270 if fld.islist:
1271 elt = SetGen([elt])
1272 else:
1273 elt = SetGen(elt)
1274 for e in elt:
1275 done[eltname] = e
1276 for x in loop(todo[:], done):
1277 yield x
1278 else:
1279 if isinstance(self.payload, NoPayload):
1280 payloads = SetGen([None]) # type: SetGen[Packet]
1281 else:
1282 payloads = self.payload
1283 for payl in payloads:
1284 # Let's make sure subpackets are consistent
1285 done2 = done.copy()
1286 for k in done2:
1287 if isinstance(done2[k], VolatileValue):
1288 done2[k] = done2[k]._fix()
1289 pkt = self.clone_with(payload=payl, **done2)
1290 yield pkt
1292 if self.explicit or self.raw_packet_cache is not None:
1293 todo = []
1294 done = self.fields
1295 else:
1296 todo = [k for (k, v) in itertools.chain(self.default_fields.items(),
1297 self.overloaded_fields.items())
1298 if isinstance(v, VolatileValue)] + list(self.fields)
1299 done = {}
1300 return loop(todo, done)
1302 def iterpayloads(self):
1303 # type: () -> Iterator[Packet]
1304 """Used to iter through the payloads of a Packet.
1305 Useful for DNS or 802.11 for instance.
1306 """
1307 yield self
1308 current = self
1309 while current.payload:
1310 current = current.payload
1311 yield current
1313 def __gt__(self, other):
1314 # type: (Packet) -> int
1315 """True if other is an answer from self (self ==> other)."""
1316 if isinstance(other, Packet):
1317 return other < self
1318 elif isinstance(other, bytes):
1319 return 1
1320 else:
1321 raise TypeError((self, other))
1323 def __lt__(self, other):
1324 # type: (Packet) -> int
1325 """True if self is an answer from other (other ==> self)."""
1326 if isinstance(other, Packet):
1327 return self.answers(other)
1328 elif isinstance(other, bytes):
1329 return 1
1330 else:
1331 raise TypeError((self, other))
1333 def __eq__(self, other):
1334 # type: (Any) -> bool
1335 if not isinstance(other, self.__class__):
1336 return False
1337 for f in self.fields_desc:
1338 if f not in other.fields_desc:
1339 return False
1340 if self.getfieldval(f.name) != other.getfieldval(f.name):
1341 return False
1342 return self.payload == other.payload
1344 def __ne__(self, other):
1345 # type: (Any) -> bool
1346 return not self.__eq__(other)
1348 # Note: setting __hash__ to None is the standard way
1349 # of making an object un-hashable. mypy doesn't know that
1350 __hash__ = None # type: ignore
1352 def hashret(self):
1353 # type: () -> bytes
1354 """DEV: returns a string that has the same value for a request
1355 and its answer."""
1356 return self.payload.hashret()
1358 def answers(self, other):
1359 # type: (Packet) -> int
1360 """DEV: true if self is an answer from other"""
1361 if other.__class__ == self.__class__:
1362 return self.payload.answers(other.payload)
1363 return 0
1365 def layers(self):
1366 # type: () -> List[Type[Packet]]
1367 """returns a list of layer classes (including subclasses) in this packet""" # noqa: E501
1368 layers = []
1369 lyr = self # type: Optional[Packet]
1370 while lyr:
1371 layers.append(lyr.__class__)
1372 lyr = lyr.payload.getlayer(0, _subclass=True)
1373 return layers
1375 def haslayer(self, cls, _subclass=None):
1376 # type: (Union[Type[Packet], str], Optional[bool]) -> int
1377 """
1378 true if self has a layer that is an instance of cls.
1379 Superseded by "cls in self" syntax.
1380 """
1381 if _subclass is None:
1382 _subclass = self.match_subclass or None
1383 if _subclass:
1384 match = issubtype
1385 else:
1386 match = lambda x, t: bool(x == t)
1387 if cls is None or match(self.__class__, cls) \
1388 or cls in [self.__class__.__name__, self._name]:
1389 return True
1390 for f in self.packetfields:
1391 fvalue_gen = self.getfieldval(f.name)
1392 if fvalue_gen is None:
1393 continue
1394 if not f.islist:
1395 fvalue_gen = SetGen(fvalue_gen, _iterpacket=0)
1396 for fvalue in fvalue_gen:
1397 if isinstance(fvalue, Packet):
1398 ret = fvalue.haslayer(cls, _subclass=_subclass)
1399 if ret:
1400 return ret
1401 return self.payload.haslayer(cls, _subclass=_subclass)
1403 def getlayer(self,
1404 cls, # type: Union[int, Type[Packet], str]
1405 nb=1, # type: int
1406 _track=None, # type: Optional[List[int]]
1407 _subclass=None, # type: Optional[bool]
1408 **flt # type: Any
1409 ):
1410 # type: (...) -> Optional[Packet]
1411 """Return the nb^th layer that is an instance of cls, matching flt
1412values.
1413 """
1414 if _subclass is None:
1415 _subclass = self.match_subclass or None
1416 if _subclass:
1417 match = issubtype
1418 else:
1419 match = lambda x, t: bool(x == t)
1420 # Note:
1421 # cls can be int, packet, str
1422 # string_class_name can be packet, str (packet or packet+field)
1423 # class_name can be packet, str (packet only)
1424 if isinstance(cls, int):
1425 nb = cls + 1
1426 string_class_name = "" # type: Union[Type[Packet], str]
1427 else:
1428 string_class_name = cls
1429 class_name = "" # type: Union[Type[Packet], str]
1430 fld = None # type: Optional[str]
1431 if isinstance(string_class_name, str) and "." in string_class_name:
1432 class_name, fld = string_class_name.split(".", 1)
1433 else:
1434 class_name, fld = string_class_name, None
1435 if not class_name or match(self.__class__, class_name) \
1436 or class_name in [self.__class__.__name__, self._name]:
1437 if all(self.getfieldval(fldname) == fldvalue
1438 for fldname, fldvalue in flt.items()):
1439 if nb == 1:
1440 if fld is None:
1441 return self
1442 else:
1443 return self.getfieldval(fld) # type: ignore
1444 else:
1445 nb -= 1
1446 for f in self.packetfields:
1447 fvalue_gen = self.getfieldval(f.name)
1448 if fvalue_gen is None:
1449 continue
1450 if not f.islist:
1451 fvalue_gen = SetGen(fvalue_gen, _iterpacket=0)
1452 for fvalue in fvalue_gen:
1453 if isinstance(fvalue, Packet):
1454 track = [] # type: List[int]
1455 ret = fvalue.getlayer(class_name, nb=nb, _track=track,
1456 _subclass=_subclass, **flt)
1457 if ret is not None:
1458 return ret
1459 nb = track[0]
1460 return self.payload.getlayer(class_name, nb=nb, _track=_track,
1461 _subclass=_subclass, **flt)
1463 def firstlayer(self):
1464 # type: () -> Packet
1465 q = self
1466 while q.underlayer is not None:
1467 q = q.underlayer
1468 return q
1470 def __getitem__(self, cls):
1471 # type: (Union[Type[Packet], str]) -> Any
1472 if isinstance(cls, slice):
1473 lname = cls.start
1474 if cls.stop:
1475 ret = self.getlayer(cls.start, nb=cls.stop, **(cls.step or {}))
1476 else:
1477 ret = self.getlayer(cls.start, **(cls.step or {}))
1478 else:
1479 lname = cls
1480 ret = self.getlayer(cls)
1481 if ret is None:
1482 if isinstance(lname, type):
1483 name = lname.__name__
1484 elif not isinstance(lname, bytes):
1485 name = repr(lname)
1486 else:
1487 name = cast(str, lname)
1488 raise IndexError("Layer [%s] not found" % name)
1489 return ret
1491 def __delitem__(self, cls):
1492 # type: (Type[Packet]) -> None
1493 del self[cls].underlayer.payload
1495 def __setitem__(self, cls, val):
1496 # type: (Type[Packet], Packet) -> None
1497 self[cls].underlayer.payload = val
1499 def __contains__(self, cls):
1500 # type: (Union[Type[Packet], str]) -> int
1501 """
1502 "cls in self" returns true if self has a layer which is an
1503 instance of cls.
1504 """
1505 return self.haslayer(cls)
1507 def route(self):
1508 # type: () -> Tuple[Optional[str], Optional[str], Optional[str]]
1509 return self.payload.route()
1511 def fragment(self, *args, **kargs):
1512 # type: (*Any, **Any) -> List[Packet]
1513 return self.payload.fragment(*args, **kargs)
1515 def display(self, *args, **kargs): # Deprecated. Use show()
1516 # type: (*Any, **Any) -> None
1517 """Deprecated. Use show() method."""
1518 self.show(*args, **kargs)
1520 def _show_or_dump(self,
1521 dump=False, # type: bool
1522 indent=3, # type: int
1523 lvl="", # type: str
1524 label_lvl="", # type: str
1525 first_call=True # type: bool
1526 ):
1527 # type: (...) -> Optional[str]
1528 """
1529 Internal method that shows or dumps a hierarchical view of a packet.
1530 Called by show.
1532 :param dump: determine if it prints or returns the string value
1533 :param int indent: the size of indentation for each layer
1534 :param str lvl: additional information about the layer lvl
1535 :param str label_lvl: additional information about the layer fields
1536 :param first_call: determine if the current function is the first
1537 :return: return a hierarchical view if dump, else print it
1538 """
1540 if dump:
1541 from scapy.themes import ColorTheme, AnsiColorTheme
1542 ct: ColorTheme = AnsiColorTheme() # No color for dump output
1543 else:
1544 ct = conf.color_theme
1545 s = "%s%s %s %s\n" % (label_lvl,
1546 ct.punct("###["),
1547 ct.layer_name(self.name),
1548 ct.punct("]###"))
1549 fields = self.fields_desc.copy()
1550 while fields:
1551 f = fields.pop(0)
1552 if isinstance(f, ConditionalField) and not f._evalcond(self):
1553 continue
1554 if hasattr(f, "fields"): # Field has subfields
1555 s += "%s %s =\n" % (
1556 label_lvl + lvl,
1557 ct.depreciate_field_name(f.name),
1558 )
1559 lvl += " " * indent * self.show_indent
1560 for i, fld in enumerate(x for x in f.fields if hasattr(self, x.name)):
1561 fields.insert(i, fld)
1562 continue
1563 if isinstance(f, Emph) or f in conf.emph:
1564 ncol = ct.emph_field_name
1565 vcol = ct.emph_field_value
1566 else:
1567 ncol = ct.field_name
1568 vcol = ct.field_value
1569 pad = max(0, 10 - len(f.name)) * " "
1570 fvalue = self.getfieldval(f.name)
1571 if isinstance(fvalue, Packet) or (f.islist and f.holds_packets and isinstance(fvalue, list)): # noqa: E501
1572 s += "%s %s%s%s%s\n" % (label_lvl + lvl,
1573 ct.punct("\\"),
1574 ncol(f.name),
1575 pad,
1576 ct.punct("\\"))
1577 fvalue_gen = SetGen(
1578 fvalue,
1579 _iterpacket=0
1580 ) # type: SetGen[Packet]
1581 for fvalue in fvalue_gen:
1582 s += fvalue._show_or_dump(dump=dump, indent=indent, label_lvl=label_lvl + lvl + " |", first_call=False) # noqa: E501
1583 else:
1584 begn = "%s %s%s%s " % (label_lvl + lvl,
1585 ncol(f.name),
1586 pad,
1587 ct.punct("="),)
1588 reprval = f.i2repr(self, fvalue)
1589 if isinstance(reprval, str):
1590 reprval = reprval.replace("\n", "\n" + " " * (len(label_lvl) + # noqa: E501
1591 len(lvl) +
1592 len(f.name) +
1593 4))
1594 s += "%s%s\n" % (begn, vcol(reprval))
1595 if self.payload:
1596 s += self.payload._show_or_dump( # type: ignore
1597 dump=dump,
1598 indent=indent,
1599 lvl=lvl + (" " * indent * self.show_indent),
1600 label_lvl=label_lvl,
1601 first_call=False
1602 )
1604 if first_call and not dump:
1605 print(s)
1606 return None
1607 else:
1608 return s
1610 def show(self, dump=False, indent=3, lvl="", label_lvl=""):
1611 # type: (bool, int, str, str) -> Optional[Any]
1612 """
1613 Prints or returns (when "dump" is true) a hierarchical view of the
1614 packet.
1616 :param dump: determine if it prints or returns the string value
1617 :param int indent: the size of indentation for each layer
1618 :param str lvl: additional information about the layer lvl
1619 :param str label_lvl: additional information about the layer fields
1620 :return: return a hierarchical view if dump, else print it
1621 """
1622 return self._show_or_dump(dump, indent, lvl, label_lvl)
1624 def show2(self, dump=False, indent=3, lvl="", label_lvl=""):
1625 # type: (bool, int, str, str) -> Optional[Any]
1626 """
1627 Prints or returns (when "dump" is true) a hierarchical view of an
1628 assembled version of the packet, so that automatic fields are
1629 calculated (checksums, etc.)
1631 :param dump: determine if it prints or returns the string value
1632 :param int indent: the size of indentation for each layer
1633 :param str lvl: additional information about the layer lvl
1634 :param str label_lvl: additional information about the layer fields
1635 :return: return a hierarchical view if dump, else print it
1636 """
1637 return self.__class__(raw(self)).show(dump, indent, lvl, label_lvl)
1639 def sprintf(self, fmt, relax=1):
1640 # type: (str, int) -> str
1641 """
1642 sprintf(format, [relax=1]) -> str
1644 Where format is a string that can include directives. A directive
1645 begins and ends by % and has the following format:
1646 ``%[fmt[r],][cls[:nb].]field%``
1648 :param fmt: is a classic printf directive, "r" can be appended for raw
1649 substitution:
1650 (ex: IP.flags=0x18 instead of SA), nb is the number of the layer
1651 (ex: for IP/IP packets, IP:2.src is the src of the upper IP layer).
1652 Special case : "%.time%" is the creation time.
1653 Ex::
1655 p.sprintf(
1656 "%.time% %-15s,IP.src% -> %-15s,IP.dst% %IP.chksum% "
1657 "%03xr,IP.proto% %r,TCP.flags%"
1658 )
1660 Moreover, the format string can include conditional statements. A
1661 conditional statement looks like : {layer:string} where layer is a
1662 layer name, and string is the string to insert in place of the
1663 condition if it is true, i.e. if layer is present. If layer is
1664 preceded by a "!", the result is inverted. Conditions can be
1665 imbricated. A valid statement can be::
1667 p.sprintf("This is a{TCP: TCP}{UDP: UDP}{ICMP:n ICMP} packet")
1668 p.sprintf("{IP:%IP.dst% {ICMP:%ICMP.type%}{TCP:%TCP.dport%}}")
1670 A side effect is that, to obtain "{" and "}" characters, you must use
1671 "%(" and "%)".
1672 """
1674 escape = {"%": "%",
1675 "(": "{",
1676 ")": "}"}
1678 # Evaluate conditions
1679 while "{" in fmt:
1680 i = fmt.rindex("{")
1681 j = fmt[i + 1:].index("}")
1682 cond = fmt[i + 1:i + j + 1]
1683 k = cond.find(":")
1684 if k < 0:
1685 raise Scapy_Exception("Bad condition in format string: [%s] (read sprintf doc!)" % cond) # noqa: E501
1686 cond, format_ = cond[:k], cond[k + 1:]
1687 res = False
1688 if cond[0] == "!":
1689 res = True
1690 cond = cond[1:]
1691 if self.haslayer(cond):
1692 res = not res
1693 if not res:
1694 format_ = ""
1695 fmt = fmt[:i] + format_ + fmt[i + j + 2:]
1697 # Evaluate directives
1698 s = ""
1699 while "%" in fmt:
1700 i = fmt.index("%")
1701 s += fmt[:i]
1702 fmt = fmt[i + 1:]
1703 if fmt and fmt[0] in escape:
1704 s += escape[fmt[0]]
1705 fmt = fmt[1:]
1706 continue
1707 try:
1708 i = fmt.index("%")
1709 sfclsfld = fmt[:i]
1710 fclsfld = sfclsfld.split(",")
1711 if len(fclsfld) == 1:
1712 f = "s"
1713 clsfld = fclsfld[0]
1714 elif len(fclsfld) == 2:
1715 f, clsfld = fclsfld
1716 else:
1717 raise Scapy_Exception
1718 if "." in clsfld:
1719 cls, fld = clsfld.split(".")
1720 else:
1721 cls = self.__class__.__name__
1722 fld = clsfld
1723 num = 1
1724 if ":" in cls:
1725 cls, snum = cls.split(":")
1726 num = int(snum)
1727 fmt = fmt[i + 1:]
1728 except Exception:
1729 raise Scapy_Exception("Bad format string [%%%s%s]" % (fmt[:25], fmt[25:] and "...")) # noqa: E501
1730 else:
1731 if fld == "time":
1732 val = time.strftime(
1733 "%H:%M:%S.%%06i",
1734 time.localtime(float(self.time))
1735 ) % int((self.time - int(self.time)) * 1000000)
1736 elif cls == self.__class__.__name__ and hasattr(self, fld):
1737 if num > 1:
1738 val = self.payload.sprintf("%%%s,%s:%s.%s%%" % (f, cls, num - 1, fld), relax) # noqa: E501
1739 f = "s"
1740 else:
1741 try:
1742 val = self.getfieldval(fld)
1743 except AttributeError:
1744 val = getattr(self, fld)
1745 if f[-1] == "r": # Raw field value
1746 f = f[:-1]
1747 if not f:
1748 f = "s"
1749 else:
1750 if fld in self.fieldtype:
1751 val = self.fieldtype[fld].i2repr(self, val)
1752 else:
1753 val = self.payload.sprintf("%%%s%%" % sfclsfld, relax)
1754 f = "s"
1755 s += ("%" + f) % val
1757 s += fmt
1758 return s
1760 def mysummary(self):
1761 # type: () -> str
1762 """DEV: can be overloaded to return a string that summarizes the layer.
1763 Only one mysummary() is used in a whole packet summary: the one of the upper layer, # noqa: E501
1764 except if a mysummary() also returns (as a couple) a list of layers whose # noqa: E501
1765 mysummary() must be called if they are present."""
1766 return ""
1768 def _do_summary(self):
1769 # type: () -> Tuple[int, str, List[Any]]
1770 found, s, needed = self.payload._do_summary()
1771 ret = ""
1772 if not found or self.__class__ in needed:
1773 ret = self.mysummary()
1774 if isinstance(ret, tuple):
1775 ret, n = ret
1776 needed += n
1777 if ret or needed:
1778 found = 1
1779 if not ret:
1780 ret = self.__class__.__name__ if self.show_summary else ""
1781 if self.__class__ in conf.emph:
1782 impf = []
1783 for f in self.fields_desc:
1784 if f in conf.emph:
1785 impf.append("%s=%s" % (f.name, f.i2repr(self, self.getfieldval(f.name)))) # noqa: E501
1786 ret = "%s [%s]" % (ret, " ".join(impf))
1787 if ret and s:
1788 ret = "%s / %s" % (ret, s)
1789 else:
1790 ret = "%s%s" % (ret, s)
1791 return found, ret, needed
1793 def summary(self, intern=0):
1794 # type: (int) -> str
1795 """Prints a one line summary of a packet."""
1796 return self._do_summary()[1]
1798 def lastlayer(self, layer=None):
1799 # type: (Optional[Packet]) -> Packet
1800 """Returns the uppest layer of the packet"""
1801 return self.payload.lastlayer(self)
1803 def decode_payload_as(self, cls):
1804 # type: (Type[Packet]) -> None
1805 """Reassembles the payload and decode it using another packet class"""
1806 s = raw(self.payload)
1807 self.payload = cls(s, _internal=1, _underlayer=self)
1808 pp = self
1809 while pp.underlayer is not None:
1810 pp = pp.underlayer
1811 self.payload.dissection_done(pp)
1813 def _command(self, json=False):
1814 # type: (bool) -> List[Tuple[str, Any]]
1815 """
1816 Internal method used to generate command() and json()
1817 """
1818 f = []
1819 iterator: Iterator[Tuple[str, Any]]
1820 if json:
1821 iterator = ((x.name, self.getfieldval(x.name)) for x in self.fields_desc)
1822 else:
1823 iterator = iter(self.fields.items())
1824 for fn, fv in iterator:
1825 fld = self.get_field(fn)
1826 if isinstance(fv, (list, dict, set)) and not fv and not fld.default:
1827 continue
1828 if isinstance(fv, Packet):
1829 if json:
1830 fv = {k: v for (k, v) in fv._command(json=True)}
1831 else:
1832 fv = fv.command()
1833 elif fld.islist and fld.holds_packets and isinstance(fv, list):
1834 if json:
1835 fv = [
1836 {k: v for (k, v) in x}
1837 for x in map(lambda y: Packet._command(y, json=True), fv)
1838 ]
1839 else:
1840 fv = "[%s]" % ",".join(map(Packet.command, fv))
1841 elif fld.islist and isinstance(fv, list):
1842 if json:
1843 fv = [
1844 getattr(x, 'command', lambda: repr(x))()
1845 for x in fv
1846 ]
1847 else:
1848 fv = "[%s]" % ",".join(
1849 getattr(x, 'command', lambda: repr(x))()
1850 for x in fv
1851 )
1852 elif isinstance(fv, FlagValue):
1853 fv = int(fv)
1854 elif callable(getattr(fv, 'command', None)):
1855 fv = fv.command(json=json)
1856 else:
1857 if json:
1858 if isinstance(fv, bytes):
1859 fv = fv.decode("utf-8", errors="backslashreplace")
1860 else:
1861 fv = fld.i2h(self, fv)
1862 else:
1863 fv = repr(fld.i2h(self, fv))
1864 f.append((fn, fv))
1865 return f
1867 def command(self):
1868 # type: () -> str
1869 """
1870 Returns a string representing the command you have to type to
1871 obtain the same packet
1872 """
1873 c = "%s(%s)" % (
1874 self.__class__.__name__,
1875 ", ".join("%s=%s" % x for x in self._command())
1876 )
1877 pc = self.payload.command()
1878 if pc:
1879 c += "/" + pc
1880 return c
1882 def json(self):
1883 # type: () -> str
1884 """
1885 Returns a JSON representing the packet.
1887 Please note that this cannot be used for bijective usage: data loss WILL occur,
1888 so it will not make sense to try to rebuild the packet from the output.
1889 This must only be used for a grepping/displaying purpose.
1890 """
1891 dump = json.dumps({k: v for (k, v) in self._command(json=True)})
1892 pc = self.payload.json()
1893 if pc:
1894 dump = dump[:-1] + ", \"payload\": %s}" % pc
1895 return dump
1898class NoPayload(Packet):
1899 def __new__(cls, *args, **kargs):
1900 # type: (Type[Packet], *Any, **Any) -> NoPayload
1901 singl = cls.__dict__.get("__singl__")
1902 if singl is None:
1903 cls.__singl__ = singl = Packet.__new__(cls)
1904 Packet.__init__(singl)
1905 return singl # type: ignore
1907 def __init__(self, *args, **kargs):
1908 # type: (*Any, **Any) -> None
1909 pass
1911 def dissection_done(self, pkt):
1912 # type: (Packet) -> None
1913 pass
1915 def add_payload(self, payload):
1916 # type: (Union[Packet, bytes]) -> NoReturn
1917 raise Scapy_Exception("Can't add payload to NoPayload instance")
1919 def remove_payload(self):
1920 # type: () -> None
1921 pass
1923 def add_underlayer(self, underlayer):
1924 # type: (Any) -> None
1925 pass
1927 def remove_underlayer(self, other):
1928 # type: (Packet) -> None
1929 pass
1931 def add_parent(self, parent):
1932 # type: (Any) -> None
1933 pass
1935 def remove_parent(self, other):
1936 # type: (Packet) -> None
1937 pass
1939 def copy(self):
1940 # type: () -> NoPayload
1941 return self
1943 def clear_cache(self):
1944 # type: () -> None
1945 pass
1947 def __repr__(self):
1948 # type: () -> str
1949 return ""
1951 def __str__(self):
1952 # type: () -> str
1953 return ""
1955 def __bytes__(self):
1956 # type: () -> bytes
1957 return b""
1959 def __nonzero__(self):
1960 # type: () -> bool
1961 return False
1962 __bool__ = __nonzero__
1964 def do_build(self):
1965 # type: () -> bytes
1966 return b""
1968 def build(self):
1969 # type: () -> bytes
1970 return b""
1972 def build_padding(self):
1973 # type: () -> bytes
1974 return b""
1976 def build_done(self, p):
1977 # type: (bytes) -> bytes
1978 return p
1980 def build_ps(self, internal=0):
1981 # type: (int) -> Tuple[bytes, List[Any]]
1982 return b"", []
1984 def getfieldval(self, attr):
1985 # type: (str) -> NoReturn
1986 raise AttributeError(attr)
1988 def getfield_and_val(self, attr):
1989 # type: (str) -> NoReturn
1990 raise AttributeError(attr)
1992 def setfieldval(self, attr, val):
1993 # type: (str, Any) -> NoReturn
1994 raise AttributeError(attr)
1996 def delfieldval(self, attr):
1997 # type: (str) -> NoReturn
1998 raise AttributeError(attr)
2000 def hide_defaults(self):
2001 # type: () -> None
2002 pass
2004 def __iter__(self):
2005 # type: () -> Iterator[Packet]
2006 return iter([])
2008 def __eq__(self, other):
2009 # type: (Any) -> bool
2010 if isinstance(other, NoPayload):
2011 return True
2012 return False
2014 def hashret(self):
2015 # type: () -> bytes
2016 return b""
2018 def answers(self, other):
2019 # type: (Packet) -> bool
2020 return isinstance(other, (NoPayload, conf.padding_layer)) # noqa: E501
2022 def haslayer(self, cls, _subclass=None):
2023 # type: (Union[Type[Packet], str], Optional[bool]) -> int
2024 return 0
2026 def getlayer(self,
2027 cls, # type: Union[int, Type[Packet], str]
2028 nb=1, # type: int
2029 _track=None, # type: Optional[List[int]]
2030 _subclass=None, # type: Optional[bool]
2031 **flt # type: Any
2032 ):
2033 # type: (...) -> Optional[Packet]
2034 if _track is not None:
2035 _track.append(nb)
2036 return None
2038 def fragment(self, *args, **kargs):
2039 # type: (*Any, **Any) -> List[Packet]
2040 raise Scapy_Exception("cannot fragment this packet")
2042 def show(self, dump=False, indent=3, lvl="", label_lvl=""):
2043 # type: (bool, int, str, str) -> None
2044 pass
2046 def sprintf(self, fmt, relax=1):
2047 # type: (str, int) -> str
2048 if relax:
2049 return "??"
2050 else:
2051 raise Scapy_Exception("Format not found [%s]" % fmt)
2053 def _do_summary(self):
2054 # type: () -> Tuple[int, str, List[Any]]
2055 return 0, "", []
2057 def layers(self):
2058 # type: () -> List[Type[Packet]]
2059 return []
2061 def lastlayer(self, layer=None):
2062 # type: (Optional[Packet]) -> Packet
2063 return layer or self
2065 def command(self):
2066 # type: () -> str
2067 return ""
2069 def json(self):
2070 # type: () -> str
2071 return ""
2073 def route(self):
2074 # type: () -> Tuple[None, None, None]
2075 return (None, None, None)
2078####################
2079# packet classes #
2080####################
2083class Raw(Packet):
2084 name = "Raw"
2085 fields_desc = [StrField("load", b"")]
2087 def __init__(self, _pkt=b"", *args, **kwargs):
2088 # type: (bytes, *Any, **Any) -> None
2089 if _pkt and not isinstance(_pkt, bytes):
2090 if isinstance(_pkt, tuple):
2091 _pkt, bn = _pkt
2092 _pkt = bytes_encode(_pkt), bn
2093 else:
2094 _pkt = bytes_encode(_pkt)
2095 super(Raw, self).__init__(_pkt, *args, **kwargs)
2097 def answers(self, other):
2098 # type: (Packet) -> int
2099 return 1
2101 def mysummary(self):
2102 # type: () -> str
2103 cs = conf.raw_summary
2104 if cs:
2105 if callable(cs):
2106 return "Raw %s" % cs(self.load)
2107 else:
2108 return "Raw %r" % self.load
2109 return Packet.mysummary(self)
2112class Padding(Raw):
2113 name = "Padding"
2115 def self_build(self):
2116 # type: (Optional[Any]) -> bytes
2117 return b""
2119 def build_padding(self):
2120 # type: () -> bytes
2121 return (
2122 bytes_encode(self.load) if self.raw_packet_cache is None
2123 else self.raw_packet_cache
2124 ) + self.payload.build_padding()
2127conf.raw_layer = Raw
2128conf.padding_layer = Padding
2129if conf.default_l2 is None:
2130 conf.default_l2 = Raw
2132#################
2133# Bind layers #
2134#################
2137def bind_bottom_up(lower, # type: Type[Packet]
2138 upper, # type: Type[Packet]
2139 __fval=None, # type: Optional[Any]
2140 **fval # type: Any
2141 ):
2142 # type: (...) -> None
2143 r"""Bind 2 layers for dissection.
2144 The upper layer will be chosen for dissection on top of the lower layer, if
2145 ALL the passed arguments are validated. If multiple calls are made with
2146 the same layers, the last one will be used as default.
2148 ex:
2149 >>> bind_bottom_up(Ether, SNAP, type=0x1234)
2150 >>> Ether(b'\xff\xff\xff\xff\xff\xff\xd0P\x99V\xdd\xf9\x124\x00\x00\x00\x00\x00') # noqa: E501
2151 <Ether dst=ff:ff:ff:ff:ff:ff src=d0:50:99:56:dd:f9 type=0x1234 |<SNAP OUI=0x0 code=0x0 |>> # noqa: E501
2152 """
2153 if __fval is not None:
2154 fval.update(__fval)
2155 lower.payload_guess = lower.payload_guess[:]
2156 lower.payload_guess.append((fval, upper))
2159def bind_top_down(lower, # type: Type[Packet]
2160 upper, # type: Type[Packet]
2161 __fval=None, # type: Optional[Any]
2162 **fval # type: Any
2163 ):
2164 # type: (...) -> None
2165 """Bind 2 layers for building.
2166 When the upper layer is added as a payload of the lower layer, all the
2167 arguments will be applied to them.
2169 ex:
2170 >>> bind_top_down(Ether, SNAP, type=0x1234)
2171 >>> Ether()/SNAP()
2172 <Ether type=0x1234 |<SNAP |>>
2173 """
2174 if __fval is not None:
2175 fval.update(__fval)
2176 upper._overload_fields = upper._overload_fields.copy() # type: ignore
2177 upper._overload_fields[lower] = fval
2180@conf.commands.register
2181def bind_layers(lower, # type: Type[Packet]
2182 upper, # type: Type[Packet]
2183 __fval=None, # type: Optional[Dict[str, int]]
2184 **fval # type: Any
2185 ):
2186 # type: (...) -> None
2187 """Bind 2 layers on some specific fields' values.
2189 It makes the packet being built and dissected when the arguments
2190 are present.
2192 This function calls both bind_bottom_up and bind_top_down, with
2193 all passed arguments.
2195 Please have a look at their docs:
2196 - help(bind_bottom_up)
2197 - help(bind_top_down)
2198 """
2199 if __fval is not None:
2200 fval.update(__fval)
2201 bind_top_down(lower, upper, **fval)
2202 bind_bottom_up(lower, upper, **fval)
2205def split_bottom_up(lower, # type: Type[Packet]
2206 upper, # type: Type[Packet]
2207 __fval=None, # type: Optional[Any]
2208 **fval # type: Any
2209 ):
2210 # type: (...) -> None
2211 """This call un-links an association that was made using bind_bottom_up.
2212 Have a look at help(bind_bottom_up)
2213 """
2214 if __fval is not None:
2215 fval.update(__fval)
2217 def do_filter(params, cls):
2218 # type: (Dict[str, int], Type[Packet]) -> bool
2219 params_is_invalid = any(
2220 k not in params or params[k] != v for k, v in fval.items()
2221 )
2222 return cls != upper or params_is_invalid
2223 lower.payload_guess = [x for x in lower.payload_guess if do_filter(*x)]
2226def split_top_down(lower, # type: Type[Packet]
2227 upper, # type: Type[Packet]
2228 __fval=None, # type: Optional[Any]
2229 **fval # type: Any
2230 ):
2231 # type: (...) -> None
2232 """This call un-links an association that was made using bind_top_down.
2233 Have a look at help(bind_top_down)
2234 """
2235 if __fval is not None:
2236 fval.update(__fval)
2237 if lower in upper._overload_fields:
2238 ofval = upper._overload_fields[lower]
2239 if any(k not in ofval or ofval[k] != v for k, v in fval.items()):
2240 return
2241 upper._overload_fields = upper._overload_fields.copy() # type: ignore
2242 del upper._overload_fields[lower]
2245@conf.commands.register
2246def split_layers(lower, # type: Type[Packet]
2247 upper, # type: Type[Packet]
2248 __fval=None, # type: Optional[Any]
2249 **fval # type: Any
2250 ):
2251 # type: (...) -> None
2252 """Split 2 layers previously bound.
2253 This call un-links calls bind_top_down and bind_bottom_up. It is the opposite of # noqa: E501
2254 bind_layers.
2256 Please have a look at their docs:
2257 - help(split_bottom_up)
2258 - help(split_top_down)
2259 """
2260 if __fval is not None:
2261 fval.update(__fval)
2262 split_bottom_up(lower, upper, **fval)
2263 split_top_down(lower, upper, **fval)
2266@conf.commands.register
2267def explore(layer=None):
2268 # type: (Optional[str]) -> None
2269 """Function used to discover the Scapy layers and protocols.
2270 It helps to see which packets exists in contrib or layer files.
2272 params:
2273 - layer: If specified, the function will explore the layer. If not,
2274 the GUI mode will be activated, to browse the available layers
2276 examples:
2277 >>> explore() # Launches the GUI
2278 >>> explore("dns") # Explore scapy.layers.dns
2279 >>> explore("http2") # Explore scapy.contrib.http2
2280 >>> explore(scapy.layers.bluetooth4LE)
2282 Note: to search a packet by name, use ls("name") rather than explore.
2283 """
2284 if layer is None: # GUI MODE
2285 if not conf.interactive:
2286 raise Scapy_Exception("explore() GUI-mode cannot be run in "
2287 "interactive mode. Please provide a "
2288 "'layer' parameter !")
2289 # 0 - Imports
2290 try:
2291 import prompt_toolkit
2292 except ImportError:
2293 raise ImportError("prompt_toolkit is not installed ! "
2294 "You may install IPython, which contains it, via"
2295 " `pip install ipython`")
2296 if not _version_checker(prompt_toolkit, (2, 0)):
2297 raise ImportError("prompt_toolkit >= 2.0.0 is required !")
2298 # Only available with prompt_toolkit > 2.0, not released on PyPi yet
2299 from prompt_toolkit.shortcuts.dialogs import radiolist_dialog, \
2300 button_dialog
2301 from prompt_toolkit.formatted_text import HTML
2302 # Check for prompt_toolkit >= 3.0.0
2303 call_ptk = lambda x: cast(str, x) # type: Callable[[Any], str]
2304 if _version_checker(prompt_toolkit, (3, 0)):
2305 call_ptk = lambda x: x.run()
2306 # 1 - Ask for layer or contrib
2307 btn_diag = button_dialog(
2308 title="Scapy v%s" % conf.version,
2309 text=HTML(
2310 '<style bg="white" fg="red">Chose the type of packets'
2311 ' you want to explore:</style>'
2312 ),
2313 buttons=[
2314 ("Layers", "layers"),
2315 ("Contribs", "contribs"),
2316 ("Cancel", "cancel")
2317 ])
2318 action = call_ptk(btn_diag)
2319 # 2 - Retrieve list of Packets
2320 if action == "layers":
2321 # Get all loaded layers
2322 lvalues = conf.layers.layers()
2323 # Restrict to layers-only (not contribs) + packet.py and asn1*.py
2324 values = [x for x in lvalues if ("layers" in x[0] or
2325 "packet" in x[0] or
2326 "asn1" in x[0])]
2327 elif action == "contribs":
2328 # Get all existing contribs
2329 from scapy.main import list_contrib
2330 cvalues = cast(List[Dict[str, str]], list_contrib(ret=True))
2331 values = [(x['name'], x['description'])
2332 for x in cvalues]
2333 # Remove very specific modules
2334 values = [x for x in values if "can" not in x[0]]
2335 else:
2336 # Escape/Cancel was pressed
2337 return
2338 # Build tree
2339 if action == "contribs":
2340 # A tree is a dictionary. Each layer contains a keyword
2341 # _l which contains the files in the layer, and a _name
2342 # argument which is its name. The other keys are the subfolders,
2343 # which are similar dictionaries
2344 tree = defaultdict(list) # type: Dict[str, Union[List[Any], Dict[str, Any]]] # noqa: E501
2345 for name, desc in values:
2346 if "." in name: # Folder detected
2347 parts = name.split(".")
2348 subtree = tree
2349 for pa in parts[:-1]:
2350 if pa not in subtree:
2351 subtree[pa] = {}
2352 # one layer deeper
2353 subtree = subtree[pa] # type: ignore
2354 subtree["_name"] = pa # type: ignore
2355 if "_l" not in subtree:
2356 subtree["_l"] = []
2357 subtree["_l"].append((parts[-1], desc)) # type: ignore
2358 else:
2359 tree["_l"].append((name, desc)) # type: ignore
2360 elif action == "layers":
2361 tree = {"_l": values}
2362 # 3 - Ask for the layer/contrib module to explore
2363 current = tree # type: Any
2364 previous = [] # type: List[Dict[str, Union[List[Any], Dict[str, Any]]]] # noqa: E501
2365 while True:
2366 # Generate tests & form
2367 folders = list(current.keys())
2368 _radio_values = [
2369 ("$" + name, str('[+] ' + name.capitalize()))
2370 for name in folders if not name.startswith("_")
2371 ] + current.get("_l", []) # type: List[str]
2372 cur_path = ""
2373 if previous:
2374 cur_path = ".".join(
2375 itertools.chain(
2376 (x["_name"] for x in previous[1:]), # type: ignore
2377 (current["_name"],)
2378 )
2379 )
2380 extra_text = (
2381 '\n<style bg="white" fg="green">> scapy.%s</style>'
2382 ) % (action + ("." + cur_path if cur_path else ""))
2383 # Show popup
2384 rd_diag = radiolist_dialog(
2385 values=_radio_values,
2386 title="Scapy v%s" % conf.version,
2387 text=HTML(
2388 (
2389 '<style bg="white" fg="red">Please select a file'
2390 'among the following, to see all layers contained in'
2391 ' it:</style>'
2392 ) + extra_text
2393 ),
2394 cancel_text="Back" if previous else "Cancel"
2395 )
2396 result = call_ptk(rd_diag)
2397 if result is None:
2398 # User pressed "Cancel/Back"
2399 if previous: # Back
2400 current = previous.pop()
2401 continue
2402 else: # Cancel
2403 return
2404 if result.startswith("$"):
2405 previous.append(current)
2406 current = current[result[1:]]
2407 else:
2408 # Enter on layer
2409 if previous: # In subfolder
2410 result = cur_path + "." + result
2411 break
2412 # 4 - (Contrib only): load contrib
2413 if action == "contribs":
2414 from scapy.main import load_contrib
2415 load_contrib(result)
2416 result = "scapy.contrib." + result
2417 else: # NON-GUI MODE
2418 # We handle layer as a short layer name, full layer name
2419 # or the module itself
2420 if isinstance(layer, types.ModuleType):
2421 layer = layer.__name__
2422 if isinstance(layer, str):
2423 if layer.startswith("scapy.layers."):
2424 result = layer
2425 else:
2426 if layer.startswith("scapy.contrib."):
2427 layer = layer.replace("scapy.contrib.", "")
2428 from scapy.main import load_contrib
2429 load_contrib(layer)
2430 result_layer, result_contrib = (("scapy.layers.%s" % layer),
2431 ("scapy.contrib.%s" % layer))
2432 if result_layer in conf.layers.ldict:
2433 result = result_layer
2434 elif result_contrib in conf.layers.ldict:
2435 result = result_contrib
2436 else:
2437 raise Scapy_Exception("Unknown scapy module '%s'" % layer)
2438 else:
2439 warning("Wrong usage ! Check out help(explore)")
2440 return
2442 # COMMON PART
2443 # Get the list of all Packets contained in that module
2444 try:
2445 all_layers = conf.layers.ldict[result]
2446 except KeyError:
2447 raise Scapy_Exception("Unknown scapy module '%s'" % layer)
2448 # Print
2449 print(conf.color_theme.layer_name("Packets contained in %s:" % result))
2450 rtlst = [] # type: List[Tuple[Union[str, List[str]], ...]]
2451 rtlst = [(lay.__name__ or "", cast(str, lay._name) or "") for lay in all_layers]
2452 print(pretty_list(rtlst, [("Class", "Name")], borders=True))
2455def _pkt_ls(obj, # type: Union[Packet, Type[Packet]]
2456 verbose=False, # type: bool
2457 ):
2458 # type: (...) -> List[Tuple[str, Type[AnyField], str, str, List[str]]] # noqa: E501
2459 """Internal function used to resolve `fields_desc` to display it.
2461 :param obj: a packet object or class
2462 :returns: a list containing tuples [(name, clsname, clsname_extras,
2463 default, long_attrs)]
2464 """
2465 is_pkt = isinstance(obj, Packet)
2466 if not issubtype(obj, Packet) and not is_pkt:
2467 raise ValueError
2468 fields = []
2469 for f in obj.fields_desc:
2470 cur_fld = f
2471 attrs = [] # type: List[str]
2472 long_attrs = [] # type: List[str]
2473 while isinstance(cur_fld, (Emph, ConditionalField)):
2474 if isinstance(cur_fld, ConditionalField):
2475 attrs.append(cur_fld.__class__.__name__[:4])
2476 cur_fld = cur_fld.fld
2477 name = cur_fld.name
2478 default = cur_fld.default
2479 if verbose and isinstance(cur_fld, EnumField) \
2480 and hasattr(cur_fld, "i2s") and cur_fld.i2s:
2481 if len(cur_fld.i2s or []) < 50:
2482 long_attrs.extend(
2483 "%s: %d" % (strval, numval)
2484 for numval, strval in
2485 sorted(cur_fld.i2s.items())
2486 )
2487 elif isinstance(cur_fld, MultiEnumField):
2488 if isinstance(obj, Packet):
2489 obj_pkt = obj
2490 else:
2491 obj_pkt = obj()
2492 fld_depend = cur_fld.depends_on(obj_pkt)
2493 attrs.append("Depends on %s" % fld_depend)
2494 if verbose:
2495 cur_i2s = cur_fld.i2s_multi.get(
2496 cur_fld.depends_on(obj_pkt), {}
2497 )
2498 if len(cur_i2s) < 50:
2499 long_attrs.extend(
2500 "%s: %d" % (strval, numval)
2501 for numval, strval in
2502 sorted(cur_i2s.items())
2503 )
2504 elif verbose and isinstance(cur_fld, FlagsField):
2505 names = cur_fld.names
2506 long_attrs.append(", ".join(names))
2507 elif isinstance(cur_fld, MultipleTypeField):
2508 default = cur_fld.dflt.default
2509 attrs.append(", ".join(
2510 x[0].__class__.__name__ for x in
2511 itertools.chain(cur_fld.flds, [(cur_fld.dflt,)])
2512 ))
2514 cls = cur_fld.__class__
2515 class_name_extras = "(%s)" % (
2516 ", ".join(attrs)
2517 ) if attrs else ""
2518 if isinstance(cur_fld, BitField):
2519 class_name_extras += " (%d bit%s)" % (
2520 cur_fld.size,
2521 "s" if cur_fld.size > 1 else ""
2522 )
2523 fields.append(
2524 (name,
2525 cls,
2526 class_name_extras,
2527 repr(default),
2528 long_attrs)
2529 )
2530 return fields
2533@conf.commands.register
2534def ls(obj=None, # type: Optional[Union[str, Packet, Type[Packet]]]
2535 case_sensitive=False, # type: bool
2536 verbose=False # type: bool
2537 ):
2538 # type: (...) -> None
2539 """List available layers, or infos on a given layer class or name.
2541 :param obj: Packet / packet name to use
2542 :param case_sensitive: if obj is a string, is it case sensitive?
2543 :param verbose:
2544 """
2545 if obj is None or isinstance(obj, str):
2546 tip = False
2547 if obj is None:
2548 tip = True
2549 all_layers = sorted(conf.layers, key=lambda x: x.__name__)
2550 else:
2551 pattern = re.compile(
2552 obj,
2553 0 if case_sensitive else re.I
2554 )
2555 # We first order by accuracy, then length
2556 if case_sensitive:
2557 sorter = lambda x: (x.__name__.index(obj), len(x.__name__))
2558 else:
2559 obj = obj.lower()
2560 sorter = lambda x: (x.__name__.lower().index(obj),
2561 len(x.__name__))
2562 all_layers = sorted((layer for layer in conf.layers
2563 if (isinstance(layer.__name__, str) and
2564 pattern.search(layer.__name__)) or
2565 (isinstance(layer.name, str) and
2566 pattern.search(layer.name))),
2567 key=sorter)
2568 for layer in all_layers:
2569 print("%-10s : %s" % (layer.__name__, layer._name))
2570 if tip and conf.interactive:
2571 print("\nTIP: You may use explore() to navigate through all "
2572 "layers using a clear GUI")
2573 else:
2574 try:
2575 fields = _pkt_ls(
2576 obj,
2577 verbose=verbose
2578 )
2579 is_pkt = isinstance(obj, Packet)
2580 # Print
2581 for fname, cls, clsne, dflt, long_attrs in fields:
2582 clsinfo = cls.__name__ + " " + clsne
2583 print("%-10s : %-35s =" % (fname, clsinfo), end=' ')
2584 if is_pkt:
2585 print("%-15r" % (getattr(obj, fname),), end=' ')
2586 print("(%r)" % (dflt,))
2587 for attr in long_attrs:
2588 print("%-15s%s" % ("", attr))
2589 # Restart for payload if any
2590 if is_pkt:
2591 obj = cast(Packet, obj)
2592 if isinstance(obj.payload, NoPayload):
2593 return
2594 print("--")
2595 ls(obj.payload)
2596 except ValueError:
2597 print("Not a packet class or name. Type 'ls()' to list packet classes.") # noqa: E501
2600@conf.commands.register
2601def rfc(cls, ret=False, legend=True):
2602 # type: (Type[Packet], bool, bool) -> Optional[str]
2603 """
2604 Generate an RFC-like representation of a packet def.
2606 :param cls: the Packet class
2607 :param ret: return the result instead of printing (def. False)
2608 :param legend: show text under the diagram (default True)
2610 Ex::
2612 >>> rfc(Ether)
2614 """
2615 if not issubclass(cls, Packet):
2616 raise TypeError("Packet class expected")
2617 cur_len = 0
2618 cur_line = []
2619 lines = []
2620 # Get the size (width) that a field will take
2621 # when formatted, from its length in bits
2622 clsize = lambda x: 2 * x - 1 # type: Callable[[int], int]
2623 ident = 0 # Fields UUID
2625 # Generate packet groups
2626 def _iterfields() -> Iterator[Tuple[str, int]]:
2627 for f in cls.fields_desc:
2628 # Fancy field name
2629 fname = f.name.upper().replace("_", " ")
2630 fsize = int(f.sz * 8)
2631 yield fname, fsize
2632 # Add padding optionally
2633 if isinstance(f, PadField):
2634 if isinstance(f._align, tuple):
2635 pad = - cur_len % (f._align[0] * 8)
2636 else:
2637 pad = - cur_len % (f._align * 8)
2638 if pad:
2639 yield "padding", pad
2640 for fname, flen in _iterfields():
2641 cur_len += flen
2642 ident += 1
2643 # The field might exceed the current line or
2644 # take more than one line. Copy it as required
2645 while True:
2646 over = max(0, cur_len - 32) # Exceed
2647 len1 = clsize(flen - over) # What fits
2648 cur_line.append((fname[:len1], len1, ident))
2649 if cur_len >= 32:
2650 # Current line is full. start a new line
2651 lines.append(cur_line)
2652 cur_len = flen = over
2653 fname = "" # do not repeat the field
2654 cur_line = []
2655 if not over:
2656 # there is no data left
2657 break
2658 else:
2659 # End of the field
2660 break
2661 # Add the last line if un-finished
2662 if cur_line:
2663 lines.append(cur_line)
2664 # Calculate separations between lines
2665 seps = []
2666 seps.append("+-" * 32 + "+\n")
2667 for i in range(len(lines) - 1):
2668 # Start with a full line
2669 sep = "+-" * 32 + "+\n"
2670 # Get the line above and below the current
2671 # separation
2672 above, below = lines[i], lines[i + 1]
2673 # The last field of above is shared with below
2674 if above[-1][2] == below[0][2]:
2675 # where the field in "above" starts
2676 pos_above = sum(x[1] for x in above[:-1]) + len(above[:-1]) - 1
2677 # where the field in "below" ends
2678 pos_below = below[0][1]
2679 if pos_above < pos_below:
2680 # they are overlapping.
2681 # Now crop the space between those pos
2682 # and fill it with " "
2683 pos_above = pos_above + pos_above % 2
2684 sep = (
2685 sep[:1 + pos_above] +
2686 " " * (pos_below - pos_above) +
2687 sep[1 + pos_below:]
2688 )
2689 # line is complete
2690 seps.append(sep)
2691 # Graph
2692 result = ""
2693 # Bytes markers
2694 result += " " + (" " * 19).join(
2695 str(x) for x in range(4)
2696 ) + "\n"
2697 # Bits markers
2698 result += " " + " ".join(
2699 str(x % 10) for x in range(32)
2700 ) + "\n"
2701 # Add fields and their separations
2702 for line, sep in zip(lines, seps):
2703 result += sep
2704 for elt, flen, _ in line:
2705 result += "|" + elt.center(flen, " ")
2706 result += "|\n"
2707 result += "+-" * (cur_len or 32) + "+\n"
2708 # Annotate with the figure name
2709 if legend:
2710 result += "\n" + ("Fig. " + cls.__name__).center(66, " ")
2711 # return if asked for, else print
2712 if ret:
2713 return result
2714 print(result)
2715 return None
2718#############
2719# Fuzzing #
2720#############
2722_P = TypeVar('_P', bound=Packet)
2725@conf.commands.register
2726def fuzz(p, # type: _P
2727 _inplace=0, # type: int
2728 ):
2729 # type: (...) -> _P
2730 """
2731 Transform a layer into a fuzzy layer by replacing some default values
2732 by random objects.
2734 :param p: the Packet instance to fuzz
2735 :return: the fuzzed packet.
2736 """
2737 if not _inplace:
2738 p = p.copy()
2739 q = cast(Packet, p)
2740 while not isinstance(q, NoPayload):
2741 new_default_fields = {}
2742 multiple_type_fields = [] # type: List[str]
2743 for f in q.fields_desc:
2744 if isinstance(f, PacketListField):
2745 for r in getattr(q, f.name):
2746 fuzz(r, _inplace=1)
2747 elif isinstance(f, MultipleTypeField):
2748 # the type of the field will depend on others
2749 multiple_type_fields.append(f.name)
2750 elif f.default is not None:
2751 if not isinstance(f, ConditionalField) or f._evalcond(q):
2752 rnd = f.randval()
2753 if rnd is not None:
2754 new_default_fields[f.name] = rnd
2755 # Process packets with MultipleTypeFields
2756 if multiple_type_fields:
2757 # freeze the other random values
2758 new_default_fields = {
2759 key: (val._fix() if isinstance(val, VolatileValue) else val)
2760 for key, val in new_default_fields.items()
2761 }
2762 q.default_fields.update(new_default_fields)
2763 new_default_fields.clear()
2764 # add the random values of the MultipleTypeFields
2765 for name in multiple_type_fields:
2766 fld = cast(MultipleTypeField, q.get_field(name))
2767 rnd = fld._find_fld_pkt(q).randval()
2768 if rnd is not None:
2769 new_default_fields[name] = rnd
2770 q.default_fields.update(new_default_fields)
2771 q = q.payload
2772 return p