Phone records and device forensics
Viokit brings phone records, forensic extraction reports and device histories you already hold into a case beside OSINT and internal datasets, and reads SIM swaps, call patterns and co-location out of them, in the spirit of i2 Analyst's Notebook.
Scope. Importers only, for material you lawfully hold: provider returns to a production order or other legal process, forensic tool exports from a lawful examination, internal datasets. Nothing here probes a device, a network or an operator. There is no interception, no IMSI-catcher and no live location feature, and there will not be.
Lawful basis and data protection
Phone records are personal data, often of people who are not suspects (everyone a target called).
- Purpose gate. Importing records is refused until the case has a recorded purpose and lawful basis (declare it in the console's “Before you look up people” panel; see People investigations). A cell site list is exempt: it describes masts, not people.
- Authority. Hold the authority the material was obtained under (production order, warrant, RIPA / IPA authorisation, consent, contract) and import only what it covers. Viokit records what you state; it does not judge the basis. You are the controller.
- Minimise. Message bodies in an extraction report are not written to the graph; only who, when and how long (and, for a database import, how long the text was). Keeping the text is a separate, ticked option with a warning, and so is keeping device-reported positions; both are recorded in the custody record's options. Import the date range the authority covers.
- Retention, erasure and restriction apply as for any personal data in the case.
Chain of custody
Every import keeps two items in the evidence store, both identified by their SHA-256: the file exactly as supplied, and a custody record. The custody record holds the exhibit reference, file name, format, source description, who handed it over, who imported it, when, the file's SHA-256, the import options (default country, subscriber, column mapping, day-first, UTC offset), counts and the number of rows that could not be read.
Every step the import writes cites both, so any number, call or SIM on the graph traces back to the exhibit. The stored bytes can be re-hashed to check them. Re-importing a file re-asserts the same events rather than duplicating them.
Formats
Format (format) |
What it reads |
|---|---|
cdr |
Call data records and phone bills, CSV (save XLSX as CSV). Comma, semicolon, tab or pipe. |
forensic-csv |
Call and message sheets from Oxygen, XRY or AXIOM: type, direction, time, duration, other party. |
ufdr |
Cellebrite report.xml (also inside a .ufdr once unzipped): device info, contacts, calls, SMS, chat messages, SIM data (ICCID, IMSI, MSISDN), Wi-Fi networks, Bluetooth devices. |
usb-setupapi |
Windows setupapi.dev.log: each USB device's first install, merging USB\VID_…&PID_… and USBSTOR\… lines by serial. |
usb-csv |
A registry tool's USBSTOR / USB / MountedDevices CSV: vendor and product id, serial, name, first and last connection. |
cell-sites |
A cell list: MCC, MNC, LAC/TAC, cell id (decimal or hex), latitude, longitude, azimuth, address, range. |
ios-backup |
An unencrypted iTunes / Finder backup folder: device details, calls, messages, contacts. See Device extraction files. |
bluetooth-wifi |
Android bt_config.conf (paired Bluetooth devices) and WifiConfigStore.xml (saved Wi-Fi networks). See Device extraction files. |
location-history |
Google Takeout Records.json, Semantic Location History months and the on-device Timeline.json: device-reported positions, only when asked for. See Device-reported locations. |
email |
.eml files and mbox archives you hold. See Email and chat exports. |
android-db |
SQLite databases from an Android logical extraction: contacts, call log, SMS, accounts. See Device extraction files. |
Device extraction files
These formats read files you already hold from a lawful extraction. Nothing connects to a device, unlocks it or gets round a protection: if the files are encrypted or locked, they are not read. Each file is kept as its own evidence item (SHA-256) beside one custody record that lists every file. Databases are opened read-only and without applying a write-ahead log, so rows not yet checkpointed are not seen. A file is recognised by the tables it holds, not by its name; one that is not a database, or holds none of the expected tables, is named in the warnings.
| File | Where it comes from | What is imported | Limits |
|---|---|---|---|
contacts2.db |
/data/data/com.android.providers.contacts/databases/ in a logical or file-system extraction |
raw_contacts + data + mimetypes: each contact's name, phone numbers (E.164) and email addresses (associated with the card's numbers); deleted contacts skipped |
Only phone and email rows; addresses, notes and photos are not read. Numbers it cannot place are warned about. |
calllog.db (or the calls table of an older contacts2.db) |
…/com.android.providers.contacts/databases/ |
calls: number, date (ms), duration, type (incoming, outgoing, missed, voicemail, rejected, blocked) as calls; the owner is the number you give as “whose records” |
No number means no call on the graph (withheld caller), counted in the warnings. SIM slot and cell data are not read. |
mmssms.db |
…/com.android.providers.telephony/databases/ |
sms: address, date, direction and the length of the text as messages; the text itself only if you tick the option to keep message text |
MMS (pdu, part) and chat apps are not read. Short codes and sender names are warned about, not guessed. |
accounts.db (accounts_ce.db, accounts_de.db) |
/data/system_ce/0/ or /data/system/users/0/ |
accounts: each account as an online account (google:alice@example.com) linked to the device, and to its email address when the name is one |
Passwords and tokens are never read. The service name is derived from the account type (com.google becomes google). |
iOS backup (ios-backup). Pick the backup folder in the wizard (or the files themselves). The wizard
reads Info.plist and Manifest.db first; the manifest says which hash-named files are the call history,
messages and address book, and only those are read and sent. Plists are read in XML or binary form.
| File | What is imported | Limits |
|---|---|---|
Info.plist |
The device: IMEI, ICCID, phone number, serial number, model (Product Type), name; a SIM record at the backup date. Becomes the device the others attach to, linked from the phone number. |
One SIM record only, so a SIM change needs a second backup. |
Manifest.db |
Finds Library/CallHistoryDB/CallHistory.storedata, Library/SMS/sms.db and Library/AddressBook/AddressBook.sqlitedb in HomeDomain. |
An encrypted backup has an unreadable manifest: it is reported, never opened or guessed at. |
CallHistory.storedata |
ZCALLRECORD: number, date, duration, direction as calls. |
FaceTime and other call kinds are read as calls; no cell data exists on iOS. |
sms.db |
message + handle: date, direction and text length as messages; text only if you tick the option to keep message text. |
Handles that are email addresses, group chats or names are counted in one warning, not imported. Messages whose text is only in attributedBody (newer iOS) have no length. |
AddressBook.sqlitedb |
ABPerson + ABMultiValue: name or organisation, numbers, emails. |
Only phone and email values. |
Bluetooth and Wi-Fi (bluetooth-wifi). Either file, or both together; each is recognised by its
content.
| File | Where it comes from | What is imported | Limits |
|---|---|---|---|
bt_config.conf |
/data/misc/bluedroid/ (older Android) |
The adapter's own address (the handset's identity when nothing else names it) and each paired device's MAC, name and, when the file has one, Timestamp: each paired device is recorded as connected to the handset over Bluetooth, with a connection event per timestamp |
Link keys and other secrets are never read. Without a timestamp the pairing has no date. Newer Android keeps this elsewhere or in a different layout; such a file is reported as not readable. |
WifiConfigStore.xml |
/data/misc/wifi/ (or /data/misc/apexdata/com.android.wifi/) |
Each saved network: SSID (quoted or hex) as the device's name, BSSID when present as its MAC, recorded as connected to the handset over Wi-Fi, with a connection event when a last-connected time is stored | Pre-shared keys and credentials are never read. A saved network is a network the handset joined at some time, not proof it was there on any date. Many stores print no times and no BSSID. |
A device the files do not identify is named after the exhibit ("Device in exhibit EXH/ABC/1"); give a device name in the wizard to label it yourself, and the handset's own number as "whose records".
Email and chat exports
Email and chat exports you already hold. Each file is kept as its own evidence item beside one custody record. The readers are bounded: a file over 256 MiB is not read; at most 100,000 messages (email) per import; headers cut at 256 KiB per message, 1,000 header fields, 16 KiB per header value, 1,000 addresses per header, 100 Received hops; multipart bodies at 8 levels and 500 parts, bodies at 100,000 characters, 100 attachment names. Every cut is a warning, never a silent loss. Messages and chat lines are recorded as messages on email, WhatsApp or Telegram, kept out of the phone findings (which are about numbers) and read by the contact analysis below.
| Format | File | What is imported | Limits |
|---|---|---|---|
email |
.eml files, or an mbox / mboxrd archive |
Headers only by default: From, To, Cc, Bcc, Date, Message-ID, In-Reply-To, Subject. Each message is recorded with its sender and recipients (to / cc / bcc), each an email address (display name kept as the contact name). The Received chain and X-Originating-IP give sending IP addresses, marked as a relay (hop 1 is the oldest) or the origin. Threads are rebuilt from Message-ID / In-Reply-To / References. RFC 2047 encoded words and folded headers are decoded. |
A message with no readable Date is skipped and named. Private, loopback and link-local relay addresses are not imported (counted in a warning). A hop is what the receiving server logged and is easily forged below the first trusted relay. Bodies and attachment names only if you tick the option to keep message text (warning in the wizard); without it only the body's length is kept. |
whatsapp-chat |
_chat.txt from “Export chat” (iOS [08/03/2024, 14:05:33] Sam: text, Android 08/03/2024, 14:05 - Sam: text), sent as text |
Each text message is recorded from its sender, with the chat named from the file name (WhatsApp Chat with X.txt). Participants are named as the export shows them; a name that is a phone number becomes a phone number. In a two-person chat the other person is the recipient; in a group only the sender is linked (the export does not list who was present). 12 or 24 hour; the date order is detected (a day above 12 settles it), else day first is used and a warning says so; times are read at the UTC offset you give. Media placeholders (<Media omitted>, image omitted, <attached: …>) are counted, not imported; system lines (encryption notice, added / left / changed subject) are skipped. |
Only text messages count towards contact. Chat exports do not say which participant is the exporter. A name is not an identity: two people of one name in a group are one. Lines over 20,000 characters are cut; 500,000 messages and 5,000,000 lines per import. Text only if you tick the option to keep message text. |
telegram-json |
Telegram Desktop result.json (“Export Telegram data”, JSON), the whole account or a single chat, sent as text |
Chats and messages: each text message is recorded with the chat's name, and replies are linked. Participants are Telegram accounts (by user id, the name as shown); the exporting account is read from personal_information and linked to its phone number when the export gives one. In a one-to-one chat the message has a direction and the other account as recipient; in groups and channels only the sender is linked. Times come from date_unixtime (UTC), else the printed date at the UTC offset you give. Service messages are skipped; media-only messages are counted, not imported. |
Only text messages count towards contact. Secret chats are not in the export. Edited and deleted messages show only their last state. Text only if you tick the option to keep message text; 500,000 messages and 10,000 chats per import; text entity arrays joined to 20,000 characters. |
Contact across channels
The phone analysis also covers contact across channels: calls, SMS, email and chats read back from the case. One person is the set of numbers, addresses, accounts and persons the case links; a chat participant who is only a name is matched to a contact name when exactly one contact has it, and is marked “matched by name only”. It gives, per person: contacts per channel, first and last contact; periods of quiet (default 30 days: a gap between two contacts, or “went quiet” when a person with three or more contacts has none in the 30 days before the last record held); and contacts two of the most active people have in common. The person in nearly every record (80% or more, and clearly the busiest) is marked as probably whose records these are and left out of the quiet and common lists. The date and time window applies. Contact is not content: it says who was in touch and when, nothing of what was said.
Message content is personal data of everyone in it. Erasing a party withholds their links and replaces the message's subject, text, attachment names, chat name and thread ids with "content withheld (erasure)"; the message keeps its time, channel and the other parties. Sending-IP entities stay on the message (network data, not content). Restricting a person leaves their messages out of the contact analysis, and the subject access export lists them.
Device-reported locations
Google location history you already hold can be read from a Takeout export (or the on-device Timeline export). It is the most revealing data this importer reads, so it is off by default: without “Keep positions the device reported” nothing is written and the preview and warnings say how many positions the file held.
| File | What is imported | Limits |
|---|---|---|
Records.json |
Each locations entry with a time and coordinates: latitude and longitude, accuracy in metres, source (GPS, WIFI, CELL) and device tag |
Entries with impossible coordinates or no time are skipped. |
Semantic Location History/<year>/<year>_<MONTH>.json |
Each place visit's start and each activity segment's start and end as points | The file's place names, addresses and activity labels are not taken: no address is read or resolved. |
Timeline.json (on-device export) |
Visit locations and path points, with latLng or geo: coordinates |
Layout varies by app version; a file of another shape is named in the warnings. |
Each point is recorded at the reported coordinates and time, linked to the device that reported it, with its source, accuracy and the sentence “Device-reported position (…), approximate; not a verified location”. It shows where the device said it was, to the accuracy it gave: not where a person was, and not a route. Erasing the device withholds its position events (only it reported them), and restricting the person who holds it keeps them out of the phone analysis.
Apple's privacy export has no documented location-history file this importer is built to; none is read. Message text and positions are personal data of the people in them: the options are recorded in the custody record. Erasing one party withholds their links to a message and the message's text, replaced by "content withheld (erasure)"; the message keeps its time, direction and the other party. The extraction file itself stays in the store (never deleted for one person), redacted from exports, and the erasure record lists the record ids taken out. Keep bodies and positions off unless the case needs them. See Retention, erasure and restriction for what erasure does and does not remove.
Column mapping. For CSV formats the preview shows the headers, a guess at which column means what and the first rows; the console's wizard shows the guess for you to correct. Fields: date and time, date, time, duration, calling, called, subscriber, other party, direction, type, IMEI, IMSI, ICCID, CGI, MCC, MNC, LAC, cell id, cell address, latitude, longitude, azimuth, range. A file with calling/called columns is read as is; a file with only “other party” and direction needs the number the records belong to (the subscriber). Always give the subscriber for a target's return: it is how the handset and SIM on each row are attributed to the right number.
Numbers are normalised to E.164 with the default country (GB, US, FR, … 22 countries): +,
00, 011 from North America, the calling code without a plus, or a national number with its trunk
prefix. Anything else (short codes, numbers with no country) is refused and the row warned about, not
guessed at.
Times without a zone are read at the stated UTC offset (default UTC); dates are read day first by default, so 02/03/2024 is 2 March. setupapi times are the computer's local time.
What goes on the graph
- Each phone number, device (handset, USB device, paired device or computer), SIM card and cell site becomes an item in the case; cell sites are placed at the mast when the record or a cell list gives it. Each call, message or data session becomes an event with its parties and the cell, duration, direction and the IMEI/IMSI/ICCID of the row. Viokit also links a number to its handset, a SIM to its handset and number over the period the records show, and a USB or paired device to its host, and records a SIM-change event for each SIM or handset change the file itself shows.
What each finding means
Each finding is a plain sentence, a probability-yardstick term with its band, what it cannot tell you, and the records behind it. None is stated as certain: records show a pattern, not a reason.
| Finding | Means | Limits |
|---|---|---|
| SIM changed / Handset changed | The ICCID (else IMSI) or IMEI serving a number differs from the one seen before: "SIM changed on +44… on 2 March 2024 14:05 UTC: ICCID …0001 → …0002". | An upgrade, a lost phone and a fraudulent SIM swap look alike. |
| Rapid SIM changes | Two SIM changes on one number within 7 days. Realistic possibility of deliberate swapping. | As above. |
| Unusual activity after a change | Within 48 hours of a change, 3+ numbers never contacted before, or a burst of messages (10+, 3× the earlier rate). | A genuine new phone looks the same. |
| One SIM in many handsets | A SIM seen in 3+ handsets. | Work phones and repairs move SIMs too. |
| Many SIMs in one handset | A handset with 3+ SIMs: likely SIM rotation ("burner rotation"). | Travellers and dual-SIM phones. |
| Dormant, then active | No records for 14+ days, then activity. | The gap may be in what was obtained, not silence. |
| Contact chain | A → B then B → C within 60 minutes. | Coincidence in a busy network. |
| Common contact | A number every one of the given numbers was in contact with. | A business or service number. |
| Possibly together | Two numbers on the same cell, or cells within 1 km, within 30 minutes. | Cells cover hundreds of metres in town and kilometres in the country, and a handset uses the best-serving cell, not the nearest. This places them in the same area at most. |
The analysis also returns top contacts per number (count, duration, first and last contact), records per ISO week, IMSIs per handset and handsets per SIM, the contact matrix (pairs, counts, seconds) and numbers also seen in other cases you may open.
Which side of a record a cell, IMEI or IMSI belongs to: the subscriber (the caller for outgoing, the callee for incoming). Records without a direction are attributed to the calling party.
In the console
The steps are in the guide: Import records and Find SIM swaps and call patterns.
Limits
- Fixtures are invented and shaped after the published formats; real exports vary by tool version and provider. Check the preview, and report a format that reads wrongly.
- XLSX is not read directly: save as CSV.
- The E.164 normaliser holds a calling code and trunk prefix per country, not a full numbering plan.
- Large returns are imported row by row; tens of thousands of rows take a while.
- Row numbers in warnings count the file's non-blank lines after the header.