blob_decoder/lib.rs
1//! `blob-decoder` — identify and decode opaque forensic blobs of unknown type.
2//!
3//! Hand it raw bytes; it reports what they are, decodes them, and returns
4//! **scored, cited candidates** — recursively unwrapping nested wrappers (a
5//! base64'd, gzip'd binary-plist is reported as the full
6//! `Base64 → Gzip → BinaryPlist` chain).
7//!
8//! The actual decoding is delegated to mature crates (`plist`, `base64`, `hex`,
9//! `uuid`, `flate2`, `snap`, `serde_json`); this crate adds only the
10//! orchestration layer: identify → dispatch → score → recursively unwrap, plus a
11//! clean forensic result type.
12//!
13//! # Epistemics
14//!
15//! A blob is often underdetermined: bytes that are valid hex are frequently also
16//! valid base64, and a run of ASCII is *technically* decodable as base64 to
17//! gibberish. `blob-decoder` never asserts a single verdict — it returns every
18//! plausible reading with an honest [`Confidence`], and a low-confidence reading
19//! lowers the rank, never hides the finding.
20//!
21//! # Example
22//!
23//! ```
24//! // gzip magic (0x1f 0x8b) → identified as a Gzip wrapper.
25//! let gz = b"\x1f\x8b\x08\x00\x00\x00\x00\x00";
26//! let cands = blob_decoder::identify(gz);
27//! assert_eq!(cands[0].kind, blob_decoder::BlobKind::Gzip);
28//! ```
29#![forbid(unsafe_code)]
30#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
31
32pub mod identify;
33
34pub use identify::{identify, identify_with_limits};
35
36/// The engine's version (`CARGO_PKG_VERSION`), for callers that surface it.
37pub const VERSION: &str = env!("CARGO_PKG_VERSION");
38
39/// A recognised (or unrecognised) blob type.
40///
41/// The `citation` and `label` are carried per-kind so a reading is traceable to
42/// the authoritative format definition it was matched against.
43#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
44#[serde(rename_all = "snake_case")]
45pub enum BlobKind {
46 /// Apple binary property list (`bplist00` magic).
47 BinaryPlist,
48 /// Apple XML property list.
49 XmlPlist,
50 /// gzip member (`1f 8b` magic).
51 Gzip,
52 /// zlib stream (RFC 1950 header).
53 Zlib,
54 /// Snappy framed stream.
55 Snappy,
56 /// base64 text (standard or URL-safe alphabet).
57 Base64,
58 /// Hexadecimal text.
59 Hex,
60 /// A UUID / GUID (16 raw bytes or the canonical hyphenated string).
61 Uuid,
62 /// JSON (object or array root).
63 Json,
64 /// Protocol Buffers wire-format message (schemaless / no `.proto`).
65 Protobuf,
66 /// UTF-16LE text.
67 Utf16Le,
68 /// UTF-8 text (printable).
69 Utf8Text,
70 /// No known type matched — the raw head bytes are reported for the analyst.
71 Unknown,
72}
73
74impl BlobKind {
75 /// A short human label.
76 #[must_use]
77 pub fn label(self) -> &'static str {
78 match self {
79 Self::BinaryPlist => "Apple binary property list",
80 Self::XmlPlist => "Apple XML property list",
81 Self::Gzip => "gzip stream",
82 Self::Zlib => "zlib stream",
83 Self::Snappy => "Snappy framed stream",
84 Self::Base64 => "base64 text",
85 Self::Hex => "hexadecimal text",
86 Self::Uuid => "UUID / GUID",
87 Self::Json => "JSON",
88 Self::Protobuf => "Protocol Buffers (schemaless)",
89 Self::Utf16Le => "UTF-16LE text",
90 Self::Utf8Text => "UTF-8 text",
91 Self::Unknown => "unknown",
92 }
93 }
94
95 /// The authoritative spec / reference this kind is matched against.
96 #[must_use]
97 pub fn citation(self) -> &'static str {
98 match self {
99 Self::BinaryPlist | Self::XmlPlist => {
100 "Apple CoreFoundation CFBinaryPList.c; `man 5 plist`"
101 }
102 Self::Gzip => "RFC 1952 (GZIP file format)",
103 Self::Zlib => "RFC 1950 (ZLIB compressed data format)",
104 Self::Snappy => "google/snappy framing_format.txt",
105 Self::Base64 => "RFC 4648 §4-5 (Base 64 / Base64url)",
106 Self::Hex => "RFC 4648 §8 (Base 16)",
107 Self::Uuid => "RFC 9562 (UUID)",
108 Self::Json => "RFC 8259 (JSON)",
109 Self::Protobuf => "protobuf.dev encoding spec (wire format)",
110 Self::Utf16Le => "The Unicode Standard; RFC 2781 (UTF-16LE)",
111 Self::Utf8Text => "RFC 3629 (UTF-8)",
112 Self::Unknown => "no matching format",
113 }
114 }
115
116 /// True when this kind is a *wrapper* whose payload is itself another blob
117 /// (base64/hex text, or a compression stream) — the recursion drivers.
118 #[must_use]
119 pub fn is_wrapper(self) -> bool {
120 matches!(
121 self,
122 Self::Gzip | Self::Zlib | Self::Snappy | Self::Base64 | Self::Hex
123 )
124 }
125}
126
127/// How strongly the evidence supports a reading. Ordered `Low < Medium < High`
128/// so candidates sort best-first by *descending* confidence.
129///
130/// - [`Confidence::High`] — a strong, near-unique MAGIC signature or a full
131/// successful structural parse (`bplist00`, `1f 8b`, a valid RFC 1950 header,
132/// a parseable JSON object, a canonical hyphenated UUID string).
133/// - [`Confidence::Medium`] — a magic matched but the payload failed to fully
134/// decode, or a heuristic wrapper (base64/hex) whose decoded payload was
135/// itself recognised as a concrete type.
136/// - [`Confidence::Low`] — a purely structural heuristic that a random blob
137/// could satisfy by coincidence (16 arbitrary bytes as a UUID; base64/hex text
138/// decoding only to more opaque bytes; plain printable text).
139#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, serde::Serialize)]
140#[serde(rename_all = "snake_case")]
141pub enum Confidence {
142 /// A coincidence-prone structural heuristic.
143 Low,
144 /// A magic matched but payload decode was partial, or a heuristic wrapper
145 /// whose payload was recognised.
146 Medium,
147 /// A strong magic signature or a full successful parse.
148 High,
149}
150
151/// One scored, cited candidate reading of a blob. A wrapper candidate nests the
152/// identification of its decoded payload in [`Candidate::inner`], so a
153/// `base64 → gzip → binary-plist` blob reports the whole chain.
154#[derive(Debug, Clone, serde::Serialize)]
155pub struct Candidate {
156 /// The identified (or unidentified) kind.
157 pub kind: BlobKind,
158 /// How strongly the evidence supports this reading.
159 pub score: Confidence,
160 /// A human summary of *what was found* (root type, byte counts, decoded
161 /// text prefix, or — for [`BlobKind::Unknown`] — the raw head bytes).
162 pub summary: String,
163 /// The authoritative spec citation for [`Candidate::kind`].
164 pub citation: &'static str,
165 /// For a wrapper kind, the identification of the decoded/decompressed
166 /// payload — the next link in the chain. `None` for a leaf reading, a failed
167 /// decode, or when the recursion depth cap was reached.
168 #[serde(skip_serializing_if = "Option::is_none")]
169 pub inner: Option<Box<DecodedChain>>,
170}
171
172/// The decoded payload of a wrapper [`Candidate`]: how many bytes it produced
173/// and the best reading of those bytes.
174#[derive(Debug, Clone, serde::Serialize)]
175pub struct DecodedChain {
176 /// Number of bytes the wrapper decoded/decompressed to (after any cap).
177 pub decoded_len: usize,
178 /// True when the decoded output was truncated at the size cap (a possible
179 /// decompression bomb) — the payload reading is of the capped prefix.
180 pub capped: bool,
181 /// The best (highest-confidence) reading of the decoded payload.
182 pub best: Box<Candidate>,
183}
184
185/// Resource bounds for [`identify_with_limits`] — the guard against
186/// decompression bombs and infinitely-nested wrappers on untrusted input.
187#[derive(Debug, Clone, Copy)]
188pub struct Limits {
189 /// Maximum recursion depth through nested wrappers.
190 pub max_depth: usize,
191 /// Maximum bytes to hold from a single decompression/decode step (a
192 /// decompression bomb is capped here, never allowed to exhaust memory).
193 pub max_output: usize,
194 /// Inputs larger than this skip the *heuristic* decoders (base64/hex/text);
195 /// magic-signature detection still runs. Bounds worst-case work.
196 pub max_input: usize,
197}
198
199impl Default for Limits {
200 fn default() -> Self {
201 Self {
202 max_depth: 8,
203 max_output: 64 * 1024 * 1024,
204 max_input: 128 * 1024 * 1024,
205 }
206 }
207}