BlockTrace is a Blockchain OSINT tool developed to trace and visualize ransomware-related cryptocurrency transactions using publicly available blockchain data.
The tool accepts a wallet address or Bitcoin transaction hash as input, performs basic blockchain and reputation checks, and visualizes transaction flow to demonstrate tracing and laundering patterns.
Due to API limitations and privacy constraints, simulated transaction data is used for visualization, as mentioned in the project guidelines.
- Wallet address tracking
- Bitcoin transaction-hash lookup
- Blockchain type detection
- Ransomware / scam reputation check
- Transaction flow visualization
- Report export (JSON, PDF, PNG)
- Bounded Bitcoin tracing across two ranked branches by default
- Transaction provenance in graph edges and JSON reports
- Local structured ransomware reputation results
- Python
- Tkinter (GUI)
- NetworkX & Matplotlib
- Public blockchain APIs
pip install -r requirements.txt
python main.py
## Tracing Scope
Bitcoin tracing follows up to two hops and queries the two highest-value
neighbor branches at each hop. Graph edges retain transferred amounts,
transaction IDs, block heights, and timestamps when the explorer provides
them. The strongest path is selected by its minimum value across all hops.
## Reputation Scope
The local database provides confirmed ransomware labels for known Bitcoin
addresses. The dashboard checks every address in the traced graph, not only
the submitted wallet. High fan-in and high fan-out are reported as heuristic
investigation indicators and are not treated as proof of criminal activity.
External label providers are not configured in this prototype.
## Monitoring Scope
Each analysis establishes a transaction-count baseline for the selected
wallet. Repeating the same analysis reports newly observed transactions;
switching wallets starts a separate baseline. Monitoring is currently manual
and runs when the user checks a wallet. Wallets can be added to or removed
from the local `watchlist.json` file in the dashboard. Automatic polling is
available through the `Poll Watchlist` action. Background scheduling is
planned for a later iteration.
Run the focused regression tests with:
```bash
python -m unittest discover -s tests