|
| 1 | +# -*- coding: utf-8 -*- |
| 2 | +"""The PyShark engine reads packet records only, as the default engine does. C.f. #1515. |
| 3 | +
|
| 4 | +:program:`tshark` numbers every record wiretap hands it, and a PCAP-NG systemd |
| 5 | +Journal Export Block, Custom Block or Sysdig Event Block is one. The default |
| 6 | +engine counts Enhanced, Simple and obsolete Packet Blocks only, so a capture |
| 7 | +holding a journal block read as one frame more through ``pyshark``, and every |
| 8 | +later frame was off by one. |
| 9 | +
|
| 10 | +The same lookup serves the verbose handler. ``pyshark`` takes the second PDML |
| 11 | +``<proto>`` as ``frame_info``, and on a packet that carries a comment that is |
| 12 | +``pkt_comment``, which has no ``protocols``. So ``verbose=True`` raised |
| 13 | +:exc:`AttributeError` on frame 1 of :file:`examples/captures/test.pcapng`. |
| 14 | +
|
| 15 | +The packets here are stand-ins shaped like what ``pyshark`` 0.6 builds from |
| 16 | +:program:`tshark` 4.6.9's PDML. The field names are the ones measured on |
| 17 | +:file:`examples/captures/test.pcapng` and on a capture holding a Custom Block and |
| 18 | +a Sysdig Event Block. ``pyshark`` itself is never imported, so this runs where it |
| 19 | +is absent or cannot run. |
| 20 | +
|
| 21 | +""" |
| 22 | + |
| 23 | +import contextlib |
| 24 | +import importlib.util |
| 25 | +import io |
| 26 | +import types |
| 27 | +import unittest |
| 28 | + |
| 29 | +from tests._support import reimport_once_per_class |
| 30 | + |
| 31 | +RUNTIME_DEPS = ('tbtrim', 'aenum', 'chardet', 'dictdumper') |
| 32 | +HAS_RUNTIME = all(importlib.util.find_spec(name) is not None for name in RUNTIME_DEPS) |
| 33 | + |
| 34 | +#: ``frame`` layer fields of a packet record; only these carry ``encap_type``. |
| 35 | +PACKET_FRAME = ('section_number', 'interface_id', 'interface_name', 'encap_type', 'time', |
| 36 | + 'time_epoch', 'number', 'len', 'cap_len', 'protocols') |
| 37 | +#: ``frame`` layer fields of a systemd Journal Export or Sysdig Event record. |
| 38 | +RECORD_FRAME = ('section_number', 'time', 'time_utc', 'time_epoch', 'number', 'len', 'cap_len', |
| 39 | + 'protocols') |
| 40 | +#: ``frame.protocols`` of frame 1 of :file:`examples/captures/test.pcapng`. |
| 41 | +PROTOCOLS = 'eth:ethertype:ip:udp:dhcp' |
| 42 | + |
| 43 | + |
| 44 | +def _layer(name: str, fields: 'tuple[str, ...]' = (), **values: str) -> types.SimpleNamespace: |
| 45 | + return types.SimpleNamespace(layer_name=name, field_names=list(fields), **values) |
| 46 | + |
| 47 | + |
| 48 | +def _packet(number: int, comment: bool = False) -> types.SimpleNamespace: |
| 49 | + """A packet record; with a comment, ``pyshark`` takes ``pkt_comment`` as ``frame_info``.""" |
| 50 | + frame = _layer('frame', PACKET_FRAME, protocols=PROTOCOLS) |
| 51 | + eth = _layer('eth', ('dst', 'src', 'type')) |
| 52 | + if comment: |
| 53 | + note = _layer('pkt_comment', ('frame_comment',)) |
| 54 | + return types.SimpleNamespace(number=str(number), frame_info=note, layers=[frame, eth]) |
| 55 | + return types.SimpleNamespace(number=str(number), frame_info=frame, layers=[eth]) |
| 56 | + |
| 57 | + |
| 58 | +def _record(number: int, frame: 'tuple[str, ...] | None', root: str) -> types.SimpleNamespace: |
| 59 | + """A non-packet record; ``frame=None`` for a root that is not ``frame`` at all.""" |
| 60 | + head = _layer('frame', frame) if frame is not None else _layer(root, ('num',)) |
| 61 | + layers = [_layer(root, ('message',))] if frame is not None else [] |
| 62 | + return types.SimpleNamespace(number=str(number), frame_info=head, layers=layers) |
| 63 | + |
| 64 | + |
| 65 | +#: Every non-packet record shape, and where it was seen. |
| 66 | +RECORDS = { |
| 67 | + 'systemd journal (4.6.9)': ('systemd_journal', RECORD_FRAME), |
| 68 | + 'custom block (4.6.9)': ('DATA', ('section_number', 'interface_id', 'time', 'number', 'len')), |
| 69 | + 'sysdig event (4.6.9)': ('sysdig', RECORD_FRAME), |
| 70 | + # 4.2.2 roots a Sysdig event at ``syscall`` and a Netflix custom block at |
| 71 | + # ``bblog`` instead of ``frame`` (epan/dissectors/packet-frame.c:858-869, :884-890). |
| 72 | + 'sysdig event (4.2.2)': ('syscall', None), |
| 73 | + 'black box log (4.2.2)': ('bblog', None), |
| 74 | +} |
| 75 | + |
| 76 | + |
| 77 | +@unittest.skipUnless(HAS_RUNTIME, 'runtime dependencies not installed') |
| 78 | +class TestPySharkNonPacketRecords(unittest.TestCase): |
| 79 | + """:meth:`PyShark.read_frame` skips every record that is not a packet.""" |
| 80 | + |
| 81 | + def setUp(self) -> None: |
| 82 | + reimport_once_per_class(self) |
| 83 | + |
| 84 | + @staticmethod |
| 85 | + def _engine(records: 'list[types.SimpleNamespace]') -> 'tuple[object, types.SimpleNamespace]': |
| 86 | + from pcapkit.foundation.engines.pyshark import PyShark |
| 87 | + |
| 88 | + stream = iter(records) |
| 89 | + extractor = types.SimpleNamespace(_frnum=0, _vfunc=lambda e, f: None, _flag_q=True, |
| 90 | + _flag_t=False, _flag_d=True, _frame=[]) |
| 91 | + engine = PyShark.__new__(PyShark) # skip __init__, which imports pyshark |
| 92 | + engine._extractor = extractor |
| 93 | + engine._extmp = types.SimpleNamespace(next=lambda: next(stream)) |
| 94 | + return engine, extractor |
| 95 | + |
| 96 | + def test_a_journal_record_is_not_a_frame(self) -> None: |
| 97 | + first, last = _packet(1, comment=True), _packet(3) |
| 98 | + engine, ext = self._engine([first, _record(2, RECORD_FRAME, 'systemd_journal'), last]) |
| 99 | + |
| 100 | + self.assertIs(engine.read_frame(), first) |
| 101 | + self.assertEqual(ext._frnum, 1) |
| 102 | + self.assertIs(engine.read_frame(), last) |
| 103 | + self.assertEqual(ext._frnum, 2, 'frames are numbered as the default engine numbers them') |
| 104 | + self.assertEqual(ext._frame, [first, last]) |
| 105 | + with self.assertRaises(StopIteration): |
| 106 | + engine.read_frame() |
| 107 | + |
| 108 | + def test_every_record_without_an_encapsulation_is_skipped(self) -> None: |
| 109 | + for label, (root, frame) in RECORDS.items(): |
| 110 | + with self.subTest(record=label): |
| 111 | + record = _record(2, frame, root) |
| 112 | + engine, ext = self._engine([_packet(1), record, _packet(3)]) |
| 113 | + frames = [engine.read_frame(), engine.read_frame()] |
| 114 | + self.assertNotIn(record, frames) |
| 115 | + self.assertEqual([f.number for f in frames], ['1', '3']) |
| 116 | + self.assertEqual(ext._frnum, 2) |
| 117 | + |
| 118 | + def test_a_trailing_record_ends_the_capture(self) -> None: |
| 119 | + engine, ext = self._engine([_packet(1), _record(2, RECORD_FRAME, 'systemd_journal')]) |
| 120 | + engine.read_frame() |
| 121 | + with self.assertRaises(StopIteration): |
| 122 | + engine.read_frame() |
| 123 | + self.assertEqual(ext._frnum, 1) |
| 124 | + |
| 125 | + def test_verbose_mode_prints_a_commented_packet(self) -> None: |
| 126 | + engine, ext = self._engine([_packet(1, comment=True), _packet(2)]) |
| 127 | + vars(ext).update(_exlyr='none', _exptl='null', _exctx=None, _flag_r=False, _flag_v=True, |
| 128 | + _ifnm='test.pcapng', record_header=lambda: None) |
| 129 | + stream = engine._extmp |
| 130 | + engine._expkg = types.SimpleNamespace(FileCapture=lambda *args, **kwargs: stream) |
| 131 | + engine.run() # installs the verbose handler |
| 132 | + |
| 133 | + with contextlib.redirect_stdout(io.StringIO()) as out: |
| 134 | + engine.read_frame() |
| 135 | + engine.read_frame() |
| 136 | + self.assertEqual(out.getvalue().splitlines(), |
| 137 | + [f'Frame 1: {PROTOCOLS}', f'Frame 2: {PROTOCOLS}']) |
| 138 | + |
| 139 | + |
| 140 | +if __name__ == '__main__': |
| 141 | + unittest.main() |
0 commit comments