# SENTINEL — Cyber Forensics Test Lab (unified)

A single, documented, **fully-working** component of the SENTINEL Track-Back
Defense Platform. It unifies the honeypot, ransom-trace, and packet-layer ideas
into **one pipeline with one dashboard**: any attack on a phone, email, link, or
server is pulled into a trap, given bait, analyzed, documented, tokenized-tracked,
and handed to law enforcement — all with **synthetic data, locally, offline**.

> **Founder's rule, obeyed everywhere:** *track-back, never hack-back.*

---

## The two branded engines

| Brand | Role | File |
|-------|------|------|
| **PhishBot 3.0** | The phishing / link + email + SMS **scanner**. Classifies incoming lures, flags them, extracts indicators, and **sanitizes** dangerous links into safe tokenized stand-ins that point back at our own lab. | `phishbot.py` |
| **VigilantGuard** | The network-defense / **deception & isolation** grid: the simulated sandbox trap, the decoy "servers", and the watermarked + tokenized **bait**. | `vigilantguard.py` |
| **Cyber Caller ID & Blocker** | Caller-ID + call screening for inbound cyber connections. Nothing passes until the caller presents a valid **typed token**; every attempt is logged caller-ID style. | `caller_id.py` |

The overall component is the **Cyber Forensics Test Lab** inside SENTINEL.

---

## The pipeline (end to end, one flow)

```
  Lure ingress (email / SMS / link)      ← decoy inbox on OUR infrastructure
        │
        ▼  PhishBot 3.0 scan             ← classify, score, sanitize links
        ▼  VigilantGuard sandbox trap    ← seal artifact INERT, never executed
        ▼  VigilantGuard bait / deception← fake creds/keys/records + decoy server,
        │                                  watermarked + canary-tokenized
        ▼  Forensics documentation       ← hashes, verdict, indicators, case file
        ▼  Signature / "cure" check      ← look up / grow the signature catalog
        ▼  Tokenized passive track-back  ← HMAC-signed, tamper-evident tracker
        ▼  Chain-of-custody evidence     ← JSON + TXT + SHA-256 → outbox/
                                           addressed to FBI IC3 / CISA
                                           (GOVERNMENT tier → isolated stream)
```

### Cyber Caller ID & Blocker (the screening gateway)

Every inbound connection is treated like a screened phone call:

1. It first drops into VigilantGuard's simulated sandbox. A **COPY** is torn
   apart with static analysis (learn everything about it); the **ORIGINAL is
   held**, untouched, never executed.
2. **Typed-token verify-back.** Tokens are structurally different by entity
   type — `PSN-` (person), `BIZ-` (business), `GOV-` (government). The presented
   token's type **must match** the type the claimed entity is registered to
   present in the SQLite registry, and its signature must verify against that
   entity's secret. A type mismatch or forged signature = instant suspicion/deny.
3. **Release or deny.** Valid token **and** clean sandbox copy → the held
   original is released with an **anchor** verification stamp. Otherwise → DENY.
4. **Leave a message.** Unknown / no-token callers are challenged and must
   present a real token to proceed; the challenge is recorded.
5. **Instant token rotation.** Any `ACTIVE_BREACH` / `SUSPICIOUS` event
   immediately rotates the affected tenant's token type (and mints a fresh
   secret), so a forged/stolen token is useless; the rotation is broadcast to
   the registry and logged.
6. **Reputation memory.** Known-good callers get a fast lane; repeat offenders
   are auto-quarantined via VigilantGuard containment.
7. **One-click export to evidence** feeds any caller record into the existing
   forensics → tracker → outbox handoff chain.

The **call log** persists every attempt with: claimed identity, token type,
verdict (`ALLOWED` / `SCREENED` / `DENIED`), severity (`INFO` / `SUSPICIOUS` /
`ACTIVE_BREACH`), a precise timestamp, and a human status ("actively breaching",
"attempting breach", "passed through", "left a message").

