HackBrowserData

repository·main·Indexed 12 days ago

https://github.com/moond4rk/hackbrowserdata

A specialized CLI tool for security researchers to extract and decrypt sensitive data—including passwords, cookies, bookmarks, history, and credit cards—from various web browsers across Windows, macOS, and Linux. It supports Chromium-based browsers, Firefox, and Safari, and features cross-host decryption capabilities allowing analysts to export master keys and profile files from an origin host to decrypt data offline on a different system.

Tokens
22.9K
Snippets
47
Records
117
Agent score
92%

What's inside HackBrowserData

  1. Overview of HackBrowserData

    main

    HackBrowserData is a command-line tool designed for security research to decrypt and export browser data. It supports extracting passwords, cookies, bookmarks, history, downloads, credit cards, extensions, LocalStorage, and SessionStorage from various browsers.

    Key capabilities include:

    • Cross-platform support: Works on Windows, macOS, and Linux.
    • Cross-host decryption: You can export master keys from an origin host and decrypt data offline on a different host or operating system, even for browsers not natively supported by the analyst's OS.
  2. Project constraints and architecture overview

    main

    HackBrowserData is a CLI security research tool designed for extracting and decrypting browser data (Chromium, Firefox, Safari) across Windows, macOS, and Linux.

    Key Technical Constraints

    • Go 1.20: The project is pinned to Go 1.20 to maintain compatibility with Windows 7. Do not use features from Go 1.21+ (e.g., log/slog, slices, maps, cmp).
    • No Public Library API: The project is designed as a CLI tool. There is no importable pkg/ surface; the CLI interacts directly with the browser package.
    • Supported Engines: Chromium (including Yandex and Opera), Firefox, and Safari.
    • Supported Platforms: Windows (DPAPI), macOS (Keychain), and Linux (D-Bus Secret Service).

    Directory Structure

    • cmd/hack-browser-data/: CLI entrypoints (cobra).
    • browser/: Browser interfaces and engine implementations (chromium, firefox, safari).
    • types/: Core data models (Category, Entry structs).
    • crypto/: Encryption and cipher detection.
    • masterkey/: Platform-specific key retrieval.
    • filemanager/: Temp file and locked file handling.
    • output/: Formatters (CSV, JSON, CookieEditor).
    • utils/: SQLite and file utilities.
  3. Parse Safari LocalStorage (WebKit Origins)

    main

    Safari 17+ uses a partition-aware nested tree for LocalStorage. Data is stored in SQLite databases located within hashed directory structures.

    Path Structure

    • Default Profile: Container/WebKit/WebsiteData/Default/
    • Named Profile: Container/WebKit/WebsiteDataStore/<uuid>/Origins/

    Under the root, the path follows: <root>/<top-frame-hash>/<frame-hash>/LocalStorage/localstorage.sqlite3.

    Origin and Item Extraction

    • Origin: The extractor parses origin blocks to report the frame origin URL (the URL exposed to JavaScript's window.localStorage).
    • ItemTable: Data is queried via SELECT key, value FROM ItemTable.
    • Value Encoding: Values are UTF-16 LE encoded JS strings.
    • Size Cap: Oversized values (≥ 2048 bytes) are replaced with a size marker to keep exports bounded.
  4. Configure output formats and file organization

    main

    The tool organizes output using a one file per category convention. All data from all profiles for a specific category is aggregated into a single file within the target directory.

    Supported Formats

    FormatExtensionDescription
    csv.csvStandard CSV with UTF-8 BOM for Excel compatibility. Headers are derived from csv struct tags.
    json.jsonFlat JSON objects. Uses two-space indentation and disables HTML escaping to preserve URLs.
    cookie-editor.jsonSpecifically formatted JSON compatible with the CookieEditor extension. Non-cookie categories fall back to standard JSON.

    Example Directory Structure

    If you extract to results/ using CSV format, the output will look like:

    results/
    ├── password.csv
    ├── cookie.csv
    ├── history.csv
    ...

    Note: Empty categories do not produce files. Files are created with restrictive permissions (0600).

  5. How Chrome App-Bound Encryption (ABE) integration works

    main

    Chrome 127+ on Windows uses App-Bound Encryption (ABE) for v10-era cookies and passwords. The decryption key is no longer a user-bound DPAPI blob but an app-bound blob that requires a call to the elevation_service COM RPC (IElevator::DecryptData).

    Because the elevation_service only responds to legitimate browser binaries (e.g., chrome.exe, msedge.exe, brave.exe), HackBrowserData cannot decrypt these keys directly from a standard Go process. Instead, it uses a multi-stage injection architecture:

    1. Preparation: The Go process reads an embedded native payload (~75 KB) and patches function pointers into its DOS stub.
    2. Injection: A fresh browser process is spawned in a suspended state. The payload is written into the browser's memory via VirtualAllocEx and WriteProcessMemory.
    3. Execution: A remote thread is created to run a C-based reflective loader (Bootstrap) inside the browser process. This loader maps the payload into memory and executes its DllMain.
    4. Extraction: The payload (the abe_extractor) performs the COM RPC call to the elevation_service to retrieve the 32-byte master key.
    5. Retrieval: The Go process waits for the payload to write the key into a specific memory offset, reads it via ReadProcessMemory, and then terminates the throwaway browser process.

    This approach ensures the project remains cross-platform and pure Go by default, as the heavy lifting for Windows-specific ABE is handled by a transient, injected native component.

    browser/chromium.Extract()
      → masterkey.Retrievers{V10: &DPAPIRetriever{}, V20: &ABERetriever{}}
      → ABERetriever.RetrieveKey():
          reads Local State → extracts APPB-prefixed blob
          resolves browser exe via registry App Paths
      → utils/injector.Reflective.Inject(exePath, payload, env)
  6. Error handling during data extraction

    main

    The extraction process uses a Collect-and-Continue pattern to maximize data recovery. If one part of the extraction fails, the tool attempts to continue with other parts based on the following hierarchy:

    Error LevelTriggerResulting Action
    Session failureTemp directory cannot be createdAbort: The entire process stops and returns an error.
    Category failureSource file missing or extraction errorSkip: The specific category is skipped, and the tool moves to the next category.
    Record failureA single row/entry decryption failsSkip: That specific record is skipped, and extraction continues for the rest of the category.

    Important: A Master key failure is non-fatal. If the master key cannot be retrieved, categories requiring decryption (Passwords, Cookies, Credit Cards) will simply return empty values, while non-encrypted categories (History, Bookmarks, Downloads) will still be successfully extracted.

  7. Understand the Retriever interface and Hints struct

    main

    The Retriever interface is used to abstract the different ways master keys are retrieved across platforms. Instead of positional arguments, retrievers accept a Hints struct to specify platform-specific requirements.

    Each retriever only processes the fields relevant to its platform:

    • macOS/Linux: Uses KeychainLabel to identify the specific keychain account or D-Bus Secret Service item (e.g., "Chrome" or "Chrome Safe Storage").
    • Windows: Uses WindowsABEKey to locate the elevation-service COM interface (e.g., "chrome", "edge") and LocalStatePath to locate the Local State JSON file.

    Callers typically populate these hints from a BrowserConfig. The result of a successful retrieval is the ready-to-use decryption key: either the raw AES key (Windows) or the PBKDF2-derived key (macOS/Linux).

    type Hints struct {
        KeychainLabel  string // macOS Keychain account / Linux D-Bus Secret Service item label
        WindowsABEKey  string // Windows ABE browser key (e.g. "chrome", "edge")
        LocalStatePath string // path to Local State JSON
    }
  8. Bypass Windows locked files (e.g., Chrome Cookies)

    main

    On Windows, Chromium-based browsers often set PRAGMA locking_mode=EXCLUSIVE on SQLite databases like the Cookies file (Network/Cookies). This uses dwShareMode=0, which prevents other processes from opening the file via standard os.ReadFile calls, resulting in an access denied error.

    To bypass this, hack-browser-data uses a kernel-level technique that does not require admin privileges. The process involves:

    1. Enumerating system handles to find the existing handle held by the browser process.
    2. Duplicating that handle into the current process using DuplicateHandle.
    3. Reading the file contents via Memory-Mapped I/O (CreateFileMappingW and MapViewOfFile).

    This method reads directly from the OS kernel's file cache, which often includes uncommitted WAL (Write-Ahead Logging) data, providing a more complete snapshot of the database than a standard read.

  9. Decrypt Chromium data on Windows

    main

    Chromium on Windows uses AES-256-GCM. The master key is recovered from the Local State file at os_crypt.encrypted_key by:

    1. Base64-decoding the value.
    2. Stripping the 5-byte DPAPI ASCII prefix.
    3. Decrypting via Windows CryptUnprotectData (DPAPI).

    Standard v10 Layout:

    | v10   | nonce  | ciphertext + auth tag (16B) |
    |-------|--------|------------------------------|
    | 3B    | 12B    | remaining bytes              |

    Legacy DPAPI (Pre-Chrome 80): Values without a v10/v20 prefix are passed directly to CryptUnprotectData as a raw DPAPI blob.

  10. How cross-host decryption works

    main

    Cross-host decryption allows an analyst to decrypt browser data on a different machine (the analyst host) than where it was collected (the origin host). This is useful for decrypting data from browsers that cannot be installed on the analyst's OS (e.g., decrypting Windows-specific browser data on macOS).

    This workflow ensures that platform-bound secrets (like DPAPI or macOS Keychain) never leave the origin host. Instead, only the master keys and the necessary profile files are moved.

    The Workflow:

    1. On the Origin Host: Run dumpkeys to export portable master keys (keys.json) and archive to pack the necessary profile files (browser-data.zip).
    2. Transfer: Move keys.json and browser-data.zip to the analyst host.
    3. On the Analyst Host: Run restore using the transferred files to produce the decrypted output.
    # On the origin host (any OS) — export the keys and pack the data
    hack-browser-data dumpkeys -o keys.json
    hack-browser-data archive -o browser-data.zip
    
    # Copy keys.json + browser-data.zip to the analyst host, then decrypt offline
    hack-browser-data restore --keys keys.json --data-zip browser-data.zip
  11. How ChainRetriever works

    main

    A ChainRetriever is a wrapper that manages multiple retrievers by attempting them in a specific priority order. It follows first-success semantics: the first retriever that returns a valid key wins, and subsequent retrievers in the chain are not executed.

    If all retrievers in the chain fail, the ChainRetriever returns a single error that combines the errors from every attempted retriever. This pattern is used for platforms like macOS and Linux where multiple strategies (e.g., memory dumping vs. keychain access) exist for the same goal.