Sourcehttps://github.com/Instinctes/forensprotoLegal / acceptable usehttps://github.com/Instinctes/forensproto/blob/main/docs/legal.mdGetting startedhttps://github.com/Instinctes/forensproto/blob/main/docs/getting-started.mdmacOS .apphttps://github.com/Instinctes/forensproto/blob/main/docs/macos-app.mdLicense MIT (plus the acceptable-use note in that file)
1. What this isForensProto is a single-user workbench you run on your own computer. You drop a wallet file onto a page that only listens on localhost. Hashcat, if installed, searches the password. Recovered seeds and keys never leave the machine unless you copy them yourself.
It is
not a hosted recovery service. You do not send a wallet to anyone. There is no company desk that "unlocks" a file for a fee. There is no court certification out of the box. Password recovery, seed reconstruction and nonce analysis are dual-use: the same tools that recover
your wallet recover someone else's if you point them there. The authors do not help with unauthorized access.
Use it when you have a legal right to the data — your own backups, an investigation you are authorized to run, or an estate case with documented authority. If you are unsure, stop and ask a lawyer, not the issue tracker.
2. Specifications| Kind | Local desktop / localhost web UI (Next.js). Optional native macOS wrapper (Tauri). |
| Bind | 127.0.0.1 only. Default npm run dev is http://127.0.0.1:3000 |
| Auth | Off until you set FORENSPROTO_AUTH=enabled |
| Data dir | .forensproto/ (gitignored), or FORENSPROTO_DATA_DIR |
| Runtime | Node.js ≥ 20 (22.5+ recommended for node:sqlite; older Node falls back to JSON) |
| Recovery engine | Hashcat (you install it). GPU optional. |
| Hash extraction | Python 3.8+ (scripts/bitcoin2john.py and wallet dumps) |
| Core wallet.dat | Hashcat mode 11300 (Bitcoin Core / similar Berkeley-DB or SQLite wallets) |
| Electrum | Detected; extraction via electrum2john. Modes 16600 / 21700 / 21800 depending on version. |
| Ethereum keystore | Detected; Hashcat mode 15700 |
| Seeds | BIP39 checksum, missing-word / partial-phrase recovery |
| On-chain (no file) | ECDSA nonce-reuse against a Bitcoin address (legacy + SegWit) |
| Audit | Hash-chained local log. Tamper breaks the chain. |
| Dossier | Ed25519-signed case bundle (metadata, custody, attestations). Independently verifiable. |
| AI | Optional, local Ollama only |
| Wordlists | You bring them. The repo ships wordlists/example.txt for a smoke test, nothing else. |
| Current tag | 0.1.0 on main — no binary GitHub release yet |
3. What is real, what is labelledThe README table is the contract. The UI uses the same words.
Core — real- Bitcoin Core wallet.dat drop → hash extract → Hashcat job
- BIP39 / missing-word recovery
- ECDSA nonce-reuse recovery (on-chain, no wallet file)
- Hash-chained audit log
- Signed recovery attestation (password is checked against the wallet material; the secret is not stored, only a SHA-256 commitment)
- Signed case dossier
Lite — local, limited- OSINT, chain tracer, file carver, stego, memory scan (WIF / xprv / BIP39 strings in a dump)
Research — labelled in the UI- Visual Key (CL-1), vanity addresses, offline pattern scan against a funded-address file you supply
Optional / advanced- Distributed agents, RBAC, Vast.ai listing. Not required for a single machine.
This is a workbench. It will not invent a password that is not in the keyspace you gave Hashcat.
4. What is true, and what is notTrue today- The default server binds localhost. Keys are not uploaded to a ForensProto server, because there is no ForensProto server.
- A found password can be attested: the tool re-derives from the wallet material and signs the result. You can verify the signature later without keeping the password on disk.
- The audit log is a hash chain. Edit a past line and the next hash fails.
- Tests exist and run on every commit: BIP39 TREZOR vector, BIP32 paths, secp256k1 Visual-Key addresses, Shamir k-of-n, nonce-reuse against a known vector, Hashcat argv regressions (--self-test-disable on Apple Silicon), dossier sign/verify. npm test — 61 tests at the time of this post.
- Source is MIT. Read it. Fork it. Do not commit wallets, seeds, potfiles or bulk wordlists.
Not true, and we will not say it- Not a guarantee you will get the coins back. A strong password with no hint is still a strong password.
- Not a replacement for Hashcat, bitcoin2john, or Electrum's own extractors. Those tools do the cryptography. This UI wires them and keeps a case file.
- Not court-certified evidence hardware. The dossier is a signed JSON/text bundle from your machine, not a lab seal.
- Not "untraceable recovery" and not a mixing service. If you later spend recovered coins, that is a normal Bitcoin transaction.
- Not a place to paste someone else's seed for "help". Secrets stay on your disk. GitHub issues are public.
- Visual Key / vanity / pattern scan are research. They are labelled. They are not a magic "draw a picture, get Satoshi's wallet" button.
5. How to startgit clone https://github.com/Instinctes/forensproto.git
cd forensproto
npm install
npm run dev
Open
http://127.0.0.1:3000.
- Check the setup strip (Hashcat + a wordlist).
- Drop a wallet.dat or keystore on the home page, or open Recovery.
- Use wordlists/example.txt only to smoke-test the pipeline. Put real dictionaries in wordlists/ yourself. They are gitignored on purpose.
macOS prerequisites:
brew install node hashcat python
Native
ForensProto.app: follow
docs/macos-app.md. Hashcat, Node and Python stay system installs — they are not fully embedded in the .app. User data goes to
~/Library/Application Support/com.forensproto.desktop.
Do
not run
npm audit fix --force — it can downgrade Next.js to an incompatible major.
6. What this is not, yet- No signed binary release. There is no GitHub Release with a notarized DMG. Build from source, or use the macOS install script, and treat the git commit as the version.
- No independent audit of the recovery path. Tests cover the vectors above. That is not the same thing.
- Apple Silicon Hashcat needs --backend-ignore-opencl and --self-test-disable or mode 11300 dies in the self-test before the first guess. The manager adds those flags. Override with FORENSPROTO_HASHCAT_BACKEND / FORENSPROTO_HASHCAT_SELFTEST=on if you know better.
- Windows / Linux desktop wrappers are not a polished shipping product. The Node UI runs anywhere Node and Hashcat run.
- No support desk. Open a GitHub issue for software bugs. Do not paste a seed.
7. Source layoutsrc/lib/wallet-analyzer.ts detect Core / Electrum / keystore
src/lib/wallet-dump.ts extract hashes
src/lib/hashcat-manager.ts argv, Apple Silicon flags, jobs
src/lib/attestation.ts re-check found password, Ed25519 attest
src/lib/dossier.ts signed case bundle
src/lib/audit (db) hash-chained log
scripts/bitcoin2john.py Core hash extract
docs/legal.md lawful use
test/ vitest — reference vectors
The tests that should stay green:
npm test
Build it, keep the keys on the machine that ran it, write down what you recover on paper. There is no one who can reset a lost phrase for you, including this tool if you never had a hint.https://github.com/Instinctes/forensprotoIf the workbench is useful and you want to support it, Bitcoin donations are welcome. Optional. No perk, no account, nothing uploaded.
1HuXWCLpdpJZvfy4GKu39RMtVg6pgUCPHA
