#------------------------------------------------------------------------------
# File: PCAP.pm
#
# Description: Read CAP, PCAP and PCAPNG Packet Capture files
#
# Revisions: 2025-03-03 - P. Harvey Created
#
# References: 1) https://www.ietf.org/archive/id/draft-gharris-opsawg-pcap-01.html
# 2) https://www.ietf.org/archive/id/draft-ietf-opsawg-pcapng-02.html
# 3) https://formats.kaitai.io/microsoft_network_monitor_v2/
#------------------------------------------------------------------------------
package Image::ExifTool::PCAP;
use strict;
use vars qw($VERSION);
use Image::ExifTool qw(:DataAccess :Utils);
$VERSION = '1.00';
%Image::ExifTool::PCAP::Main = (
GROUPS => { 0 => 'File', 1 => 'File', 2 => 'Other' },
VARS => { NO_LOOKUP => 1 }, # omit tags from lookup
NOTES => 'Tags extracted from CAP, PCAP and PCAPNG Packet Capture files.',
# (Note: All string values are UTF-8 but I'm going to be lazy and not bother decoding them)
ByteOrder => {
PrintConv => {
II => 'Little-endian (Intel, II)',
MM => 'Big-endian (Motorola, MM)',
},
},
PCAPVersion => { },
LinkType => {
PrintConvColumns => 2,
PrintConv => {
# (see https://datatracker.ietf.org/doc/html/draft-richardson-opsawg-pcaplinktype-01 for a full list)
0 => 'BSD Loopback',
1 => 'IEEE 802.3 Ethernet',
2 => 'Experimental 4Mb Ethernet',
3 => 'AX.25',
4 => 'PRONET',
5 => 'MIT CHAOSNET',
6 => 'IEEE 802.5',
7 => 'ARCNET BSD',
8 => 'SLIP',
9 => 'PPP',
10 => 'fddI',
# 11-49 not to be used
50 => 'PPP HDLC',
51 => 'PPP Ethernet',
# 52-98 not to be used
99 => 'Symantec Firewall',
100 => 'ATM RFC 1483',
101 => 'Raw',
102 => 'SLIP BSD/OS',
103 => 'PPP BSD/OS',
104 => 'Cisco PPP with HDLC',
105 => 'IEEE 802.11',
106 => 'ATM Classical IP',
107 => 'Frame Relay',
108 => 'OpenBSD Loopback',
109 => 'OpenBSD IPSEC',
110 => 'ATM LANE 802.3',
111 => 'NetBSD HIPPI',
112 => 'NetBSD HDLC',
113 => 'Linux SLL',
114 => 'Apple LocalTalk',
115 => 'Acorn Econet',
116 => 'OpenBSD ipfilter',
117 => 'OpenBSD pflog',
118 => 'Cisco IOS',
119 => 'IEEE 802.11 Prism',
120 => 'IEEE 802.11 Aironet',
121 => 'Siemens HiPath HDLC',
122 => 'IP-over-Fibre',
123 => 'SunATM',
124 => 'RapidIO',
125 => 'PCI Express',
126 => 'Xilinx Aurora',
127 => 'IEEE 802.11 Radiotap',
128 => 'Tazmen Sniffer',
129 => 'ARCNET Linux',
130 => 'Juniper MLPPP',
131 => 'Juniper MLFR',
132 => 'Juniper ES',
133 => 'Juniper GGSN',
134 => 'Juniper MFR',
135 => 'Juniper ATM2',
136 => 'Juniper Services',
137 => 'Juniper ATM1',
138 => 'Apple IP-over-IEEE 1394',
139 => 'MTP2 with PHDR',
140 => 'MTP2',
141 => 'MTP3',
142 => 'SCCP',
143 => 'DOCSIS',
144 => 'Linux IrDA',
145 => 'IBM SP',
146 => 'IBM SN',
# 147-162 - reserved
163 => 'IEEE 802.11 AVS',
164 => 'Juniper Monitor',
165 => 'BACnet MS/TP',
166 => 'PPP PPPD',
167 => 'Juniper PPPOE',
168 => 'Juniper PPPOE ATM',
169 => 'GPRS LLC',
170 => 'GPF-T',
171 => 'GPF-F',
172 => 'Gcom T1/E1',
173 => 'Gcom Serial',
174 => 'Juniper PIC Peer',
175 => 'ERF ETH',
176 => 'ERF POS',
177 => 'Linux LAPD',
178 => 'Juniper Ether',
179 => 'Juniper PPP',
180 => 'Juniper Frame Relay',
181 => 'Juniper CHDLC',
182 => 'MFR',
182 => 'Juniper VP',
185 => 'A653 ICM',
186 => 'USB FreeBSD',
187 => 'Bluetooth HCI H4',
188 => 'IEEE 802.16 MAC CPS',
189 => 'USB Linux',
190 => 'CAN 2.0B',
191 => 'IEEE 802.15.4 Linux',
192 => 'PPI',
193 => 'IEEE 802.16 MAC CPS Radio',
194 => 'Juniper ISM',
195 => 'IEEE 802.15.4 with FCS',
196 => 'SITA',
197 => 'ERF',
198 => 'RAIF1',
199 => 'IPMB Kontron',
200 => 'Juniper ST',
201 => 'Bluetooth HCI H4 with PHDR',
202 => 'AX.25 KISS',
203 => 'LAPD',
204 => 'PPP with DIR',
205 => 'Cisco HDLC with DIR',
206 => 'Frame Relay with DIR',
207 => 'LAPB with DIR',
# 208 reserved
209 => 'IPMB Linux',
210 => 'FlexRay',
211 => 'MOST',
212 => 'LIN',
213 => 'X2E Serial',
214 => 'X2E Xoraya',
215 => 'IEEE 802.15.4 Nonask PHY',
216 => 'Linux evdev',
217 => 'GSMtap Um',
218 => 'GSMtap Abis',
219 => 'MPLS',
220 => 'USB Linux MMapped',
221 => 'DECT',
222 => 'AOS',
223 => 'Wireless HART',
224 => 'FC-2',
225 => 'FC-2 with Frame Delims',
226 => 'IPNET',
227 => 'CAN Socketcan',
228 => 'IPv4',
229 => 'IPv6',
230 => 'IEEE 802.15.4 No FCS',
231 => 'D-Bus',
232 => 'Juniper VS',
233 => 'Juniper SRX E2E',
234 => 'Juniper Fibre Channel',
235 => 'DVB-CI',
236 => 'Mux 27.010',
237 => 'STANAG 5066 D_PDU',
238 => 'Juniper ATM Cemic',
239 => 'NFLOG',
240 => 'Netanalyzer',
241 => 'Netanalyzer Transparent',
242 => 'IP-over-InfiniBand',
243 => 'MPEG-2 TS',
244 => 'NG40',
245 => 'NFC LLCP',
246 => 'Pfsync',
247 => 'InfiniBand',
248 => 'SCTP',
249 => 'USBPcap',
250 => 'RTAC Serial',
251 => 'Bluetooth LE LL',
252 => 'Wireshark Upper PDU',
253 => 'Netlink',
254 => 'Bluetooth Linux Monitor',
255 => 'Bluetooth BREDR BB',
256 => 'Bluetooth LE LL with PHDR',
257 => 'PROFIBUS Data Link',
258 => 'Apple PKTAP',
259 => 'EPON',
260 => 'IPMI HPM.2',
261 => 'Z-Wave R1/R2',
262 => 'Z-Wave R3',
263 => 'WattStopper DLM',
264 => 'ISO 14443',
265 => 'RDS',
266 => 'USB Darwin',
267 => 'Openflow',
268 => 'SDLC',
269 => 'TI LLN Sniffer',
270 => 'LoRaTap',
271 => 'Vsock',
272 => 'Nordic BLE',
273 => 'DOCSIS 31 XRA31',
274 => 'Ethernet MPacket',
275 => 'DisplayPort AUX',
276 => 'Linux SLL2',
277 => 'Sercos Monitor',
278 => 'Openvizsla',
279 => 'Elektrobit EBHSR',
280 => 'VPP Dispatch',
281 => 'DSA Tag BRCM',
282 => 'DSA Tag BRCM Prepend',
283 => 'IEEE 802.15.4 Tap',
284 => 'DSA Tag DSA',
285 => 'DSA Tag EDSA',
286 => 'ELEE',
287 => 'Z-Wave Serial',
288 => 'USB 2.0',
289 => 'ATSC ALP',
},
},
TimeStamp => {
Groups => { 2 => 'Time' },
ValueConv => q{
return $val if $$self{WindowsTS};
return ConvertUnixTime($val, 1, $$self{TSResol} < 1e-7 ? 9 : 6);
},
PrintConv => '$self->ConvertDateTime($val)',
},
#
# "options" tags common to all blocks
#
1 => 'Comment',
2988 => {
Name => 'CustomOption1',
ValueConv => q{
return undef unless length($val) > 4;
my $len = Get16u(\$val, 2);
return undef unless $len > 4 and $len <= length($val) - 4;
my $str = 'Type='.Get16u(\$val,0).' PEN='.Get32u(\$val,4). ' Val='.substr($val, 8, $len-4);
},
},
2989 => {
Name => 'CustomOption2',
Binary => 1,
},
19372 => {
Name => 'CustomOption3',
ValueConv => q{
return undef unless length($val) > 4;
my $len = Get16u(\$val, 2);
return undef unless $len > 4 and $len <= length($val) - 4;
my $str = 'Type='.Get16u(\$val,0).' PEN='.Get32u(\$val,4). ' Val='.substr($val, 8, $len-4);
},
},
19373 => {
Name => 'CustomOption3',
Binary => 1,
},
#
# "options" tags in Section Header Block
#
'SHB-2' => 'Hardware',
'SHB-3' => 'OperatingSytem',
'SHB-4' => 'UserApplication',
#
# "options" tags in Interface Description Block
#
'IDB-2' => 'DeviceName',
'IDB-3' => 'Description',
'IDB-4' => {
Name => 'IPv4Addr',
Description => 'IPv4 Addr',
# IP address and net mask
ValueConv => '$_=join(".", unpack("C*", $val))); s/(:.*?:.*?:.*?):/$1 /; $_',
},
'IDB-5' => {
Name => 'IPv6Addr',
Description => 'IPv6 Addr',
ValueConv => 'join(":", unpack("(H4)8", $val)) . "/" . unpack("x16C",$val)',
},
'IDB-6' => {
Name => 'MACAddr',
ValueConv => 'join("-", unpack("(H2)6", $val))',
},
'IDB-7' => {
Name => 'EUIAddr',
ValueConv => 'join(":", unpack("(H4)4", $val))',
},
'IDB-8' => {
Name => 'Speed',
Format => 'int64u',
},
'IDB-9' => {
Name => 'TimeStampResolution',
Format => 'int8u',
RawConv => '$$self{TSResol} = ($val & 0x80 ? 2 ** -($val & 0x7f) : 10 ** -$val)',
},
'IDB-10' => 'TimeZone',
'IDB-11' => {
Name => 'Filter',
ValueConv => 'Get8u(\$val,0) . ": " . substr($val, 1)',
},
'IDB-12' => 'OperatingSytem',
'IDB-13' => { Name => 'FCSLen', Format => 'int8u' },
'IDB-14' => {
Name => 'TimeStampOffset',
Format => 'int64u',
RawConv => '$$self{TSOff} = $val',
},
'IDB-15' => 'Hardware',
'IDB-16' => { Name => 'TXSpeed', Format => 'int64u' },
'IDB-17' => { Name => 'RXSpeed', Format => 'int64u' },
'IDB-18' => 'TimezoneName',
);
#------------------------------------------------------------------------------
# Extract metadata from a PCAP file
# Inputs: 0) ExifTool ref, 1) dirInfo ref
# Returns: 1 on success, 0 if this wasn't a valid PCAP file
sub ProcessPCAP($$)
{
my ($et, $dirInfo) = @_;
my $raf = $$dirInfo{RAF};
my ($buff, $tagTablePtr, $type, $ts, $byteOrder, $verPos);
# verify this is a valid PCAP file
return 0 unless $raf->Read($buff, 24) == 24;
if ($buff =~ /^\xa1\xb2(\xc3\xd4|\x3c\x4d)\0.\0.|(\xd4\xc3|\x4d\x3c)\xb2\xa1.\0.\0/s) {
$type = 'PCAP';
my $tmp = $1 || $2;
$$et{TSResol} = ($tmp eq "\xc3\xd4" or $tmp eq "\xd4\xc3") ? 1e-6 : 1e-9;
$byteOrder = $buff =~ /^\xa1/ ? 'MM' : 'II';
$verPos = 4;
} elsif ($buff =~ /^\x0a\x0d\x0d\x0a.{4}(\x1a\x2b\x3c\x4d|\x4d\x3c\x2b\x1a)/s) {
$type = 'PCAPNG';
$byteOrder = $1 eq "\x1a\x2b\x3c\x4d" ? 'MM' : 'II';
$verPos = 12;
} elsif ($buff =~ /^GMBU\0\x02/) {
# handle Windows Network Monitor 2.0 CAP files
# http://web.archive.org/web/20240430011527/https://learn.microsoft.com/en-us/windows/win32/netmon2/capturefile-header-values
$Image::ExifTool::static_vars{OverrideFileDescription}{CAP} = 'Microsoft Network Monitor Capture';
$et->SetFileType('CAP', 'application/octet-stream', 'cap');
$type = 'CAP';
$tagTablePtr = GetTagTable('Image::ExifTool::PCAP::Main');
my @a = unpack('x6v*', $buff);
$$et{WindowsTS} = 1;
my $val = sprintf('%.4d:%.2d:%.2d %.2d:%.2d:%.2d.%.3d',@a[1,2,4..8]);
$et->HandleTag($tagTablePtr, LinkType => $a[0]);
$et->HandleTag($tagTablePtr, TimeStamp => $val);
if ($raf->Seek(40,0) and $raf->Read($buff,8)==8) {
my ($off, $len) = unpack('V2', $buff);
# extract comment
if ($len < 1024 and $raf->Seek($off,0) and $raf->Read($buff,$len) == $len) {
$et->HandleTag($tagTablePtr, 1 => $buff); # (NC) null terminated? Unicode?
}
}
return 1;
} else {
return 0;
}
$et->SetFileType($type);
SetByteOrder($byteOrder);
$tagTablePtr = GetTagTable('Image::ExifTool::PCAP::Main');
my $ver = Get16u(\$buff, $verPos) . '.' . Get16u(\$buff, $verPos+2);
$et->HandleTag($tagTablePtr, PCAPVersion => "$type $ver");
$et->HandleTag($tagTablePtr, ByteOrder => $byteOrder);
if ($type eq 'PCAP') {
$et->HandleTag($tagTablePtr, LinkType => Get16u(\$buff, 22));
$raf->Read($buff, 8) == 8 or $et->Warn('Truncated PCAP file'), return 1;
$ts = Get32u(\$buff, 0) + Get32u(\$buff, 4) * $$et{TSResol};
$et->HandleTag($tagTablePtr, TimeStamp => $ts);
return 1;
}
# read through PCAPNG options for the SHB, IDB and get the timestamp from the first EPD
my $dir = 'SHB'; # Section Header Block
for (;;) {
$raf->Read($buff, 4) == 4 or last;
my $opt = Get16u(\$buff, 0);
my $len = Get16u(\$buff, 2);
if ($opt == 0) { # (end of options?)
last unless $raf->Read($buff, 20) == 20;
my $dirNum = Get32u(\$buff, 4);
if ($dirNum == 1) {
$et->HandleTag($tagTablePtr, LinkType => Get16u(\$buff, 12));
$dir = 'IDB'; # Interface Description Block
next; # continue with IDB options
} elsif ($dirNum == 6) { # EPD (Enhanced Packet Data)
my $ts = 4294967296 * Get32u(\$buff, 16);
$raf->Read(\$buff, 4) == 4 or last;
if ($$et{TSResol}) {
$ts = ($ts + Get32u(\$buff, 0)) * $$et{TSResol} + ($$et{TSOff} || 0);
$et->HandleTag($tagTablePtr, TimeStamp => $ts);
}
}
last;
}
my $n = ($len + 3) & 0xfffc; # round to an even 4 bytes
$raf->Read($buff, $n) == $n or $et->Warn("Error reading $dir options"), last;
my $id = $$tagTablePtr{$opt} ? $opt : "$dir-$opt";
$et->HandleTag($tagTablePtr, $id, undef,
DataPt => \$buff,
DataPos => $raf->Tell() - $n,
Size => $len,
MakeTagInfo => 1,
);
}
return 1;
}
1; # end
__END__
=head1 NAME
Image::ExifTool::PCAP - Read CAP, PCAP and PCAPNG Packet Capture files
=head1 SYNOPSIS
This module is used by Image::ExifTool
=head1 DESCRIPTION
This module contains definitions required by Image::ExifTool to read
metadata from CAP, PCAP and PCAPNG Packet Capture files.
=head1 AUTHOR
Copyright 2003-2025, Phil Harvey (philharvey66 at gmail.com)
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
=head1 REFERENCES
=over 4
=item L<https://www.ietf.org/archive/id/draft-gharris-opsawg-pcap-01.html>
=item L<https://www.ietf.org/archive/id/draft-ietf-opsawg-pcapng-02.html>
=item L<https://formats.kaitai.io/microsoft_network_monitor_v2/>
=back
=head1 SEE ALSO
L<Image::ExifTool::TagNames/PCAP Tags>,
L<Image::ExifTool(3pm)|Image::ExifTool>
=cut