# SENTINEL Honeypot — Upgrade Notes: Cloning + Quarantine

This upgrade adds three new capabilities to the existing honeypot component
**without changing or breaking any existing functionality**. Everything is
passive/defensive, synthetic, and never executes a sample — consistent with
`../shared/BRIEF.md`.

---

## The demo story (one sentence)

> **An attack lands on a decoy → the sample is sealed in the "Bubble Boy
> glovebox" → a fresh clean decoy is auto-cloned while the dirty one is frozen
> for forensics → the sealed sample is analyzed (simulated) → a signature
> fragment is cataloged → the threat database grows.**

You can watch this whole chain fire in a single call:

```bash
python demo_seed.py           # populates all panels with synthetic data
python honeypot_server.py     # then open http://127.0.0.1:8080/dashboard

# drive the live flow (optionally naming the decoy that was hit):
curl -F "sample=@/path/to/file" -F "decoy_id=decoy-xxxxxxxx" \
     http://127.0.0.1:8080/submit-sample
```

The response returns `quarantine_id`, `frozen_decoy`, `spawned_clone`,
`sample_id`, and `signature_id` — the entire pipeline in one JSON object.

---

## What was added

### 1. `quarantine.py` — the "Bubble Boy glovebox"

A malware quarantine model. When a sample arrives it is **sealed into an
isolated quarantine record**:

- stored **only as inert base64 text** (never an executable, never run),
- marked `contained = true`,
- stamped with a **containment timestamp** and a note that analysts observe it
  **"through the glass" only**,
- hashed (sha256) for integrity.

**Functions:** `quarantine_sample(name, data) -> quarantine_id`,
`get_quarantine(id)`, `list_quarantined()` (plus `mark_analyzed()` to link a
sealed record to its later analysis).

Persisted in the new **`quarantine`** SQLite table (via `db.py`). A clear code
comment states that in production this maps to an **isolated VM /
network-segmented sandbox** and that **nothing is ever executed here**.

### 2. `auto_clone.py` — auto-cloning decoy model

When an intrusion is detected on a decoy, the platform:

1. **freezes** the compromised ("dirty") decoy — `status='frozen_for_forensics'`
   with a `frozen_ts` — so the crime scene is preserved intact, and
2. **spawns a fresh clean decoy** with **new fake credentials, a new bait
   fileset, and a new decoy id** (next clone generation) so the trap keeps
   catching more attackers.

**Functions:** `register_decoy()`, `on_intrusion(decoy_id)` (freezes the dirty
decoy and returns the new clean decoy record), plus `list_decoys()` and
`get_decoy()`.

Persisted in the new **`decoys`** SQLite table. **Nothing here touches any
external system** — it is entirely internal record-keeping of *our own* decoys.
"Cloning" means creating a new local record + fresh synthetic bait; it never
copies, accesses, or attacks anyone else's machine.

### 3. `fragment_catalog.py` — the growing threat-signature database

After a quarantined sample is analyzed (reusing `forensics_lab.py`'s **simulated**
analysis), a small **signature fragment** is extracted and stored:

- full-sample sha256 + a hash of the fragment itself,
- the first N printable strings (from the microscope's `notable_strings`),
- a synthetic **reverse-engineering notes** summary, explicitly labelled
  **INDICATIVE**,
- a synthetic **suggested mitigation / removal note**,
- the simulated family guess + threat score.

**Functions:** `catalog_fragment(sample_id, quarantine_id=None)`,
`search_signatures(query)`, `list_signatures()`.

Persisted in the new **`signatures`** SQLite table. This is the "huge database
of all threats" the founder wants — it grows every time a sample is cataloged
and is fully searchable. All content is synthetic and RE notes are indicative.

### 4. Wiring into `honeypot_server.py`

- **New JSON routes:** `/api/quarantine`, `/api/decoys`, `/api/signatures`
  (the last supports `?q=` search).
- **New orchestration helper** `handle_incoming_sample(filename, data, decoy_id)`
  runs the full flow: **quarantine → auto-clone → simulated analysis → catalog
  signature**.
- `/submit-sample` now drives that full flow (and accepts an optional
  `decoy_id` form field to trigger the auto-clone), instead of only analyzing.
- All existing routes (`/`, `/admin/login`, `/files`, `/beacon/<token>`, probe
  traps, `/dashboard`, `/api/summary|events|beacons|samples|evidence`,
  `/api/build-evidence`) are unchanged.

### 5. Three new dashboard panels (`dashboard.html`)

Added in the **same dark security-console style** (same CSS variables, fonts,
pill/table patterns, and 4-second polling):

- **Quarantine Glovebox** — sealed samples, `contained` pills, "sealed · never
  executed" counter.
- **Auto-Cloned Decoys** — active (green) vs. `frozen_for_forensics` (red)
  decoys, with generation, fake creds, bait fileset, and clone lineage.
- **Threat Signature Database** — searchable table of fragments with family,
  score, fragment hash, string fragments, and RE notes + mitigation.

A second KPI row was added: Sealed in Glovebox, Active Decoys, Frozen for
Forensics, Threat Signatures, Containment Rate (100%), and Samples Executed (0).

### 6. `demo_seed.py` seeding

Now also seeds (all synthetic):

- **quarantined samples** — several sealed into the glovebox and analyzed,
- **auto-cloned decoys** — an origin decoy plus a second standing decoy, then a
  simulated intrusion that leaves **one frozen** and a freshly **spawned active
  clone**,
- **cataloged threat signatures** — one per analyzed glovebox sample.

---

## `db.py` schema additions (new tables only)

| Table        | Purpose |
| ------------ | ------- |
| `quarantine` | Sealed glovebox records: inert base64, `contained`, containment ts, "through the glass" note, link to analysis. |
| `decoys`     | Auto-cloning decoy registry: `decoy_id`, `status` (active / frozen_for_forensics), `generation`, `parent_id`, fake creds, bait fileset. |
| `signatures` | Growing threat DB: sha256, fragment hash, family, score, string fragments, indicative RE notes, mitigation. |

Existing tables (`events`, `beacons`, `tokens`, `samples`, `evidence`) are
untouched, and `init_db()` remains idempotent — the new tables use
`CREATE TABLE IF NOT EXISTS`, so existing databases upgrade cleanly.

---

## Verification performed

- `quarantine.py`, `auto_clone.py`, `fragment_catalog.py` each run standalone
  (self-tests pass).
- `python demo_seed.py` seeds events, beacons, samples, **4 quarantined samples,
  3 decoys (1 frozen / 2 active incl. a clone), and 4 threat signatures**.
- Server starts; `/api/quarantine`, `/api/decoys`, `/api/signatures`, and
  `/api/signatures?q=ransom` all return valid JSON.
- `POST /submit-sample` with a `decoy_id` returned the full chain
  (`quarantine_id`, `frozen_decoy`, `spawned_clone`, `sample_id`,
  `signature_id`, verdict Malicious/100).
- `/dashboard` loads (HTTP 200) and renders all three new panels populated in
  the existing style.

---

## Legal guardrails honored

- **No hack-back / passive-defensive only** — auto-clone is internal
  record-keeping of our own decoys; no external system is ever touched.
- **No executing real malware** — samples are stored as inert base64 and only
  hashed/read; a comment marks the production mapping to an isolated sandbox.
- **Synthetic data only** — all decoys, credentials, samples, and signatures are
  fabricated; RE notes and attribution are labelled **indicative only**.
