Skip to main content

wire_desktop_forensic/
lib.rs

1//! Forensic anomaly analysis for **Wire desktop** IndexedDB artifacts, layered on
2//! the [`wire_desktop_core`] reader.
3//!
4//! The reader interprets the Chromium IndexedDB Dexie stores into typed
5//! [`wire_desktop_core::WireRecord`]s; this crate inspects an interpreted
6//! [`wire_desktop_core::WireStore`] and reports observations as canonical
7//! [`forensicnomicon::report::Finding`]s, so Wire findings aggregate alongside
8//! every other `SecurityRonin` analyzer.
9//!
10//! | Code | Category | Meaning |
11//! |---|---|---|
12//! | `WIRE-MESSAGE-ENCRYPTED-UNRECOVERABLE` | Provenance | a message body is client-side (Proteus) encrypted; the key is not in the OS Safe Storage, so plaintext is unrecoverable |
13//! | `WIRE-MESSAGE-CLEARTEXT` | Residue | a cleartext message body was recovered from the store |
14//! | `WIRE-RECORD-DELETED-RESIDUAL` | Residue | a tombstoned (deleted) Wire record survives in the LevelDB and was recovered |
15//! | `WIRE-OTR-KEY-PRESENT` | Threat | the Wire `otr_key` (attachment key) is present in the IndexedDB — recoverable key material |
16//!
17//! Findings are observations, never legal conclusions.
18
19#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
20
21use forensicnomicon::report::{Category, Evidence, Finding, Location, Severity, Source};
22use wire_desktop_core::{PayloadState, WireRecord, WireStore};
23
24/// Analyzer name, recorded on every finding's [`forensicnomicon::report::Source`].
25pub const ANALYZER: &str = "wire-desktop-forensic";
26
27/// The documented Wire attachment-decryption key name (hunjison, *Forensic
28/// Analysis of Wire Messenger in Windows OS*). Its presence in the IndexedDB is
29/// recoverable key material — the domain's documented literal, not a fixture
30/// special-case.
31const OTR_KEY_NAME: &str = "otr_key";
32
33/// A Wire IndexedDB observation, with the offending evidence attached.
34///
35/// The reader keeps its typed record output; this analyzer keeps its typed
36/// anomaly kind (domain knowledge) and converts to canonical findings.
37#[derive(Debug, Clone, PartialEq, Eq)]
38pub enum AnomalyKind {
39    /// A message body is client-side (Proteus) encrypted and its key is not
40    /// recoverable from this artifact.
41    EncryptedMessage {
42        /// The conversation the message belongs to.
43        conversation: Option<String>,
44        /// The message time, if known.
45        time: Option<String>,
46    },
47    /// A cleartext message body was recovered from the store.
48    CleartextMessage {
49        /// The conversation the message belongs to.
50        conversation: Option<String>,
51        /// The sender, if known.
52        sender: Option<String>,
53        /// The message time, if known.
54        time: Option<String>,
55    },
56    /// A deletion tombstone survived in the LevelDB and was recovered.
57    DeletedRecord {
58        /// The object store it came from.
59        store: String,
60        /// Its primary key.
61        primary_key: String,
62    },
63    /// The Wire `otr_key` (attachment key) is present in the IndexedDB.
64    OtrKeyPresent {
65        /// The object store it came from.
66        store: String,
67        /// Its primary key.
68        primary_key: String,
69    },
70}
71
72impl AnomalyKind {
73    /// Stable, scheme-prefixed machine code (a published contract).
74    #[must_use]
75    pub fn code(&self) -> &'static str {
76        match self {
77            AnomalyKind::EncryptedMessage { .. } => "WIRE-MESSAGE-ENCRYPTED-UNRECOVERABLE",
78            AnomalyKind::CleartextMessage { .. } => "WIRE-MESSAGE-CLEARTEXT",
79            AnomalyKind::DeletedRecord { .. } => "WIRE-RECORD-DELETED-RESIDUAL",
80            AnomalyKind::OtrKeyPresent { .. } => "WIRE-OTR-KEY-PRESENT",
81        }
82    }
83
84    /// Canonical severity for the observation.
85    #[must_use]
86    pub fn severity(&self) -> Severity {
87        match self {
88            AnomalyKind::EncryptedMessage { .. } => Severity::Info,
89            AnomalyKind::CleartextMessage { .. } => Severity::Low,
90            AnomalyKind::DeletedRecord { .. } => Severity::Medium,
91            AnomalyKind::OtrKeyPresent { .. } => Severity::High,
92        }
93    }
94
95    /// Analytical lens for the observation.
96    #[must_use]
97    pub fn category(&self) -> Category {
98        match self {
99            AnomalyKind::EncryptedMessage { .. } => Category::Provenance,
100            AnomalyKind::CleartextMessage { .. } | AnomalyKind::DeletedRecord { .. } => {
101                Category::Residue
102            }
103            AnomalyKind::OtrKeyPresent { .. } => Category::Threat,
104        }
105    }
106
107    /// Human-readable, consistent-with note.
108    #[must_use]
109    pub fn note(&self) -> String {
110        match self {
111            AnomalyKind::EncryptedMessage { conversation, .. } => format!(
112                "a message in conversation {} is client-side (Proteus) encrypted; Wire's message \
113                 key is not held in the Chromium OS Safe Storage, so the plaintext is \
114                 unrecoverable from this artifact",
115                conversation.as_deref().unwrap_or("<unknown>")
116            ),
117            AnomalyKind::CleartextMessage { conversation, .. } => format!(
118                "a cleartext message body was recovered from conversation {} in the Wire IndexedDB",
119                conversation.as_deref().unwrap_or("<unknown>")
120            ),
121            AnomalyKind::DeletedRecord { store, primary_key } => format!(
122                "a deleted Wire record ({store}/{primary_key}) survives as a LevelDB tombstone and \
123                 was recovered — consistent with residual data after deletion"
124            ),
125            AnomalyKind::OtrKeyPresent { store, primary_key } => format!(
126                "the Wire otr_key attachment key is present in the IndexedDB ({store}/{primary_key}) \
127                 — consistent with recoverable attachment-decryption key material"
128            ),
129        }
130    }
131
132    /// MITRE ATT&CK techniques this observation is consistent with.
133    #[must_use]
134    fn mitre(&self) -> &'static [&'static str] {
135        match self {
136            // Unsecured Credentials — key material recoverable from local storage.
137            AnomalyKind::OtrKeyPresent { .. } => &["T1552"],
138            _ => &[],
139        }
140    }
141
142    /// Evidence rows for the observation.
143    fn evidence(&self) -> Vec<Evidence> {
144        match self {
145            AnomalyKind::EncryptedMessage { conversation, time }
146            | AnomalyKind::CleartextMessage {
147                conversation, time, ..
148            } => {
149                let mut ev = Vec::new();
150                if let Some(c) = conversation {
151                    ev.push(Evidence {
152                        field: "conversation".to_string(),
153                        value: c.clone(),
154                        location: None,
155                    });
156                }
157                if let Some(t) = time {
158                    ev.push(Evidence {
159                        field: "time".to_string(),
160                        value: t.clone(),
161                        location: None,
162                    });
163                }
164                ev
165            }
166            AnomalyKind::DeletedRecord { store, primary_key }
167            | AnomalyKind::OtrKeyPresent { store, primary_key } => vec![Evidence {
168                field: "record".to_string(),
169                value: format!("{store}/{primary_key}"),
170                location: Some(Location::Key(primary_key.clone())),
171            }],
172        }
173    }
174
175    /// Convert this observation into a canonical [`Finding`].
176    fn to_finding(&self, source: Source) -> Finding {
177        let mut builder = Finding::observation(self.severity(), self.category(), self.code())
178            .note(self.note())
179            .source(source);
180        for ev in self.evidence() {
181            builder = builder.evidence_item(ev);
182        }
183        for technique in self.mitre() {
184            builder = builder.mitre(*technique);
185        }
186        builder.build()
187    }
188}
189
190/// Build the [`Source`] stamped on every finding.
191fn source() -> Source {
192    Source {
193        analyzer: ANALYZER.to_string(),
194        scope: "IndexedDB".to_string(),
195        version: Some(env!("CARGO_PKG_VERSION").to_string()),
196    }
197}
198
199/// Classify one record into the observations it warrants.
200fn observe(record: &WireRecord) -> Vec<AnomalyKind> {
201    let mut out = Vec::new();
202
203    if record.deleted {
204        out.push(AnomalyKind::DeletedRecord {
205            store: record.store.clone(),
206            primary_key: record.primary_key.clone(),
207        });
208    }
209
210    if record
211        .primary_key
212        .to_ascii_lowercase()
213        .contains(OTR_KEY_NAME)
214    {
215        out.push(AnomalyKind::OtrKeyPresent {
216            store: record.store.clone(),
217            primary_key: record.primary_key.clone(),
218        });
219    }
220
221    match &record.payload {
222        PayloadState::Encrypted { .. } => out.push(AnomalyKind::EncryptedMessage {
223            conversation: record.conversation.clone(),
224            time: record.time.clone(),
225        }),
226        PayloadState::Cleartext if record.text.is_some() => {
227            out.push(AnomalyKind::CleartextMessage {
228                conversation: record.conversation.clone(),
229                sender: record.sender.clone(),
230                time: record.time.clone(),
231            });
232        }
233        _ => {}
234    }
235
236    out
237}
238
239/// Audit an interpreted Wire store, returning a canonical [`Finding`] for each
240/// observation.
241#[must_use]
242pub fn audit_store(store: &WireStore) -> Vec<Finding> {
243    let src = source();
244    store
245        .records
246        .iter()
247        .flat_map(observe)
248        .map(|a| a.to_finding(src.clone()))
249        .collect()
250}