Contributing

How to set up the dev environment and contribute to HackBrowserData.

Contributions are welcome — bug fixes, new browser support, decryption work, and docs. Base all work on the main branch. Before opening a pull request, open or link an issue describing the problem or feature so the change can be discussed first. See CONTRIBUTING.md(opens in a new tab) in the tool repository for the authoritative guidelines.

#Reporting bugs and vulnerabilities

For a normal bug, use the issue templates(opens in a new tab) and include the output of hack-browser-data version, OS and browser versions, the command you ran, reproduction steps, and sanitized verbose logs.

Never attach keys.json, browser databases, exported cookies or passwords, output archives, tokens, or unredacted personal paths to a public issue. If the report describes a 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. SECURITY.md(opens in a new tab) explains what is in scope.

#Dev environment

Warning

The project targets Go 1.20 to keep Windows 7 support, and CI enforces it. A newer Go toolchain builds fine (the binary just won’t run on Windows 7), but do not bump the go directive in go.mod.

Because of the Go 1.20 floor, do not use Go 1.21+ standard-library packages — including log/slog, slices, maps, and cmp. Their absence is intentional; use the existing helpers instead. The SQLite driver modernc.org/sqlite is also pinned at v1.31.1 (v1.32+ requires Go 1.21) and should not be upgraded without a deliberate, separate change.

git clone https://github.com/moond4rk/HackBrowserData.git
cd HackBrowserData
go build ./cmd/hack-browser-data/

The module path is github.com/moond4rk/hackbrowserdata and the CLI lives in ./cmd/hack-browser-data/.

#Build, test, lint, format

Standard Go tooling drives the loop:

go build ./cmd/hack-browser-data/   # build the binary
go test ./...                       # run the test suite
golangci-lint run                   # lint (requires golangci-lint v2)

Note

golangci-lint must be v2 — the config is not compatible with v1. CI pins v2.14.

Formatting is enforced; run both before committing:

gofumpt -l -w .
goimports -w -local github.com/moond4rk/hackbrowserdata .

Spelling is checked by golangci-lint’s misspell linter, so golangci-lint run covers it.

#Windows App-Bound Encryption build

The default build omits Chrome 127+ App-Bound Encryption support. If your change touches ABE code, build and exercise the ABE binary with make build-windows — see Installation → Windows App-Bound Encryption build for prerequisites and the payload-rebuild steps.

#Commit and PR conventions

• Use Conventional Commits(opens in a new tab) for commit messages: feat, fix, chore, docs, refactor, test.
• Link the PR to an issue so the motivation is traceable.
• For behavioral changes, include before/after examples in the description.
• For new features, include unit tests.

#Requesting or adding a new browser

A “browser” is a configuration entry, not bespoke code. Every supported browser is one row in a single table, internal/browser/table.go, shared by all platforms.

Each row has a Name (the value used by --browser), a DisplayName, the engine Base (Chromium, Firefox, or Safari), and one Platform block per OS it runs on (Windows, Darwin, Linux). A platform block lists the browser’s user-data directories and, where needed, its macOS Keychain label or its Windows App-Bound Encryption setting. A browser without a block for an OS is not offered there.

Adding a browser means adding a row. For most Chromium-based browsers no new decryption code is required — the existing engine handles them once the profile location is registered. To request support for a browser you cannot add yourself, open an issue with the browser name, platform, and its user-data directory path.

#Architecture orientation

A short map of where things live, for finding your way around the source:

Everything lives under internal/, so the module has no importable Go API — the CLI is the interface. Deeper design notes live in rfcs/ in the source repository. For a conceptual walkthrough of discovery, encryption, and cross-host decryption, see How It Works.

#Code of Conduct and license

This project follows a Code of Conduct(opens in a new tab) — please read it before participating. HackBrowserData is released under the MIT License.