mirror of
https://github.com/mvt-project/mvt.git
synced 2026-09-03 08:30:51 +02:00
Add WhatsappContacts module to extract WhatsApp disappearing messages state
WhatsApp on iOS stores the disappearing messages timer for 1:1 chats on the contact records in ContactsV2.sqlite, not in ChatStorage.sqlite. Add a new WhatsappContacts module which extracts contact records from this database, including phone numbers, WhatsApp and LID identifiers, and the per-contact disappearing messages duration, and emits a timeline event when a disappearing messages timer was set. The database is often missing from incremental backups, so the module logs a clear warning and returns no results instead of failing. Columns are selected based on the actual table schema to tolerate changes across WhatsApp versions, and if the disappearing messages column is absent the state is reported as unknown rather than off. The test fixture is a synthetic ContactsV2.sqlite with fictional contacts, stored under the backup file ID derived from the WhatsApp shared app group domain.
This commit is contained in:
Donncha Ó Cearbhaill
@@ -421,3 +421,15 @@ This JSON file is created by mvt-ios' `WhatsApp` module. The module extracts a l
|
||||
|
||||
If indicators are provided through the command-line, they are checked against the extracted HTTP links. Any matches are stored in *whatsapp_detected.json*.
|
||||
|
||||
---
|
||||
|
||||
### `whatsapp_contacts.json`
|
||||
|
||||
!!! info "Availability"
|
||||
Backup: :material-check:
|
||||
Full filesystem dump: :material-check:
|
||||
|
||||
This JSON file is created by mvt-ios' `WhatsappContacts` module. The module extracts WhatsApp contact records from the SQLite database located at *private/var/mobile/Containers/Shared/AppGroup/\*/ContactsV2.sqlite*, including each contact's phone number, WhatsApp and LID identifiers, and the per-contact disappearing messages timer, which is not recorded in *ChatStorage.sqlite*. Contacts with a disappearing messages timer set produce a `disappearing_mode_set` event in the timeline.
|
||||
|
||||
This database is often missing from incremental backups. When it cannot be found, the module logs a warning and produces no results, in which case the disappearing messages state of chats cannot be determined from the backup.
|
||||
|
||||
|
||||
@@ -26,6 +26,7 @@ from .tcc import TCC
|
||||
from .webkit_resource_load_statistics import WebkitResourceLoadStatistics
|
||||
from .webkit_session_resource_log import WebkitSessionResourceLog
|
||||
from .whatsapp import Whatsapp
|
||||
from .whatsapp_contacts import WhatsappContacts
|
||||
|
||||
MIXED_MODULES = [
|
||||
Calls,
|
||||
@@ -47,6 +48,7 @@ MIXED_MODULES = [
|
||||
WebkitResourceLoadStatistics,
|
||||
WebkitSessionResourceLog,
|
||||
Whatsapp,
|
||||
WhatsappContacts,
|
||||
Shortcuts,
|
||||
Applications,
|
||||
Calendar,
|
||||
|
||||
@@ -0,0 +1,262 @@
|
||||
# Mobile Verification Toolkit (MVT)
|
||||
# Copyright (c) 2021-2026 The MVT Authors.
|
||||
# Use of this software is governed by the MVT License 1.1 that can be found at
|
||||
# https://license.mvt.re/1.1/
|
||||
|
||||
import logging
|
||||
import sqlite3
|
||||
from typing import Optional
|
||||
|
||||
from mvt.common.module import DatabaseNotFoundError
|
||||
from mvt.common.module_types import (
|
||||
ModuleAtomicResult,
|
||||
ModuleResults,
|
||||
ModuleSerializedResult,
|
||||
)
|
||||
from mvt.common.utils import convert_mactime_to_iso
|
||||
|
||||
from ..base import IOSExtraction
|
||||
|
||||
WHATSAPP_CONTACTS_BACKUP_IDS = [
|
||||
# SHA-1 of "AppDomainGroup-group.net.whatsapp.WhatsApp.shared-ContactsV2.sqlite"
|
||||
"b8548dc30aa1030df0ce18ef08b882cf7ab5212f",
|
||||
]
|
||||
WHATSAPP_CONTACTS_ROOT_PATHS = [
|
||||
"private/var/mobile/Containers/Shared/AppGroup/*/ContactsV2.sqlite",
|
||||
]
|
||||
|
||||
# WhatsApp's standard disappearing-messages timer values, in seconds.
|
||||
DISAPPEARING_DURATION_LABELS = {
|
||||
86400: "24 hours",
|
||||
604800: "7 days",
|
||||
1209600: "14 days",
|
||||
2592000: "30 days",
|
||||
7776000: "90 days",
|
||||
}
|
||||
|
||||
# Output field -> candidate columns in ZWAADDRESSBOOKCONTACT, in order of
|
||||
# preference. WhatsApp renames columns across versions, so the query is built
|
||||
# from the columns actually present in the database.
|
||||
COLUMN_CANDIDATES = {
|
||||
"whatsapp_id": ["ZWHATSAPPID"],
|
||||
"lid": ["ZLID"],
|
||||
"phone_number": ["ZPHONENUMBER"],
|
||||
"localized_phone_number": ["ZLOCALIZEDPHONENUMBER"],
|
||||
"full_name": ["ZFULLNAME"],
|
||||
"given_name": ["ZGIVENNAME"],
|
||||
"last_name": ["ZLASTNAME"],
|
||||
"user_name": ["ZUSERNAME"],
|
||||
"business_name": ["ZBUSINESSNAME"],
|
||||
"about_text": ["ZABOUTTEXT"],
|
||||
"about_emoji": ["ZABOUTEMOJI"],
|
||||
"notes": ["ZNOTES"],
|
||||
"disappearing_mode_duration": ["ZDISAPPEARINGMODEDURATION"],
|
||||
"disappearing_mode_timestamp": ["ZDISAPPEARINGMODETIMESTAMP"],
|
||||
"about_timestamp": ["ZABOUTTIMESTAMP"],
|
||||
"last_updated": ["ZLASTUPDATED"],
|
||||
"phone_status": ["ZPHONESTATUS", "ZPHONENUMBERSTATUS"],
|
||||
"sync_policy": ["ZSYNCPOLICY"],
|
||||
}
|
||||
|
||||
STRING_FIELDS = [
|
||||
"whatsapp_id",
|
||||
"lid",
|
||||
"phone_number",
|
||||
"localized_phone_number",
|
||||
"full_name",
|
||||
"given_name",
|
||||
"last_name",
|
||||
"user_name",
|
||||
"business_name",
|
||||
"about_text",
|
||||
"about_emoji",
|
||||
"notes",
|
||||
]
|
||||
|
||||
DATE_FIELDS = [
|
||||
"disappearing_mode_timestamp",
|
||||
"about_timestamp",
|
||||
"last_updated",
|
||||
]
|
||||
|
||||
|
||||
def _decode_string(value) -> Optional[str]:
|
||||
# CoreData stores string attributes as UTF-8 blobs in some WhatsApp
|
||||
# versions, so values can arrive as either bytes or str.
|
||||
if value is None:
|
||||
return None
|
||||
if isinstance(value, bytes):
|
||||
return value.decode("utf-8", "replace")
|
||||
return str(value)
|
||||
|
||||
|
||||
def _label_duration(duration) -> str:
|
||||
if not duration:
|
||||
return "off"
|
||||
return DISAPPEARING_DURATION_LABELS.get(
|
||||
int(duration), f"{int(duration)} seconds"
|
||||
)
|
||||
|
||||
|
||||
class WhatsappContacts(IOSExtraction):
|
||||
"""This module extracts WhatsApp contact records and per-contact
|
||||
disappearing-messages settings from ContactsV2.sqlite.
|
||||
|
||||
ChatStorage.sqlite does not record the disappearing-messages state of 1:1
|
||||
chats: the authoritative timer is stored on each contact record in this
|
||||
database, alongside the mapping between a contact's LID and phone number
|
||||
identifiers.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
file_path: Optional[str] = None,
|
||||
target_path: Optional[str] = None,
|
||||
results_path: Optional[str] = None,
|
||||
module_options: Optional[dict] = None,
|
||||
log: logging.Logger = logging.getLogger(__name__),
|
||||
results: Optional[ModuleResults] = None,
|
||||
) -> None:
|
||||
super().__init__(
|
||||
file_path=file_path,
|
||||
target_path=target_path,
|
||||
results_path=results_path,
|
||||
module_options=module_options,
|
||||
log=log,
|
||||
results=results,
|
||||
)
|
||||
|
||||
def serialize(self, record: ModuleAtomicResult) -> ModuleSerializedResult:
|
||||
timestamp = record.get("disappearing_mode_timestamp")
|
||||
if not timestamp:
|
||||
return {}
|
||||
|
||||
contact = (
|
||||
record.get("whatsapp_id")
|
||||
or record.get("lid")
|
||||
or record.get("phone_number")
|
||||
or "unknown"
|
||||
)
|
||||
data = (
|
||||
f"WhatsApp disappearing messages timer set to "
|
||||
f"'{record.get('disappearing_mode_label')}' for {contact}"
|
||||
)
|
||||
full_name = record.get("full_name")
|
||||
if full_name:
|
||||
data += f" ({full_name})"
|
||||
|
||||
return {
|
||||
"timestamp": timestamp,
|
||||
"module": self.__class__.__name__,
|
||||
"event": "disappearing_mode_set",
|
||||
"data": data,
|
||||
}
|
||||
|
||||
def run(self) -> None:
|
||||
try:
|
||||
self._find_ios_database(
|
||||
backup_ids=WHATSAPP_CONTACTS_BACKUP_IDS,
|
||||
root_paths=WHATSAPP_CONTACTS_ROOT_PATHS,
|
||||
)
|
||||
except DatabaseNotFoundError:
|
||||
self.log.warning(
|
||||
"Unable to find the WhatsApp ContactsV2.sqlite database in "
|
||||
"this backup or filesystem dump. WhatsApp disappearing "
|
||||
"messages settings and contact records cannot be extracted. "
|
||||
"This database is often missing from incremental backups."
|
||||
)
|
||||
return
|
||||
|
||||
self.log.info(
|
||||
"Found WhatsApp contacts database at path: %s", self.file_path
|
||||
)
|
||||
|
||||
assert self.file_path is not None
|
||||
conn = self._open_sqlite_db(self.file_path)
|
||||
cur = conn.cursor()
|
||||
try:
|
||||
try:
|
||||
cur.execute("PRAGMA table_info(ZWAADDRESSBOOKCONTACT)")
|
||||
available_columns = {row[1] for row in cur.fetchall()}
|
||||
except sqlite3.DatabaseError as exc:
|
||||
self.log.error(
|
||||
"Unable to read the ZWAADDRESSBOOKCONTACT table schema: %s",
|
||||
exc,
|
||||
)
|
||||
return
|
||||
|
||||
if not available_columns:
|
||||
self.log.warning(
|
||||
"The WhatsApp contacts database does not contain a "
|
||||
"ZWAADDRESSBOOKCONTACT table"
|
||||
)
|
||||
return
|
||||
|
||||
selected = {}
|
||||
for field, candidates in COLUMN_CANDIDATES.items():
|
||||
for candidate in candidates:
|
||||
if candidate in available_columns:
|
||||
selected[field] = candidate
|
||||
break
|
||||
|
||||
# A record with no duration column is "unknown", not "off": the
|
||||
# timer state cannot be determined from this database version.
|
||||
has_duration = "disappearing_mode_duration" in selected
|
||||
if not has_duration:
|
||||
self.log.warning(
|
||||
"The ZDISAPPEARINGMODEDURATION column is not present in "
|
||||
"this WhatsApp contacts database: disappearing messages "
|
||||
"state is unknown"
|
||||
)
|
||||
|
||||
columns = ["Z_PK"] + list(selected.values())
|
||||
cur.execute(
|
||||
f"SELECT {', '.join(columns)} FROM ZWAADDRESSBOOKCONTACT;"
|
||||
)
|
||||
fields = ["row_pk"] + list(selected.keys())
|
||||
|
||||
for row in cur:
|
||||
record = dict(zip(fields, row))
|
||||
|
||||
for field in STRING_FIELDS:
|
||||
if field in record:
|
||||
record[field] = _decode_string(record[field])
|
||||
else:
|
||||
record[field] = None
|
||||
|
||||
for field in DATE_FIELDS:
|
||||
if record.get(field) is not None:
|
||||
record[field] = (
|
||||
convert_mactime_to_iso(record[field]) or None
|
||||
)
|
||||
else:
|
||||
record[field] = None
|
||||
|
||||
duration = record.get("disappearing_mode_duration")
|
||||
if has_duration:
|
||||
record["disappearing_mode_is_on"] = bool(duration)
|
||||
record["disappearing_mode_label"] = _label_duration(
|
||||
duration
|
||||
)
|
||||
else:
|
||||
record["disappearing_mode_duration"] = None
|
||||
record["disappearing_mode_is_on"] = None
|
||||
record["disappearing_mode_label"] = None
|
||||
|
||||
record.setdefault("phone_status", None)
|
||||
record.setdefault("sync_policy", None)
|
||||
|
||||
self.results.append(record)
|
||||
finally:
|
||||
cur.close()
|
||||
conn.close()
|
||||
|
||||
total_ephemeral = sum(
|
||||
1 for record in self.results if record["disappearing_mode_is_on"]
|
||||
)
|
||||
self.log.info(
|
||||
"Extracted a total of %d WhatsApp contacts (%d with disappearing "
|
||||
"messages enabled)",
|
||||
len(self.results),
|
||||
total_ephemeral,
|
||||
)
|
||||
Binary file not shown.
@@ -0,0 +1,49 @@
|
||||
# Mobile Verification Toolkit (MVT)
|
||||
# Copyright (c) 2021-2026 The MVT Authors.
|
||||
# Use of this software is governed by the MVT License 1.1 that can be found at
|
||||
# https://license.mvt.re/1.1/
|
||||
|
||||
from mvt.common.module import run_module
|
||||
from mvt.ios.modules.mixed.whatsapp_contacts import WhatsappContacts
|
||||
|
||||
from ..utils import get_ios_backup_folder
|
||||
|
||||
|
||||
class TestWhatsappContactsModule:
|
||||
def test_extraction(self):
|
||||
m = WhatsappContacts(target_path=get_ios_backup_folder())
|
||||
run_module(m)
|
||||
assert len(m.results) == 2
|
||||
|
||||
alice = next(r for r in m.results if r["given_name"] == "Alice")
|
||||
assert alice["full_name"] == "Alice Example"
|
||||
assert alice["phone_number"] == "+14155550100"
|
||||
assert alice["whatsapp_id"] == "14155550100@s.whatsapp.net"
|
||||
assert alice["lid"] == "100000000000001@lid"
|
||||
assert alice["user_name"] == "alice.example"
|
||||
assert alice["disappearing_mode_duration"] == 86400.0
|
||||
assert alice["disappearing_mode_is_on"] is True
|
||||
assert alice["disappearing_mode_label"] == "24 hours"
|
||||
assert alice["disappearing_mode_timestamp"] == "2025-07-23 21:46:40.000000"
|
||||
assert alice["last_updated"] == "2025-08-04 11:33:20.000000"
|
||||
|
||||
bob = next(r for r in m.results if r["given_name"] == "Bob")
|
||||
assert bob["lid"] is None
|
||||
assert bob["disappearing_mode_duration"] is None
|
||||
assert bob["disappearing_mode_is_on"] is False
|
||||
assert bob["disappearing_mode_label"] == "off"
|
||||
assert bob["disappearing_mode_timestamp"] is None
|
||||
|
||||
assert len(m.timeline) == 1
|
||||
assert m.timeline[0]["event"] == "disappearing_mode_set"
|
||||
assert m.timeline[0]["timestamp"] == "2025-07-23 21:46:40.000000"
|
||||
assert "24 hours" in m.timeline[0]["data"]
|
||||
assert "14155550100@s.whatsapp.net" in m.timeline[0]["data"]
|
||||
|
||||
assert len(m.alertstore.alerts) == 0
|
||||
|
||||
def test_missing_database(self, tmp_path):
|
||||
m = WhatsappContacts(target_path=str(tmp_path))
|
||||
run_module(m)
|
||||
assert m.results == []
|
||||
assert len(m.alertstore.alerts) == 0
|
||||
@@ -15,8 +15,8 @@ class TestFilesystem:
|
||||
def test_filesystem(self):
|
||||
m = Filesystem(target_path=get_ios_backup_folder())
|
||||
run_module(m)
|
||||
assert len(m.results) == 15
|
||||
assert len(m.timeline) == 15
|
||||
assert len(m.results) == 17
|
||||
assert len(m.timeline) == 17
|
||||
assert len(m.alertstore.alerts) == 0
|
||||
|
||||
def test_detection(self, indicator_file):
|
||||
@@ -29,6 +29,6 @@ class TestFilesystem:
|
||||
)
|
||||
m.indicators = ind
|
||||
run_module(m)
|
||||
assert len(m.results) == 15
|
||||
assert len(m.timeline) == 15
|
||||
assert len(m.results) == 17
|
||||
assert len(m.timeline) == 17
|
||||
assert len(m.alertstore.alerts) == 1
|
||||
|
||||
Reference in New Issue
Block a user