---

## Run it

```bash
cd /home/user/workspace/sentinel/forensics_lab_unified
pip install -r requirements.txt
python demo_seed.py        # seed a full synthetic run (lures + callers)
python verify_run.py       # prints PASS for every stage
python lab_server.py       # dashboard at http://127.0.0.1:5060
```

`verify_run.py` runs the whole pipeline headless plus the caller-ID flow and
asserts each stage produced correct output (12 stages, all must PASS).

---

## Files

| File | Purpose |
|------|---------|
| `lab_server.py` | Flask dashboard + API on **127.0.0.1:5060** (dark black-and-teal console). |
| `pipeline.py` | Orchestrator: ingress → PhishBot → sandbox → bait → forensics+cure → tracker → outbox. |
| `phishbot.py` | **PhishBot 3.0** lure scanner + link sanitizer. |
| `vigilantguard.py` | **VigilantGuard** sandbox containment + watermarked/tokenized bait + decoy servers. |
| `caller_id.py` | **Cyber Caller ID & Blocker** typed-token screening gateway, call log, rotation, evidence export. |
| `forensics.py` | Simulated (non-executing) analysis + growing signature/"cure" catalog. |
| `tracker_mint.py` | HMAC-signed, tamper-evident **passive** track-back trackers. |
| `db.py` | Self-contained SQLite schema (`lab.db`). |
| `demo_seed.py` | Seeds lures across all tiers + a realistic caller mix. |
| `verify_run.py` | Headless end-to-end verification; prints PASS per stage. |
| `requirements.txt` | Flask (everything else is stdlib). |
| `outbox/` | Chain-of-custody evidence bundles (`outbox/government/` = isolated gov stream). |
| `bait_files/` | Generated watermarked decoy bait files (synthetic). |

---

## API routes

| Method | Route | Purpose |
|--------|-------|---------|
| GET | `/` | Dashboard |
| POST | `/ingest` | Submit a lure → run full pipeline |
| POST | `/analyze` | Re-run pipeline forensics on a lure id |
| GET | `/api/cases` | Forensics case files |
| GET | `/api/trackers` | Minted passive trackers |
| GET | `/api/outbox` | Chain-of-custody bundles |
| GET | `/api/signatures` | Signature / "cure" catalog |
| GET | `/api/calllog` | Cyber Caller ID call log |
| GET | `/api/registry` | Caller / tenant registry |
| GET | `/api/rotations` | Token rotation events |
| GET | `/api/counts` | Live-ish counters |
| POST | `/api/screen` | Screen one inbound cyber "call" |
| POST | `/api/rotate` | Manually rotate a tenant's token type |
| POST | `/api/export_call` | Export a caller record to the evidence chain |
| GET | `/beacon/<token>` | Passive canary beacon sink (records only) |

---

## ABSOLUTE LEGAL GUARDRAILS (from `../shared/BRIEF.md` — obeyed throughout)

1. **Track-back, never hack-back.** No code here reaches out to, accesses,
   damages, or exfiltrates from any system we do not own. We do the opposite of
   a CFAA violation.
2. **Trackers/beacons are PASSIVE tokens only.** They identify an artifact/case;
   they take no action on anyone's device. A beacon fires only when an attacker
   voluntarily opens our bait on *their* machine (a lawful honeytoken).
3. **No live malware execution.** The sandbox is **SIMULATED containment** —
   artifacts are read (static analysis) and stored as inert base64, never run.
4. **Collect and report.** Evidence goes to FBI IC3 / CISA; pursuit is performed
   by **law enforcement**, never by us. Attribution fields are *indicative only*.
5. **All data is synthetic.** Fake credentials are documentation-range /
   obviously fake; senders use `.invalid` domains; no real PII, no real IPs.
6. **Local-first.** The server **binds `127.0.0.1`** only. No telemetry, no
   external network egress anywhere in the component.
