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 in the tool repository for the authoritative guidelines.

#Reporting bugs and vulnerabilities

For a normal bug, use the issue templates 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, contact the maintainer privately at me@moond4rk.com instead of opening a public issue.

#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.

Formatting is enforced; run both before committing:

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

Spelling is checked with typos :

typos

#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 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 in a per-platform registry, not bespoke code. Each platform has its own table:

Each entry is a config record with a Key (the value used by --browser), a Name, the engine Kind (Chromium or Firefox), a UserDataDir, and — on Windows, for Chrome-family browsers — an optional App-Bound Encryption flag. Display names are defined as constants in browser/consts.go.

Adding a browser means adding a new entry in the relevant OS file (and a display-name constant in consts.go). 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:

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 — please read it before participating. HackBrowserData is released under the MIT License.