pcap_parser/lib.rs
1//! [](./LICENSE-MIT)
2//! [](./LICENSE-APACHE)
3//! [](https://crates.io/crates/pcap-parser)
4//! [](https://docs.rs/pcap-parser)
5//! [](https://github.com/rusticata/pcap-parser/actions)
6//! [](#rust-version-requirements)
7//!
8//! # PCAP and PCAPNG parsers
9//!
10//! This crate contains several parsers for PCAP and PCAPNG files.
11//!
12//! Compared to other similar projects, it is designed to offer a complete support of the many
13//! possible formats (legacy pcap, pcapng, little or big-endian, etc.) and features (pcapng files
14//! with multiple sections, interfaces, and endianness) while using only safe code and without
15//! copying data (zero-copy).
16//!
17//! The code is available on [Github](https://github.com/rusticata/pcap-parser)
18//! and is part of the [Rusticata](https://github.com/rusticata) project.
19//!
20//! # The pcap format(s)
21//!
22//! The [PCAP] format (files usually ending with `.pcap` extension) is rather
23//! trivial. The [PCAPNG] format (usually `.pcapng` extension) is much more complex: it
24//! can be composed of multiple sections, each with multiple interfaces, having
25//! different capture lengths, time precision and even endianness!
26//!
27//! These formats are more containers than data formats: packets contain data,
28//! formatted according to its interface linktype. There are *many* possible
29//! linktypes, defined in the [linktypes registry]. Support for parsing some of
30//! them is provided using the `data` feature (disabled by default).
31//!
32//! This crate provides an abstraction over these different formats.
33//!
34//! [PCAP]: https://wiki.wireshark.org/Development/LibpcapFileFormat
35//! [PCAPNG]: https://pcapng.github.io/pcapng/
36//! [linktypes registry]: https://www.tcpdump.org/linktypes.html
37//!
38//! # Parsing a file
39//!
40//! `pcap-parser` provides several ways of parsing pcap data. Choosing the right
41//! one is mostly driven by resources: if the input file is small, the
42//! `parse_pcap` and `parse_pcapng` functions can be used directly.
43//!
44//! Fine-grained functions are also available, to parse specifically some block
45//! types for example. They are listed in the `pcap` and `pcapng` modules.
46//!
47//! If the input is larger and cannot fit into memory, then streaming parsers
48//! are available. They work by iterating on blocks, and so do not require to map
49//! the entire input. They cannot seek to a specific block, however.
50//!
51//! *Note: due to PCAPNG limitations, it is not possible to directly seek in
52//! a file to get a packet and handle it: the caller has to iterate though the
53//! file and store (at least) the interface descriptions for the current
54//! section, in order of appearance.*
55//!
56//! ## Example: streaming parsers
57//!
58//! The following code shows how to parse a file in the pcap-ng format, using a
59//! [`PcapNGReader`] streaming parser.
60//! This reader provides a convenient abstraction over the file format, and takes
61//! care of the endianness.
62//!
63//! ```rust
64//! use pcap_parser::*;
65//! use pcap_parser::traits::PcapReaderIterator;
66//! use std::fs::File;
67//!
68//! # let path = "assets/test001-le.pcapng";
69//! let file = File::open(path).unwrap();
70//! let mut num_blocks = 0;
71//! let mut reader = PcapNGReader::new(65536, file).expect("PcapNGReader");
72//! loop {
73//! match reader.next() {
74//! Ok((offset, _block)) => {
75//! println!("got new block");
76//! num_blocks += 1;
77//! reader.consume(offset);
78//! },
79//! Err(PcapError::Eof) => break,
80//! Err(PcapError::Incomplete(_)) => {
81//! reader.refill().unwrap();
82//! },
83//! Err(e) => panic!("error while reading: {:?}", e),
84//! }
85//! }
86//! println!("num_blocks: {}", num_blocks);
87//! ```
88//! See [`PcapNGReader`] for a complete example,
89//! including handling of linktype and accessing packet data.
90//!
91//! See also the [`pcapng`] module for more details about the new capture file format.
92//!
93//! For legacy pcap files, use similar code with the
94//! [`LegacyPcapReader`] streaming parser.
95//!
96//! See [pcap-analyzer](https://github.com/rusticata/pcap-analyzer), in particular the
97//! [libpcap-tools](https://github.com/rusticata/pcap-analyzer/tree/master/libpcap-tools) and
98//! [pcap-info](https://github.com/rusticata/pcap-analyzer/tree/master/pcap-info) modules
99//! for more examples.
100//!
101//! ## Example: generic streaming parsing
102//!
103//! To create a pcap reader for input in either PCAP or PCAPNG format, use the
104//! [`create_reader`] function.
105//!
106//! # Serialization
107//!
108//! Support for serialization (*i.e.* generating binary data) is available by
109//! enabling the `serialize` feature.
110//! Most structures gain the `to_vec()` method (provided by the `ToVec` trait).
111//!
112//! Note: support is still experimental, though working. API may change in the
113//! future.
114
115#![deny(/*missing_docs,*/
116 unstable_features,
117 unused_import_braces, unused_qualifications)]
118#![deny(unsafe_code)]
119#![allow(clippy::upper_case_acronyms)]
120// pragmas for doc
121#![deny(rustdoc::broken_intra_doc_links)]
122#![cfg_attr(docsrs, feature(doc_cfg))]
123#![doc(test(
124 no_crate_inject,
125 attr(deny(warnings/*, rust_2018_idioms*/), allow(dead_code, unused_variables))
126))]
127
128mod utils;
129pub use utils::{Data, MutableData};
130
131mod blocks;
132mod capture;
133mod endianness;
134mod error;
135mod linktype;
136pub use blocks::*;
137pub use capture::*;
138pub use error::*;
139pub use linktype::*;
140
141pub mod pcap;
142pub mod pcapng;
143pub use pcap::*;
144pub use pcapng::*;
145
146pub mod traits;
147
148#[cfg(feature = "serialize")]
149#[cfg_attr(docsrs, doc(cfg(feature = "serialize")))]
150mod serialize;
151#[cfg_attr(docsrs, doc(cfg(feature = "serialize")))]
152#[cfg(feature = "serialize")]
153pub use serialize::ToVec;
154
155#[cfg(feature = "data")]
156#[cfg_attr(docsrs, doc(cfg(feature = "data")))]
157pub mod data;
158
159// re-exports
160pub use nom;