# SENTINEL — Honeypot + Forensics Lab + Track-Back (Prototype)

Part of the **SENTINEL Track-Back Defense Platform**. This component lures
attackers into decoys, records everything they do, analyzes captured samples in
a simulated isolated lab, records passive "track-back" beacons, and assembles a
chain-of-custody evidence package for law enforcement.

> **This is a TRACK-BACK platform, not a hack-back platform.** It is passive and
> defensive. See the Legal Use Notice at the bottom — read it before running.

---

## What's in here

| File                 | Role |
| -------------------- | ---- |
| `honeypot_server.py` | Flask decoy server: fake admin login + fake "data center" file portal. Logs every interaction (IP, UA, path, POSTed creds, headers) to `events.db`. Hosts `/beacon/<token>`, `/dashboard`, `/api/*`, `/submit-sample`. |
| `canary_token.py`    | Generates watermarked decoy/bait files, each embedding a unique canary token + callback (beacon) URL. |
| `forensics_lab.py`   | **Simulated** malware "microscope": hashes, file type, size, printable strings, synthetic verdict + indicative attribution hint. **Never executes samples.** |
| `evidence_report.py` | Builds a chain-of-custody evidence package (JSON + human-readable `.txt`), hashes it for integrity, and simulates forwarding to authorities via `outbox/`. |
| `quarantine.py`      | **The "Bubble Boy glovebox."** Seals an arriving sample into an isolated quarantine record as **inert base64 text** (`contained=true`, containment timestamp, "observed through the glass" note). **Never stores an executable; never runs anything.** |
| `auto_clone.py`      | **Auto-cloning decoy model.** On a detected intrusion it **freezes** the compromised decoy (`status='frozen_for_forensics'`) and spawns a **fresh clean decoy** (new fake creds, new bait set, new id) so the trap keeps working. Purely internal record-keeping of *our own* decoys. |
| `fragment_catalog.py`| **The growing threat-signature database.** After a quarantined sample is analyzed, extracts a small **signature fragment** (hash + first-N strings + synthetic reverse-engineering notes + suggested mitigation) into the `signatures` table. All synthetic; RE notes are **indicative only**. |
| `dashboard.html`     | Dark security-console UI (served at `/dashboard`) showing live events, beacons, microscope samples, evidence packages, **Quarantine Glovebox, Auto-Cloned Decoys, and the Threat Signature Database**. |
| `demo_seed.py`       | Inserts realistic **synthetic** data so the dashboard looks populated (events, beacons, samples, **quarantined samples, auto-cloned decoys, and cataloged signatures**). |
| `db.py`              | Shared SQLite schema/helpers (`events.db`) — now also `quarantine`, `decoys`, and `signatures` tables. |

Generated at runtime: `events.db`, `bait_files/`, `outbox/`, `demo_samples/`.

---

## Setup

Requires **Python 3.9+**.

```bash
pip install flask
```

(That is the only third-party dependency — everything else is Python stdlib:
`sqlite3`, `hashlib`, `json`, `uuid`, `string`.)

---

## Run (single command)

```bash
# 1) Populate the database with synthetic demo data (also generates bait files):
python demo_seed.py

# 2) Start the decoy server + dashboard:
python honeypot_server.py
```

Then open:

- **Dashboard (operations console):** http://127.0.0.1:8080/dashboard
- Decoy admin login: http://127.0.0.1:8080/
- Decoy file portal (bait): http://127.0.0.1:8080/files

### Try the track-back beacon (safe, local)

Downloading a bait file and "opening" it (requesting its embedded beacon URL)
simulates an attacker's own machine phoning home:

```bash
# grab a token from the registry, then hit its beacon endpoint
curl http://127.0.0.1:8080/files/passwords.xlsx        # shows the CANARY block
curl http://127.0.0.1:8080/beacon/<token-from-that-file>
```

A new beacon appears on the dashboard within a few seconds.

### Submit a sample to the microscope (simulated analysis)

```bash
curl -F "sample=@/path/to/file" http://127.0.0.1:8080/submit-sample
```

Returns a JSON summary of the full defensive flow. Pass `-F decoy_id=<id>` to
mark which decoy it arrived at and trigger the auto-clone. The file is
**sealed inert in the glovebox, hashed, and read — never executed.**

The response shows the whole chain in one shot:

```
attack -> quarantine (glovebox) -> auto-clone fresh decoy
       -> simulated analysis -> catalog signature -> grow database
```

```json
{
  "quarantine_id": 5, "contained": true,
  "frozen_decoy": "decoy-f77ecaa8", "spawned_clone": "decoy-bb6facec",
  "sample_id": 10, "signature_id": 5,
  "analysis": { "verdict": "Malicious", "threat_score": 100, ... }
}
```

### Inspect the upgraded panels (JSON feeds)

```bash
curl http://127.0.0.1:8080/api/quarantine          # sealed glovebox records
curl http://127.0.0.1:8080/api/decoys              # auto-cloning decoy registry
curl http://127.0.0.1:8080/api/signatures          # threat-signature database
curl "http://127.0.0.1:8080/api/signatures?q=ransom"  # search the database
```

### Build an evidence package

Click **"Build Chain-of-Custody Package"** on the dashboard, or:

```bash
curl -X POST http://127.0.0.1:8080/api/build-evidence
```

Output lands in `outbox/` as `<case-id>.json` + `<case-id>.txt`.

---

## Individual modules (runnable standalone)

```bash
python canary_token.py       # generate all bait files
python forensics_lab.py      # analyze a built-in demo sample
python evidence_report.py    # build an evidence package from current DB
python quarantine.py         # seal a demo sample into the glovebox
python auto_clone.py         # register a decoy, simulate intrusion, spawn clone
python fragment_catalog.py   # analyze + catalog a demo signature fragment
python db.py                 # initialize an empty database
```

---

## LEGAL USE NOTICE (read before running)

This prototype implements **passive, defensive active-defense only**, consistent
with U.S. law and the SENTINEL brief:

1. **No hack-back. No retaliation.** Nothing in this code reaches out to,
   accesses, damages, corrupts, or exfiltrates from any system you do not own.
   Doing so would violate the Computer Fraud and Abuse Act (18 U.S.C. § 1030).
   We do the opposite: we watch our own decoys.
2. **Track-back = passive beacons / canary tokens.** Watermarked bait files
   phone home only when an attacker **voluntarily opens them on their own
   machine**. Their machine reports to us; we never touch theirs. Honeypots,
   canary tokens, and beacons are lawful defensive techniques.
3. **Malware analysis is SIMULATED.** Samples are hashed and read for strings
   only — **never executed or detonated.** Arriving samples are first sealed in
   the **quarantine glovebox** as inert base64 text (`contained=true`) and
   observed "through the glass" only. Real deployments run true analysis inside
   an isolated, air-gapped sandbox — this code never executes anything.
   **Auto-cloning** is purely internal record-keeping of *our own* decoys; it
   never touches, copies, or accesses any external system.
4. **Attribution is INDICATIVE ONLY** and is intended solely as a lead for
   **law enforcement (CISA / FBI IC3)**. We collect and report; law enforcement
   pursues and acts. We never identify or pursue a private person ourselves.
5. **All prototype data is SYNTHETIC.** No real PII. Synthetic source IPs use
   the RFC 5737 documentation ranges (`192.0.2.0/24`, `198.51.100.0/24`,
   `203.0.113.0/24`) so no address maps to a real person.

Run only against systems and data you own or are explicitly authorized to test.
