Expose shared packet capture and protocol inspection with retained bounds

This commit is contained in:
Dylan M. Taylor committed 2026-11-17 08:41:16 -05:00
1 parent eb83770464
commit 33a83bab9b
25 files changed
+244 -62

No files matched your search

+4
View File
@@ -132,3 +132,7 @@ Sanitization, animation fitting and numeric output policy remain caller-owned.
## JSONC span-preserving editing
`crates/jsonc` is extracted from Craft Anything `crates/formats/src/jsonc.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). The original implementation and hardening by BFlat, newline preservation by NetterSilver, and subsequent RRFZ/Afloat correctness fixes retain separate primary-author port commits with immutable source revisions. Shared API wiring and optional input-byte admission are subsequent changes. Compatibility parsing and all existing formatting/editing tests are retained; application file I/O and policy are not imported.
## Packet capture and protocol inspection
`crates/pcap` extracts Craft Anything `crates/formats/src/pcap.rs`, its checked byte reader primitives and synthetic packet fixtures/regressions at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the implementation, byte reader and fixtures in `f64ae3bf3c8863a982af1304e06de20653803968`. Subsequent fixes by phatloi0010, GGWA, BFlat, Afloat, NetterSilver, Max Mittelstädt and RRFZ retain separate primary-author source-history commits with immutable source revisions. Shared error/API wiring and chrono-based timestamp formatting with exhaustive day-boundary parity tests are subsequent Dylan M. Taylor changes. No packet reassembly, decryption, live capture or app analysis policy is imported.
Generated
+10
View File
@@ -2625,6 +2625,16 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-pcap"
version = "0.1.0"
dependencies = [
"chrono",
"serde",
"serde_json",
"thiserror 2.0.21",
]
[[package]]
name = "craft-pdf"
version = "0.1.0"
+1
View File
@@ -11,6 +11,7 @@ rust-version = "1.95"
repository = "https://github.com/storytold/craft-libs"
[workspace.dependencies]
craft-pcap = { path = "crates/pcap" }
craft-jsonc = { path = "crates/jsonc" }
craft-palette = { path = "crates/palette" }
craft-score = { path = "crates/score" }
+17
View File
@@ -0,0 +1,17 @@
[package]
name = "craft-pcap"
description = "Read-only PCAP/PCAPNG and per-frame protocol inspection"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
serde = { workspace = true }
thiserror = { workspace = true }
chrono = { workspace = true }
[dev-dependencies]
serde_json = { workspace = true }
+49
View File
@@ -0,0 +1,49 @@
//! Checked little/big-endian reads over untrusted bytes. Every read returns `None` when out of range.
#[derive(Debug, Clone, Copy)]
pub struct Reader<'a> {
data: &'a [u8],
}
impl<'a> Reader<'a> {
pub fn new(data: &'a [u8]) -> Self {
Reader { data }
}
pub fn slice(&self, off: usize, len: usize) -> Option<&'a [u8]> {
let end = off.checked_add(len)?;
self.data.get(off..end)
}
pub fn u8(&self, off: usize) -> Option<u8> {
self.data.get(off).copied()
}
fn arr<const N: usize>(&self, off: usize) -> Option<[u8; N]> {
self.slice(off, N)?.try_into().ok()
}
pub fn u16_le(&self, off: usize) -> Option<u16> {
self.arr(off).map(u16::from_le_bytes)
}
pub fn u32_le(&self, off: usize) -> Option<u32> {
self.arr(off).map(u32::from_le_bytes)
}
pub fn u64_le(&self, off: usize) -> Option<u64> {
self.arr(off).map(u64::from_le_bytes)
}
pub fn u16_be(&self, off: usize) -> Option<u16> {
self.arr(off).map(u16::from_be_bytes)
}
pub fn u32_be(&self, off: usize) -> Option<u32> {
self.arr(off).map(u32::from_be_bytes)
}
pub fn u64_be(&self, off: usize) -> Option<u64> {
self.arr(off).map(u64::from_be_bytes)
}
}
+73 -26
View File
@@ -1,12 +1,32 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
//! Saved packet captures: classic pcap (microsecond and nanosecond, either byte order) and pcapng
//! (section, interface, enhanced/simple/obsolete packet blocks). Frames are decoded from Ethernet
//! (with VLAN tags), raw IP, Linux cooked (SLL/SLL2) and BSD loopback links into IPv4/IPv6,
//! TCP/UDP/ICMP, and the application facts most people ask about: DNS questions and answers,
//! HTTP/1.x request and status lines with the Host header, and the TLS ClientHello server name
//! (SNI) and ALPN. Each frame is decoded on its own: no TCP reassembly, no decryption. Pure, no I/O,
//! every length checked.
//! every length checked. Input bytes remain caller-owned and must be admitted to a caller budget.
//! Packet, flow and inventory caps below are retained; they are not a total allocator-byte guarantee.
use crate::FormatError;
mod bytes;
#[cfg(test)]
#[path = "../tests/support/mod.rs"]
mod test_support;
/// Why capture inspection could not start or finish.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum PcapError {
#[error("the file ends early ({0})")]
Truncated(String),
#[error("the file is malformed ({0})")]
Malformed(String),
#[error("not supported: {0}")]
Unsupported(String),
}
use crate::PcapError as FormatError;
use crate::bytes::Reader;
use serde::Serialize;
use std::collections::{BTreeMap, BTreeSet, HashMap};
@@ -245,7 +265,9 @@ impl<'a> Capture<'a> {
if p >= self.data.len() {
return None;
}
let (Some(sec), Some(frac), Some(incl), Some(orig)) = (rd_u32(&r, le, p), rd_u32(&r, le, p + 4), rd_u32(&r, le, p + 8), rd_u32(&r, le, p + 12)) else {
let (Some(sec), Some(frac), Some(incl), Some(orig)) =
(rd_u32(&r, le, p), rd_u32(&r, le, p + 4), rd_u32(&r, le, p + 8), rd_u32(&r, le, p + 12))
else {
return self.stop(format!("record header at offset {p} is cut short"));
};
let Some(body) = usize::try_from(incl).ok().and_then(|n| r.slice(p + 16, n)) else {
@@ -1022,7 +1044,8 @@ fn dns(msg: &[u8], d: &mut Decoded, label: &'static str, mdns_wire_format: bool)
return;
}
d.protocols.push(label);
let mut out = Dns { id, response: flags & 0x8000 != 0, rcode: (flags & 0xf) as u8, questions: Vec::new(), answers: Vec::new(), incomplete: false };
let mut out =
Dns { id, response: flags & 0x8000 != 0, rcode: (flags & 0xf) as u8, questions: Vec::new(), answers: Vec::new(), incomplete: false };
let mut off = 12usize;
for _ in 0..qd {
let Some((name, next, _)) = dns_name(msg, off, true) else {
@@ -1236,7 +1259,8 @@ fn tcp_app(p: &[u8], d: &mut Decoded) {
remaining = remaining.get(end + 2..).unwrap_or(&[]);
}
d.protocols.push("http");
d.http = Some(Http { kind: "request", method: Some(m.to_string()), target: Some(strip_userinfo(t)), status: None, version: v.to_string(), host });
d.http =
Some(Http { kind: "request", method: Some(m.to_string()), target: Some(strip_userinfo(t)), status: None, version: v.to_string(), host });
return;
}
tls(p, d);
@@ -1559,7 +1583,8 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result<Summary, F
let mut flows = FlowTable::default();
let mut flow_rows: Vec<Flow> = Vec::new();
let (mut protocols, mut stacks, mut endpoints) = (Tally::default(), Tally::default(), Tally::default());
let (mut queries, mut answers, mut http, mut sni, mut alpn) = (Tally::default(), Tally::default(), Tally::default(), Tally::default(), Tally::default());
let (mut queries, mut answers, mut http, mut sni, mut alpn) =
(Tally::default(), Tally::default(), Tally::default(), Tally::default(), Tally::default());
let mut addresses = Tally::default();
for f in cap.by_ref() {
if f.number % 4096 == 0 && cancelled() {
@@ -1680,30 +1705,21 @@ pub fn summarize(data: &[u8], cancelled: &dyn Fn() -> bool) -> Result<Summary, F
/// `YYYY-MM-DDThh:mm:ss.nnnnnnnnnZ` for nanoseconds since the Unix epoch.
pub fn iso8601(ns: u64) -> String {
let secs = ns / 1_000_000_000;
let (days, rem) = (secs / 86_400, secs % 86_400);
// Civil-from-days (proleptic Gregorian), valid for every u64 day count we can reach.
let z = days as i64 + 719_468;
let era = z.div_euclid(146_097);
let doe = z - era * 146_097;
let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
let mp = (5 * doy + 2) / 153;
let day = doy - (153 * mp + 2) / 5 + 1;
let month = if mp < 10 { mp + 3 } else { mp - 9 };
let year = yoe + era * 400 + i64::from(month <= 2);
format!("{year:04}-{month:02}-{day:02}T{:02}:{:02}:{:02}.{:09}Z", rem / 3600, rem % 3600 / 60, rem % 60, ns % 1_000_000_000)
// u64 nanoseconds span only 1970..2554, entirely within chrono's representable range.
chrono::DateTime::from_timestamp((ns / 1_000_000_000) as i64, (ns % 1_000_000_000) as u32)
.map(|time| time.to_rfc3339_opts(chrono::SecondsFormat::Nanos, true))
.unwrap_or_default()
}
#[cfg(test)]
mod tests {
use super::*;
use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, pcap, pcapng, sample_frames, udp};
use crate::test_support::{dns_query, eth, ipv4_pkt, pcap, pcapng, sample_frames, udp};
#[test]
fn rejected_simple_packets_count_toward_the_scan_limit() {
let mut data = pcapng(&[]);
let rejected = craft_anything_testkit::pcap::block(3, &1u32.to_le_bytes());
let rejected = crate::test_support::block(3, &1u32.to_le_bytes());
for _ in 0..3 {
data.extend(&rejected);
}
@@ -1722,7 +1738,7 @@ mod tests {
#[test]
fn rejected_simple_packets_at_eof_do_not_report_a_truncated_scan() {
let mut data = pcapng(&[]);
let rejected = craft_anything_testkit::pcap::block(3, &1u32.to_le_bytes());
let rejected = crate::test_support::block(3, &1u32.to_le_bytes());
for _ in 0..2 {
data.extend(&rejected);
}
@@ -1737,8 +1753,8 @@ mod tests {
#[test]
fn valid_and_rejected_simple_packets_share_the_scan_limit() {
let mut data = pcapng(&[]);
data.extend(craft_anything_testkit::pcap::block(3, &1u32.to_le_bytes()));
let valid = craft_anything_testkit::pcap::block(3, &0u32.to_le_bytes());
data.extend(crate::test_support::block(3, &1u32.to_le_bytes()));
let valid = crate::test_support::block(3, &0u32.to_le_bytes());
data.extend(&valid);
data.extend(&valid);
let mut cap = Capture::new(&data).unwrap();
@@ -1751,7 +1767,7 @@ mod tests {
#[test]
fn malformed_packet_blocks_share_the_budget_and_report_each_reason_once() {
use craft_anything_testkit::pcap::block;
use crate::test_support::block;
let mut data = pcapng(&[]);
for kind in [2, 6] {
let mut body = [0; 20];
@@ -1794,7 +1810,7 @@ mod tests {
#[test]
fn subnanosecond_decimal_resolutions_keep_the_interface_offset() {
use craft_anything_testkit::pcap::block;
use crate::test_support::block;
let mut data = pcapng(&[]);
data.truncate(28);
let mut idb = vec![1, 0, 0, 0, 0, 0, 0, 0, 9, 0, 1, 0, 127, 0, 0, 0, 14, 0, 8, 0];
@@ -2134,3 +2150,34 @@ mod tests {
assert!(dns_name(&[0xc0, 0x00], 0, true).is_none());
}
}
#[cfg(test)]
mod timestamp_parity {
fn legacy_iso8601(ns: u64) -> String {
let secs = ns / 1_000_000_000;
let (days, rem) = (secs / 86_400, secs % 86_400);
// Civil-from-days (proleptic Gregorian), valid for every u64 day count we can reach.
let z = days as i64 + 719_468;
let era = z.div_euclid(146_097);
let doe = z - era * 146_097;
let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
let mp = (5 * doy + 2) / 153;
let day = doy - (153 * mp + 2) / 5 + 1;
let month = if mp < 10 { mp + 3 } else { mp - 9 };
let year = yoe + era * 400 + i64::from(month <= 2);
format!("{year:04}-{month:02}-{day:02}T{:02}:{:02}:{:02}.{:09}Z", rem / 3600, rem % 3600 / 60, rem % 60, ns % 1_000_000_000)
}
#[test]
fn every_representable_day_and_boundaries_match_legacy() {
let day = 86_400_000_000_000u64;
for d in 0..=u64::MAX / day {
let ns = d * day;
assert_eq!(super::iso8601(ns), legacy_iso8601(ns));
}
for ns in [0, 1, 999_999_999, 1_000_000_000, u64::MAX - 1, u64::MAX] {
assert_eq!(super::iso8601(ns), legacy_iso8601(ns));
}
}
}
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::{Dns, decode};
use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, udp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::{Dns, decode};
use support::{dns_query, eth, ipv4_pkt, udp};
fn answer(kind: u16, rd: &[u8]) -> Dns {
let mut msg = dns_query();
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::{decode, summarize};
use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, pcap, udp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::{decode, summarize};
use support::{dns_query, eth, ipv4_pkt, pcap, udp};
fn packet(message: &[u8]) -> Vec<u8> {
eth(0x0800, &ipv4_pkt(17, [192, 0, 2, 1], [192, 0, 2, 2], &udp(51000, 53, message)))
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::{decode, summarize};
use craft_anything_testkit::pcap::{dns_query, eth, ipv4_pkt, pcap, udp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::{decode, summarize};
use support::{dns_query, eth, ipv4_pkt, pcap, udp};
fn response(record_type: u16, rdata: &[u8], declared_length: usize) -> Vec<u8> {
let mut message = dns_query();
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::{Dns, decode};
use craft_anything_testkit::pcap::{ipv4_pkt, udp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::{Dns, decode};
use support::{ipv4_pkt, udp};
fn query(last: usize, compressed: bool) -> Dns {
let mut msg = vec![0, 1, 1, 0, 0, if compressed { 2 } else { 1 }, 0, 0, 0, 0, 0, 0];
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::{Dns, decode};
use craft_anything_testkit::pcap::{ipv4_pkt, udp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::{Dns, decode};
use support::{ipv4_pkt, udp};
fn response(data: &[u8]) -> Dns {
let mut msg = vec![0, 1, 0x81, 0x80, 0, 0, 0, 1, 0, 0, 0, 0];
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::summarize;
use craft_anything_testkit::pcap::{block, eth, ipv4_pkt, pcap, pcapng, udp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::summarize;
use support::{block, eth, ipv4_pkt, pcap, pcapng, udp};
fn frame() -> Vec<u8> {
eth(0x0800, &ipv4_pkt(17, [1; 4], [2; 4], &udp(100, 200, b"body")))
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::{Http, decode};
use craft_anything_testkit::pcap::{ipv4_pkt, tcp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::{Http, decode};
use support::{ipv4_pkt, tcp};
fn request(data: &[u8]) -> Http {
decode(101, &ipv4_pkt(6, [1; 4], [2; 4], &tcp(100, 80, 0x18, data))).http.unwrap()
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::decode;
use craft_anything_testkit::pcap::{ipv4_pkt, tcp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::decode;
use support::{ipv4_pkt, tcp};
/// WebDAV and extension methods retain the same HTTP evidence as core methods.
#[test]
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::decode;
use craft_anything_testkit::pcap::{ipv4_pkt, udp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::decode;
use support::{ipv4_pkt, udp};
#[test]
fn incomplete_ipv4_base_headers_explain_why_decoding_stopped() {
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::decode;
use craft_anything_testkit::pcap::{eth, udp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::decode;
use support::{eth, udp};
fn packet(offset: u16, next: u8, payload: &[u8]) -> Vec<u8> {
let mut ip = vec![0u8; 40];
@@ -1,4 +1,4 @@
use craft_anything_formats::pcap::decode;
use craft_pcap::decode;
/// Build a raw IPv6 packet with the given payload and Next Header field.
fn packet(next: u8, payload: &[u8]) -> Vec<u8> {
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::decode;
use craft_anything_testkit::pcap::{eth, ipv4_pkt};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::decode;
use support::{eth, ipv4_pkt};
fn raw_packets() -> (Vec<u8>, Vec<u8>) {
let ipv4 = ipv4_pkt(17, [1; 4], [2; 4], &[0; 20]);
+1 -1
View File
@@ -1,4 +1,4 @@
use craft_anything_formats::pcap::decode;
use craft_pcap::decode;
/// Decode a raw IPv4 packet with a TCP header and the specified control bits.
fn flags_on_wire(bits: u8) -> String {
+5 -2
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::Capture;
use craft_anything_testkit::pcap::{block, pcapng};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::Capture;
use support::{block, pcapng};
fn capture(original: u32, snaplen: u32, payload: &[u8]) -> Vec<u8> {
let mut out = pcapng(&[]);
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::summarize;
use craft_anything_testkit::pcap::{block, pcapng, sample_frames};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::summarize;
use support::{block, pcapng, sample_frames};
#[test]
fn mismatched_block_footers_stop_the_capture_with_a_warning() {
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::{Decoded, decode};
use craft_anything_testkit::pcap::{dns_query, dns_response, ipv4_pkt, tcp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::{Decoded, decode};
use support::{dns_query, dns_response, ipv4_pkt, tcp};
fn decoded(payload: &[u8]) -> Decoded {
decode(101, &ipv4_pkt(6, [192, 0, 2, 1], [192, 0, 2, 2], &tcp(53, 51000, 0x18, payload)))
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::{Decoded, decode};
use craft_anything_testkit::pcap::{ipv4_pkt, tcp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::{Decoded, decode};
use support::{ipv4_pkt, tcp};
fn decoded(segment: &[u8]) -> Decoded {
decode(101, &ipv4_pkt(6, [192, 0, 2, 1], [192, 0, 2, 2], segment))
+6 -3
View File
@@ -1,5 +1,8 @@
use craft_anything_formats::pcap::{Decoded, decode};
use craft_anything_testkit::pcap::{client_hello, ipv4_pkt, tcp};
#[path = "support/mod.rs"]
mod support;
use craft_pcap::{Decoded, decode};
use support::{client_hello, ipv4_pkt, tcp};
fn decoded(record: &[u8]) -> Decoded {
decode(101, &ipv4_pkt(6, [192, 0, 2, 1], [192, 0, 2, 2], &tcp(51000, 443, 0x18, record)))
@@ -101,7 +104,7 @@ fn complete_hello_metadata_is_unchanged() {
assert!(!hello.partial);
}
fn hello_with_vectors(session: &[u8], suites: &[u8], compression: &[u8], extensions: &[(u16, &[u8])]) -> craft_anything_formats::pcap::TlsHello {
fn hello_with_vectors(session: &[u8], suites: &[u8], compression: &[u8], extensions: &[(u16, &[u8])]) -> craft_pcap::TlsHello {
let mut record = client_hello("unused.test");
record.truncate(43);
record.push(session.len() as u8);
+7 -1
View File
@@ -1,3 +1,4 @@
#![allow(dead_code)]
//! Packet-capture fixtures: hand-built Ethernet/IPv4 frames (DNS, TCP handshake, TLS
//! ClientHello, HTTP request, ARP) written as classic pcap or pcapng.
@@ -104,7 +105,12 @@ pub fn sample_frames() -> Vec<Vec<u8>> {
eth(0x0800, &ipv4_pkt(6, c, web, &tcp(50001, 443, 0x18, &client_hello("example.com")))),
eth(
0x0800,
&ipv4_pkt(6, c, web, &tcp(50002, 80, 0x18, b"GET http://user:pw@example.com/a?b=1 HTTP/1.1\r\nHost: example.com\r\nUser-Agent: t\r\n\r\n")),
&ipv4_pkt(
6,
c,
web,
&tcp(50002, 80, 0x18, b"GET http://user:pw@example.com/a?b=1 HTTP/1.1\r\nHost: example.com\r\nUser-Agent: t\r\n\r\n"),
),
),
eth(0x0806, &[0u8; 28]),
]