HackBrowserData
On this page

FAQ & Troubleshooting

Common errors, platform caveats, safe data handling, and responsible-use guidance.

Answers are grouped by theme. Start with responsible use, then jump to your platform or the empty-results checklist.

Responsible use

Warning

HackBrowserData is a security-research and DFIR tool. With the default --category all, dump exports passwords, cookies, credit cards, browsing history, downloads, and other personal data. Only run it against systems and accounts you own or are explicitly authorized to examine.

If you do not need credential-bearing categories, narrow the scope:

terminal
# Exclude passwords, cookies, and credit cards
hack-browser-data dump --browser chrome --category history,bookmark,download

History, bookmarks, downloads, extensions, and storage are not credentials, but they can still be sensitive. Protect every export according to the data it contains. See About for the project’s license and disclaimer.

macOS: why does it ask for my login password?

Chromium browsers need their per-browser Safe Storage secret from the login Keychain. Safari passwords are also stored in the Keychain. When a selected browser needs Keychain access, HackBrowserData asks for the current macOS login password in the terminal, verifies it, and uses it to unlock the Keychain directly. The input is hidden.

For non-interactive use, pipe the password in with --keychain-pw-stdin, which reads the first line of stdin. --keychain-pw also works, but it exposes the password in shell history and process listings:

terminal
printf '%s\n' "$KEYCHAIN_PW" | hack-browser-data dump --browser chrome --keychain-pw-stdin

If direct unlock is unavailable, the tool may fall back to the macOS security command, which can display a Keychain access dialog. If no valid password or Keychain secret is available, records may still be exported with Keychain-protected fields blank. For Chromium-based browsers the run summary marks them partial (or error); Safari passwords are exported as metadata only under an ok row, so watch for the [WRN] line ending in keychain-protected data is exported as metadata only. Categories that do not require decryption can still succeed.

list does not retrieve keys and never asks for the login password. Firefox also does not use the macOS Keychain.

macOS: my Safari export is empty

Safari profile files require Full Disk Access. Grant it to the terminal app or binary running HackBrowserData, quit and reopen the terminal, then retry. See Safari → Grant Full Disk Access first.

Full Disk Access controls access to Safari’s files; the macOS login password controls access to Safari’s Keychain-backed passwords. You may need both.

Warning

Safari passwords may fail to export on macOS 26.4 or later. Run with --verbose to capture diagnostics, and do not assume a blank password field means the profile contains no saved login.

Windows: Chrome, Edge, or Brave cookies are blank

Chromium 127+ protects newer cookies with App-Bound Encryption (v20). The standard build cannot derive that key, so affected cookie values are blank. Use the Windows amd64 App-Bound Encryption build. ABE applies to Chrome, Chrome Beta, Edge, Brave, and CocCoc.

The Windows arm64 release is a standard build because the native ABE payload is currently amd64-only.

Linux: do I need a keyring?

It depends on the cipher tier present in the profile:

  • Chromium v10 uses the historical peanuts fallback and does not require a keyring.
  • Chromium v11 requires an accessible D-Bus Secret Service, such as GNOME Keyring or KDE Wallet.
  • Chromium v12, used by the Flatpak SecretPortal provider, is not implemented yet.

A profile can contain both v10 and v11 records. In a headless shell, container, or SSH session without a session bus, v10 may decrypt while v11 fields remain blank.

Why is Yandex data partially empty?

HackBrowserData supports Yandex’s Chromium data layout, including its password and credit-card formats. If Yandex Master Password is enabled, saved passwords and cards are still exported, but without their secrets — HackBrowserData does not prompt for or guess that password — and the run summary marks them partial. Cookies and the other requested categories export normally.

Where are my files, and what is the format?

Output goes to results/ by default (override with --dir), as one file per non-empty category (password.json, cookie.json, and so on). For the exact file model, ZIP behavior, permissions, timestamps, and field schemas, see Output & Data Formats.

What output formats exist?

Exactly three, via --format: json (default), csv, and cookie-editor. Any other value returns unsupported format. cookie-editor reshapes only the cookie category; every other requested category falls back to plain JSON, and all of those files keep the .json extension.

Is this malware? Why does antivirus flag it?

HackBrowserData decrypts locally stored browser secrets, behavior that credential-stealing malware also performs. Heuristic antivirus and EDR products may therefore flag the binary. Review the source, verify the release checksum, or build it yourself; never disable a security product unless your authorized procedure explicitly permits it.

How do I find a browser key or profile path?

Run list to print detected browser display names, profiles, and paths; add --detail for per-category counts:

terminal
hack-browser-data list --detail

The Browser column contains display names such as Chrome or Microsoft Edge, not necessarily the canonical CLI key. Use the key in Supported Browsers, such as chrome, edge, or opera-gx, with --browser.

To target a specific Chromium profile, find its directory via chrome://version (the Profile Path field) and pass it with --profile-path:

terminal
hack-browser-data dump --browser chrome --profile-path "/path/to/User Data/Profile 1"

Why is the result empty or incomplete?

Work through these checks in order:

  1. Read the run summary printed at the end: each row says whether a category was absent, unsupported, partial (with how many values were not recovered), or error, and why.
  2. Run hack-browser-data version and record the exact version, commit, and build date.
  3. Run hack-browser-data list --detail to confirm the browser and profile were detected.
  4. Check the canonical --browser key and, if needed, provide the exact profile with --profile-path.
  5. Close the browser so its databases and sidecar files are in a stable state, then retry.
  6. Run the same command with --verbose and inspect Keychain, DPAPI, D-Bus, file-access, and unsupported-cipher messages.
  7. Apply the platform notes above: Full Disk Access on Safari, Keychain access on macOS, the ABE build on Windows, or a D-Bus Secret Service for Linux v11.

If the problem remains, open a bug report(opens in a new tab) with the version output, OS version, browser version, command, and sanitized verbose logs.

Caution

Never attach keys.json, profile databases, output files, cookies, passwords, tokens, or unredacted paths to a public issue. For a suspected security vulnerability, do not open a public issue; report it privately through GitHub Security Advisories(opens in a new tab), or email me@moond4rk.com if you cannot use GitHub.

Cross-host: I have a copy of a profile but not the machine

Chromium master keys are bound to the origin host, so export them there and decrypt elsewhere. See Cross-Host Decryption for the Chromium-only dumpkeys → archive → restore workflow, including streaming keys over SSH. A copied profile without its matching keys is not enough to decrypt protected fields.

Known limitations

  • Safari on macOS 26.4 or later — passwords may fail to export.
  • Chromium v12 on Linux Flatpak — SecretPortal key derivation is not implemented; affected values export blank and are counted as not recovered in the run summary.
  • Firefox Primary Password — saved logins are exported without their usernames and passwords and marked partial; other Firefox categories export normally.
  • Yandex Master Password — saved passwords and cards are exported without their secrets and marked partial; the rest of the profile exports normally.
  • Windows ABE on arm64 — the native App-Bound Encryption payload is amd64-only.

Check GitHub Issues(opens in a new tab) for recently reported regressions and browser-version-specific gaps.