mirror of
https://github.com/LORDBABUINO/stealth.git
synced 2026-05-03 02:49:59 -07:00
117 lines
3.5 KiB
Markdown
117 lines
3.5 KiB
Markdown
# stealth-engine
|
||
|
||
Detects Bitcoin UTXO privacy vulnerabilities by analysing a wallet's transaction
|
||
history on a Bitcoin Core node via JSON-RPC.
|
||
|
||
The library receives a pre-built `WalletHistory` (via any `BlockchainGateway`
|
||
implementation), indexes it into a `TxGraph`, then runs independent
|
||
vulnerability detectors through `TxGraph::detect_all()`. Results are returned
|
||
as a structured `Report` that serialises to JSON.
|
||
|
||
Primary public scanning API: `TxGraph::detect_all(...)`.
|
||
|
||
## Detected vulnerabilities
|
||
|
||
| # | Vulnerability | Default severity |
|
||
| --- | --------------------------------------- | ---------------- |
|
||
| 1 | Address reuse | HIGH |
|
||
| 2 | Common-input-ownership heuristic (CIOH) | HIGH – CRITICAL |
|
||
| 3 | Dust UTXO reception | MEDIUM – HIGH |
|
||
| 4 | Dust spent alongside normal inputs | HIGH |
|
||
| 5 | Identifiable change outputs | MEDIUM |
|
||
| 6 | UTXOs born from consolidation txs | MEDIUM |
|
||
| 7 | Mixed script types in inputs | HIGH |
|
||
| 8 | Cross-origin cluster merge | HIGH |
|
||
| 9 | UTXO age / lookback-depth spread | LOW |
|
||
| 10 | Exchange-origin batch withdrawal | MEDIUM |
|
||
| 11 | Tainted UTXO merge | HIGH |
|
||
| 12 | Behavioural fingerprinting | MEDIUM |
|
||
|
||
## Prerequisites
|
||
|
||
- **Rust** >= 1.93.1
|
||
- **Bitcoin Core** (`bitcoind`) >= 0.29.0 — must be on your `PATH`
|
||
|
||
### Installing Bitcoin Core
|
||
|
||
```bash
|
||
# macOS (Homebrew)
|
||
brew install bitcoin
|
||
|
||
# Ubuntu / Debian
|
||
sudo apt install bitcoind
|
||
|
||
# Or download from https://bitcoincore.org/en/download/
|
||
```
|
||
|
||
Verify it is available:
|
||
|
||
```bash
|
||
bitcoind --version
|
||
```
|
||
|
||
## Usage
|
||
|
||
Add the crate to your `Cargo.toml`:
|
||
|
||
```toml
|
||
[dependencies]
|
||
stealth-engine = "0.1.0"
|
||
```
|
||
|
||
```rust,ignore
|
||
use stealth_engine::gateway::BlockchainGateway;
|
||
use stealth_engine::TxGraph;
|
||
use stealth_bitcoincore::BitcoinCoreRpc;
|
||
|
||
// Connect to a wallet-loaded bitcoind
|
||
let gateway = BitcoinCoreRpc::from_url(
|
||
"http://127.0.0.1:8332",
|
||
Some("user".into()),
|
||
Some("pass".into()),
|
||
).unwrap();
|
||
let history = gateway.scan_wallet("my_wallet").unwrap();
|
||
|
||
let graph = TxGraph::from_wallet_history(history);
|
||
let report = graph.detect_all(&Default::default(), None, None);
|
||
|
||
for finding in &report.findings {
|
||
println!("{}: {}", finding.severity, finding.vulnerability_type);
|
||
}
|
||
```
|
||
|
||
## Running the tests
|
||
|
||
The integration tests spin up a temporary `bitcoind` in regtest mode
|
||
(via [`corepc-node`](https://crates.io/crates/corepc-node)).
|
||
No external setup is required — just ensure `bitcoind` is on your `PATH`.
|
||
|
||
```bash
|
||
# Run all tests (unit + all regtest integration tests)
|
||
cargo test -p stealth-engine
|
||
|
||
# Run a single test with output
|
||
cargo test -p stealth-engine detect_address_reuse -- --nocapture
|
||
```
|
||
|
||
> **Note:** The integration tests create ephemeral regtest nodes that are
|
||
> automatically cleaned up. Each test takes a few seconds due to block mining.
|
||
|
||
## Project structure
|
||
|
||
```
|
||
core/
|
||
├── Cargo.toml
|
||
├── src/
|
||
│ ├── lib.rs # Crate root and re-exports
|
||
│ ├── engine.rs # AnalysisEngine — canonical scan entry point
|
||
│ ├── graph.rs # TxGraph — indexed wallet transaction view
|
||
│ └── detect.rs # all vulnerability detectors + detect_all()
|
||
└── tests/
|
||
└── integration.rs # all regtest integration tests
|
||
```
|
||
|
||
## License
|
||
|
||
[MIT](../LICENSE)
|