# SENTINEL — On-Chain Ransom Tracing Module (Prototype)

Part of the **SENTINEL Track-Back Defense Platform**. This component follows a
ransom payment across a **public-style blockchain ledger**, computes how much of
the tainted amount reaches each downstream address, flags likely cash-out points
(exchanges / mixers), and produces a **law-enforcement-ready tracing report**.

> ## ⚖️ TRACE, DO NOT TOUCH — read this first
>
> **We TRACE the public ledger and REPORT — we never touch, move, or seize funds.**
>
> The blockchain is a **public ledger**. The legitimate, real-world technique
> used by firms like **Chainalysis** and **TRM Labs** is simply to *read* that
> ledger: once a ransom is paid to an address, you can **follow the money**
> downstream and hand the trail to law enforcement.
>
> This module does the **opposite of a hack-back**. It does **NOT**:
> - inject tokens into anyone's wallet,
> - move, seize, freeze, or claw back funds,
> - attach anything to a criminal's money (that is impossible on a blockchain
>   and would be illegal),
> - contact any real system, wallet, or blockchain.
>
> It performs **read-only analysis** and writes a report. **Identification of the
> people behind the addresses and any seizure of funds are performed EXCLUSIVELY
> by law enforcement through lawful process** (for example, a subpoena to the
> exchange at the cash-out point for its KYC records). *We collect and report;
> investigators act.* (See `../shared/BRIEF.md`, guardrails #1 and #4.)
>
> **All data in this prototype is synthetic/demo. There is no real chain,
> wallet, fund, or network access anywhere in the code.**

---

## What's in here

| File               | Role |
| ------------------ | ---- |
| `chain_model.py`   | A **simulated** blockchain ledger (SQLite): synthetic `addresses` (with labels like RANSOM / EXCHANGE / MIXER) and `transactions`. No network, no real chain. |
| `tracer.py`        | Graph-tracing logic. `trace(start_address, max_hops)` follows outgoing transactions breadth-first, builds the flow graph, computes **proportional taint** per downstream address, and flags cash-out points. Pure read-only analysis. |
| `report.py`        | Builds a law-enforcement tracing report (JSON + human-readable TXT) into `outbox/`, with the ransom address, hop path, tainted amounts, flagged cash-out points, an integrity hash, and the legal trace-not-touch notice. |
| `app.py`           | Flask dashboard (dark security-console style) that visualizes the fund-flow trail, tainted amounts per hop, and cash-out points, with a button to generate the report. |
| `demo_seed.py`     | Seeds a realistic **synthetic** ransom scenario into the ledger. |
| `templates/`       | `dashboard.html` — the operations-console UI. |
| `outbox/`          | Generated reports land here (simulated hand-off to FBI IC3 / CISA). |

Generated at runtime: `ledger.db`, files under `outbox/`.

---

## Setup

Requires **Python 3.9+**.

```bash
pip install -r requirements.txt
```

(Flask is the only third-party dependency; everything else is stdlib.)

---

## Run (single command)

```bash
# From inside sentinel/ransom_trace/ :
python demo_seed.py && python app.py
```

Then open **http://127.0.0.1:5057** — the dashboard auto-traces the seeded
ransom address, draws the fund-flow trail, highlights the flagged exchange /
mixer cash-out points, and lets you generate a tracing report into `outbox/`.

### Command-line only (no dashboard)

```bash
python demo_seed.py     # seed the synthetic scenario
python tracer.py        # print the trace summary + cash-out points
python report.py        # write JSON + TXT report into outbox/
```

---

## The demo scenario (all synthetic)

```
VICTIM (Acme Hospital)
   │ 12.0 BTC  ransom payment
   ▼
RANSOM address  ──split──►  Intermediary A ─┬─► Peel addr ─┐
                └─split──►  Intermediary B  │              ├─► Consolidation ─┬─► EXCHANGE  (cash-out)
                └─peel───►  Peel addr ───────┘              │                 └─► EXCHANGE #2 (cash-out)
                                              Intermediary B ─► MIXER ─► EXCHANGE (post-mix cash-out)
```

The tracer follows the 12.0 BTC from the criminal `RANSOM` address through the
layering / peel-chain hops to the labeled **exchange** and **mixer** cash-out
points, and the report tells investigators exactly which exchange deposit
addresses to pursue via subpoena.

---

## How the taint model works

`tracer.py` uses the standard **proportional ("haircut") taint** method: when a
tainted address sends funds, the taint is split across its outgoing transactions
in proportion to each transaction's share of total outgoing value. Taint only
ever dilutes as it fans out and can never exceed the value that actually arrived
at a recipient. This mirrors the read-only fund-flow analysis used by real
tracing firms — applied here to our own simulated ledger.

---

## Legal Use Notice

This is a **track-back / trace-and-report** tool, not a hack-back tool. It is
passive and read-only. It never reaches out to, accesses, damages, or drains any
system, wallet, or account it does not own — doing so would violate the CFAA
(18 U.S.C. § 1030). Its sole output is a forensic tracing report intended to be
handed to law enforcement (FBI IC3 / CISA), who alone pursue identification and
seizure through lawful process. **We trace the public ledger and report — we
never touch, move, or seize funds.**
