Skip to content

refactor: implement vulnerability detection in Rust crate#11

Closed
satsfy wants to merge 8 commits intostealth-bitcoin:mainfrom
satsfy:refactor-vulnerability-detection
Closed

refactor: implement vulnerability detection in Rust crate#11
satsfy wants to merge 8 commits intostealth-bitcoin:mainfrom
satsfy:refactor-vulnerability-detection

Conversation

@satsfy
Copy link
Copy Markdown
Collaborator

@satsfy satsfy commented Mar 24, 2026

Partially solves #10

This PR is a combination of rust refactors from @brenorb in #15 and me.

Implement the wallet analysis engine in a dedicated Rust crate. Deletes the old deprecated Python solution. Ports 5 privacy heuristics inspired by am-i-exposed.

New privacy heuristics in this PR:

  • Dust attack — detects wallets receiving dust intended to poison future spends or reveal ownership
  • Peel chain — detects repeated spend patterns where value is peeled off across a chain of transactions
  • Deterministic links — detects transaction structures that create strong, guessable links between inputs and outputs
  • Unnecessary input — detects transactions that include more inputs than needed, increasing linkability
  • Toxic change — detects change outputs that are especially privacy-damaging to spend later

This PR:

  • Converts the repo into a Rust workspace with separate crates for core, api, cli, bitcoincore, and a new shared domain crate.
  • Introduces a canonical AnalysisEngine + BlockchainGateway architecture so API, CLI, and library usage all go through one main scan path.
  • Extracts shared domain types, interfaces, config, errors, descriptors, and scan models out of core into a separate crate (types → later renamed domain / stealth-domain).
  • Adds a new Bitcoin Core RPC adapter crate (stealth-bitcoincore) implementing the gateway abstraction, including descriptor import, wallet scanning, tx fetching, and cookie/auth handling.
  • Adds a new HTTP API crate (stealth-api) with POST /api/wallet/scan, request validation, structured error responses, RPC autodetection, and regtest end-to-end tests.
  • Adds a new CLI crate (stealth-cli) that can scan a single descriptor, multiple descriptors from a file, or raw UTXOs, with text/json output modes.
  • Expands the detector set from the old smaller set to 17 privacy detectors, including newer detections like dust attack, peel chain, deterministic links, unnecessary input, and toxic change.
  • Refactors TxGraph away from the old live-RPC/lazy-fetch shape into a prebuilt graph from WalletHistory, with precomputed caches and a spending index for deterministic analysis.
  • Removes the old compatibility scanner module (core/src/scanner.rs) after earlier demoting it, so the PR ends with the legacy path deleted rather than merely discouraged.
  • Rewrites a large part of the docs/README/testing story: documents the workspace crates, setup flow, project structure, detector taxonomy, and updates integration tests to use the new gateway/engine path instead of direct client wiring.

Reviewer Notes

Open the branch locally, run cargo build to verify it compiles and run cargo test. Inspect the e2e test in api/ or the integration tests in engine/.

Run the api with cargo run --bin stealth-api and test that call:

curl 'http://localhost:20899/api/wallet/scan' \
  -H 'content-type: application/json' \
  -d '{"descriptor":"wpkh(xpub.../0/*)"}' | jq

@satsfy
Copy link
Copy Markdown
Collaborator Author

satsfy commented Mar 26, 2026

This new rebase implementation blends my solution and Breno's solution from #15. I force-pushed the branch after reconciling the overlapping architecture changes so the result keeps the single canonical execution path, removes the leftover compatibility layer, and preserves the cleaner domain/core separation.

@satsfy satsfy force-pushed the refactor-vulnerability-detection branch 2 times, most recently from 71dbe40 to 87e459e Compare March 26, 2026 03:24
@satsfy satsfy force-pushed the refactor-vulnerability-detection branch from 87e459e to 9411892 Compare March 26, 2026 14:25
@satsfy
Copy link
Copy Markdown
Collaborator Author

satsfy commented Mar 26, 2026

Supplanted by pr #16

@satsfy satsfy closed this Mar 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants