How It Works

A short tour of what hack-browser-data does under the hood: one pipeline from checking flags to the run summary.

A short tour of what hack-browser-data does when you run it — enough to use the tool well and to make sense of partial results. For the commands, see the CLI reference; for the output schema, Output & Data Formats.

At a high level, every run follows the same path:

validate flags
   → discover browsers + profiles
   → plan which files each category needs
   → capture those files into an isolated temp directory
   → extract each category, decrypting where needed
   → export one file per data category
   → report a summary

#One pipeline for every browser

dump and restore run all seven stages, and they run them the same way for Chromium-based browsers, Firefox, and Safari — only the readers and the key handling differ. archive stops after capturing and zips the copies instead of decrypting them; list --detail extracts only to count, without retrieving any OS key.

The tool copies first, then reads — it never touches the browser’s live files in place, which may be locked or changing. The temporary copies are removed when the run ends, including when you stop it with Ctrl-C.

#What’s encrypted, and what isn’t

Most browser data is plaintext. For Chromium, only 3 of the 9 categories are encrypted and need the master key:

This is why a run can partly succeed: if a master key cannot be retrieved, the encrypted categories are still exported with blank values while the six plaintext categories continue normally. Problems are reported, not fatal — the summary shows a category with no data as absent, an unreadable file as error, values that could not be decrypted as partial with N not recovered, and a failed key retrieval as its own error row.

#Cipher tiers at a glance

Each encrypted value carries a 3-byte prefix that picks the cipher and where its key comes from. You rarely need this — except for the two troubleshooting cases below.

• v20 cookies come back empty on Windows? You’re on the standard build — use the Windows App-Bound Encryption build.
• Blank fields from a Flatpak profile? Chromium’s v12 SecretPortal provider is not implemented yet, so those values export blank. The summary marks the category partial with N not recovered, and --verbose logs each failure.

Keys come from DPAPI on Windows, the login Keychain on macOS (each browser’s Safe Storage item), and either a fixed v10 fallback or the D-Bus Secret Service for v11 on Linux. On macOS, the tool asks for the current login password when the selected browser needs Keychain access; a system Keychain dialog may appear as a fallback. See the macOS FAQ.

#Export model

Results are aggregated across all profiles into one file per non-empty category. See Output & Data Formats for the file model and the per-category schema.

#Cross-host decryption

For Chromium-based browsers, key retrieval and file copying are separate steps. You can export keys on the origin host and restore the matching profile data on another supported OS — even when that browser cannot be installed on the analyst system. See Cross-Host Decryption for the dumpkeys → archive → restore workflow.

#Firefox, Safari, and Yandex

The pipeline is the same for every engine; what differs is where the key comes from:

• Firefox — per-profile key derived from key4.db (NSS); no OS keychain.
• Safari — macOS-only, Keychain-backed passwords, needs Full Disk Access. Safari passwords may fail to export on macOS 26.4 or later.
• Yandex — a Chromium fork with its own password and credit-card formats. With a Yandex Master Password set, saved passwords and cards are still exported without their secrets and marked partial; cookies and other categories export normally.

For per-browser coverage, see Supported Browsers.